Mac OS 9 Compared

On Mac OS 9, applications access hardware in a way that is entirely different from the way it is done on OS X. The difference in approach is largely due to differences in architecture, particularly in the relationship between an application and a driver.

Unlike OS X, Mac OS 9 does not maintain an inviolable barrier between an application's address space and the address space of anything that would be found in the OS X kernel. An application has access to the address of any other process in the system, including that of a driver.

This access affects how completion routines are invoked. The structure behind all I/O on a Mac OS 9 system is called a parameter block. The parameter block contains the fields typically required for a DMA transfer:

• Host address

• Target address

• Direction of transfer

• Completion routine and associated data

The completion routine is implemented by the application to handle any returned results. The driver maintains a linked list of parameter blocks as I/O requests or jobs for the DMA engine to perform. When a job completes, the hardware triggers an interrupt, prompting the driver to call the application’s completion routine. The application code implementing the completion routine runs at “interrupt time”—that is, in the context of the hardware interrupt. This leads to a greater likelihood that a programming error in the completion routine can crash or hang the entire system.

If the same thing with interrupts happened on OS X, there would additionally be the overhead of crossing the kernel–user space boundary (with its performance implications) as well as the risk to system stability that comes with exporting kernel resources to user space.

I/O Kit Family Device Interfaces

A device interface is the flip side of what is known as a user client in the kernel. A device interface is a library or plug-in through whose interface an application can access a device. The application can call any of the functions defined by the interface to communicate with or control the device. In turn, the library or plug-in talks with a user-client object (an instance of a subclass of IOUserClient) in a driver stack in the kernel. (See The Architecture of User Clients for a full description of these types of driver objects.)

Several I/O Kit families provide device interfaces for applications and other user-space clients. These families include (but are not limited to) the SCSI, HID, USB, and FireWire families. (Check the header files in the I/O Kit framework to find out about the complete list of families providing device interfaces.) If your driver is a member of one of these families, your user-space clients need only use the device interface of the family to access the hardware controlled by your driver.

See Finding and Accessing Devices in Accessing Hardware From Applications for a detailed presentation of the procedure for acquiring and using device interfaces.

Using POSIX APIs

For each storage, network, and serial device the I/O Kit dynamically creates a device file in the file system’s /dev directory when it discovers a device and finds a driver for it, either at system startup or as part of its ongoing matching process. If your device driver is a member of the I/O Kit’s Storage, Network, or Serial families, then your clients can access your driver’s services by using POSIX I/O routines. They can simply use the I/O Registry to discover the device file that is associated with the device your driver controls. Then, with that device file as a parameter, they call POSIX I/O functions to open and close the device and read and write data to it.

Because the I/O Kit dynamically generates the contents of the /dev directory as devices are attached and detached, you should never hard-code the name of a device file or expect it to remain the same whenever your application runs. To obtain the path to a device file, you must use device matching to obtain a device path from the I/O Registry. Once you have found the correct path, you can use POSIX functions to access the device. For information on using the I/O Registry to find device-file paths, see Accessing Hardware From Applications.

Accessing Device Properties

The I/O Registry is the dynamic database that the I/O Kit uses to store the current properties and relationships of driver objects in an OS X system. APIs in the kernel and in user space give access to the I/O Registry, allowing code to get and set properties of objects in the Registry. This common access makes possible a limited form of communication between driver and application.

All driver objects in the kernel derive from IOService, which is in turn a subclass of the IORegistryEntry class. The methods of IORegistryEntry enable code in the kernel to search the I/O Registry for specific entries and to get and set the properties of those entries. A complementary set of functions (defined in IOKitLib.h) exist in the I/O Kit framework. Applications can use the functions to fetch data stored as properties of a driver object or to send data to a driver object.

This property-setting mechanism is suitable for situations where the following conditions are true:

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

• The application is transferring—by copy—a limited amount of data (under a page)

  With the property-setting mechanism, the application can pass arbitrary amounts of data by reference (that is, using pointers).

• The data sent causes no change in driver state or results in a single, permanent change of state.

• You control the driver in the kernel (and thus can implement the setProperties method described below).

The property-setting mechanism is thus suitable for some forms of device control and is ideal for one-shot downloads of data, such as for loading firmware. It is not suitable for connection-oriented tasks because such tasks usually require the allocation of memory or the acquisition of devices. Moreover, this mechanism does not allow the driver to track when its clients die.

The general procedure for sending data from an application to a driver object as a property starts with establishing a connection with the driver. The procedure for this, described in The Basic Connection and I/O Procedure, consists of three steps:

1. Getting the I/O Kit master port

2. Obtaining an instance of the driver

3. Creating a connection

Once you have a connection, do the following steps:

1. Call the IOConnectSetCFProperties function, passing in the connection and a Core Foundation container object, such as a CFDictionary.

   The Core Foundation object contains the data you want to pass to the driver. Note that you can call IOConnectSetCFProperty instead if you want to pass only a single, value-type Core Foundation object, such as a CFString or a CFNumber and that value’s key. Both function calls cause the invocation of the IORegistryEntry::setProperties method in the driver.

2. In the driver, implement the setProperties method.

   Before it invokes this method, the I/O Kit converts the Core Foundation object passed in by the user process to a corresponding libkern container object (such as OSDictionary). In its implementation of this method, the driver object extracts the data from the libkern container object and does with it what is expected.

The Core Foundation object passed in by the user process must, of course, have a libkern equivalent. Table 4-1 shows the allowable Core Foundation types and their corresponding libkern objects.

The following example (Listing 4-1) shows how the I/O Kit’s Serial family uses the I/O Registry property-setting mechanism to let a user process make a driver thread idle until a serial port is free to use (when there are devices, such as a modem and a fax, competing for the port).

Listing 4-1  Controlling a serial device using setProperties

IOReturn IOSerialBSDClient::

setOneProperty(const OSSymbol *key, OSObject *value)

{

    if (key == gIOTTYWaitForIdleKey) {

        int error = waitForIdle();

        if (ENXIO == error)

            return kIOReturnOffline;

        else if (error)

            return kIOReturnAborted;

        else

            return kIOReturnSuccess;

    }

    return kIOReturnUnsupported;

}

IOReturn IOSerialBSDClient::

setProperties(OSObject *properties)

{

    IOReturn res = kIOReturnBadArgument;

    if (OSDynamicCast(OSString, properties)) {

        const OSSymbol *propSym =

            OSSymbol::withString((OSString *) properties);

        res = setOneProperty(propSym, 0);

        propSym->release();

    }

    else if (OSDynamicCast(OSDictionary, properties)) {

        const OSDictionary *dict = (const OSDictionary *) properties;

        OSCollectionIterator *keysIter;

        const OSSymbol *key;

        keysIter = OSCollectionIterator::withCollection(dict);

        if (!keysIter) {

            res = kIOReturnNoMemory;

            goto bail;

        }

        while ( (key = (const OSSymbol *) keysIter->getNextObject()) ) {

            res = setOneProperty(key, dict->getObject(key));

            if (res)

                break;

        }

        keysIter->release();

    }

bail:

    return res;

}

Custom User Clients

If you cannot make your hardware properly accessible to applications using I/O Kit’s off-the-shelf device interfaces, POSIX APIs, or I/O Registry properties, then you’ll probably have to write a custom user client. To reach this conclusion, you should first have answered “no” the following questions:

• If your device a member of an I/O Kit family, does that family provide a device interface?

• Is your device a serial, networking, or storage device?

• Are I/O Registry properties sufficient for the needs of the application? (If you need to move huge amounts of data, or if you don’t have control over the driver code, then they probably aren’t.)

If you have determined that you need to write a custom user client for your hardware and its driver, read on for the information describing how to do this.

Types of User-Client Transport

The I/O Kit’s APIs enable several different types of transport across the boundary between the kernel and user space:

• Passing untyped data: This mechanism uses arrays of structures containing pointers to the methods to invoke in a driver object; the methods must conform to prototypes for primitive functions with parameters only indicating general type (scalar for a single, 32-bit value or structure for a group of values), number of scalar parameters, size of structures, and direction (input or output). The passing of untyped data using this mechanism can be synchronous or asynchronous.

• Sharing memory: This is a form of memory mapping in which one or more pages of memory are mapped into the address space of two tasks—in this case, the driver and the application process. Either process can then access or modify the data stored in those shared pages. The user-client mechanism for shared memory uses IOMemoryDescriptor objects on the kernel side and buffer pointers vm_address_t on the user side to map hardware registers to user space. This method of data transfer is intended for hardware that is not DMA-based and is ideal for moving large amounts of data between the hardware and the application. User processes can also map their memory into the kernel’s address space.

• Sending notifications: This mechanism passes notification ports in and out of the kernel to send notifications between the kernel and user processes. These methods are used in asynchronous data-passing.

An important point to keep in mind is that the implementation of a user client is not restricted to only one of the mechanisms listed above. It can use two or more of them; for example, it might used the synchronous untyped-data mechanism to program a DMA engine and shared memory for the actual data transfer.

Synchronous Versus Asynchronous Data Transfer

Two styles of untyped-data passing are possible with the I/O Kit's user-client APIs: Synchronous and asynchronous. Each has its strengths and drawbacks, and each is more suitable to certain characteristics of hardware and user-space API. Although the asynchronous I/O model is somewhat comparable to the way Mac OS 9 applications access hardware, it is different in some respects. The most significant of these differences is an aspect of architecture shared with the synchronous model: In OS X, the client provides the thread on which I/O completion routines are called, but the kernel controls the thread. I/O completion routines execute outside the context of the kernel.

The following discussion compares the synchronous (blocking) I/O and asynchronous (non-blocking, with completion) I/O models from an architectural perspective and without discussion of specific APIs. For an overview of those APIs, see Creating a User Client Subclass.

In synchronous I/O, the user process issues an I/O request on a thread that calls into the kernel and blocks until the I/O request has been processed (completed). The actual I/O work is completed on the work-loop thread of the driver. When the I/O completes, the user client wakes the user thread, gives it any results from the I/O operation, and returns control of the thread to the user process. After handling the result of the I/O, the thread delivers another I/O request to the user client, and the process starts again.

The defining characteristic of the synchronous model is that the client makes a function call into the kernel that doesn't return until the I/O has completed. The major disadvantage of the synchronous approach is that the thread that issues the I/O request cannot do any more work until the I/O completes. However, it is possible to interrupt blocking synchronous routines by using signals, for example. In this case, the user client has to know that signals might be sent and how to handle them. It must be prepared to react appropriately in all possible situations, such as when an I/O operation is in progress when the signal is received.

In asynchronous I/O, the user-process client has at least two threads involved in I/O transfers. One thread delivers an I/O request to the user client and returns immediately. The client also provides a thread to the user client for the delivery of notifications of I/O completions. The user client maintains a linked list of these notifications from prior I/O operations. If there are pending notifications, the user client invokes the notification thread's completion routine, passing in the results of an I/O operation. Otherwise, if there are no notifications in this list, the user client puts the notification thread to sleep.

The user process should create and manage the extra threads in this model using some user-level facility such as BSD pthreads. This necessity points at the main drawback of the asynchronous model: The issue of thread management in a multithreaded environment. This is something that is difficult to do right. Another problem with asynchronous I/O is related to performance; with this type of I/O there are two kernel–user space round-trips per I/O. One way to mitigate this problem is to batch completion notifications and have the notification thread process several of them at once. For the asynchronous approach, you also might consider basing the client's I/O thread on a run-loop object (CFRunLoop); this object is an excellent multiplexor, allowing you to have different user-space event sources.

So which model for I/O is better, synchronous or asynchronous? As with many aspects of design, the answer is a definite “it depends.” It depends on any legacy application code you're working with, it depends on the sophistication of your thread programming, and it depends on the rate of I/O. The asynchronous approach is good when the number of I/O operations per second is limited (well under 1000 per second). Otherwise, consider the synchronous I/O model, which takes better advantage of the OS X architecture.

Range of Accessibility

The design of the user side of a user-client connection depends on the probable number and nature of the applications (and other user processes) that want to communicate with your driver. If you’re designing your user client for only one particular application, and that application is based on Mach-O object code, then you can incorporate the connection and I/O code into the application itself. See The Basic Connection and I/O Procedure for the general procedure.

However, a driver writer often wants his driver accessible by more than one application. The driver could be intended for use by a family of applications made by a single software developer. Or any number of applications—even those you are currently unaware of—should be able to access the services of the driver. In these situations, you should put the code related to the user side of the user-client connection into a separate module, such as a shared library or plug-in. This module, known as a device interface, should abstract common connection and I/O functionality and present a friendly programmatic interface to application clients.

So let’s say you’ve decided to put your connection and I/O code into a device interface; you now must decide what form this device interface should take. The connection and I/O code must call functions defined in the I/O Kit framework, which contains a Mach-O dynamic shared library; consequently, all device interfaces should be built as executable code based on the Mach-O object-file format. The device interface can be packaged as a bundle containing a dynamic shared library or as a plug-in. In other words, the common API choice is between CFBundle (or Cocoa’s NSBundle) or CFPlugIn.

The decision between bundle and plug-in is conditioned by the nature of the applications that will be the clients of your user client. If there is a good chance that CFM-based applications will want to access your driver, you should use the CFBundle APIs because CFBundle provides cross-architecture capabilities. If you require a more powerful abstraction for device accessibility, and application clients are not likely to be CFM-based, you can use the CFPlugIn APIs. As an historical note, the families of the I/O Kit use CFPlugIns for their device interfaces because these types of plug-ins provide a greater range of accessibility by enabling third-party developers to create driver-like modules in user space.

If only one application is going to be the client of your custom user client, but that application is based on CFM-PEF object code, you should create a Mach-O bundle (using CFBundle or NSBundle APIs) as the device interface for the application.

In most cases, you can safely choose CFBundle (or NSBundle) for your device interface. In addition to their capability for cross-architecture calling, these bundle APIs make it easy to create a device interface.

Design of Legacy Applications

A major factor in the design of your user client is the API of applications that currently access the hardware on other platforms, such as Mac OS 9 or Windows. Developers porting these applications to OS X will (understandably) be concerned about how hard it will be to get their applications to work with a custom user client. They will probably want to move over as much of their application's hardware-related code as they can to OS X, but this may not be easy to do.

For example, if the application API is based on interrupt-triggered asynchronous callbacks, such as on Mac OS 9, that API is not suitable for OS X, where the primary-interrupt thread must remain in the kernel. Although the I/O Kit does have APIs for asynchronous I/O, these APIs are considerably different than those in Mac OS 9. Moreover, the preferred approach for OS X is to use synchronous calls. So this might be a good opportunity for the application developer to revamp his hardware-API architecture.

If application developers decide to radically redesign their hardware API, the design of that API should influence the choices made for kernel–user space transport. For example, if the high-level API is asynchronous with callbacks, a logical choice would be to base the new application API on the I/O Kit's asynchronous untyped data–passing API. On the other hand, if the high-level API is already synchronous, than the I/O Kit's synchronous untyped data–passing API should clearly be used. The synchronous API is much easier and cleaner to implement, and if done properly does not suffer performance-wise in comparison with the asynchronous approach.

Hardware

The design for your user client depends even more on the hardware your driver is controlling. Your user-client API needs to accommodate the underlying hardware. Two issues here are data throughput and interrupt frequency. If the data rates are quite large, such as with a video card, then try using mapped memory. If the hardware delivers just a few interrupts a second, you can consider handling those interrupts in user space using some asynchronous notification mechanism. But there are latency problems in such mechanisms, so if the hardware produces thousands of interrupts a second, you should handle them in the kernel code.

Finally, there is the issue of hardware memory management. Perhaps the most important aspect of a device, in terms of user-client design, is its memory-management capabilities. These capabilities affect how applications can access hardware registers. The hardware can use either PIO (Programmed Input/Output) or DMA (Direct Memory Access). With PIO, the CPU itself moves data between a device and system (physical) memory; with DMA, a bus controller takes on this role, freeing up the microprocessor for other tasks. Almost all hardware now uses DMA, but some older devices still use PIO.

The simplest approach to application control of a device is to map device resources (such as hardware registers or frame buffers) into the address space of the application process. However, this approach poses a considerable security risk and should only be attempted with caution. Moreover, mapping registers into user space is not a feasible option with DMA hardware because the user process won’t have access to physical memory, which it needs. DMA hardware requires that the I/O work be performed inside the kernel where the virtual-memory APIs yield access to physical addresses. If your device uses DMA memory-management, it is incumbent upon you to find the most efficient way for your driver to do the I/O work.

Given these requirements, you can take one of four approaches in the design of your user client. The first two are options if your hardware memory management is accessed through PIO:

• Full PIO memory management. Because you don’t require interrupts or physical-memory access, you can map the hardware registers into your application’s address space and control the device from there.

• PIO memory management with interrupts. If the PIO hardware uses interrupts, you must attempt a modified version of the previous approach. You can map the registers to user space, but the user process has to provide the thread to send interrupt notifications on. The drawback of this approach is that the memory management is not that good; it is suitable only for low data throughput.

See Mapping Device Registers and RAM Into User Space for more information on these two memory-mapping approaches.

The next two design approaches are appropriate to hardware that uses DMA for memory management. With DMA, your code requires the physical addresses of the registers and must deal with the interrupts signaled by the hardware. If your hardware fits this description, you should use a design based on the untyped data–passing mechanism of the IOUserClient class and handle the I/O within your user client and driver. There are two types of such a design:

• Function-based user client. This kind of user client defines complementary sets of functions on both sides of the kernel–user space boundary (for example, WriteBlockToDevice or ScanImage). Calling one function on the user side results in the invocation of the function on the kernel side. Unless the set of functions is small, you should not take this approach because it would put too much code in the kernel.

• Register-based task files. A task file is an array that batches a series of commands for getting and setting register values and addresses. The user client implements only four “primitive” functions that operate on the contents of the task file. Task files are fully explained in the following section, Task Files.

User clients using register-based task files are the recommended design approach when you have DMA hardware. See Passing Untyped Data Synchronously for examples.

Task Files

Task files give you an efficient way to send I/O requests from a user process to a driver object. A task file is an array containing a series of simple commands for the driver to perform on the hardware registers it controls. By batching multiple I/O requests in this fashion, task files mitigate the performance penalty for crossing the boundary between kernel and user space. You only need one crossing to issue multiple I/O requests.

On the kernel side, all you need are four “primitive” methods that perform the basic operations possible with hardware registers:

• Get value in register x

• Set register x to value y

• Get address in register x

• Set register x to address y

This small set of methods limits the amount of code in the kernel that is dedicated to I/O for the client and moves most of this code to the user-space side of the design. The device interface presents an interface to the application that is more functionally oriented. These functions are implemented, however, to “break down” functional requests into a series of register commands.

See Passing Untyped Data Synchronously for an example of task files.

A Design Scenario

The first step in determining the approach to take is to look at the overall architecture of the system and decide whether any existing solutions for kernel–user space I/O are appropriate. If you decide you need a custom user client, then analyze what is the design approach to take that is most appropriate to your user-space API and hardware.

As an example, say you have a PCI card with digital signal processing (DSP) capabilities. There is no I/O Kit family for devices of this type, so you know that there cannot be any family device interface that you can use. Now, let's say the card uses both DMA memory management and interrupts, so there must be code inside the kernel to handle these things; hence, a driver must be written to do this, and probably a user client. Because a large amount of DSP data must be moved to and from the card, I/O Registry properties are not an adequate solution. Thus a custom user client is necessary.

On another platform there is user-space code that hands off processing tasks to the DSP. This code works on both Mac OS 9 and Windows. Fortunately, the existing API is completely synchronous; there can be only one outstanding request per thread. This aspect of the API makes it a logical step to adapt the code to implement synchronous data passing in the user client and map the card memory into the application's address space for DMA transfers.

The Basic Connection and I/O Procedure

You must complete certain tasks in the user-side code for a connection whether you are creating a library or incorporating the connection and I/O functionality in a single application client. This section summarizes those tasks, all of which involve calling functions defined in IOKitLib.h.

typedef struct MySampleStruct

{

    UInt16 int16;

    UInt32 int32;

} MySampleStruct;

enum

{

    kMyUserClientOpen,

    kMyUserClientClose,

    kMyScalarIStructImethod,

    kMyScalarIStructOmethod,

    kMyScalarIScalarOmethod,

    kMyStructIStructOmethod,

    kNumberOfMethods

};

kernResult = IOMasterPort(MACH_PORT_NULL, &masterPort);

classToMatch = IOServiceMatching(kMyDriversIOKitClassName);

    kernResult = IOServiceGetMatchingServices(masterPort, classToMatch, &iterator);

    if (kernResult != KERN_SUCCESS)

    {

        printf("IOServiceGetMatchingServices returned %d\n\n", kernResult);

        return 0;

    }

    serviceObject = IOIteratorNext(iterator);

    IOObjectRelease(iterator);

    // ...

    kern_return_t   kernResult;

    mach_port_t     masterPort;

    io_service_t    serviceObject;

    io_connect_t    dataPort;

    io_iterator_t   iterator;

    CFDictionaryRef classToMatch;

    // ...

    kernResult = IOMasterPort(MACH_PORT_NULL, &masterPort);

    if (kernResult != KERN_SUCCESS)

    {

        printf( "IOMasterPort returned %d\n", kernResult);

        return 0;

    }

    classToMatch = IOServiceMatching(kMyDriversIOKitClassName);

    if (classToMatch == NULL)

    {

        printf( "IOServiceMatching returned a NULL dictionary.\n");

        return 0;

    }

    kernResult = IOServiceGetMatchingServices(masterPort, classToMatch,

                                            &iterator);

    if (kernResult != KERN_SUCCESS)

    {

        printf("IOServiceGetMatchingServices returned %d\n\n", kernResult);

        return 0;

    }

    serviceObject = IOIteratorNext(iterator);

    IOObjectRelease(iterator);

    if (serviceObject != NULL)

    {

        kernResult = IOServiceOpen(serviceObject, mach_task_self(), 0,

                                    &dataPort);

        IOObjectRelease(serviceObject);

        if (kernResult != KERN_SUCCESS)

        {

            printf("IOServiceOpen returned %d\n", kernResult);

            return 0;

        }

    // ...

enum{    kMyUserClientOpen,    kMyUserClientClose,    // ...};

// ...

    kern_return_t   kernResult;

// ...

    kernResult = IOConnectMethodScalarIScalarO(dataPort, kMyUserClientOpen,

                                                0, 0);

    if (kernResult != KERN_SUCCESS)

        {

            IOServiceClose(dataPort);

            return kernResult;

        }

    // ...

kern_return_t

IOConnectMethodScalarIStructureO(

    io_connect_t    connect,

    unsigned int    index,

    IOItemCount     scalarInputCount,

    IOByteCount *   structureSize,

    ... );

kern_return_t

MyScalarIStructureOExample(io_connect_t dataPort)

{

    MySampleStruct  sampleStruct;

    int             sampleNumber1 = 154;    // This number is random.

    int             sampleNumber2 = 863;    // This number is random.

    IOByteCount     structSize = sizeof(MySampleStruct);

    kern_return_t   kernResult;

    kernResult = IOConnectMethodScalarIStructureO(dataPort,

                        kMyScalarIStructOmethod, // method index

                        2,  // number of scalar input values

                        &structSize, // size of ouput struct

                        sampleNumber1,  // scalar input value

                        sampleNumber2,  // another scalar input value

                        &sampleStruct   // pointer to output struct

                        );

    if (kernResult == KERN_SUCCESS)

    {

        printf("kMyScalarIStructOmethod was successful.\n");

        printf("int16 = %d, int32 = %d\n\n", sampleStruct.int16,

                (int)sampleStruct.int32);

        fflush(stdout);

    }

    return kernResult;

}

kernResult = IOConnectMethodScalarIScalarO(dataPort, kMyUserClientClose, 0,

                                            0);

Aspects of Design for Device Interfaces

When you design your device interface, try to move as much code and logic into it as possible. Only put code in the kernel that absolutely has to be there. The user-interface code in the kernel should be tightly associated with the hardware, especially when the design is based on the task-file approach.

One reason for this has been stressed before: Code in the kernel can be a drain on performance and a source of instability. But another reason should be just as important to developers. User-space code is much easier to debug than kernel code.

User-Client Project Basics

A user client is, first and foremost, a driver object. It is at the “top” of a driver stack between its provider (the driver) and its client (the user process). As a driver object, it must participate in the driver life-cycle by implementing the appropriate methods: start, open, and so on (see IOKit Fundamentals for a description of the driver life cycle). It must communicate with its provider at the appropriate moments. And it must also maintain a connection with its client (the user process) along with any state related to that connection; additionally, it’s the user client’s responsibility to clean up when the client goes away.

Given the close relationship between a driver and its user client, it’s recommended that you include the source files for your user client in the project for your driver. If you want the I/O Kit, in response to IOServiceOpen being called in user space, to automatically allocate, start, and attach an instance of your user-client subclass, specify the IOUserClientClass property in the information property list of your driver. The value of the property should be the full class name of your user client. Alternatively, your driver class can implement the IOService method newUserClient to create, attach, and start an instance of the your IOUserClient subclass.

In the user client’s header file, declare the life-cycle methods that you are overriding; these can include start, message, terminate, and finalize. These messages are propagated up the driver stack, from the driver object closest to the hardware to the user client. Also declare open and close methods; messages invoking these methods are propagated in the opposite direction, and are originated by the application or device interface itself. The open method, in which the user client opens its provider, is particularly important as the place where exclusive device access is enforced. For more on the user client’s open and close methods, see Exclusive Device Access and the open Method; for the application’s role in this, see Open the User Client.

There is one particular thing to note about the start method. In your implementation of this method, verify that the passed-in provider object is an instance of your driver’s class (using OSDynamicCast) and assign it to an instance variable. Your user client needs to send several messages to its provider during the time it’s loaded, so it’s helpful to keep a reference to the provider handy.

You’ll also have to declare and implement some methods specific to initialization of the user client and termination of the client process. The following sections discuss these methods.

bool

com_apple_dts_SimpleUserClient::initWithTask(task_t owningTask,

                                    void *security_id , UInt32 type)

{

    IOLog("SimpleUserClient::initWithTask()\n");

    if (!super::initWithTask(owningTask, security_id , type))

        return false;

    if (!owningTask)

    return false;

    fTask = owningTask;

    fProvider = NULL;

    fDead = false;

    return true;

}

 static const IOExternalMethod sMethods[kNumberOfMethods] =

    {

        {   // kMyUserClientOpen

            NULL,

            (IOMethod) &com_apple_dts_SimpleUserClient::open,

            kIOUCScalarIScalarO,

            0,

            0

        },

        {   // kMyUserClientClose

            NULL,

            (IOMethod) &com_apple_dts_SimpleUserClient::close,

            kIOUCScalarIScalarO,

            0,

            0

        },

      // ...

   );

IOReturn

com_apple_dts_SimpleUserClient::open(void)

{

    if (isInactive())

        return kIOReturnNotAttached;

    if (!fProvider->open(this))

        return kIOReturnExclusiveAccess;

    return kIOReturnSuccess;

}

IOReturn

com_apple_dts_SimpleUserClient::close(void)

{

    IOLog("SimpleUserClient::close()\n");

    if (!fProvider)

        return kIOReturnNotAttached;

    if (fProvider->isOpen(this))

        fProvider->close(this);

    return kIOReturnSuccess;

}

IOReturn

com_apple_dts_SimpleUserClient::clientClose(void)

{

    // release my hold on my parent (if I have one).

    close();

    terminate();

    if (fTask)

    fTask = NULL;

    fProvider = NULL;

    // DON'T call super::clientClose, which just returns notSupported

    return kIOReturnSuccess;

}

IOReturn

com_apple_dts_SimpleUserClient::clientDied(void)

{

    IOReturn ret = kIOReturnSuccess;

    IOLog("SimpleUserClient::clientDied()\n");

    // do any special clean up here

    ret = super::clientDied();

    return ret;

}

Passing Untyped Data Synchronously

The primary IOUserClient mechanism for passing data between a driver and an application is, at its core, an array of pointers to member functions implemented in the driver or, in some cases, the user client. The user client and the user process agree upon a set of constants that act as indexes into the array. When the user process makes a call to read or write some data, it passes this index along with some input and output parameters. Using the index, the user client finds the desired method and invokes it, passing along the required parameters.

That’s the basic mechanism in a nutshell, but the description leaves out important details. These start with the fact that the data passed into or out of the kernel is essentially untyped. The kernel cannot know or predict data types in user space and so can only accept the most generalized types of data. The ensuing discussion describes how the I/O Kit’s user-client API (on both sides of the kernel boundary) accommodates this restriction and how your subclass of IOUserClient must implement its part of the untyped data–passing mechanism. As you read along, refer to Figure 4-4, which graphically shows the relationships among the pieces of the untyped data–passing API.

typedef IOReturn (IOService::*IOMethod)(void * p1, void * p2, void * p3,

                                void * p4, void * p5, void * p6 );

static const IOExternalMethod sMethods[kNumberOfMethods] =

{

    {   // kMyUserClientOpen

        NULL,                   // Target determined at runtime.

        (IOMethod) &com_apple_dts_SimpleUserClient::open,

        kIOUCScalarIScalarO,    // Scalar Input, Scalar Output.

        0,                      // No scalar input values.

        0                       // No scalar output values.

    },

    {   // kMyUserClientClose

        NULL,                   // Target determined at runtime.

        (IOMethod) &com_apple_dts_SimpleUserClient::close,

        kIOUCScalarIScalarO,    // Scalar Input, Scalar Output.

        0,                      // No scalar input values.

        0                       // No scalar output values.

    },

    {   // kMyScalarIStructImethod

        NULL,                   // Target determined at runtime.

        (IOMethod) &com_apple_dts_SimpleDriver::method1,

        kIOUCScalarIStructI,    // Scalar Input, Struct Input.

        1,                      // One scalar input value.

        sizeof(MySampleStruct)  // The size of the input struct.

    },

    {   // kMyScalarIStructOmethod

        NULL,                   // Target determined at runtime.

        (IOMethod) &com_apple_dts_SimpleDriver::method2,

        kIOUCScalarIStructO,    // Scalar Input, Struct Output.

        2,                      // Two scalar input values.

        sizeof(MySampleStruct)  // The size of the output struct.

    },

    {   // kMyScalarIScalarOmethod

        NULL,                   // Target determined at runtime.

        (IOMethod) &com_apple_dts_SimpleDriver::method3,

        kIOUCScalarIScalarO,    // Scalar Input, Scalar Output.

        2,                      // Two scalar input values.

        1                       // One scalar output value.

    },

    {   // kMyStructIStructOmethod

        NULL,                   // Target determined at runtime.

        (IOMethod) &com_apple_dts_SimpleDriver::method4,

        kIOUCStructIStructO,    // Struct Input, Struct Output.

        sizeof(MySampleStruct), // The size of the input struct.

        sizeof(MySampleStruct)  // The size of the output struct.

    },

};

Implementing getTargetAndMethodForIndex

All subclasses of IOUserClient that use the untyped-data mechanism for data transfer between application and driver must implement the getTargetAndMethodForIndex method (or, for asynchronous delivery, getAsyncTargetAndMethodForIndex). A typical implementation of getTargetAndMethodForIndex has to do two things:

• Return directly a pointer to the appropriate IOExternalMethod structure identifying the method to invoke.

• Return a reference to the object that implements the method (the target).

You can either statically assign the target to the IOExternalMethod field when you initialize the structure, or you can dynamically determine the target at run time. Because the target is usually the user client’s provider, often all you need to do is return your reference to your provider (assuming you’ve stored it as an instance variable). Listing 4-13 shows one approach for doing this.

Listing 4-13  Implementing the getTargetAndMethodForIndex method

IOExternalMethod *

com_apple_dts_SimpleUserClient::getTargetAndMethodForIndex(IOService **

target, UInt32 index)

{

// Make sure IOExternalMethod method table has been constructed

// and that the index of the method to call exists

if (index < (UInt32)kNumberOfMethods)

{

if (index == kMyUserClientOpen || index == kMyUserClientClose)

{

// These methods exist in SimpleUserClient

*target = this;

}

else

{

// These methods exist in SimpleDriver

*target = fProvider;

}

return (IOExternalMethod *) &sMethods[index];

}

return NULL;

};

Passing Untyped Data Asynchronously

The defining characteristic of the procedure described in Passing Untyped Data Synchronously is the behavior of the user-space thread making an I/O request. When the client in user space requests an I/O transfer by calling one of the IOConnectMethod functions, the thread bearing the request must block and wait for the user client to return when the I/O completes. This behavior is synchronous. However, the IOUserClient class also provides APIs for asynchronous data transfer between user process and user client. With these APIs, when the user process calls an IOConnectMethod function, it can go on immediately to other tasks because it is not blocked in the function. Later, the user client invokes a callback in the client application, passing it the result and any resulting data.

Although you can dedicate a separate application thread for notifications of I/O completions (as described in Synchronous Versus Asynchronous Data Transfer), a notification thread is not necessary for asynchronous I/O. In fact, there is an alternative to a notification thread that is much easier to implement.

You can accomplish the same asynchronous behavior using the application’s run loop (CFRunLoop). Each application’s main thread has a run-loop object that has receive rights on a Mach port set on which all event sources pertinent to the application (mouse events, display events, user-space notifications, and so on) have send rights. Running in a tight loop, the CFRunLoop checks if any of the event sources in its Mach port set have pending events and, if they do, dispatches the event to the intended destination.

Because run loops are so ubiquitous in user space—every application has one—they offer an easy solution to the problem of posting completions of I/O from the kernel to user space. An I/O notification source for the user client just needs to be added to the run loop. Then the application (or device interface) just needs to pass this port to the user client as well as a pointer to a completion routine for the user client to invoke when the I/O completes.

This section describes the general procedures that the user client and the application should follow to implement asynchronous I/O using CFRunLoop and some of the APIs in the I/O Kit framework and the IOUserClient class. (Many of the APIs in the IOUserClient class that are tagged with “async” are not essential for implementing asynchronous I/O.) Although this section illustrates the procedure with only one CFRunLoop (associated with the application’s main thread) and one run-loop source, it is possible to have multiple run loops and multiple run-loop sources.

Mapping Device Registers and RAM Into User Space

If your driver has hardware with full PIO memory management, your user client may map the hardware registers into the address space of the user process. In this case, the user process does not require access to physical addresses. However, if the PIO hardware does require the use of interrupts, you will have to factor this requirement into your code. It is always possible, even with DMA hardware, to publish device RAM to user space.

The user process initiates a request for mapped memory by calling IOConnectMapMemory, passing in, among other parameters, a pointer to (what will become) the mapped memory in its own address space. The IOConnectMapMemory call results in the invocation of the clientMemoryForType method in the user client. In its implementation of this method, the user client returns the IOMemoryDescriptor object it created in its open or start method that backs the mapping to the hardware registers. The user process receives back this mapping in terms of virtual-memory types of vm_address_t and vm_size_t. It is now free to read from and write to the hardware registers.

Instead of creating an IOMemoryDescriptor object, a user client can (in most cases) simply get the IODeviceMemory object created by its provider's nub. Then, in its clientMemoryForType method, it returns a pointer to the IODeviceMemory object. (IODeviceMemory is a subclass of IOMemoryDescriptor.) If it does this, it should ensure the no-caching flag is turned on (by OR-ing the appropriate flag in the IOOptionBits parameter). The nub of the providing driver uses the IODeviceMemory object to map the registers of the PCI device’s physical address space to the kernel’s virtual address space. Through this object, it can get at the kernel’s address space, which most drivers do when they want to talk to hardware registers. Returning the provider’s IODeviceMemory object in the clientMemoryForType method is also how you publish (PCI) device RAM out to user space.

Make sure you retain the IODeviceMemory or any other IOMemoryDescriptor object in your implementation of clientMemoryForType so a reference to it can be returned to the caller.

If the user client creates an IOMemoryDescriptor object in its open method, it should release the object in its close method; if the user client creates an IOMemoryDescriptor object in its start method, it should release the object in its stop method. If the user client passes on an IODeviceMemory object created by its provider, it should not release it at all (the provider should release it appropriately). At the close of I/O, the device interface or application should call IOConnectUnmapMemory.

For example implementations of IOConnectMapMemory and clientMemoryForType, see Listing 4-18 and Listing 4-24, respectively.