USBHub.h Reference

Declared in
USBHub.h

Overview

Constants and definitions used with Hub devices.

Included Headers

  • <IOKit/usb/USB.h>

  • <IOKit/usb/USBSpec.h>

Data Types

See the Overview section above for header-level documentation.

IOUSBHubPortReEnumerateParam

typedef struct IOUSBHubPortReEnumerateParam IOUSBHubPortReEnumerateParam;
Discussion

Used to specify the port that needs to be reenumerated

Availability
  • Available in OS X v10.1 and later.
Declared In
USBHub.h

IOUSBHubStatus

typedef struct IOUSBHubStatus IOUSBHubStatus;
Discussion

Used to get the port status and change flags using GetPortStatus()

Availability
  • Available in OS X v10.0 and later.
Declared In
USBHub.h

IOUSBHubDescriptor

struct IOUSBHubDescriptor {
   UInt8 length;
   UInt8 hubType;
   UInt8 numPorts;
   UInt16 characteristics __attribute__((packed));
   UInt8 powerOnToGood; // Port settling time, in 2ms
   UInt8 hubCurrent;
   // These are received packed, will have to be unpacked
   UInt8 removablePortFlags[kNumPortBytes];
   UInt8 pwrCtlPortFlags[kNumPortBytes];
};
Discussion

USB Hub Descriptor. See the USB HID Specification at http://www.usb.org.

IOUSBHubStatus

struct IOUSBHubStatus {
   UInt16 statusFlags;
   UInt16 changeFlags;
};
Discussion

Used to get the port status and change flags using GetPortStatus()

Constants

See the Overview section above for header-level documentation.

Hub Class Request

enum USBHubClassRequest {
   kUSBHubRqGetStatus = 0,
   kUSBHubRqClearFeature = 1,
   kUSBHubRqGetState = 2,
   kUSBHubRqSetFeature = 3,
   kUSBHubRqReserved2 = 4,
   kUSBHubRqSetAddress = 5,
   kUSBHubRqGetDescriptor = 6,
   kUSBHubRqSetDescriptor = 7,
   kUSBHubRqGetConfig = 8,
   kUSBHubRqSetConfig = 9,
   kUSBHubRqGetInterface = 10,
   kUSBHubRqSetInterface = 11,
};
Discussion

Specifies values for the bRequest field of a Device Request.

See Also
  • USBHubClassRequest

Hub Descriptor Type

enum {
   kUSBHubDescriptorType = 0x29,
   kUSB3HubDescriptorType = 0x2A
};

Hub Device Requests

enum {
   kClearHubFeature =  (
   (
   (
   UInt16)kUSBRqClearFeature << 8) +  (
   (
   UInt16) kUSBDevice +  (
   (
   UInt16) kUSBClass << kUSBRqTypeShift) +  (
   (
   UInt16) kUSBOut << kUSBRqDirnShift))),
   kClearPortFeature =  (
   (
   (
   UInt16)kUSBRqClearFeature << 8) +  (
   (
   UInt16) kUSBOther +  (
   (
   UInt16) kUSBClass << kUSBRqTypeShift) +  (
   (
   UInt16) kUSBOut << kUSBRqDirnShift))),
   kGetPortState =  (
   (
   (
   UInt16)kUSBRqGetState << 8) +  (
   (
   UInt16) kUSBOther +  (
   (
   UInt16) kUSBClass << kUSBRqTypeShift) +  (
   (
   UInt16) kUSBIn << kUSBRqDirnShift))),
   kGetHubDescriptor =  (
   (
   (
   UInt16)kUSBRqGetDescriptor << 8) +  (
   (
   UInt16) kUSBDevice +  (
   (
   UInt16) kUSBClass << kUSBRqTypeShift) +  (
   (
   UInt16) kUSBIn << kUSBRqDirnShift))),
   kGetHub3Descriptor=  (
   (
   (
   UInt16)kUSBRqGetDescriptor << 8) +  (
   (
   UInt16) kUSBDevice +  (
   (
   UInt16) kUSBClass << kUSBRqTypeShift) +  (
   (
   UInt16) kUSBIn << kUSBRqDirnShift))),
   kGetHubStatus =  (
   (
   (
   UInt16)kUSBRqGetStatus << 8) +  (
   (
   UInt16) kUSBDevice +  (
   (
   UInt16) kUSBClass << kUSBRqTypeShift) +  (
   (
   UInt16) kUSBIn << kUSBRqDirnShift))),
   kGetPortStatus =  (
   (
   (
   UInt16)kUSBRqGetStatus << 8) +  (
   (
   UInt16) kUSBOther +  (
   (
   UInt16) kUSBClass << kUSBRqTypeShift) +  (
   (
   UInt16) kUSBIn << kUSBRqDirnShift))),
   kSetHubDescriptor =  (
   (
   (
   UInt16)kUSBRqGetDescriptor << 8) +  (
   (
   UInt16) kUSBDevice +  (
   (
   UInt16) kUSBClass << kUSBRqTypeShift) +  (
   (
   UInt16) kUSBOut << kUSBRqDirnShift))),
   kSetHubFeature =  (
   (
   (
   UInt16)kUSBRqSetFeature << 8) +  (
   (
   UInt16) kUSBDevice +  (
   (
   UInt16) kUSBClass << kUSBRqTypeShift) +  (
   (
   UInt16) kUSBOut << kUSBRqDirnShift))),
   kSetPortFeature =  (
   (
   (
   UInt16)kUSBRqSetFeature << 8) +  (
   (
   UInt16) kUSBOther +  (
   (
   UInt16) kUSBClass << kUSBRqTypeShift) +  (
   (
   UInt16) kUSBOut << kUSBRqDirnShift)))
};
Discussion

Encoding of the hub specific standard requests

 
Request          bmRequestType bRequest       wValue  wIndex wLength Data
ClearHubFeature  0010 0000B    CLEAR_FEATURE  Feature Zero    Zero   None
ClearPortFeature 0010 0011B                   Feature Port    Zero   None
 
GetBusState      1010 0011B    GET_STATE      Zero    Port    One    Port Bus State
 
GetHubDescriptor 1010 0000B    GET_DESCRIPTOR Type    Zero    Length Descriptor
 
GetHubStatus     1010 0000B    GET_STATUS     Zero    Zero    Four   Hub Status
GetPortStatus    1010 0011B                   Zero    Port    Four   Port Status
 
SetHubDescriptor 0010 0000B    SET_DESCRIPTOR Type    Zero    Length Descriptor
 
SetHubFeature    0010 0000B    SET_FEATURE    Feature Zero    Zero   None
SetPortFeature   0010 0011B                   Feature Port    Zero   None

HubCharacteristics

enum {
   kPerPortSwitchingBit = (
   1 << 0),
   kNoPowerSwitchingBit = (
   1 << 1),
   kCompoundDeviceBit = (
   1 << 2),
   kPerPortOverCurrentBit = (
   1 << 3),
   kNoOverCurrentBit = (
   1 << 4),
   kUSBHubOvercurrentMask = 0x18,
   kUSBHubOvercurrentShift = 3,
   kHubTTThinkTimeMask = 0x60,
   kHubTTThinkTimeShift = 5,
   kHubPortIndicatorBit = 7,
   kHubPortIndicatorMask = 0x0080
};

HubFeatures

enum {
   kUSBHubLocalPowerChangeFeature = 0, /* Hub features */
   kUSBHubOverCurrentChangeFeature = 1,
   kUSBHubPortConnectionFeature = 0, /* port features */
   kUSBHubPortEnableFeature = 1,
   kUSBHubPortSuspendFeature = 2,
   kUSBHubPortOverCurrentFeature = 3,
   kUSBHubPortResetFeature = 4,
   kUSBHubPortPowerFeature = 8,
   kUSBHubPortLowSpeedFeature = 9,
   kUSBHubPortConnectionChangeFeature = 16,
   kUSBHubPortEnableChangeFeature = 17,
   kUSBHubPortSuspendChangeFeature = 18,
   kUSBHubPortOverCurrentChangeFeature = 19,
   kUSBHubPortResetChangeFeature = 20,
   kUSBHubPortTestFeature = 21,
   kUSBHubPortIndicatorFeature = 22,
   // USB 3.0
   kUSBHubPortLinkStateFeature = 5, /* port features */
   kUSBHubPortU1TimeoutFeature = 23,
   kUSBHubPortU2TimeoutFeature = 24,
   kUSBHubPortLinkStateChangeFeature = 25,
   kUSBHubPortConfigErrorChangeFeature = 26,
   kUSBHubPortRemoteWakeMaskFeature = 27,
   kUSBHubPortBHPortResetFeature = 28,
   kUSBHubPortBHResetChangeFeature = 29,
   kUSBHubPortForceLinkPMAcceptFeature = 30,
};
Discussion

Used with SET_FEATURE to set hub and port features

HubPortStatus

enum {
   kSSHubPortStatusConnectionBit = 0,
   kSSHubPortStatusEnabledBit = 1,
   kSSHubPortStatusOverCurrentBit = 3,
   kSSHubPortStatusResetBit = 4,
   // USB 3.0
   kSSHubPortStatusLinkStateShift = 5,
   kSSHubPortStatusPowerBit = 9,
   kSSHubPortStatusSpeedShift = 10,
   kSSHubPortChangeBHResetBit = 5,
   kSSHubPortChangePortLinkStateBit = 6,
   kSSHubPortChangePortConfigErrBit = 7,
   kHubPortConnection = 0x0001,
   kHubPortEnabled = 0x0002,
   kHubPortSuspend = 0x0004,
   kHubPortOverCurrent = 0x0008,
   kHubPortBeingReset = 0x0010,
   kHubPortPower = 0x0100,
   kHubPortLowSpeed = 0x0200,
   kHubPortHighSpeed = 0x0400,
   kHubPortTestMode = 0x0800,
   kHubPortIndicator = 0x1000,
   kHubPortSuperSpeed = 0x2000, // This is a synthesized bit that is using a reserved bit from the Hub Port Status definition in USB 2.0.
   kHubPortBit14 = 0x4000, // That bit is used by the hub driver to encode the USB3 link state into the USB2 PortStatus (using bits 5-7 as well,
   that are reserved in the USB 2 spec)
   kHubPortDebouncing = 0x8000, // This is a synthesized bit that is using a reserved bit from the Hub Port Status definition in USB 2.0.
   // USB 3.0
   kSSHubPortStatusConnectionMask = (
   1 << kSSHubPortStatusConnectionBit ),
   kSSHubPortStatusEnabledMask = (
   1 << kSSHubPortStatusEnabledBit ),
   kSSHubPortStatusOverCurrentMask = (
   1 << kSSHubPortStatusOverCurrentBit ),
   kSSHubPortStatusBeingResetMask = (
   1 << kSSHubPortStatusResetBit ),
   kSSHubPortStatusLinkStateMask = 0x01E0,
   kSSHubPortStatusPowerMask = (
   1 << kSSHubPortStatusPowerBit ),
   kSSHubPortStatusSpeedMask = 0x1C00,
   kSSHubPortChangeBHResetMask = (
   1 << kSSHubPortChangeBHResetBit ),
   kSSHubPortChangePortLinkStateMask = (
   1 << kSSHubPortChangePortLinkStateBit ),
   kSSHubPortChangePortConfigErrMask = (
   1 << kSSHubPortChangePortConfigErrBit ),
   // these are the bits which cause the hub port state machine to keep moving (USB 3.0)
   kHubPortSuperSpeedStateChangeMask = (
   kHubPortConnection | kHubPortEnabled | kHubPortSuspend | kHubPortOverCurrent | kHubPortBeingReset | kSSHubPortStatusBeingResetMask | kSSHubPortChangePortLinkStateMask | kSSHubPortChangePortConfigErrMask), 
   // these are the bits which cause the hub port state machine to keep moving (USB 2.0)
   kHubPortStateChangeMask = (
   kHubPortConnection | kHubPortEnabled | kHubPortSuspend | kHubPortOverCurrent | kHubPortBeingReset)
};
Discussion

Used to decode the Port Status and Change

HubStatus

enum {
   kHubLocalPowerStatus = 1,
   kHubOverCurrentIndicator = 2,
   kHubLocalPowerStatusChange = 1,
   kHubOverCurrentIndicatorChange = 2
};
Discussion

Used to decode the Hub Status and Change

IOUSBHubDescriptor

enum{
   // Support a maximum of 64 ports,
   which will pack into 9 bytes
   kNumPortBytes = 9
};
   
typedef struct IOUSBHubDescriptor IOUSBHubDescriptor;
Discussion

USB Hub Descriptor. See the USB HID Specification at http://www.usb.org.

See Also

Link State for USB 3.0

enum {
   kSSHubPortLinkStateU0 = 0,
   kSSHubPortLinkStateU1 = 1,
   kSSHubPortLinkStateU2 = 2,
   kSSHubPortLinkStateU3 = 3,
   kSSHubPortLinkStateSSDisabled = 4,
   kSSHubPortLinkStateRxDetect = 5,
   kSSHubPortLinkStateSSInactive = 6,
   kSSHubPortLinkStatePolling = 7,
   kSSHubPortLinkStateRecovery = 8,
   kSSHubPortLinkStateHotReset = 9,
   kSSHubPortLinkStateComplianceMode = 10,
   kSSHubPortLinkStateLoopBack = 11,
   kSSHubPortSpeed5Gbps = 0
};
Discussion

Used to decode the Port Status and Change

PortIndicatorSelectors

enum {
   kHubPortIndicatorAutomatic = 0,
   kHubPortIndicatorAmber,
   kHubPortIndicatorGreen,
   kHubPortIndicatorOff
};

PowerSwitching

enum {
   kHubSupportsGangPower = 0,
   kHubSupportsIndividualPortPower = 1,
   kHubPortSetPowerOff = 0,
   kHubPortSetPowerOn = 1
};

Root Hub specific

enum {
   kPrdRootHubApple = 0x8005, // ProductID for classic speed root hubs
   kPrdRootHubAppleE = 0x8006, // ProductID for high speed root hubs
   kPrdRootHubAppleSS = 0x8007, // ProductID for super speed root hubs
   kUSBRootHubPollingRate = 32 // Enpoint polling rate interval for root hubs
};

USB 3 Hub Class Request

enum {
   kUSBHubRqSetHubDepth = 12,
   kUSBHubRqGetPortErrorCount = 13
};
Discussion

Specifies values for the bRequest field of a Device Request.

USBHubClassRequest

enum USBHubClassRequest {
   kUSBHubRqGetStatus = 0,
   kUSBHubRqClearFeature = 1,
   kUSBHubRqGetState = 2,
   kUSBHubRqSetFeature = 3,
   kUSBHubRqReserved2 = 4,
   kUSBHubRqSetAddress = 5,
   kUSBHubRqGetDescriptor = 6,
   kUSBHubRqSetDescriptor = 7,
   kUSBHubRqGetConfig = 8,
   kUSBHubRqSetConfig = 9,
   kUSBHubRqGetInterface = 10,
   kUSBHubRqSetInterface = 11,
};
Discussion

Specifies values for the bRequest field of a Device Request.