Reference Counting

The IOKitLib contains three reference-counting functions:

• IOObjectGetRetainCount

• IOObjectRetain

• IOObjectRelease

Each of these functions operates on the retain count of the underlying kernel object (the object on the other side of the Mach port) and not on the io_object_t object itself. In other words, if you want to retain, release, or get the retain count of the in-kernel IORegistryEntry object an io_registry_entry_t object represents, you use one of the IOKitLib reference-counting functions. For example, Listing 4-2 shows a code fragment that releases the in-kernel IOIterator object underlying an io_iterator_t object after it’s been used to find a serial port modem.

Listing 4-2  Releasing the underlying kernel object of an io_iterator_t object

io_iterator_t serialPortIterator = NULL;

char deviceFilePath[ MAXPATHLEN ];

kernResult = MyFindSerialPortModems(&serialPortIterator, &masterPort);

if (kernResult == kIOReturnSuccess) {

    kernResult = MyGetPathOfFirstModem (serialPortIterator, deviceFilePath,

            sizeof(deviceFilePath));

    //Release the iterator since we want only the first modem.

    IOObjectRelease(serialPortIterator);

    //If MyGetPathOfFirstModem found a modem, communicate with it.

...

}

As a matter of good programming practice, you should use IOObjectRelease to release all io_object_t objects you create in your code when they’re no longer needed.

If you suspect that you are leaking io_object_t objects, however, IOObjectGetRetainCount won’t help you because this function informs you of the underlying kernel object’s retain count (which is often much higher). Instead, because the retain count of an io_object_t object is essentially the retain count of the send rights on the Mach port, you use a Mach function to get this information. Listing 4-3 shows how to use the Mach functionmach_port_get_refs (defined in mach/mach_port.h in the Kernel framework) to get the retain count of an io_object_t object.

Listing 4-3  Getting the retain count of an io_object_t object

#include <mach/mach_port.h>

kern_return_t kr;

unsigned int count;

io_object_t theObject;

kr = mach_port_get_refs ( mach_task_self(), theObject, MACH_PORT_RIGHT_SEND,

            &count );

printf ("Retain count for object ID %#X is %d\n", theObject, count);

Introspection

The IOKitLib provides three object-introspection functions that operate on the in-kernel object the passed-in io_object_t object represents (not the io_object_t object itself):

• IOObjectConformsTo

• IOObjectGetClass

• IOObjectIsEqualTo

The first function, IOObjectConformsTo, simply performs the in-kernel object’s metaCast method and returns the Boolean result. The IOObjectGetClass function calls the in-kernel object’s getMetaClass method and then calls that class’s getClassName method to return the class name as a C string. IOKitLib implements the IOObjectIsEqualTo function as a shallow pointer comparison of the two passed-in objects, returning the result as a Boolean value.

Creating Matching Dictionaries

When you use IOKitLib functions to create a matching dictionary, you receive a reference to a Core Foundation dictionary object. The IOKitLib uses Core Foundation classes, such as CFMutableDictionary and CFString, because they closely corrrespond to the in-kernel collection and container classes, such as OSDictionary and OSString (defined in libkern/c++ in the Kernel framework).

The I/O Kit automatically translates a CFDictionary object into its in-kernel counterpart when it crosses the user-kernel boundary, allowing you to create an object in user-space that is later used in the kernel. For more information on using Core Foundation objects to represent in-kernel objects, see Viewing Properties of I/O Registry Objects.

The IOKitLib defines the following functions to create matching dictionaries:

• IOServiceMatching

• IOServiceNameMatching

• IOBSDNameMatching

These functions create a mutable Core Foundation dictionary object containing the appropriate key and your passed-in value. Table 4-1 shows the keys each of the dictionary-creation functions use, along with the I/O Kit framework files in which the keys are defined.

If, for example, you call IOServiceNameMatching with the argument i2c-modem, the resulting dictionary looks like this:

{

    IONameMatch = i2c-modem;

}

All dictionary-creation functions return a reference to a CFMutableDictionary object. Usually, you pass the dictionary to one of the look-up functions (discussed next in Looking Up Devices), each of which consumes one reference to it. If you use the dictionary in some other way, you should adjust its retain count accordingly, using CFRetain or CFRelease (defined in the Core Foundation framework).

Looking Up Devices

IOKitLib provides three look-up functions that look up registered objects in the I/O Registry that match a passed-in matching dictionary:

• IOServiceGetMatchingServices

• IOServiceGetMatchingService

• IOServiceAddMatchingNotification

IOKitLib implements its most general look-up function, IOServiceGetMatchingServices, by transforming your matching dictionary into an OSDictionary object and invoking the IOService method getMatchingServices. This method returns an IOIterator object that contains a list of matching IOService objects. IOServiceGetMatchingServices then releases the matching dictionary you passed in and returns to you an io_iterator_t object representing the in-kernel IOIterator object.

The IOServiceGetMatchingService function is simply a special case of IOServiceGetMatchingServices: It returns the first matching object in the list instead of an iterator that provides access to the entire list.

If you receive an io_iterator_t object from IOServiceGetMatchingServices, you should release it with IOObjectRelease when you’re finished with it; similarly, you should use IOObjectRelease to release the io_object_t object you receive from IOServiceGetMatchingService.

The IOServiceAddMatchingNotification function not only looks up matching objects in the I/O Registry, it also installs a request for notification of matching objects that meet your passed-in criterion. The IOKitLib implements this function by invoking the IOService addNotification method, which creates a persistent notification handler that can be notified of IOService events.

To use IOServiceAddMatchingNotification, however, you must first use some other functions in the IOKitLib to set up the notification mechanism. For more information on these functions, see the next section, Setting Up and Receiving Notifications. For an outline of the steps your application takes to set up a notification mechanism using a run loop, see Getting Notifications of Device Arrival and Departure.

Setting Up and Receiving Notifications

The IOKitLib provides several functions you use to set up and manage notification objects:

• IONotificationPortCreate

• IONotificationPortGetRunLoopSource

• IONotificationPortGetMachPort

• IODispatchCalloutFromMessage

• IONotificationPortDestroy

Whether you choose to receive notifications on a run loop or a Mach port (using a run loop is the recommended approach), you must first create an object that can listen for I/O Kit notifications. To do this, you use the IONotificationPortCreate function, which returns an object of type IONotificationPortRef. IOKitLib implements this function by allocating a receive right on the current Mach port, giving it the name of the IONotificationPort object you pass in.

To receive notifications on a run loop, you first use the IONotificationPortGetRunLoopSource function to get a run-loop source you can install on your application’s current run loop. In OS X, a run loop registers input sources, such as Mach ports, and enables the delivery of events, such as IOService object status changes, through those sources. The run-loop source object you receive from IONotificationPortGetRunLoopSource function is of type CFRunLoopSourceRef. (For more information about how to install the run-loop source on your application’s run loop, see Getting Notifications of Device Arrival and Departure.)

The IOKitLib provides two functions that allow you use a Mach port you create on which to listen for notifications, rather than a run loop. Although this method is available to you, it’s recommended that you use the easier-to-implement and more automatic run-loop solution instead. The IONotificationPortGetMachPort function returns a Mach port on which the IONotificationPortRef object can listen for notifications. When the notification object receives a message, you pass the message to the IODispatchCalloutFromMessage function to generate the callback function associated with the notification.

The IONotificationPortDestroy function cleans up and destroys all rights named by the passed-in port name (the IONotificationPortRef object you received from IONotificationPortCreate). You should call this function when you no longer want to receive notifications.

Iterating Over Matching Devices

To access the matching objects a look-up function returns, you use the IOIteratorNext function. IOKitLib contains three functions that operate on io_iterator_t objects:

• IOIteratorNext

• IOIteratorIsValid

• IOIteratorReset

As a subclass of OSIterator, the in-kernel IOIterator object defines the methods getNextObject, isValid, and reset. IOKitLib invokes these methods in its implementation of IOIteratorNext, IOIteratorIsValid, and IOIteratorReset, respectively.

IOIteratorNext simply returns a reference to the current object in the list (an io_object_t object) and advances the iterator to the next object.

IOIteratorIsValid returns a Boolean value indicating whether the iterator is still valid. Sometimes, if the I/O Registry changes while you’re using an iterator, the iterator becomes invalid. When this is the case, IOIteratorIsValid returns zero and you can reset the invalid iterator to the beginning of the list, using IOIteratorReset. Of course, you can use IOIteratorReset to start over at the beginning of the list for any reason, not only because the iterator is invalid.

Traversing the I/O Registry

When you use the IOServiceGetMatchingServices look-up function, you get an iterator you can use to access each object in a list of matching I/O Registry objects. But what if you want to search the I/O Registry using some criteria other than a matching dictionary? Say, for example, you want to find all the children (clients) of a particular object, regardless of whether they are currently registered in the I/O Registry. The following functions give you access to the parents and children of an io_registry_entry_t object:

• IORegistryEntryGetChildEntry

• IORegistryEntryGetChildIterator

• IORegistryEntryGetParentEntry

• IORegistryEntryGetParentIterator

Not surprisingly, the functions with the word “iterator” in their names supply you with an io_iterator_t object you can pass to IOIteratorNext to access each io_registry_entry_t object in the list. IORegistryEntryGetParentIterator, for example, looks in the specified plane to find all ancestors of the passed-in object and returns an iterator you can use to access them. As you do with the IOServiceGetMatchingService and IOServiceAddMatchingNotification functions, be sure to release the returned io_iterator_t object when you’re finished with it (recall that releasing the iterator you receive from IOServiceAddMatchingNotification also disables that notification). The other two functions, IORegistryEntryGetChildEntry and IORegistryEntryGetParentEntry, return the first child or ancestor of the passed-in object in the specified plane.

For even broader searches, you can use the following functions to search the entire I/O Registry, from any point and to any depth:

• IORegistryCreateIterator

• IORegistryEntryCreateIterator

• IORegistryIteratorEnterEntry

• IORegistryIteratorExitEntry

• IORegistryGetRootEntry

The IORegistryCreateIterator function returns an io_iterator_t object that begins at the root of the I/O Registry and iterates over all its children in the specified plane. Similarly, IORegistryEntryCreateIterator returns an io_iterator_t object that begins at the passed-in io_registry_entry_t object and iterates over either all its ancestors or all its children in the passed-in plane.

Both these functions allow you to specify an option that tells the iterator to automatically recurse into objects as they are returned, or only when you call IORegistryIteratorEnterEntry to recurse into the current object. The IORegistryIteratorExitEntry function undoes the effect of IORegistryIteratorEnterEntry by resetting the iterator to the current object, allowing the iterator to continue from where it left off. As its name implies, IORegistryGetRootEntry returns an io_registry_entry_t object representing the root of the I/O Registry.

Getting Information About I/O Registry Objects

The IOKitLib provides a handful of functions, listed below, that return information about a particular I/O Registry object, such as its name or path.

• IORegistryEntryGetName

• IORegistryEntryGetNameInPlane

• IORegistryEntryGetPath

• IORegistryEntryGetLocationInPlane

• IORegistryEntryInPlane

IOKitLib implements these functions by invoking IORegistryEntry methods such as getName and getLocation. Each function returns a C string that contains the object’s name or location. For example, Listing 4-4 shows how to use some of these functions on the object representing an Apple USB keyboard.

Listing 4-4  Using the IORegistryEntryGet functions

io_service_t device;

io_name_t devName;

io_string_t pathName;

IORegistryEntryGetName(device, devName);

printf("Device's name = %s\n", devName);

IORegistryEntryGetPath(device, kIOServicePlane, pathName);

printf("Device's path in IOService plane = %s\n", pathName);

IORegistryEntryGetPath(device, kIOUSBPlane, pathName);

printf("Device's path in IOUSB plane = %s\n", pathName);

The code in Listing 4-4 displays information like the following:

Device's name = Apple Extended USB Keyboard

Device's path in IOService plane = IOService:/MacRISC2PE/pci@f2000000/

    AppleMacRiscPCI/usb@18/AppleUSBOHCI/Apple Extended USB Keyboard@1211000

Device's path in IOUSB plane = IOUSB:/IOUSBHubDevice@1200000/Hub in Apple

    Extended USB Keyboard@1210000/Apple Extended USB Keyboard@1211000

If you’re more interested in whether an object exists in a particular plane than in its path or name, you can use the IORegistryEntryInPlane function, which returns TRUE if the object has a parent in the plane and FALSE otherwise.

Viewing Properties of I/O Registry Objects

Each object in the I/O Registry has two dictionaries associated with it:

• The property table for the object—if the object is a driver, this is the matching dictionary that defines one of the driver’s personalities (if the object is a nub, the device family publishes device properties in the nub’s property table).

• The plane dictionary—this dictionary describes how the object is connected to other objects in the I/O Registry.

These dictionaries are instances of OSDictionary. The libkern C++ library defines container classes, which hold primitive values, such as numbers and strings, and collection classes, which hold groups of both container objects and other collection objects. To view the contents of these objects in an application, you must use IOKitLib functions to convert the in-kernel collection or container object (such as OSDictionary or OSString) to the equivalent Core Foundation object. Currently, only the following libkern classes are available as Core Foundation analogues:

• OSDictionary

• OSArray

• OSSet

• OSSymbol

• OSString

• OSData

• OSNumber

• OSBoolean

The following IOKitLib functions allow you to access an object’s properties as Core Foundation types:

• IORegistryEntryCreateCFProperty

• IORegistryEntryCreateCFProperties

• IORegistryEntrySearchCFProperty

The IORegistryEntryCreateCFProperty function creates a Core Foundation container representing the value associated with the passed-in property key. For example, you can get a CFTypeRef to a storage device’s device-file name by passing a handle to the device (an io_object_t object) and the key kIOBSDNameKey (defined in IOBSD.h) to IORegistryEntryCreateCFProperty:

CFTypeRef deviceFileName;

deviceFileName = IORegistryEntryCreateCFProperty(deviceHandle,

                CFSTR(kIOBSDNameKey), kCFAllocatorDefault, 0);

The IORegistryEntryCreateCFProperties function creates a Core Foundation dictionary object containing the passed-in object’s property table. After your application gets the CFDictionary representation of an object’s property table, it can call Core Foundation functions (such as CFDictionaryGetValue and CFNumberGetValue) to access the dictionary’s values.

The IORegistryEntrySearchCFProperty function searches for the passed-in property, beginning with a specified io_registry_entry_t object’s property table, and continuing with either its parents or its children in the specified plane. When it finds the property you passed in, it returns a Core Foundation container object representing the property.

When you’re finished with the Core Foundation container object you receive from these functions, you should call CFRelease on it.

Because the I/O Registry is a dynamic database that is constantly being updated, the properties a function such as IORegistryEntryCreateCFProperties returns represent a snapshot of the I/O Registry’s state at a single instant. For this reason, you should not assume that the properties you receive are static—if you call these functions multiple times in your application, you may get different results each time.

Setting Properties of I/O Registry Objects

In addition to viewing an object’s properties in an application, you can also use IOKitLib functions to place new properties into an object’s property table.

Setting properties from user space is suitable for some types of device control, in particular, single downloads of data, such as the loading of firmware. This type of user space–kernel communication works because both the application and the in-kernel object have access to the device object’s property table in the I/O Registry. Of course, when you use IOKitLib functions to set properties in an object’s property table, it’s important to realize that you’re only manipulating the OSDictionary representation of an object’s information property list, not the property list itself.

Before you consider setting an object’s properties in your application, make sure your situation meets the following conditions:

• Your device family implements the setProperties method or you control the in-kernel driver, and in it, you implement the setProperties method.

• The driver does not have to allocate permanent resources to complete the transaction.

• The data sent either causes no change in the driver’s state, or causes a single, permanent change.

• If the application transfers data by copy, it sends only a limited amount, such as a page or less. (If the application sends data by reference, it can send an arbitrary amount of data.)

The IOKitLib provides four functions that allow you to set properties in an object’s I/O Registry property table:

• IORegistryEntrySetCFProperty

• IORegistryEntrySetCFProperties

• IOConnectSetCFProperty

• IOConnectSetCFProperties

The first two functions, IORegistryEntrySetCFProperty and IORegistryEntrySetCFProperties, are generic functions that set either a single property value or a collection of property values (typically, in a CFDictionary object) in the specified io_registry_entry_t object. The in-kernel object interprets the Core Foundation container or collection object as it chooses.

If you’re developing your own device interface–user client solution, you’re more likely to use the IOConnectSetCFProperty and IOConnectSetCFProperties functions to set properties. This is because you are working with the io_connect_t object that represents the connection you opened to the in-kernel driver object with IOServiceOpen and these functions provide more access control than IORegistryEntrySetProperty and IORegistryEntrySetProperties. For a brief overview of how to create a connection to a user client, see Device-Interface Development.

Determining Busy States

The IOKitLib includes a handful of functions that give you information about the busy state of various IOService objects and allow you to wait until these objects are no longer busy:

• IOServiceGetBusyState

• IOKitGetBusyState

• IOServiceWaitQuiet

• IOKitWaitQuiet

Because activities such as registration, matching, and termination are asynchronous, an IOService object in the process of one of these activities is considered busy and its busyState value is increased by one. When any of these activities concludes, the IOService’s busyState value is decreased by one. Additionally, any time an IOService object’s busyState value changes, its provider’s busyState value changes to match, which means that an IOService object is considered to be busy when any of its clients is busy.

To get the busy state of an individual io_service_t object, you use the IOServiceGetBusyState function, which IOKitLib implements by invoking the object’s getBusyState method.

You can get the busy state of all IOService objects by calling the IOKitGetBusyState function. As the provider of all IOService objects in the I/O Registry, the root of the Service plane is busy when any of its clients (in other words, any IOService object) is busy. The IOKitGetBusyState function returns the busy state of the Service plane root, effectively informing you of the busy state of the I/O Registry as a whole.

You can wait until objects cease to be busy by calling either the IOServiceWaitQuiet or IOKitWaitQuiet functions. Both functions allow you to specify a maximum time to wait and block the calling process until either the time runs out or the object becomes nonbusy.

Creating a User Space–Kernel Connection

The IOKitLib provides several functions that allow you to create and manipulate connections to in-kernel objects, typically user clients. As with the other functions described in this section, you should use them only when your device family does not provide a device-interface solution and you’ve decided to implement both the in-kernel user client and the user-space device interface.

For an application to communicate with a device, the first thing it must do is create a connection between itself and the in-kernel object representing the device. To do this, it creates a user client object.

After it gets the io_service_t object representing the device driver (by calling IOServiceGetMatchingServices, for example), the application calls the IOKitLib IOServiceOpen function to create the connection. The IOServiceOpen function invokes the io_service_t object’s newUserClient method, which instantiates, initializes, and attaches the user client. As a result of calling IOServiceOpen, the application receives an io_connect_t object (representing the user-client object) that it can use with the IOKitLib IOConnect functions.

For example, in the SimpleUserClient example project, the application portion of the project creates a user client with code like that shown in Listing 4-5.

Listing 4-5  Creating a user client

//Code to get the I/O Kit master port, create a matching dictionary, and get

//an io_service_t object representing the in-kernel driver is not shown here.

io_service_t serviceObject;

io_connect_t dataPort;

kern_return_t kernResult;

kernResult = IOServiceOpen(serviceObject, mach_task_self(), 0, &dataPort);

An application destroys a connection to a user client with a call to the IOServiceClose function, which invokes the clientClose method in the user client. If, for some reason, the application terminates before it’s able to call IOServiceClose, the user client invokes the clientDied method. Typically, the user client responds to both methods by invoking close on its provider (usually the device nub).

If you’re developing your own user client and device-interface library, the IOKitLib functions you’re most likely to use are the four IOConnectMethod functions (which call the user client’s external methods) and, if your user client can map hardware registers into your application’s address space, IOConnectMapMemory and IOConnectUnmapMemory.

//kMyUserClientOpen is one of the enum constants the SimpleUserClient

//project uses as indexes into the IOExternalMethod array.

kernResult = IOConnectMethodScalarIScalarO(dataPort, kMyUserClientOpen,

                 0, 0);

//MySampleStruct is defined in the header file both the user client

//and the application include and consists of two integer variable

//declarations.

MySampleStruct sampleStruct = {586, 8756}; //Random numbers.

int sampleNumber = 15; //Random number.

IOByteCount structSize = sizeof(MySampleStruct);

kern_return_t kernResult;

kernResult = IOConnectMethodScalarIStructureI(dataPort, // from IOServiceOpen

                kMyScalarIStructImethod, // method index

                1, // number of scalar input values

                structSize, // size of input structure

                sampleNumber, // scalar input value

                &sampleStruct // pointer to input structure

                );

Managing the User Space–Kernel Connection

The remaining IOConnect functions in IOKitLib are primarily intended to help you manage your custom user space–kernel connection. As with the other IOConnect functions, you should not use them with I/O Kit family-supplied or third-party device interfaces because they operate directly on the io_connect_t object representing the connection, circumventing the existing device interface.

The IOKitLib contains the following functions to manipulate the io_connect_t object:

• IOConnectAddClient

• IOConnectAddRef

• IOConnectRelease

• IOConnectGetService

• IOConnectSetNotificationPort

The IOConnectAddClient function creates a connection between two user-client objects in the kernel by invoking the first user client’s connectClient method. You can use this function in the unlikely event that you have two user clients that need to be able to communicate.

As their names suggest, IOConnectAddRef and IOConnectRelease adjust the reference count on the passed-in io_connect_t object.

The IOConnectGetService function returns an io_service_t object representing the IOService object on which the passed-in io_connect_t object was opened. IOKitLib implements this function by invoking the user client’s getService method.

To identify a Mach port on which to receive family-specific notifications (notification types not interpreted by the I/O Kit), you use the IOConnectSetNotificationPort function. You pass in, among other arguments, the io_connect_t object representing the user client connection and a mach_port_t object representing the Mach port on which you want to receive notifications. The IOKitLib implements this function by invoking the user client’s registerNotificationPort method.