IOKit/usb/IOUSBHostControllerInterfaceDefinitions.h Kernel.framework

@enum IOUSBHostCIExceptionType @brief Exception specifier included as message argument to <code>kUSBHostMessageControllerException</code> @discussion The kernel driver sends a <code>kUSBHostMessageControllerException</code> message to its clients when a fatal problem has occurred, with a refCon of the IOUSBHostController instance and a <code>IOUSBHostCIExceptionType</code> in the message arguments. When any <code>kUSBHostMessageControllerException</code> message is received, the specified IOUSBHostControllerInterface must be destroyed.

@enum IOUSBHostCIMessageType @brief Values to be populated in IOUSBHostCIMessageControlType of an IOUSBHostCIMessage structure

@enum IOUSBHostCIMessageStatus @brief Values to be populated in IOUSBHostCIMessageControlStatus of an IOUSBHostCIMessage structure

@enum IOUSBHostCIDeviceSpeed @brief Values to represent a connected device speed, to be used in IOUSBHostCIMessages and IOUSBHostsCIPortStatus

@enum IOUSBHostCILinkState @brief Values to represent a port's link state, to be used in IOUSBHostCIMessages and IOUSBHostCIPortStatus

@enum @brief Fields in IOUSBHostCIPortStatus @discussion IOUSBHostCIPortStatusPowered is set if the port is currently powered IOUSBHostCIPortStatusOvercurrent is set if the port is currently observing an overcurrent condition IOUSBHostCIPortStatusConnected is set if the port is currently observing a connected device IOUSBHostCIPortStatusLinkState is populated with a IOUSBHostCILinkState value IOUSBHostCIPortStatusSpeed is populated with a IOUSBHostCIDeviceSpeed value IOUSBHostCIPortStatusOvercurrentChange is set if a change to IOUSBHostCIPortStatusOvercurrent has been observed IOUSBHostCIPortStatusConnectChange is set if a change to IOUSBHostCIPortStatusConnected has been observed IOUSBHostCIPortStatusLinkStateChange is set if the link has independently transitioned from an enabled to disabled state. See IOUSBHostCILinkStateEnabled(...) to determine if a particular link state is considered to be enabled or disabled. IOUSBHostCIPortStatusChangeMask is a mask combining all change bits

@typedef IOUSBHostCIDoorbell @brief Structured message used to notify the client that the specified endpoint or stream has updated IOUSBHostCIMessage messages to process @discussion The kernel driver uses IOUSBHostCIDoorbell messages to transition an endpoint to the IOUSBHostCIEndpointStateActive state (if eligible), or to notify the client that additional valid IOUSBHostCIMessage structures have been appended to an already active queue. When received, the client should perform the following actions: 1. Locate the iOUSBHostCIEndpointStateMachine associated with the endpoint selector in IOUSBHostCIDoorbellDeviceAddress and IOUSBHostCIDoorbellEndpointAddress of the command 2. Utilize the IOUSBHostCIEndpointStateMachine processDoorbell interface to determine if the doorbell can be processed 3. If successful and the endpoint is not already processing transfer messages, use the IOUSBHostCIEndpointStateMachine's currentTransferMessage property to begin processing transfer messages

typedef uint32_t IOUSBHostCIDoorbell

@enum @brief Fields in IOUSBHostCIDoorbell @discussion IOUSBHostCIDoorbellDeviceAddress is populated with the device address targeted by the IOUSBHostCIDoorbell IOUSBHostCIDoorbellEndpointAddress is populated with the endpoint address targeted by the IOUSBHostCIDoorbell IOUSBHostCIDoorbellStreamID is populated with the stream ID targeted by the IOUSBHostCIDoorbell

@typedef IOUSBHostCIMessage @brief Foundational IOUSBHostControllerInterface message structure used for commands, transfers, and interrupts @discussion IOUSBHostCIMessage structures are control structures passed between the IOUSBHostControllerInterface client and the kernel driver. They are used to represent capabilities during initialization, commands and transfers sent from the kernel, and interrupt events sent to the kernel.

@enum @brief Fields used in all IOUSBHostCIMessage structures @discussion IOUSBHostCIMessageControlType is populated in the control field with IOUSBHostCIMessageType. IOUSBHostCIMessageControlStatus is populated in the control field with IOUSBHostCIMessageStatus. IOUSBHostCIMessageControlNoResponse is set in the control field to incidate the recipient should not send a reply message. IOUSBHostCIMessageControlValid is set in the control field to indicate the message is fully initialized and ready for consumption by the recipient.

@enum @brief Fields used in IOUSBHostCIMessage structures with an IOUSBHostCIMessageControlType of IOUSBHostCIMessageTypeControllerCapabilities @discussion IOUSBHostCICapabilitiesMessageControlPortCount is populated in the control field with the number of ports supported by this controller. IOUSBHostCICapabilitiesMessageData0CommandTimeoutThreshold is populated in the data0 field to indicate a timeout threshold for commands from the kernel. Format is 2^n seconds. A command timeout is a fatal error and will generate a IOUSBHostCIExceptionTypeCommandTimeout exception. IOUSBHostCICapabilitiesMessageData0ConnectionLatency is populated in the data0 field to indicate the time needed to pass a transfer structure and its associated data payload between the IOUSBHostControllerInterface and its target. Format is 2^n milliseconds.

@enum @brief Fields used in IOUSBHostCIMessage structures with an IOUSBHostCIMessageControlType of IOUSBHostCIMessageTypePortCapabilities @discussion IOUSBHostCIPortCapabilitiesMessageControlPortNumber is populated in the control field with the nonzero port number described by the structure. IOUSBHostCIPortCapabilitiesMessageControlInternalConnector is set in the control field to indicate the port is not user-accessible, such as for a captive device. IOUSBHostCIPortCapabilitiesMessageControlConnectorType is populated in the control field with the ACPI Connector Type IOUSBHostCIPortCapabilitiesMessageData0MaxPower is populated in the data0 field with the maximum power consumption allowed by the port, in 8mA @ 5V units.

@enum @brief Fields used in IOUSBHostCIMessage structures with an IOUSBHostCIMessageControlType value in the range of IOUSBHostCIMessageTypeCommandMin to IOUSBHostCIMessageTypeCommandMax @discussion IOUSBHostCICommandMessageControlStatus is populated in command response messages, see IOUSBHostCIMessageControlStatus IOUSBHostCICommandMessageData0RootPort is populated in the data0 field with the nonzero port number if the command targets a port IOUSBHostCICommandMessageData0DeviceAddress is populated in the data0 field with the device address if the command targets a device, endpoint, or stream IOUSBHostCICommandMessageData0EndpointAddress is populated in the data0 field with the endpoint address if the command targets an endpoint or stream IOUSBHostCICommandMessageData0StreamID is populated in the data0 field with the stream ID if the command targets a stream

@enum IOUSBHostCIControllerState @brief Host controller state managed by IOUSBHostCIControllerStateMachine @discussion IOUSBHostCIControllerStateOff is the initial state of a newly created IOUSBHostCIControllerStateMachine instance, and represents a completely quiesced controller. All root ports must be in the IOUSBHostCIPortStateOff state. IOUSBHostCIControllerStatePaused represents a controller that is idle. In this state the controller is not processing IO requests, but can detect port changes such as connect events or remote wakes. Root ports must not be in the IOUSBHostCIPortStateActive state. IOUSBHostCIControllerStateActive represents a controller that is fully functional and able to service IO requests. Root ports may be in the IOUSBHostCIPortStateActive state.

@enum IOUSBHostCIPortState @brief Port state managed by IOUSBHostCIPortStateMachine @discussion IOUSBHostCIPortStateOff is the initial state of a newly created IOUSBHostCIPortStateMachine and represents an unpowered port which is unable to detect events such as connections. Downstream devices, if any, must be in the IOUSBHostCIDeviceStateDestroyed state. IOUSBHostCIPortStatePowered represents a powered port which is able to detect events such as connections. Downstream devices, if any, must be in the IOUSBHostCIDeviceStateDestroyed state. IOUSBHostCIPortStateSuspended represents a port with a downstream device that is in a low-power state such as U3 or L2. The port is able to detect events such as remote wakes, and is not actively transmitting data. Downstream devices must be in the IOUSBHostCIDeviceStatePaused state. IOUSBHostCIPortStateActive represents a port with a downstream device that is able to immediately transfer data. The downstream device may be in the IOUSBHostCIDeviceStateActive state.

@enum @brief Fields used in IOUSBHostCIMessage structures with an IOUSBHostCIMessageControlType of IOUSBHostCIMessageTypePortEvent @discussion IOUSBHostCIPortEventMessageData0PortNumber is populated in the data0 field with the nonzero port number of the port that needs to process events.

@enum @brief Fields used in some IOUSBHostCIMessage structures with an IOUSBHostCIMessageControlType in the range of IOUSBHostCIMessageTypePortPowerOn to IOUSBHostCIMessageTypePortStatus @discussion IOUSBHostCIPortStatusCommandData1Powered is set in the data1 field of command responses if the port is currently powered IOUSBHostCIPortStatusCommandData1Overcurrent is set in the data1 field of command responses if the port is currently observing an overcurrent condition IOUSBHostCIPortStatusCommandData1Connected is set in the data1 field of command responses if the port is currently observing a connected device IOUSBHostCIPortStatusCommandData1LinkState is populated in the data1 field of command responses with the currently observed IOUSBHostCILinkState IOUSBHostCIPortStatusCommandData1Speed is populated in the data1 field of command responses with the currently observed IOUSBHostCIDeviceSpeed IOUSBHostCIPortStatusCommandData1OvercurrentChange is set in the data1 field of commands if the bit should be cleared on subsequent command responses. It is set in the data1 field of command responses if IOUSBHostCIPortStatusCommandData1Overcurrent has changed. IOUSBHostCIPortStatusCommandData1ConnectChange is set in the data1 field of commands if the bit should be cleared on subsequent command responses. It is set in the data1 field of command responses if IOUSBHostCIPortStatusCommandData1Connected has changed. IOUSBHostCIPortStatusCommandData1LinkStateChange is set in the data1 field of commands if the bit should be cleared on subsequent command responses. It is set in the data1 field of command responses if the link has independently transitioned from an enabled to disabled state. See IOUSBHostCILinkStateEnabled(...) to determine if a particular link state is considered to be enabled or disabled. IOUSBHostCIPortStatusCommandData1ChangeMask is a mask combining all change bits from the data1 field.

@enum IOUSBHostCIDeviceState @brief Device state managed by IOUSBHostCIDeviceStateMachine @discussion IOUSBHostCIDeviceStateDestroyed represents a device that is no longer usable, and whose resources will be destroyed and freed IOUSBHostCIDeviceStatePaused represents a device that may have IO requests enqueued, but they are not active on the bus. The state is closely correlated to IOUSBHostCIPortStateSuspended, and endpoints associated with this device may not be in the IOUSBHostCIEndpointStateActive state. IOUSBHostCIDeviceStateActive is the initial sate of a newly created IOUSBHsotCIDeviceStateMachine, and represents a device that can be processing IO requests. Endpoints associated with this device may be in the IOUSBHostCIEndpointStateActive state.

@enum @brief Fields used in IOUSBHostCIMessage structures with an IOUSBHostCIMessageControlType of IOUSBHostCIMessageTypeDeviceCreate @discussion IOUSBHostCIDeviceCreateCommandData0RootPort is populated in the data0 field of the command with the nonzero root port number for which to create a device IOUSBHostCIDeviceCreateCommandData0Route is populated in the data0 field of the command with the USB route string (see USB 3.2 § 8.9) IOUSBHostCIDeviceCreateCommandData1DeviceAddress is populated in the data1 field of the command response with the USB address assigned to the newly created device

@enum @brief Fields used in IOUSBHostCIMessage structures with an IOUSBHostCIMessageControlType of IOUSBHostCIMessageTypeDeviceUpdate @discussion IOUSBHostCIDeviceUpdateCommandData1DescriptorAddress is populated in the data1 field of the command with the virtual address of a USB descriptor (see USB 3.2 § 9.5) applicable to the device. If a device has multple descriptors, the IOUSBHostCIDeviceUpdateCommandData1DescriptorAddress address points to a synthetic configuration descriptor that serves as a container. IOUSBGetNextDescriptorWithType can be used to locate specific descriptors within the synthetic configuration descriptor.

@enum IOUSBHostCIEndpointState @brief Endpoint state managed by IOUSBHostCIEndpointStateMachine @discussion IOUSBHostCIEndpointStateDestroyed represents an endpoint that is no longer usable, and whose resources will be destroyed and freed. IOUSBHostCIEndpointStateHalted represents an endpoint that has encountered an IO error. The client must not access or modify transfer structures or IO buffers for an endpoint in this state. IOUSBHostCIEndpointStatePaused is the initial state of a newly created IOUSBHostCIEndpointStateMachine, and represents an endpoint that is not currently servicing IO requests. The client must not access or modify transfer structures or IO buffers for an endpoint in this state. IOUSBHostCIEndpointStateActive represents an endpoint that is currently servicing an IO request, or is idle after successfully servicing its queue of IO requests. In this state the client may access transfer structures and IO buffers.

@enum @brief Fields used in IOUSBHostCIMessage structures with an IOUSBHostCIMessageControlType of IOUSBHostCIMessageTypeEndpointCreate @discussion IOUSBHostCIEndpointCreateCommandData1Descriptor is populated in the data1 field of the command with the virtual address of the USB endpoint descriptor(s) (see USB 3.2 § 9.5) describing the endpoint. If an endpoint has multple descriptors, the IOUSBHostCIEndpointCreateCommandData1Descriptor address points to a synthetic configuration descriptor that serves as a container for the endpoint descriptors. IOUSBGetNextDescriptorWithType can be used to locate specific descriptors within the synthetic configuration descriptor.

@enum @brief Fields used in IOUSBHostCIMessage structures with an IOUSBHostCIMessageControlType of IOUSBHostCIMessageTypeEndpointUpdate @discussion IOUSBHostCIEndpointUpdateCommandData1Descriptor is populated in the data1 field of the command with the virtual address of the USB endpoint descriptors (see USB 3.2 § 9.5) describing updated endpoint capabilities. If an endpoint has multple descriptors, the IOUSBHostCIEndpointUpdateCommandData1Descriptor address points to a synthetic configuration descriptor that serves as a container for the endpoint descriptors. IOUSBGetNextDescriptorWithType can be used to locate specific descriptors within the synthetic configuration descriptor.

@enum @brief Fields used in IOUSBHostCIMessage structures with an IOUSBHostCIMessageControlType of IOUSBHostCIMessageTypeEndpointReset @discussion IOUSBHostCIEndpointResetCommandData1ClearState is set in the data1 field of the command to indicate the endpoint state (e.g. data toggle) should be reset as part of processing the command.

@enum @brief Fields used in IOUSBHostCIMessage structures with an IOUSBHostCIMessageControlType of IOUSBHostCIMessageTypeEndpointSetNextTransfer @discussion IOUSBHostCIEndpointSetNextTransferCommandData1Address is populated in the data1 field of the command with the virtual address of the next IOUSBHostCIMessage transfer message to process.

@enum @brief Fields used in IOUSBHostCIMessage structures with an IOUSBHostCIMessageControlType of IOUSBHostCIMessageTypeSetupTransfer @discussion See USB 3.2 § 9.3 for a description of the control request fields. IOUSBHostCISetupTransferData1bmRequestType is populated in the data1 field with the control request's bmRequestType IOUSBHostCISetupTransferData1bRequest is populated in the data1 field with the control request's bRequest IOUSBHostCISetupTransferData1wValue is populated in the data1 field with the control request's wValue IOUSBHostCISetupTransferData1wIndex is populated in the data1 field with the control request's wIndex IOUSBHostCISetupTransferData1wLength is populated in the data1 field with the control request's wLength

@enum @brief Fields used in IOUSBHostCIMessage structures with an IOUSBHostCIMessageControlType of IOUSBHostCIMessageTypeNormalTransfer @discussion IOUSBHostCINormalTransferData0Length is populated in the data0 field with the length of the transfer, in bytes IOUSBHostCINormalTransferData1Buffer is populated in the data1 field with the virtual address of the buffer to use for the transfer

@enum @brief Fields used in IOUSBHostCIMessage structures with an IOUSBHostCIMessageControlType of IOUSBHostCIMessageTypeIsochronousTransfer @discussion IOUSBHostCIIsochronousTransferControlFrameNumber is populated in the control field with the least significant bits of the frame number for this transfer IOUSBHostCIIsochronousTransferControlASAP is set in the control field to indicate IOUSBHostCIIsochronousTransferControlFrameNumber should be ignored and the transfer should be sent at the endpoint's next service opportunity IOUSBHostCIIsochronousTransferData0Length is populated in the data0 field with the length of the transfer, in bytes IOUSBHostCIIsochronousTransferData1BufferPhase is populated in the data1 field with the virtual address of the buffer to use for the transfer

@enum @brief Fields used in IOUSBHostCIMessage structures with an IOUSBHostCIMessageControlType of IOUSBHostCIMessageTypeLink @discussion IOUSBHostCILinkData1TransferStructureAddress is populated with the virtual address of the next IOUSBHostCIMessage structure to consume.

@enum @brief Fields used in IOUSBHostCIMessage structures with an IOUSBHostCIMessageControlType of IOUSBHostCIMessageTypeTransferComplete @discussion IOUSBHostCITransferCompletionMessageControlStatus is populated in the control field with a IOUSBHostCIMessageStatus describing the result of the transfer IOUSBHostCITransferCompletionMessageControlDeviceAddress is populated in the control field with the device address associated with the transfer IOUSBHostCITransferCompletionMessageControlEndpointAddress is populated in the control field with the endpoint address associated with the transfer IOUSBHostCITransferCompletionMessageData0TransferLength is populated in the data0 field with the actual number of bytes transferred for the transfer IOUSBHostCITransferCompletionMessageData1TransferStructure is populated in the data1 field with the virtual address of the IOUSBHostCIMessage transfer structure that generated this event