USB.h

Includes:

Overview

Public Interfaces to the USB implementation in Mac OS X.

Discussion

This header file contains definitions and structures that are used in the different USB API's in Mac OS X, both in the kernel and in the user space.

Typedefs

IOUSBCompletion
IOUSBCompletionAction
IOUSBCompletionActionWithTimeStamp
IOUSBCompletionWithTimeStamp
IOUSBConfigurationDescHeader
IOUSBConfigurationDescriptor
IOUSBDescriptorHeader
IOUSBDeviceDescriptor
IOUSBDeviceQualifierDescriptor
IOUSBDevRequest
IOUSBDevRequestDesc
IOUSBDevRequestTO
IOUSBDFUDescriptor
IOUSBEndpointDescriptor
IOUSBFindEndpointRequest
IOUSBFindInterfaceRequest
IOUSBGetFrameStruct
IOUSBHIDDescriptor
IOUSBHIDReportDesc
IOUSBInterfaceAssociationDescriptor
IOUSBInterfaceDescriptor
IOUSBIsocCompletion
IOUSBIsocCompletionAction
IOUSBIsocFrame
IOUSBLowLatencyIsocCompletion
IOUSBLowLatencyIsocCompletionAction
IOUSBLowLatencyIsocFrame
USBDeviceInformationBits
USBLowLatencyBufferType
USBPowerRequestTypes
USBReEnumerateOptions
USBStatus

IOUSBCompletion


typedef struct IOUSBCompletion { 
    void *target; 
    IOUSBCompletionAction action; 
    void *parameter; 
} IOUSBCompletion;

Fields

target: The target to pass to the action function.
action: The function to call.
parameter: The parameter to pass to the action function.

Discussion

Struct specifying action to perform when a USB I/O completes.

IOUSBCompletionAction


typedef void ( *IOUSBCompletionAction)( 
    void *target, 
    void *parameter, 
    IOReturn status, 
    UInt32 bufferSizeRemaining);

Fields

target: The target specified in the IOUSBCompletion struct.
parameter: The parameter specified in the IOUSBCompletion struct.
status: Completion status.
bufferSizeRemaining: Bytes left to be transferred.

Discussion

Function called when USB I/O completes.

IOUSBCompletionActionWithTimeStamp


typedef void ( *IOUSBCompletionActionWithTimeStamp)( 
    void *target, 
    void *parameter, 
    IOReturn status, 
    UInt32 bufferSizeRemaining, 
    AbsoluteTime timeStamp);

Fields

target: The target specified in the IOUSBCompletion struct.
parameter: The parameter specified in the IOUSBCompletion struct.
status: Completion status.
bufferSizeRemaining: Bytes left to be transferred.
timeStamp: Time at which the transaction was processed.

Discussion

Function called when USB I/O completes.

IOUSBCompletionWithTimeStamp


typedef struct IOUSBCompletionWithTimeStamp { 
    void *target; 
    IOUSBCompletionActionWithTimeStamp action; 
    void *parameter; 
} IOUSBCompletionWithTimeStamp;

Fields

target: The target to pass to the action function.
action: The function to call.
parameter: The parameter to pass to the action function.

Discussion

Struct specifying action to perform when a USB I/O completes.

IOUSBConfigurationDescHeader


typedef struct IOUSBConfigurationDescHeader IOUSBConfigurationDescHeader;

Discussion

Header of a IOUSBConfigurationDescriptor. Used to get the total length of the descriptor.

See Also

IOUSBConfigurationDescHeader

IOUSBConfigurationDescriptor


typedef struct IOUSBConfigurationDescriptor IOUSBConfigurationDescriptor;

Discussion

Standard USB Configuration Descriptor. It is variable length, so this only specifies the known fields. We use the wTotalLength field to read the whole descriptor. See the USB Specification at http://www.usb.org.

See Also

IOUSBConfigurationDescriptor

IOUSBDescriptorHeader


typedef struct IOUSBDescriptorHeader IOUSBDescriptorHeader;

Discussion

Standard header used for all USB descriptors. Used to read the length of a descriptor so that we can allocate storage for the whole descriptor later on.

See Also

IOUSBDescriptorHeader

IOUSBDeviceDescriptor


typedef struct IOUSBDeviceDescriptor IOUSBDeviceDescriptor;

Discussion

Descriptor for a USB Device. See the USB Specification at http://www.usb.org.

See Also

IOUSBDeviceDescriptor

IOUSBDeviceQualifierDescriptor


typedef struct IOUSBDeviceQualifierDescriptor IOUSBDeviceQualifierDescriptor;

Discussion

USB Device Qualifier Descriptor. See the USB Specification at http://www.usb.org.

See Also

IOUSBDeviceQualifierDescriptor

IOUSBDevRequest


typedef struct { 
    UInt8 bmRequestType; 
    UInt8 bRequest; 
    UInt16 wValue; 
    UInt16 wIndex; 
    UInt16 wLength; 
    void *pData; 
    UInt32 wLenDone; 
} IOUSBDevRequest;

Fields

rdDirection: Direction of data part of request: kUSBIn or kUSBOut
rqType: Request type: kUSBStandard, kUSBClass or kUSBVendor
rqRecipient: Target of the request: kUSBDevice, kUSBInterface, kUSBEndpoint or kUSBOther
bRequest: Request code
wValue: 16 bit parameter for request, host endianess
wIndex: 16 bit parameter for request, host endianess
wLength: Length of data part of request, 16 bits, host endianess
pData: Pointer to data for request - data returned in bus endianess
wLenDone: Set by standard completion routine to number of data bytes actually transferred

Discussion

Parameter block for control requests, using a simple pointer for the data to be transferred.

IOUSBDevRequestDesc


typedef struct { 
    UInt8 bmRequestType; 
    UInt8 bRequest; 
    UInt16 wValue; 
    UInt16 wIndex; 
    UInt16 wLength; 
    IOMemoryDescriptor *pData; 
    UInt32 wLenDone; 
} IOUSBDevRequestDesc;

Fields

rdDirection: Direction of data part of request: kUSBIn or kUSBOut
rqType: Request type: kUSBStandard, kUSBClass or kUSBVendor
rqRecipient: Target of the request: kUSBDevice, kUSBInterface, kUSBEndpoint or kUSBOther
bRequest: Request code
wValue: 16 bit parameter for request, host endianess
wIndex: 16 bit parameter for request, host endianess
wLength: Length of data part of request, 16 bits, host endianess
pData: Pointer to memory descriptor for data for request - data returned in bus endianess
wLenDone: Set by standard completion routine to number of data bytes actually transferred

Discussion

Parameter block for control requests, using a memory descriptor for the data to be transferred. Only available in the kernel.

IOUSBDevRequestTO


typedef struct { 
    UInt8 bmRequestType; 
    UInt8 bRequest; 
    UInt16 wValue; 
    UInt16 wIndex; 
    UInt16 wLength; 
    void *pData; 
    UInt32 wLenDone; 
    UInt32 noDataTimeout; 
    UInt32 completionTimeout; 
} IOUSBDevRequestTO;

Fields

rdDirection: Direction of data part of request: kUSBIn or kUSBOut
rqType: Request type: kUSBStandard, kUSBClass or kUSBVendor
rqRecipient: Target of the request: kUSBDevice, kUSBInterface, kUSBEndpoint or kUSBOther
bRequest: Request code
wValue: 16 bit parameter for request, host endianess
wIndex: 16 bit parameter for request, host endianess
wLength: Length of data part of request, 16 bits, host endianess
pData: Pointer to data for request - data returned in bus endianess
wLenDone: Set by standard completion routine to number of data bytes actually transferred
noDataTimeout: Specifies a time value in milliseconds. Once the request is queued on the bus, if no data is transferred in this amount of time, the request will be aborted and returned.
completionTimeout: Specifies a time value in milliseconds. Once the request is queued on the bus, if the entire request is not completed in this amount of time, the request will be aborted and returned

Discussion

Parameter block for control requests with timeouts, using a simple pointer for the data to be transferred. Same as a IOUSBDevRequest except for the two extra timeout fields.

IOUSBDFUDescriptor


typedef struct IOUSBDFUDescriptor IOUSBDFUDescriptor;

Discussion

USB Device Firmware Update Descriptor. See the USB Device Firmware Update Specification at http://www.usb.org.

See Also

IOUSBDFUDescriptor

IOUSBEndpointDescriptor


typedef struct IOUSBEndpointDescriptor IOUSBEndpointDescriptor;

Discussion

Descriptor for a USB Endpoint. See the USB Specification at http://www.usb.org.

See Also

IOUSBEndpointDescriptor

IOUSBFindEndpointRequest


typedef struct { 
    UInt8 type; 
    UInt8 direction; 
    UInt16 maxPacketSize; 
    UInt8 interval; 
} IOUSBFindEndpointRequest;

Fields

type: Type of endpoint: kUSBControl, kUSBIsoc, kUSBBulk, kUSBInterrupt, kUSBAnyType. If kUSBAnyType is specified, this field is treated as a don't care.
direction: Direction of endpoint: kUSBOut, kUSBIn, kUSBAnyDirn. If kUSBAnyDirn is specified, this field is treated as a don't care.
maxPacketSize: maximum packet size of endpoint.
interval: Polling interval in mSec for endpoint.

Discussion

Struct used to find endpoints of an interface type and direction are used to match endpoints, type, direction, maxPacketSize and interval are updated with the properties of the found endpoint.

IOUSBFindInterfaceRequest


typedef struct { 
    UInt16 bInterfaceClass; // requested class 
    UInt16 bInterfaceSubClass; // requested subclass 
    UInt16 bInterfaceProtocol; // requested protocol 
    UInt16 bAlternateSetting; // requested alt setting 
} IOUSBFindInterfaceRequest;

Discussion

Structure used with FindNextInterface.

IOUSBGetFrameStruct


typedef struct { 
    UInt64 frame; 
    AbsoluteTime timeStamp; 
} IOUSBGetFrameStruct;

Fields

frame: frame number
timeStamp: AbsoluteTime when the frame was updated

Discussion

Structure used from user space to return the frame number and a timestamp on when the frame register was read.

IOUSBHIDDescriptor


typedef struct IOUSBHIDDescriptor IOUSBHIDDescriptor;

Discussion

USB HID Descriptor. See the USB HID Specification at http://www.usb.org. (This structure should have used the #pragma pack(1) compiler directive to get byte alignment.

See Also

IOUSBHIDDescriptor

IOUSBHIDReportDesc


typedef struct IOUSBHIDReportDesc IOUSBHIDReportDesc;

Discussion

USB HID Report Descriptor header. See the USB HID Specification at http://www.usb.org. (This structure should have used the #pragma pack(1) compiler directive to get byte alignment.

See Also

IOUSBHIDReportDesc

IOUSBInterfaceAssociationDescriptor


typedef struct IOUSBInterfaceAssociationDescriptor IOUSBInterfaceAssociationDescriptor;

Discussion

USB Inerface Association Descriptor. ECN to the USB 2.0 Spec. See the USB Specification at http://www.usb.org.

See Also

IOUSBInterfaceAssociationDescriptor

IOUSBInterfaceDescriptor


typedef struct IOUSBInterfaceDescriptor IOUSBInterfaceDescriptor;

Discussion

Descriptor for a USB Interface. See the USB Specification at http://www.usb.org.

See Also

IOUSBInterfaceDescriptor

IOUSBIsocCompletion


typedef struct IOUSBIsocCompletion { 
    void *target; 
    IOUSBIsocCompletionAction action; 
    void *parameter; 
} IOUSBIsocCompletion;

Fields

target: The target to pass to the action function.
action: The function to call.
parameter: The parameter to pass to the action function.

Discussion

Struct specifying action to perform when an Isochronous USB I/O completes.

IOUSBIsocCompletionAction


typedef void ( *IOUSBIsocCompletionAction)( 
    void *target, 
    void *parameter, 
    IOReturn status, 
    IOUSBIsocFrame *pFrames);

Fields

target: The target specified in the IOUSBIsocCompletionn struct.
parameter: The parameter specified in the IOUSBIsocCompletion struct.
status: Completion status.
pFrames: Pointer to the frame list containing the status for each frame transferred.

Discussion

Function called when Isochronous USB I/O completes.

IOUSBIsocFrame


typedef struct IOUSBIsocFrame { 
    IOReturn frStatus; 
    UInt16 frReqCount; 
    UInt16 frActCount; 
} IOUSBIsocFrame;

Fields

frStatus: Returns status associated with the frame.
frReqCount: Input specifiying how many bytes to read or write.
frActCount: Actual # of bytes transferred.

Discussion

Structure used to encode information about each isoc frame.

IOUSBLowLatencyIsocCompletion


typedef struct IOUSBLowLatencyIsocCompletion { 
    void *target; 
    IOUSBLowLatencyIsocCompletionAction action; 
    void *parameter; 
} IOUSBLowLatencyIsocCompletion;

Fields

target: The target to pass to the action function.
action: The function to call.
parameter: The parameter to pass to the action function.

Discussion

Struct specifying action to perform when an Low Latency Isochronous USB I/O completes.

IOUSBLowLatencyIsocCompletionAction


typedef void ( *IOUSBLowLatencyIsocCompletionAction)( 
    void *target, 
    void *parameter, 
    IOReturn status, 
    IOUSBLowLatencyIsocFrame *pFrames);

Fields

target: The target specified in the IOUSBLowLatencyIsocCompletion struct.
parameter: The parameter specified in the IOUSBLowLatencyIsocCompletion struct.
status: Completion status.
pFrames: Pointer to the low latency frame list containing the status for each frame transferred.

Discussion

Function called when Low Latency Isochronous USB I/O completes.

IOUSBLowLatencyIsocFrame


typedef struct IOUSBLowLatencyIsocFrame IOUSBLowLatencyIsocFrame;

Fields

frStatus: Returns status associated with the frame.
frReqCount: Input specifiying how many bytes to read or write.
frActCount: Actual # of bytes transferred.
frTimeStamp: Time stamp that indicates time when frame was procesed.

Discussion

Structure used to encode information about each isoc frame that is processed at hardware interrupt time (low latency).

See Also

IOUSBLowLatencyIsocFrame

USBDeviceInformationBits


typedef enum { 
    kUSBInformationDeviceIsCaptiveBit = 0, 
    kUSBInformationDeviceIsAttachedToRootHubBit = 1, 
    kUSBInformationDeviceIsInternalBit = 2, 
    kUSBInformationDeviceIsConnectedBit = 3, 
    kUSBInformationDeviceIsEnabledBit = 4, 
    kUSBInformationDeviceIsSuspendedBit = 5, 
    kUSBInformationDeviceIsInResetBit = 6, 
    kUSBInformationDeviceOvercurrentBit = 7, 
    kUSBInformationDevicePortIsInTestModeBit = 8, 
    kUSBInformationDeviceIsRootHub = 9, 
    kUSBInformationRootHubisBuiltIn = 10, 
    kUSBInformationDeviceIsCaptiveMask = (
        1 << kUSBInformationDeviceIsCaptiveBit), 
    kUSBInformationDeviceIsAttachedToRootHubMask = (
        1 << kUSBInformationDeviceIsAttachedToRootHubBit), 
    kUSBInformationDeviceIsInternalMask = (
        1 << kUSBInformationDeviceIsInternalBit), 
    kUSBInformationDeviceIsConnectedMask = (
        1 << kUSBInformationDeviceIsConnectedBit), 
    kUSBInformationDeviceIsEnabledMask = (
        1 << kUSBInformationDeviceIsEnabledBit), 
    kUSBInformationDeviceIsSuspendedMask = (
        1 << kUSBInformationDeviceIsSuspendedBit), 
    kUSBInformationDeviceIsInResetMask = (
        1 << kUSBInformationDeviceIsInResetBit), 
    kUSBInformationDeviceOvercurrentMask = (
        1 << kUSBInformationDeviceOvercurrentBit), 
    kUSBInformationDevicePortIsInTestModeMask = (
        1 << kUSBInformationDevicePortIsInTestModeBit), 
    kUSBInformationDeviceIsRootHubMask = (
        1 << kUSBInformationDeviceIsRootHub), 
    kUSBInformationRootHubisBuiltInMask = (
        1 << kUSBInformationRootHubisBuiltIn) 
} USBDeviceInformationBits;

Constants

kUSBInformationDeviceIsCaptiveBit: The USB device is directly attached to its hub and cannot be removed.
kUSBInformationDeviceIsAttachedToRootHubBit: The USB device is directly attached to the root hub
kUSBInformationDeviceIsInternalBit: The USB device is internal to the computer (all the hubs it attaches to are captive)
kUSBInformationDeviceIsConnectedBit: The USB device is connected to its hub
kUSBInformationDeviceIsEnabledBit: The hub port to which the USB device is attached is enabled
kUSBInformationDeviceIsSuspendedBit: The hub port to which the USB device is attached is suspended
kUSBInformationDeviceIsInResetBit: The hub port to which the USB device is attached is being reset
kUSBInformationDeviceOvercurrentBit: The USB device generated an overcurrent
kUSBInformationDevicePortIsInTestModeBit: The hub port to which the USB device is attached is in test mode
kUSBInformationDeviceIsRootHub: The device is actually the root hub simulation
kUSBInformationRootHubisBuiltIn: If this is a root hub simulation and it's built into the machine, this bit is set. If it's on an expansion card, it will be cleared

Discussion

GetUSBDeviceInformation will return a unit32_t value with bits set indicating that a particular state is present in the USB device. These bits are described here

USBLowLatencyBufferType


typedef enum { 
    kUSBLowLatencyWriteBuffer = 0, 
    kUSBLowLatencyReadBuffer = 1, 
    kUSBLowLatencyFrameListBuffer = 2 
} USBLowLatencyBufferType;

Constants

kUSBLowLatencyWriteBuffer: The buffer will be used to write data out to a device.
kUSBLowLatencyReadBuffer: The buffer will be used to read data from a device.
kUSBLowLatencyFrameListBuffer: The buffer will be used for a low latency isoch frame list.

Discussion

Used to specify what kind of buffer to create when calling LowLatencyCreateBuffer().

USBPowerRequestTypes


typedef enum { 
    kUSBPowerDuringSleep = 0, 
    kUSBPowerDuringWake = 1 
} USBPowerRequestTypes;

Constants

kUSBPowerDuringSleep: The power is to be used during sleep.
kUSBPowerDuringWake: The power is to be used while the system is awake (i.e not sleeping)

Discussion

Used to specify what kind of power will be reserved using the IOUSBDevice RequestExtraPower and ReturnExtraPower APIs.

USBReEnumerateOptions


typedef enum { 
    kUSBAddExtraResetTimeBit = 31, 
    kUSBAddExtraResetTimeMask = (
        1 << kUSBAddExtraResetTimeBit) 
} USBReEnumerateOptions;

Constants

kUSBAddExtraResetTimeBit: Setting this bit will cause the Hub driver to wait 100ms before addressing the device after the reset following the re-enumeration.

Discussion

Options used when calling ReEnumerateDevice.

USBStatus


typedef UInt16 USBStatus;

Discussion

Type used to get a DeviceStatus as a single quantity.

Structs and Unions

IOUSBConfigurationDescHeader
IOUSBConfigurationDescriptor
IOUSBDescriptorHeader
IOUSBDeviceDescriptor
IOUSBDeviceQualifierDescriptor
IOUSBDFUDescriptor
IOUSBEndpointDescriptor
IOUSBHIDDescriptor
IOUSBHIDReportDesc
IOUSBInterfaceAssociationDescriptor
IOUSBInterfaceDescriptor
IOUSBLowLatencyIsocFrame

IOUSBConfigurationDescHeader


struct IOUSBConfigurationDescHeader { 
    UInt8 bLength; 
    UInt8 bDescriptorType; 
    UInt16 wTotalLength; 
};

Discussion

Header of a IOUSBConfigurationDescriptor. Used to get the total length of the descriptor.

See Also

IOUSBConfigurationDescHeader

IOUSBConfigurationDescriptor


struct IOUSBConfigurationDescriptor { 
    UInt8 bLength; 
    UInt8 bDescriptorType; 
    UInt16 wTotalLength; 
    UInt8 bNumInterfaces; 
    UInt8 bConfigurationValue; 
    UInt8 iConfiguration; 
    UInt8 bmAttributes; 
    UInt8 MaxPower; 
};

Discussion

See Also

IOUSBConfigurationDescriptor

IOUSBDescriptorHeader


struct IOUSBDescriptorHeader { 
    UInt8 bLength; 
    UInt8 bDescriptorType; 
};

Discussion

Standard header used for all USB descriptors. Used to read the length of a descriptor so that we can allocate storage for the whole descriptor later on.

See Also

IOUSBDescriptorHeader

IOUSBDeviceDescriptor


struct IOUSBDeviceDescriptor { 
    UInt8 bLength; 
    UInt8 bDescriptorType; 
    UInt16 bcdUSB; 
    UInt8 bDeviceClass; 
    UInt8 bDeviceSubClass; 
    UInt8 bDeviceProtocol; 
    UInt8 bMaxPacketSize0; 
    UInt16 idVendor; 
    UInt16 idProduct; 
    UInt16 bcdDevice; 
    UInt8 iManufacturer; 
    UInt8 iProduct; 
    UInt8 iSerialNumber; 
    UInt8 bNumConfigurations; 
};

Discussion

Descriptor for a USB Device. See the USB Specification at http://www.usb.org.

See Also

IOUSBDeviceDescriptor

IOUSBDeviceQualifierDescriptor


struct IOUSBDeviceQualifierDescriptor { 
    UInt8 bLength; 
    UInt8 bDescriptorType; 
    UInt16 bcdUSB; 
    UInt8 bDeviceClass; 
    UInt8 bDeviceSubClass; 
    UInt8 bDeviceProtocol; 
    UInt8 bMaxPacketSize0; 
    UInt8 bNumConfigurations; 
    UInt8 bReserved; 
};

Discussion

USB Device Qualifier Descriptor. See the USB Specification at http://www.usb.org.

See Also

IOUSBDeviceQualifierDescriptor

IOUSBDFUDescriptor


struct IOUSBDFUDescriptor { 
    UInt8 bLength; 
    UInt8 bDescriptorType; 
    UInt8 bmAttributes; 
    UInt16 wDetachTimeout; 
    UInt16 wTransferSize; 
};

Discussion

USB Device Firmware Update Descriptor. See the USB Device Firmware Update Specification at http://www.usb.org.

See Also

IOUSBDFUDescriptor

IOUSBEndpointDescriptor


struct IOUSBEndpointDescriptor { 
    UInt8 bLength; 
    UInt8 bDescriptorType; 
    UInt8 bEndpointAddress; 
    UInt8 bmAttributes; 
    UInt16 wMaxPacketSize; 
    UInt8 bInterval; 
};

Discussion

Descriptor for a USB Endpoint. See the USB Specification at http://www.usb.org.

See Also

IOUSBEndpointDescriptor

IOUSBHIDDescriptor


struct IOUSBHIDDescriptor { 
    UInt8 descLen; 
    UInt8 descType; 
    UInt16 descVersNum; 
    UInt8 hidCountryCode; 
    UInt8 hidNumDescriptors; 
    UInt8 hidDescriptorType; 
    UInt8 hidDescriptorLengthLo; 
    UInt8 hidDescriptorLengthHi; 
};

Discussion

USB HID Descriptor. See the USB HID Specification at http://www.usb.org. (This structure should have used the #pragma pack(1) compiler directive to get byte alignment.

See Also

IOUSBHIDDescriptor

IOUSBHIDReportDesc


struct IOUSBHIDReportDesc { 
    UInt8 hidDescriptorType; 
    UInt8 hidDescriptorLengthLo; 
    UInt8 hidDescriptorLengthHi; 
};

Discussion

USB HID Report Descriptor header. See the USB HID Specification at http://www.usb.org. (This structure should have used the #pragma pack(1) compiler directive to get byte alignment.

See Also

IOUSBHIDReportDesc

IOUSBInterfaceAssociationDescriptor


struct IOUSBInterfaceAssociationDescriptor { 
    UInt8 bLength; 
    UInt8 bDescriptorType; 
    UInt8 bFirstInterface; 
    UInt8 bInterfaceCount; 
    UInt8 bFunctionClass; 
    UInt8 bFunctionSubClass; 
    UInt8 bFunctionProtocol; 
    UInt8 iFunction; 
};

Discussion

USB Inerface Association Descriptor. ECN to the USB 2.0 Spec. See the USB Specification at http://www.usb.org.

See Also

IOUSBInterfaceAssociationDescriptor

IOUSBInterfaceDescriptor


struct IOUSBInterfaceDescriptor { 
    UInt8 bLength; 
    UInt8 bDescriptorType; 
    UInt8 bInterfaceNumber; 
    UInt8 bAlternateSetting; 
    UInt8 bNumEndpoints; 
    UInt8 bInterfaceClass; 
    UInt8 bInterfaceSubClass; 
    UInt8 bInterfaceProtocol; 
    UInt8 iInterface; 
};

Discussion

Descriptor for a USB Interface. See the USB Specification at http://www.usb.org.

See Also

IOUSBInterfaceDescriptor

IOUSBLowLatencyIsocFrame


struct IOUSBLowLatencyIsocFrame { 
    IOReturn frStatus; 
    UInt16 frReqCount; 
    UInt16 frActCount; 
    AbsoluteTime frTimeStamp; 
};

Fields

frStatus: Returns status associated with the frame.
frReqCount: Input specifiying how many bytes to read or write.
frActCount: Actual # of bytes transferred.
frTimeStamp: Time stamp that indicates time when frame was procesed.

Discussion

Structure used to encode information about each isoc frame that is processed at hardware interrupt time (low latency).

See Also

IOUSBLowLatencyIsocFrame

Enumerated Types

bRequest Shifts and Masks
Default timeout values
IOOptionBits
kIOUSBFindInterfaceDontCare
kIOUSBFindInterfaceDontCare
kUSBMaxIsocFrameReqCount
MicrosecondsInFrame
Miscellaneous Constants
Standard Device Requests
USBDeviceSpeed

bRequest Shifts and Masks


enum { 
    kUSBRqDirnShift = 7, 
    kUSBRqDirnMask = 1,  
    kUSBRqTypeShift = 5, 
    kUSBRqTypeMask = 3,  
    kUSBRqRecipientMask = 0X1F 
};

Discussion

These are used to create the macro to encode the bRequest filed of a Device Request

Default timeout values


enum { 
    kUSBDefaultControlNoDataTimeoutMS = 5000, 
    kUSBDefaultControlCompletionTimeoutMS = 0 
};

Discussion

default values used for data and completion timeouts.

IOOptionBits


enum { 
    kIOUSBInterfaceOpenAlt = 0x00010000 
};

Constants

kIOUSBInterfaceOpenAlt: Open the alternate interface specified when creating the interface.

Discussion

Parameter passed to an IOService::open() call.

kIOUSBFindInterfaceDontCare


enum { 
    kIOUSBFindInterfaceDontCare = 0xFFFF 
};

Discussion

Constant that can be used for the fields of IOUSBFindInterfaceRequest to specify that they should not be matched.

kIOUSBFindInterfaceDontCare


enum { 
    kIOUSBVendorIDAppleComputer = 0x05AC 
};

Discussion

USB Vendor ID for Apple Computer, Inc.

kUSBMaxIsocFrameReqCount


enum { 
    kUSBMaxFSIsocEndpointReqCount = 1023, // max size (bytes) of any one Isoc frame for 1 FS endpoint 
    kUSBMaxHSIsocEndpointReqCount = 3072, // max size (bytes) of any one Isoc frame for 1 HS endpoint 
    kUSBMaxHSIsocFrameCount = 7168 // max size (bytes) of all Isoc transfers in a HS frame 
};

Discussion

Maximum size in bytes allowed for one Isochronous frame

MicrosecondsInFrame


enum { 
    kUSBFullSpeedMicrosecondsInFrame = 1000, 
    kUSBHighSpeedMicrosecondsInFrame = 125 
};

Constants

kUSBFullSpeedMicrosecondsInFrame: The device is attached to a bus running at full speed (1 ms / frame).
kUSBHighSpeedMicrosecondsInFrame: The device is attached to a bus running at high speed (125 microseconds / frame).

Discussion

Returns the number of microseconds in a USB frame.

Miscellaneous Constants


enum { 
    kUSBDeviceIDShift = 7, 
    kUSBMaxDevices = 128, 
    kUSBMaxDevice = kUSBMaxDevices-1, 
    kUSBDeviceIDMask = 0x7f,  
    kUSBPipeIDMask = 0xf, 
    kUSBMaxPipes = 32, // In and Out pipes can have same pipe number.  
    kUSBInterfaceIDShift = 8, 
    kUSBMaxInterfaces = 1 << kUSBInterfaceIDShift, 
    kUSBInterfaceIDMask = kUSBMaxInterfaces-1,  
    kUSBEndPtShift = 7, 
    kUSBDeviceMask = (
        (
            1 << kUSBEndPtShift) -1),  
    kUSBNoPipeIdx = -1 
};

Standard Device Requests


enum { 
    kClearDeviceFeature =  (
        (
            (
                UInt16)kUSBRqClearFeature << 8) +  (
            (
                UInt16) kUSBDevice +  (
                (
                    UInt16) kUSBStandard << kUSBRqTypeShift) +  (
                (
                    UInt16) kUSBOut << kUSBRqDirnShift))), 
    kClearInterfaceFeature =  (
        (
            (
                UInt16)kUSBRqClearFeature << 8) +  (
            (
                UInt16) kUSBInterface +  (
                (
                    UInt16) kUSBStandard << kUSBRqTypeShift) +  (
                (
                    UInt16) kUSBOut << kUSBRqDirnShift))), 
    kClearEndpointFeature =  (
        (
            (
                UInt16)kUSBRqClearFeature << 8) +  (
            (
                UInt16) kUSBEndpoint +  (
                (
                    UInt16) kUSBStandard << kUSBRqTypeShift) +  (
                (
                    UInt16) kUSBOut << kUSBRqDirnShift))), 
    kGetConfiguration =  (
        (
            (
                UInt16)kUSBRqGetConfig << 8) +  (
            (
                UInt16) kUSBDevice +  (
                (
                    UInt16) kUSBStandard << kUSBRqTypeShift) +  (
                (
                    UInt16) kUSBIn << kUSBRqDirnShift))), 
    kGetDescriptor =  (
        (
            (
                UInt16)kUSBRqGetDescriptor << 8) +  (
            (
                UInt16) kUSBDevice +  (
                (
                    UInt16) kUSBStandard << kUSBRqTypeShift) +  (
                (
                    UInt16) kUSBIn << kUSBRqDirnShift))), 
    kGetInterface =  (
        (
            (
                UInt16)kUSBRqGetInterface << 8) +  (
            (
                UInt16) kUSBInterface +  (
                (
                    UInt16) kUSBStandard << kUSBRqTypeShift) +  (
                (
                    UInt16) kUSBIn << kUSBRqDirnShift))), 
    kGetDeviceStatus =  (
        (
            (
                UInt16)kUSBRqGetStatus << 8) +  (
            (
                UInt16) kUSBDevice +  (
                (
                    UInt16) kUSBStandard << kUSBRqTypeShift) +  (
                (
                    UInt16) kUSBIn << kUSBRqDirnShift))), 
    kGetInterfaceStatus =  (
        (
            (
                UInt16)kUSBRqGetStatus << 8) +  (
            (
                UInt16) kUSBInterface +  (
                (
                    UInt16) kUSBStandard << kUSBRqTypeShift) +  (
                (
                    UInt16) kUSBIn << kUSBRqDirnShift))), 
    kGetEndpointStatus =  (
        (
            (
                UInt16)kUSBRqGetStatus << 8) +  (
            (
                UInt16) kUSBEndpoint +  (
                (
                    UInt16) kUSBStandard << kUSBRqTypeShift) +  (
                (
                    UInt16) kUSBIn << kUSBRqDirnShift))), 
    kSetAddress =  (
        (
            (
                UInt16)kUSBRqSetAddress << 8) +  (
            (
                UInt16) kUSBDevice +  (
                (
                    UInt16) kUSBStandard << kUSBRqTypeShift) +  (
                (
                    UInt16) kUSBOut << kUSBRqDirnShift))), 
    kSetConfiguration =  (
        (
            (
                UInt16)kUSBRqSetConfig << 8) +  (
            (
                UInt16) kUSBDevice +  (
                (
                    UInt16) kUSBStandard << kUSBRqTypeShift) +  (
                (
                    UInt16) kUSBOut << kUSBRqDirnShift))), 
    kSetDescriptor =  (
        (
            (
                UInt16)kUSBRqSetDescriptor << 8) +  (
            (
                UInt16) kUSBDevice +  (
                (
                    UInt16) kUSBStandard << kUSBRqTypeShift) +  (
                (
                    UInt16) kUSBOut << kUSBRqDirnShift))), 
    kSetDeviceFeature =  (
        (
            (
                UInt16)kUSBRqSetFeature << 8) +  (
            (
                UInt16) kUSBDevice +  (
                (
                    UInt16) kUSBStandard << kUSBRqTypeShift) +  (
                (
                    UInt16) kUSBOut << kUSBRqDirnShift))), 
    kSetInterfaceFeature =  (
        (
            (
                UInt16)kUSBRqSetFeature << 8) +  (
            (
                UInt16) kUSBInterface +  (
                (
                    UInt16) kUSBStandard << kUSBRqTypeShift) +  (
                (
                    UInt16) kUSBOut << kUSBRqDirnShift))), 
    kSetEndpointFeature =  (
        (
            (
                UInt16)kUSBRqSetFeature << 8) +  (
            (
                UInt16) kUSBEndpoint +  (
                (
                    UInt16) kUSBStandard << kUSBRqTypeShift) +  (
                (
                    UInt16) kUSBOut << kUSBRqDirnShift))), 
    kSetInterface =  (
        (
            (
                UInt16)kUSBRqSetInterface << 8) +  (
            (
                UInt16) kUSBInterface +  (
                (
                    UInt16) kUSBStandard << kUSBRqTypeShift) +  (
                (
                    UInt16) kUSBOut << kUSBRqDirnShift))), 
    kSyncFrame =  (
        (
            (
                UInt16)kUSBRqSyncFrame << 8) +  (
            (
                UInt16) kUSBEndpoint +  (
                (
                    UInt16) kUSBStandard << kUSBRqTypeShift) +  (
                (
                    UInt16) kUSBIn << kUSBRqDirnShift))), 
};

Discussion

Encoding of the standard device requests.


bmRequestType bRequest          wValue        wIndex     wLength Data
00000000B     CLEAR_FEATURE     Feature       Zero       Zero    None (device)
00000001B                       Feature       Interface  Zero    None (Interface)
00000010B                       Feature       Endpoint   Zero    None (Endpoint)

10000000B     GET_CONFIGURATION Zero          Zero       One     Configuration
10000000B     GET_DESCRIPTOR    Type          LangID     Length  Descriptor
10000001B     GET_INTERFACE     Zero          Interface  One     Alternate

10000000B     GET_STATUS        Zero          Zero       Two     status (device)
10000001B                       Zero          Interface  Two     status (Interface)
10000010B                       Zero          Endpoint   Two     status (Endpoint)

00000000B     SET_ADDRESS       Address       Zero       Zero    None
00000000B     SET_CONFIGURATION Configuration Zero       Zero    None
00000000B     SET_DESCRIPTOR    Type          LangID     Length  Descriptor

00000000B     SET_FEATURE       Feature       Zero       Zero    None (device)
00000001B                       Feature       Interface  Zero    None (Interface)
00000010B                       Feature       Endpoint   Zero    None (Endpoint)

00000001B     SET_INTERFACE     Alternate     Interface  Zero    None
10000010B     SYNCH_FRAME       Zero          Endpoint   Two     Frame Number

USBDeviceSpeed


enum { 
    kUSBDeviceSpeedLow = 0, 
    kUSBDeviceSpeedFull = 1, 
    kUSBDeviceSpeedHigh = 2 
};

Constants

kUSBDeviceSpeedLow: The device a low speed device.
kUSBDeviceSpeedFull: The device a full speed device.
kUSBDeviceSpeedHigh: The device a high speed device.

Discussion

Returns the speed of a particular USB device.

Macro Definitions

EncodeRequest
Endian conversion definitions
iokit_usb_err
iokit_usb_msg
IOUSBFamily error codes
IOUSBFamily hardware error codes
IOUSBFamily message codes
kCallInterfaceOpenWithGate
kIOUSBLinkErr
kUSBDevicePropertySpeed
Property Definitions
USBmakebmRequestType
USBToHostWord

EncodeRequest


#define EncodeRequest(request, direction, type, recipient) \ 
    (((UInt16)request << 8) + \ 
    ((UInt16)recipient + \ 
    ((UInt16)type << kUSBRqTypeShift) + \ 
    ((UInt16)direction << kUSBRqDirnShift)))

Discussion

Macro that encodes the bRequest and bRequestType fields of a IOUSBDevRequest into a single value. It is useful when one needs to know what type of request the IOUSBDevRequest encodes and simplifies comparisons.

Endian conversion definitions


#define USBToHostWord OSSwapLittleToHostInt16

Discussion

The USB API's use a convention of specifying parameters in the host order. The USB spec specifies that multi-byte items should be formatted in little endian order. The following macros allow one to translate multi-byte values from Host order to USB order and vice versa. There are separate macros for in-kernel use and for user space use.

See Also

USBToHostWord

iokit_usb_err


#define iokit_usb_err(return)

Discussion

Errors specific to the IOUSBFamily. Note that the iokit_usb_err(x) translates to 0xe0004xxx, where xxx is the value in parenthesis as a hex number.

See Also

IOUSBFamily

iokit_usb_msg


#define iokit_usb_msg(message)

Discussion

Messages specific to the IOUSBFamily. Note that the iokit_usb_msg(x) translates to 0xe0004xxx, where xxx is the value in parenthesis as a hex number.

See Also

IOUSBFamily

IOUSBFamily error codes


#define iokit_usb_err(return)

Discussion

Errors specific to the IOUSBFamily. Note that the iokit_usb_err(x) translates to 0xe0004xxx, where xxx is the value in parenthesis as a hex number.

See Also

iokit_usb_err

IOUSBFamily hardware error codes


#define kIOUSBLinkErr

Discussion

These errors are returned by the OHCI controller. The # in parenthesis (xx) corresponds to the OHCI Completion Code. For the following Completion codes, we return a generic IOKit error instead of a USB specific error.

Completion Code         Error Returned              Description
9                       kIOReturnUnderrun           (Data Underrun) EP returned less data than max packet size
8                       kIOReturnOverrun            (Data Overrun) Packet too large or more data than buffer
5                       kIOReturnNotResponding      Device Not responding
4                       kIOUSBPipeStalled           Endpoint returned a STALL PID

See Also

kIOUSBLinkErr

IOUSBFamily message codes


#define iokit_usb_msg(message)

Discussion

Messages specific to the IOUSBFamily. Note that the iokit_usb_msg(x) translates to 0xe0004xxx, where xxx is the value in parenthesis as a hex number.

See Also

iokit_usb_msg

kCallInterfaceOpenWithGate


#define kCallInterfaceOpenWithGate "kCallInterfaceOpenWithGate"

Discussion

If the USB Device has this property, drivers for any of its interfaces will have their handleOpen method called while holding the workloop gate.

kIOUSBLinkErr


#define kIOUSBLinkErr

Discussion

Completion Code         Error Returned              Description
9                       kIOReturnUnderrun           (Data Underrun) EP returned less data than max packet size
8                       kIOReturnOverrun            (Data Overrun) Packet too large or more data than buffer
5                       kIOReturnNotResponding      Device Not responding
4                       kIOUSBPipeStalled           Endpoint returned a STALL PID

See Also

IOUSBFamily

kUSBDevicePropertySpeed


#define kUSBDevicePropertySpeed "Device Speed"

Discussion

Useful property names in USB land.

See Also

Property

Property Definitions


#define kUSBDevicePropertySpeed "Device Speed"

Discussion

Useful property names in USB land.

See Also

kUSBDevicePropertySpeed

USBmakebmRequestType


#define USBmakebmRequestType(direction, type, recipient) \ 
    ((direction & kUSBRqDirnMask) << kUSBRqDirnShift) | \ 
    ((type & kUSBRqTypeMask) << kUSBRqTypeShift) | \ 
    (recipient & kUSBRqRecipientMask)

Discussion

Macro to encode the bRequest field of a Device Request. It is used when constructing an IOUSBDevRequest.

USBToHostWord


#define USBToHostWord OSSwapLittleToHostInt16

Discussion

See Also

Endian

Mac Dev Center Mac OS X Reference Library Drivers, Kernel, & Hardware: Kernel Device Drivers Kernel Framework Reference

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.

Last Updated: 2010-07-29