Read Me About IOPrintSuperClasses

=================================

1.1

The sample is a trivial example of using the I/O Kit registry, but it also represents a useful tool for exploring the I/O Kit class hierarchy. Given the name of a class, this tool will print all of the super-classes of that class.  For example, if you ask it for the super-classes of IOUSBInterface, the tool will print IOUSBNub, IORegistryEntry, IOService, and OSObject.

I built and tested this version of the sample on Mac OS X 10.4.  However, I tested the compatibility target back to Mac OS X 10.2.x.

Packing List

------------

The sample contains the following items:

o ReadMe.txt -- This document.

o IOPrintSuperClasses.c -- Source code to the sample.

o IOPrintSuperClasses.xcodeproj -- An Xcode 2.1 project for the sample.

o build -- A compiled version of the project.

Using the Sample

----------------

To test the sample, just run the tool and supply it I/O Kit class names on the command line.  For example:

$ cd Desktop/IOPrintSuperClasses

$ build/Development/IOPrintSuperClasses IOUSBInterface

Superclasses of IOUSBInterface:

  IOUSBNub

  IOService

  IORegistryEntry

  OSObject

Building the Sample

-------------------

The sample was built using Xcode 2.1.  You should be able to just open the project and choose Build from the Build menu.  There are two targets:

o The "IOPrintSuperClasses" target builds the "IOPrintSuperClasses" tool.  This is a universal binary that runs on Mac OS X 10.4 and later.

o "The IOPrintSuperClasses-compat" target builds the "IOPrintSuperClasses-compat" tool.  This is a PowerPC-only binary that I tested back to Mac OS X 10.2.x.

How it Works

------------

The sample is has two different implementations.

o Mac OS X 10.4 has a snazzy new routine, IOObjectCopySuperclassForClass, that lets you get the superclass of an I/O Kit object directly.

o Prior to Mac OS X 10.4 this routine didn't exist (there was no user space equivalent of the kernel getSuperClass method <rdar://problem/2740942>).  So, on earlier systems, the sample uses a sneaky workaround.  It first finds an object of the specified class by iterating through the I/O registry, then it gets a list of all the I/O Kit classes from the "IOKitDiagnostics" property, then it loops through each class to see whether the found object "conforms to" the class using IOObjectConformsTo.

You can force the sample to use the old implementation by passing the "-o" flag on the command line.

Caveats

-------

When using the old implementation, the output is not sorted in class inheritance order. This is an artifact of the implementation.  This isn't a problem when using the new implementation.

When using the old implementation, an object of the class you specify on the command line must exist in the I/O registry. Again, this is an artifact of the implementation and is not a problem for the new code.

Credits and Version History

---------------------------

If you find any problems with this sample, mail <dts@apple.com> and I'll try to fix them up.

1.0b1 (Oct 2002) was the first shipping version.

1.1 (Jul 2005) was an update whose primary goal was to produce a universal binary.  Indeed, the old code worked just fine on Intel-based Macintosh computers.  However, while I had the code open I also decided to adopt IOObjectCopySuperclassForClass, which has changed the code quite a bit.

Share and Enjoy.

Apple Developer Technical Support

Networking, Communications, Hardware

3 Aug 2005

$Log: Read\040Me.txt,v $

Revision 1.1  2005/08/03 13:37:06  eskimo1

Version 1.1 update.