IOKit/usb/IOUSBHostFamily.h Kernel.framework

@header IOUSBHostFamily.h @brief IOUSBHostFamily provides support for discovering, enumerating, and communicating with USB devices. @discussion Starting with Mac OS X El Capitan, IOUSBHostFamily serves as a replacement for IOUSBFamily. <h3>Architecture</h3> USB host controller hardware is managed by AppleUSBHostController subclasses such as AppleUSBXHCI and AppleUSBEHCI. Each AppleUSBHostController is the parent to one or more AppleUSBHostPort services, and each AppleUSBHostPort is able to enumerate a single IOUSBHostDevice service. IOUSBHostDevice is the parent to zero or more IOUSBHostInterface services, and IOUSBHostInterface provides access to zero or more IOUSBHostPipe objects. USB 3.0 and newer streaming-capable IOUSBHostPipe objects can generate one or more IOUSBHostStream objects. AppleUSBHostPort services provide a workloop that is dedicated for use by the port, its enumerated device, and any attached drivers. As such, drivers should not create or manage their own workloops. IOUSBHostDevice and IOUSBHostInterface services can be matched on and controlled by third-party drivers, and are documented in IOUSBHostDevice.h and IOUSBHostInterface.h. IOUSBHostPipe and IOUSBHostStream services share a common IOUSBHostIOSource base class, and are documented in IOUSBHostIOSource.h, IOUSBHostPipe.h, and IOUSBHostStream.h. AppleUSBHostController and AppleUSBHostPort should be considered opaque classes. <h3>Matching</h3> IOUSBHostDevice and IOUSBHostInterface matching uses the same properties as the deprecated IOUSBDevice and IOUSBInterface classes. See <a href="https://developer.apple.com/library/mac/qa/qa1076/_index.html">QA1076: Tips on USB driver matching for Mac OS X</a> for additional information. <h3>Power management</h3> IOUSBHostFamily supports more advanced power management capabilities, including pausing IO, and automatic suspend of idle devices. All of this functionality is guided by idle policies set on IOUSBHostInterface services and IOUSBHostPipe objects. The idle policy functionality allows most drivers to ignore suspend or resume events on the bus, and makes it unnecessary for them to actively participate in power management. <h4>Idle suspend</h4> By default, interfaces and pipes do not enable an idle policy, and the device will remain in the active (not suspended) state as long as the host machine is awake. To enable idle suspend, the driver controlling an IOUSBHostInterface must enable an idle policy with the <code>IOUSBHostInterface::setIdlePolicy</code> API. In the simple case of a device with only a single interface, when the interface's endpoints have no IO requests pending, the system will wait the time specified in the setIdlePolicy call, and then electrically suspend the device. A new IO request during the wait period will cancel the suspend, and a new IO request after the device has suspended will immediately resume the device and initiate the IO. In the more complex case of a device with multiple interfaces, a consensus idle policy must be calculated by finding the largest idle policy for all interfaces, excluding those which have not been opened by a driver. Selection of an idle policy depends on the individual device, and should factor in resume latency tolerance. The recommended idle policy for an interface is 50ms or larger. Idle suspend is disabled if a driver is the power child of the IOUSBHostDevice and resides in a power state with an input power requirement that does not include <code>kIOPMLowPower</code>. <h4>Pausing IO</h4> A more advanced approach to idle suspend allows the device to suspend while transfers are still pending. This is particularly useful for interfaces with interrupt IN endpoints that always have an IO pending, and otherwise would not idle suspend. To enable IO pause, endpoints that would otherwise keep the device in the active state must enable an idle policy with the <code>IOUSBHostPipe::setIdlePolicy</code> API. When an IOUSBHostPipe with an idle policy begins servicing a new IO, but does not complete it within the wait time specified in the idle policy, the IOUSBHostPipe is now considered idle and will not keep the device in the active state. Idle endpoints are still serviced on the bus, and the IOUSBHostPipe is capable of moving data even when idle. When all endpoints in the device have no pending IO requests or are idle, the idle suspend wait period begins as described above. If the idle suspend period elapses without any new IO requests that would cancel the suspend, IOUSBHostFamily will pause the transfers on the bus and suspend the device. IO requests are not aborted or returned to the driver when paused in this manner. After resuming the device due to a remote wake or a new IO request, the pending IO requests are resumed on the bus, and data movement can continue. If a large transfer is interrupted by a suspend, IOUSBHostFamily will combine the packets from before and after the suspend and return them as a single transfer result. Note that not all firmware supports a mid-transfer suspend/resume, and pausing IO should only be enabled for devices that have been tested for this use case. Control and isochronous IOUSBHostPipe objects never enable an idle policy, and pending IO on these endpoints will always prevent idle suspend. Selection of an idle policy depends on the individual endpoint, and should factor in resume latency tolerance and expected data transfer frequency. The recommended idle policy for IN-direction bulk and interrupt endpoints is 50ms or larger. Firmware must be capable of handling a mid-transfer suspend/resume, and should issue a remote wake when data is available to be read. Enabling an idle policy for OUT-direction bulk or interrupt endpoints is not generally recommended, but if enabled, firmware should have the ability to issue a remote wake when there is space in its endpoint buffer for additional data. <h4>System power state changes</h4> For devices that idle suspend, it may be necessary to perform IO as the system enters the sleep state, for example to enable wake-on-LAN for an Ethernet controller. Drivers that wish to perform this type of IO should call <code>IOService::registerInterestedDriver</code> on the PM root to be notified of system-level changes. During the <code>powerStateWillChangeTo</code> notification with a capability flag including <code>kIOPMSleepCapability</code>, the driver can initiate an IO request and resume the device. Once the driver acknowledges this <code>powerStateWillChangeTo</code> notification, the device may not be able to raise its power state until the system wakes. Attempting an IO request from other PM root <code>powerStateWillChangeTo</code> and <code>powerStateDidChangeTo</code> notifications may result in a deadlock waiting for a power state change. <h3>Comparison to IOUSBFamily</h3> Developers already familiar with IOUSBFamily can take advantage of new capabilities in IOUSBHostFamily that can simplify driver development and maintenace. <h4>Workloops</h4> IOUSBFamily provided a workloop for each controller, and all downstream devices shared that workloop. By contrast, each AppleUSBHostPort creates a workloop dedicated for its attached device, which significantly reduces lock contention and improves responsiveness for drivers attached to IOUSBHostDevice or IOUSBHostInterface services. Because the workloop is not shared across many unrelated services, driver developers are discouraged from creating an additional workloop. <h4>Synchronous IO from completion callbacks</h4> IOUSBFamily did not permit synchronous IO to be executed from a completion callback, but this restriction has been removed in IOUSBHostFamily. Driver developers can now issue a sequence of synchronous commands in a completion routine without chaining thread calls or using complex state machines. <h4>IO bookkeeping</h4> IOUSBHostFamily now tracks all outstanding IOs for an endpoint, and offers more predictable behavior when aborting transfers or terminating services. In most cases, driver developers no longer need to track the number of outstanding IOs, and can terminate their services with more determinism. <h3>Driver Recommendations</h3> <ul> <li>Do not create a separate workloop</li> <li>If joining the power plane, reside in a <code>kIOPMLowPower</code> state to enable idle suspend</li> <li>If supporting pausing IO, only enable an idle policy on bulk or interrupt IN endpoints</li> <li>If interested in system power state changes, call <code>registerInterestedDriver</code> on the PM root</li> </ul>

#define IOUSBHostFamily_IOUSBHostFamily_h 

typedef uint16_t tUSBHostDeviceAddress

typedef enum tEndpointDirection tEndpointDirection

typedef enum tEndpointType tEndpointType

typedef enum tEndpointUsageType tEndpointUsageType

typedef enum tEndpointSynchronizationType tEndpointSynchronizationType

typedef enum tDeviceRequestDirection tDeviceRequestDirection

typedef enum tDeviceRequestType tDeviceRequestType

typedef enum tDeviceRequestRecipient tDeviceRequestRecipient

static inline uint8_t makeDeviceRequestbmRequestType(
	tDeviceRequestDirection direction,
	tDeviceRequestType type,
	tDeviceRequestRecipient recipient
)

#define kUSBHostMessageUpdateIdlePolicy iokit_usbhost_msg(0x100)

#define kUSBHostMessageRemoteWake iokit_usbhost_msg(0x101)

#define kUSBHostMessageDeviceSuspend iokit_usbhost_msg(0x102)

#define kUSBHostMessageDeviceResume iokit_usbhost_msg(0x103)

#define kUSBHostMessagePortsCreated iokit_usbhost_msg(0x104)

#define kUSBHostMessageDeviceConnected iokit_usbhost_msg(0x105)

#define kUSBHostMessageDeviceDisconnected iokit_usbhost_msg(0x106)

#define kUSBHostMessageControllerPoweredOn iokit_usbhost_msg(0x107)

#define kUSBHostMessageNonInterruptIsochFrame iokit_usbhost_msg(0x108)

#define kUSBHostMessageInterfaceAlternateSetting iokit_usbhost_msg(0x109)

#define kUSBHostMessageDeviceLegacyCapture iokit_usbhost_msg(0x10A)

#define kUSBHostMessageControllerInterrupt iokit_usbhost_msg(0x10B)

#define kUSBHostMessageDeviceIdentify iokit_usbhost_msg(0x10C)

#define kUSBHostMessageDeviceRegister iokit_usbhost_msg(0x10D)

#define kUSBHostMessageDevicePreferredConfigurationChanged iokit_usbhost_msg(0x10E)

#define kUSBHostMessageInterruptIsochFrame iokit_usbhost_msg(0x10F)

#define kUSBLegacyMessagePortHasBeenSuspended iokit_usblegacy_err_msg(0x0d)

#define kUSBLegacyMessagePortHasBeenResumed iokit_usblegacy_err_msg(0x0b)

#define kUSBHostMessageOvercurrentCondition iokit_usblegacy_err_msg(0x13)

#define kUSBHostMessageNotEnoughPower iokit_usblegacy_err_msg(0x14)

#define kIOUSBHostMessageReallocateExtraCurrent iokit_usblegacy_err_msg(0x18)

#define kUSBHostMessageEndpointCountExceeded iokit_usblegacy_err_msg(0x19)

#define kUSBHostMessageDeviceCountExceeded iokit_usblegacy_err_msg(0x1a)

#define kUSBHostMessageUnsupportedConfiguration iokit_usblegacy_err_msg(0x1c)

#define kUSBHostMessageHubCountExceeded iokit_usblegacy_err_msg(0x1d)

#define kUSBHostMessageTDMLowBattery iokit_usblegacy_err_msg(0x1e)

typedef enum tUSBHostPortConnectable tUSBHostPortConnectable;

typedef enum tUSBHostConnectorType tUSBHostConnectorType;

typedef enum tUSBHostPowerSourceType tUSBHostPowerSourceType;

typedef enum tUSBLinkState tUSBLinkState;

typedef enum tUSBLPMExitLatency tUSBLPMExitLatency;

typedef enum tUSBDeviceLPMStatus tUSBDeviceLPMStatus;