ADC Home > Reference Library > Reference > Darwin > Kernel Framework Reference

USB.h

Include Path :	<IOKit/usb/USB.h>
Path:	/System/Library/Frameworks/Kernel.framework/Versions/A/Headers/IOKit/usb/USB.h
Includes:	<libkern/OSByteOrder.h> <IOKit/IOMemoryDescriptor.h> <architecture/byte_order.h> <IOKit/IOTypes.h>

Overview

This header contains the public interfaces to the USB implementation in Mac OS X. It includes definitions and structures that are used in the USB APIs in Mac OS X, both in the kernel and in user space.

Typedefs

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

See Also:

IOUSBConfigurationDescHeader

typedef struct IOUSBConfigurationDescHeader IOUSBConfigurationDescHeader;

Discussion

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

IOUSBConfigurationDescriptor

See Also:

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.

IOUSBDescriptorHeader

See Also:

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.

IOUSBDeviceDescriptor

See Also:

IOUSBDeviceDescriptor

typedef struct IOUSBDeviceDescriptor IOUSBDeviceDescriptor;

Discussion

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

IOUSBDeviceQualifierDescriptor

See Also:

IOUSBDeviceQualifierDescriptor

typedef struct IOUSBDeviceQualifierDescriptor IOUSBDeviceQualifierDescriptor;

Discussion

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

IOUSBDevRequest

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

Fields

bmRequestType: An encoded value that contains the direction, type, and recipient of the request. Use the USBmakebmRequestType macro to encode this field.
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

bmRequestType: An encoded value that contains the direction, type, and recipient of the request. Use the USBmakebmRequestType macro to encode this field.
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

bmRequestType: An encoded value that contains the direction, type, and recipient of the request. Use the USBmakebmRequestType macro to encode this field.
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

See Also:

IOUSBDFUDescriptor

typedef struct IOUSBDFUDescriptor IOUSBDFUDescriptor;

Discussion

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

IOUSBEndpointDescriptor

See Also:

IOUSBEndpointDescriptor

typedef struct IOUSBEndpointDescriptor IOUSBEndpointDescriptor;

Discussion

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

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

See Also:

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.

IOUSBHIDReportDesc

See Also:

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.

IOUSBInterfaceAssociationDescriptor

See Also:

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.

IOUSBInterfaceDescriptor

See Also:

IOUSBInterfaceDescriptor

typedef struct IOUSBInterfaceDescriptor IOUSBInterfaceDescriptor;

Discussion

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

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

See Also:

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).

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().

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

See Also:

IOUSBConfigurationDescHeader

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

Discussion

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

IOUSBConfigurationDescriptor

See Also:

IOUSBConfigurationDescriptor

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

Discussion

IOUSBDescriptorHeader

See Also:

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.

IOUSBDeviceDescriptor

See Also:

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.

IOUSBDeviceQualifierDescriptor

See Also:

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.

IOUSBDFUDescriptor

See Also:

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.

IOUSBEndpointDescriptor

See Also:

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.

IOUSBHIDDescriptor

See Also:

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.

IOUSBHIDReportDesc

See Also:

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.

IOUSBInterfaceAssociationDescriptor

See Also:

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.

IOUSBInterfaceDescriptor

See Also:

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.

IOUSBLowLatencyIsocFrame

See Also:

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).

Enumerations

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.

kIOUSBVendorIDAppleComputer

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.

#defines

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.

HostToUSBLong

See Also:

Kernel

#define HostToUSBLong OSSwapHostToLittleInt32

Discussion

The USB APIs 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.

HostToUSBWord

See Also:

Kernel

#define HostToUSBWord OSSwapHostToLittleInt16

Discussion

iokit_usb_err

See Also:

IOUSBFamily

#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.

iokit_usb_msg

See Also:

IOUSBFamily

#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.

IOUSBFamily error codes

See Also:

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.

IOUSBFamily hardware error codes

See Also:

kIOUSBLinkErr

#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

IOUSBFamily message codes

See Also:

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.

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.

Kernel Endian conversion definitions

See Also:

USBToHostWord

HostToUSBWord

USBToHostLong

HostToUSBLong

#define USBToHostWord OSSwapLittleToHostInt16 
#define HostToUSBWord OSSwapHostToLittleInt16 
#define USBToHostLong OSSwapLittleToHostInt32 
#define HostToUSBLong OSSwapHostToLittleInt32

Discussion

kIOUSBLinkErr

See Also:

IOUSBFamily

#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

kUSBDevicePropertySpeed

See Also:

Property

#define kUSBDevicePropertySpeed "Device Speed"

Discussion

Useful property names in USB land.

Property Definitions

See Also:

kUSBDevicePropertySpeed

#define kUSBDevicePropertySpeed "Device Speed"

Discussion

Useful property names in USB land.

USBmakebmRequestType

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

Parameters

direction: Direction of data. Use either kUSBIn or kUSBOut.
type: Request type. Use kUSBStandard, kUSBClass, or kUSBVendor.
recipient: Recipient target of request. Use kUSBDevice, kUSBInterface, kUSBEndpoint, or kUSBOther.

Discussion

Macro to encode the bRequest field of a Device Request. Use it to construct an IOUSBDevRequest.

USBToHostLong

See Also:

Kernel

#define USBToHostLong OSSwapLittleToHostInt32

Discussion

USBToHostWord

See Also:

Kernel

#define USBToHostWord OSSwapLittleToHostInt16

Discussion

USBToHostWord

See Also:

User

#define USBToHostWord NXSwapLittleShortToHost

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.

User Space Endian conversion definitions

See Also:

USBToHostWord

#define USBToHostWord NXSwapLittleShortToHost

Discussion

Did this document help you?

Yes: Tell us what works for you.

It’s good, but: Report typos, inaccuracies, and so forth.

It wasn’t helpful: Tell us what would have helped.

Last Updated: 2008-12-19