Driver Personalities

Every device driver must declare one or more personalities that define the types of devices it can support. These personalities are in the form of XML dictionaries contained in the information property list (Info.plist file) in the driver’s kernel extension (KEXT) bundle.

Each entry in the matching dictionary is made up of a key-value pair in which the XML tags <key> and </key> enclose the key and the associated value is enclosed by XML tags that indicate its data type.

At minimum, all driver personalities contain the following two keys:

• The IOClass key declares the name of the class the I/O Kit instantiates when probing. For example,

  <key>IOClass</key>

  <string>IOATAPIProtocolTransport</string>

  tells the I/O Kit to instantiate the IOATAPIProtocolTransport driver when probing the device for this personality.

• The IOProviderClass key declares the name of the nub class a driver personality attaches to. For example,

  <key>IOProviderClass</key>

  <string>IOFireWireSBP2LUN</string>

  tells the I/O Kit that this driver personality attaches to an IOFireWireSBP2LUN nub.

  The provider class defines the family-specific matching keys used in the passive matching step, described in Driver Matching.

Most driver personalities also contain the IOProbeScore key, which declares the initial probe score for a personality. For example,

<key>IOProbeScore</key>

<integer>5000</integer>

declares a base probe score of 5000, which can be increased or decreased during the matching process, reflecting the driver’s suitability for the device.

Driver Matching

Driver matching occurs when a device is discovered. Each candidate driver has a probe score that reflects how well suited it is to drive the device. During the matching process, the family can increase the probe score with each property match. The driver with the highest probe score is given the first opportunity to drive the device.

The driver matching process consists of three phases:

1. In the class matching phase, the I/O Kit eliminates drivers of the wrong class. For example, the I/O Kit eliminates drivers that descend from a SCSI class when searching for a USB driver.

2. In the passive matching phase, the I/O Kit examines the personality of the driver for family-specific properties. In the SCSI Architecture Model family, the more matching properties found, the higher the driver’s probe score. For example, a driver that matches on both vendor name and product name has a higher probe score than a driver that matches only on vendor name. The Storage family, on the other hand, does not influence a driver’s probe score during matching.

   Often this step is sufficient to determine if a driver is suitable for a device. If there is no family-specific matching, however, the next step is automatically invoked.

3. In the active matching phase, the candidate driver is allowed to communicate with the device and verify that it can drive it. The I/O Kit loads the drivers remaining after the passive matching phase and each driver’s probe function is called with reference to the device it is being matched against. The probe method can examine the device in any way it chooses, as long as it leaves the device in the same state in which it was found.

   For example, a vendor may use certain bits of a property value to signify the presence of a particular device component. A logical unit driver for that device can implement a probe method that examines those bits to determine if the component is indeed present.

   Depending on the results of the probe, the driver increases or decreases its probe score to indicate its suitability to drive the device.

The I/O Kit chooses the driver with the highest probe score and starts it. If the driver starts successfully, any remaining driver candidates are discarded. If it is not successful, the driver with the next highest probe score is started and the process continues until a successful driver is found.

Driver Starting

When probing, a driver can perform a detailed examination of the device, including, if necessary, memory allocations, but it must leave the device in the same state in which it found it. If a driver starts successfully, it can reuse the memory it allocated in its probe method but if it is unsuccessful, it must be sure to deallocate the memory in its free method.

When a driver starts, it should call its superclass’s start method before doing anything else. If the superclass’s start method succeeds, the driver can then perform its initializations or allocations. Because a driver may not be able to perform initializations or allocations safely after it starts, it should perform such tasks in its start method. If the driver is unable to complete its tasks, it can notify the I/O Kit and the driver with the next highest probe score starts.

The FireWire SBP-2 Protocol Services Driver

As described in Construction of a Mass Storage Driver Stack, the protocol services driver for a FireWire SBP-2 mass storage device must match on the IOFireWireSBP2LUN nub published by the IOFireWireTarget object in the physical interconnect layer. The IOFireWireSBP2LUN object contains the following seven keys:

• Command_Set

• Command_Set_Spec_ID

• Vendor_ID

• Command_Set_Revision

• IOUnit

• Firmware_Revision

• Device_Type

The IOFireWireTarget object scans the device’s configuration ROM and fills in the values for these keys. If the device doesn’t declare one or more of these properties in its configuration ROM, the IOFireWireSPB2LUN publishes the corresponding key with a zero value.

To match on the IOFireWireSBP2LUN, the IOFireWireSerialBusProtocolTransport driver personality includes the keys shown in Listing 3-1.

Listing 3-1  The IOFireWireSerialBusProtocolTransport driver personality dictionary

<dict>

    <!-- CFBundleIdentifier denotes the name of the driver in

     -- reverse DNS notation. -->

    <key>CFBundleIdentifier</key>

    <string>com.apple.iokit.IOFireWireSerialBusProtocolTransport</string>

    <!-- Command_Set refers to the organization responsible

     -- for the definition of the command set. -->

    <key>Command_Set</key>

    <integer>66776</integer>

    <!-- Command_Set_Spec_ID specifies the commands

     -- understood by the device. -->

    <key>Command_Set_Spec_ID</key>

    <integer>24734</integer>

    <!-- The name of the class the I/O Kit instantiates

     -- when probing. -->

    <key>IOClass</key>

    <string>IOFireWireSerialBusProtocolTransport</string>

    <!-- The initial probe score for this personality. -->

    <key>IOProbeScore</key>

    <integer>4096</integer>

    <!-- The provider class is the name of the nub class this

     -- driver personality attaches to. -->

    <key>IOProviderClass</key>

    <string>IOFireWireSBP2LUN</string>

    <!-- The next two keys describe which

     -- bus the device is on and whether it is

     -- internal or external.-->

    <key>Physical Interconnect</key>

    <string>FireWire</string>

    <key>Physical Interconnect Location</key>

    <string>External</string>

</dict>

A subclass of the IOFireWireSerialBusProtocolTransport driver can use more of the seven keys in the IOFireWireSBP2LUN object to more narrowly define the device it is suited to drive. It can also examine the property values in its probe method to further determine its suitability. For example, a vendor can use some of the bits in a property value to declare the presence of a device component. A driver that needs to determine the presence of this component can examine those bits in its probe method. Listing 3-2 shows how this can be done for a subclass of the IOFireWireSerialBusProtocolTransport driver.

Listing 3-2  Example FireWire protocol services driver probe method

// This example probe method tests the Firmware_Revision value.

IOService *com_MySoftwareCompany_driver_MyFWProtocolLayerDriver::probe(

                IOService *provider, SInt32 *score )

{

    IOFireWireSBP2LUN *fwSBP2LUN = NULL;

    OSObject *firmwareObject;

    IOService *returnValue = 0;

    // Override probe method inherited from IOFireWireSBP2LUN.

    // Incorporate additional matching based on bits within

    // firmware revision data.

    // Allow superclass first chance at probe

    if ( !IOFireWireSerialBusProtocolTransport::probe( provider, score ) )

        goto ErrorExit;

    fwSBP2LUN = OSDynamicCast( IOFireWireSBP2LUN, provider );

    if ( fwSBP2LUN == NULL )

        goto ErrorExit;

    // Get key from registry that IOFireWireSBP2LUN published

    firmwareObject = provider->getProperty( "Firmware_Revision" );

    if ( firmwareObject )

    {

        OSNumber *firmwareNumberObject;

        UInt32 firmwareValue = 0;

        // Translate the Firmware_Revision property

        // into an OSNumber value for inspection.

        firmwareNumberObject = OSDynamicCast( OSNumber, firmwareObject );

        if ( firmwareNumberObject )

        {

            firmwareValue = firmwareNumberObject->unsigned32BitValue( );

        }

        // Check bits 8 through 23 of the Firmware_Revision value by

        // comparing them with the constants kMyConstant1 and

        // kMyConstant2.

        // These constants represent identification codes and

        // would be defined earlier in the driver's code.

        if ( ( ( ( firmwareValue >> 8 ) & 0x000FFF ) == kMyConstant1 )

        ||

         ( ( ( firmwareValue >> 8 ) & 0x000FFF ) == kMyConstant2 ) )

        {

            IOLog( "%s: Device component detected\n", getName( ) );

            returnValue = this;

        }

    }

ErrorExit:

    return returnValue;

}

The USB Mass Storage Class Protocol Services Driver

When a USB mass storage class device is discovered, the USB family abstracts the contents of the device descriptor into an I/O Kit nub object called IOUSBDevice. The device descriptor includes information such as the device’s class and subclass, vendor and product numbers, and the number of configurations.

Because USB mass storage class devices are defined as composite class devices, the AppleUSBComposite driver matches against the IOUSBDevice nub object and sets the first configuration in the device. This causes the USB family to abstract each interface descriptor in the configuration into an IOUSBInterface nub object. The IOUSBMassStorageClass driver then matches on the mass storage class-compliant interface nub objects.

The Apple-provided IOUSBMassStorageClass driver contains six personalities that correspond to the six mass storage subclasses. Each subclass represents the type of command block set the device’s interfaces use. If the device is compliant with the USB mass storage class specification, its interface descriptor contains its subclass and protocol in the bInterfaceSubClass and bInterfaceProtocol fields, respectively.

The subclass code in the bInterfaceSubClass field refers to one of the subclasses listed in Table 3-1. These codes denote industry-standard specifications that describe the command block definitions used by the interfaces of USB mass storage class devices. They do not refer to specific device types since most USB mass storage class devices can choose to comply with any command block specification.

The bInterfaceProtocol field in the interface descriptor denotes the transport protocol the interface uses. The IOUSBMassStorageClass driver supports the interface protocols shown in Table 3-2.

If the device is mass storage class compliant, one of the IOUSBMassStorageClass driver’s personalities matches on the device’s interface subclass. Listing 3-3 shows the first personality in the IOUSBMassStorageClass driver’s personality dictionary.

Listing 3-3  One of the IOUSBMassStorageClass driver’s personalities

<dict>

    <!-- CFBundleIdentifier denotes the name of the driver in

     -- reverse DNS notation. -->

    <key>CFBundleIdentifier</key>

    <string>com.apple.iokit.IOUSBMassStorageClass</string>

    <!-- IOUSBMassStorageClass is the name of the class the I/O Kit

     -- instantiates. -->

    <key>IOClass</key>

    <string>IOUSBMassStorageClass</string>

    <!-- IOUSBInterface is the name of the nub class this

     -- personality attaches to. -->

    <key>IOProviderClass</key>

    <string>IOUSBInterface</string>

    <!-- The next two keys describe which bus

     -- the device is on and whether it is internal

     -- or external.-->

    <key>Physical Interconnect</key>

    <string>USB</string>

    <key>Physical Interconnect Location</key>

    <string>External</string>

    <!-- The interface class this driver matches on.-->

    <key>bInterfaceClass</key>

    <integer>8</integer>

    <!-- Interface subclass 1 refers to the Reduced Block Commands

     -- subclass.-->

    <key>bInterfaceSubClass</key>

    <integer>1</integer>

<dict>

    <key>CFBundleIdentifier</key>

    <string>com.apple.iokit.IOUSBMassStorageClass</string>

    <!-- IOUSBMassStorageClass is the name of the class the

     -- I/O Kit instantiates when probing. -->

    <key>IOClass</key>

    <string>IOUSBMassStorageClass</string>

    <!-- IOUSBInterface is the name of the nub class

    < -- the driver attaches to. -->

    <key>IOProviderClass</key>

    <string>IOUSBInterface</string>

    <!-- The following two keys describe

     -- which bus the device is on and whether it

     -- is internal or external. -->

    <key>Physical Interconnect</key>

    <string>USB</string

    <key>Physical Interconnect Location</key>

    <string>External</string>

    <key>USB Mass Storage Characteristics</key>

    <dict>

        <!-- The bInterfaceProtocol value is Control/Bulk/Interrupt

         -- with command completion interrupt. -->

        <key>Preferred Protocol</key>

        <integer>1</integer>

        <!-- The bInterfaceSubclass value is SFF8070I. -->

        <key>Preferred Subclass</key>

        <integer>5</integer>

    </dict>

    <!-- The following four keys are used for interface

     -- matching. -->

    <key>bConfigurationValue</key>

    <integer>MyConfigurationValue</integer>

    <key>bInterfaceNumber</key>

    <integer>MyInterfaceNumber</integer>

    <key>idProduct</key>

    <integer>MyProductID</integer>

    <key>idVendor</key>

    <integer>MyVendorID</integer>

</dict>

The ATAPI Protocol Services Driver

When an ATAPI mass storage device is discovered, the ATAPI bus controller publishes an ATA device nub that is a concrete subclass of IOATADevice. The ATA family defines no family-specific matching so all matching is active. This means the driver probes the device to determine if it is suited to drive it.

In its start method during active matching, the IOATAPIProtocolTransport driver compares the properties in its personality to the device’s properties. In particular, if the device’s ATA device type is ATAPI, the driver loads for that device. Listing 3-5 shows the personality for the IOATAPIProtocolTransport driver.

Listing 3-5  The IOATAPIProtocolTransport driver personality dictionary

<dict>

    <!-- CFBundleIdentifier denotes the name of the driver in

     -- reverse DNS notation. -->

    <key>CFBundleIdentifier</key>

    <string>com.apple.iokit.IOATAPIProtocolTransport</string>

    <!-- IOATAPIProtocolTransport is the class the I/O Kit

     -- instantiates when probing. -->

    <key>IOClass</key>

    <string>IOATAPIProtocolTransport</string>

    <!-- IOATADevice is the nub this driver attaches to. -->

    <key>IOProviderClass</key>

    <string>IOATADevice</string>

    <!-- The next two keys describe which bus the

     -- device is on and whether it is internal

     -- or external.-->

    <key>Physical Interconnect</key>

    <string>ATAPI</string>

    <key>Physical Interconnect Location</key>

    <string>Internal<string>

    <!-- The value of this key is compared to the ATA device type

     -- of the device. -->

    <key>ata device type</key>

    <string>atapi</string>

</dict>

A subclass of the IOATAPIProtocolTransport driver should include the same keys shown in Listing 3-5 in its personality dictionary. If you need to address ATAPI-specific issues such as a device that needs to do a hard reset after a particular event, you need to develop a subclass of IOATAPIProtocolTransport that overrides the appropriate methods. To ensure that your subclass driver loads, you should implement the probe method and increase the probe score after determining that your driver can, in fact, drive the device.

In order to change a device’s DMA or UDMA modes, however, you can take advantage of a feature in the IOATAPIProtocolTransport driver that allows a subclass to override the mode the device reports. You enable this feature by creating a KEXT that consists of an Info.plist file containing a dictionary named “ATAPI Mass Storage Characteristics” in addition to the keys shown in Listing 3-5. This dictionary contains the device model name and the DMA and UDMA mode values you choose. The device model name is the string the device returns when it responds to the ATA Identify command. The DMA and UDMA mode values are bitmasks defined in the ATA/ATAPI-5 specification (available at http://www.t13.org). Listing 3-6 shows an example personality dictionary that overrides the DMA and UDMA values returned by the device.

Listing 3-6  A personality dictionary that overrides DMA and UDMA values

<dict>

    <key>ATAPI Mass Storage Characteristics</key>

    <dict>

        <key>DMA Mode</key>

        <integer>0</integer>

        <key>UDMA Mode</key>

        <integer>0</integer>

        <key>device model</key>

        <string>MyDeviceModel</string>

    </dict>

    <key>CFBundleIdentifier</key>

    <string>com.apple.iokit.IOATAPIProtocolTransport</string>

    <key>IOClass</key>

    <string>IOATAPIProtocolTransport</string>

    <key>IOProbeScore</key>

    <integer>5000</integer>

    <key>IOProviderClass</key>

    <string>IOATADevice</string>

    <key>Physical Interconnect</key>

    <string>ATAPI</string>

    <key>Physical Interconnect Location</key>

    <string>Internal</string>

    <key>ata device type</key>

    <string>atapi</string>

</dict>

In this example, when this device is discovered, the I/O Kit allows all KEXTs with the key-value pair

<key>ata device type</key>

<string>atapi</string>

to probe the device. If a KEXT’s personality contains the ATAPI Mass Storage Characteristics dictionary, the I/O Kit compares the value of the device model string with the device model name reported by the device. If they match, the I/O Kit loads the IOATAPIProtocolTransport driver and applies the DMA and UDMA overrides declared in the ATAPI Mass Storage Characteristics dictionary.