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

IOUSBControllerV2

Inherits from:	IOUSBController
Declared In:	IOUSBControllerV2.h

Overview

Subclass of the IOUSBController to provide support for high speed devices and split transactions.

Discussion

The IOUSBController class provide sufficient functionality to work with full (12Mb/s) and low (1.5Mb/s) devices. IOUSBControllerV2 introduces the support for high (480Mb/s) speed devices from the USB 2.0 spec. In particular IOUSBControllerV2 indicates the high speed hub a full or low speed device is attached to so that split transactions can be directed to the hub at high speed to be forwarded to the full or low speed device by the hub. It also gives support for bulk endoints of greater than 256 bytes.

Functions

ConfigureDeviceZero: configure pipe zero of device zero, as IOUSBController, but also keeping note of high speed hub device is attached to.
CreateDevice: Create a new device as IOUSBController, making a note of the high speed hub device ID and port number the full/low speed device is attached to.
GetFrameNumberWithTime: Real Time A/V applications send and receive Iscohronous data scheduled on certain USB frame numbers. The clock for these frame numbers is independent of the system clock, and drivers need to synchronize these two clocks. This routine will return a system time which corresponds to the beginning of a USB frame number. It is not necessarily the currrent frame, but it will be a frame in the recent past (within the past minute). The jitter between the start of the USB frame and the system time will be as low as possible, but due to hardware interrupt latencies could be as high as 200 microseconds.
GetLowLatencyOptionsAndPhysicalMask: Low Latency transfers require that the client have access to the memory after the Isochronous I/O request has already been scheduled. This might be used, for example to fill in outgoing data "just in time." Some controllers, however, may have requirements which need to be followed in order to make sure that the memory buffer isn't moved after the call is made. This call will return an IOOptionBits and mach_vm_address_t which can be used in a call to IOBufferMemoryDescriptor::inTaskWithPhysicalMask which will help meet these requirements.
openPipe
OpenPipe
Read
ReadV2
UIMCreateBulkEndpoint: Create an endpoint in the controller to do bulk transactions.
UIMCreateControlEndpoint: Create an endpoint in the controller to do control transactions.
UIMCreateInterruptEndpoint: Create an endpoint in the controller to do interrupt transactions.
UIMCreateIsochEndpoint(short, short, UInt32, UInt8, USBDeviceAddress, int): Create an endpoint in the controller to do Isochronous transactions.
UIMCreateIsochEndpoint(short, short, UInt32, UInt8, USBDeviceAddress, int, UInt8): Create an endpoint in the controller to do Isochronous transactions.

ConfigureDeviceZero

configure pipe zero of device zero, as IOUSBController, but also keeping note of high speed hub device is attached to.

public

virtual IOReturn ConfigureDeviceZero(
    UInt8 maxPacketSize,
    UInt8 speed,
    USBDeviceAddress hub,
    int port);

Parameters

maxPacketSize: max packet size for the pipe
speed: speed of the device kUSBDeviceSpeedLow, kUSBDeviceSpeedFull, kUSBDeviceSpeedHigh
hub: USB ID of hub the device is immediatly attached to. (Not necessarily high speed)
port: port number of port the device is attached to.

CreateDevice

Create a new device as IOUSBController, making a note of the high speed hub device ID and port number the full/low speed device is attached to.

public

virtual IOReturn CreateDevice(
    IOUSBDevice *newDevice, 
    USBDeviceAddress deviceAddress, 
    UInt8 maxPacketSize, 
    UInt8 speed, 
    UInt32 powerAvailable, 
    USBDeviceAddress hub, 
    int port);

Parameters

newDevice: new device object to work with
deviceAddress: USB device ID
maxPacketSize: max packet size of endpoint zero
speed: speed of the device kUSBDeviceSpeedLow, kUSBDeviceSpeedFull, kUSBDeviceSpeedHigh
powerAvailable: power available to the device
hub: USB ID of hub the device is immediatly attached to. (Not necessarily high speed)
port: port number of port the device is attached to.

GetFrameNumberWithTime

Real Time A/V applications send and receive Iscohronous data scheduled on certain USB frame numbers. The clock for these frame numbers is independent of the system clock, and drivers need to synchronize these two clocks. This routine will return a system time which corresponds to the beginning of a USB frame number. It is not necessarily the currrent frame, but it will be a frame in the recent past (within the past minute). The jitter between the start of the USB frame and the system time will be as low as possible, but due to hardware interrupt latencies could be as high as 200 microseconds.

public

virtual IOReturn GetFrameNumberWithTime(
    UInt64 *frameNumber,
    AbsoluteTime *theTime);

Parameters

frameNumber: A pointer to a UInt64 in which to hold the USB frame number corresponding to the given system time.
theTime: A pointer to an AbsoluteTime corresponding to the system time at the beginning of the given USB frame number.

Return Value

returns kIOReturnSuccess if the method is implemented by the controller, otherwise kIOReturnUnsupported

GetLowLatencyOptionsAndPhysicalMask

Low Latency transfers require that the client have access to the memory after the Isochronous I/O request has already been scheduled. This might be used, for example to fill in outgoing data "just in time." Some controllers, however, may have requirements which need to be followed in order to make sure that the memory buffer isn't moved after the call is made. This call will return an IOOptionBits and mach_vm_address_t which can be used in a call to IOBufferMemoryDescriptor::inTaskWithPhysicalMask which will help meet these requirements.

public

virtual IOReturn GetLowLatencyOptionsAndPhysicalMask(
    IOOptionBits *optionBits,
    mach_vm_address_t *physicalMask);

Parameters

optionBits: Pointer to an an IOOptionBits. The only bit which may be returned is kIOMemoryPhysicallyContiguous. Other bits, e.g. direction bits, must be ORd in by the client as needed. This call replaces the old property based method of obtaining this information.
physicalMask: Pointer to a mach_vm_address_t which should be used in the call to IOBufferMemoryDescriptor::inTaskWithPhysicalMask and will guarantee that when the memory is wired down it will be accessible by both the client and the USB controller at the same time.

Return Value

returns kIOReturnSuccess if the method is implemented by the controller, otherwise kIOReturnUnsupported

openPipe

public

virtual IOReturn OpenPipe(
    USBDeviceAddress address, 
    UInt8 speed, 
    Endpoint *endpoint );

Parameters

address: Address of the device on the USB bus
speed: of the device: kUSBDeviceSpeedLow, kUSBDeviceSpeedFull or kUSBDeviceSpeedHigh
endpoint: description of endpoint to connect to

Discussion

Open a pipe to the specified device endpoint

OpenPipe

public

virtual IOReturn OpenPipe(
    USBDeviceAddress address, 
    UInt8 speed, 
    Endpoint *endpoint );

Parameters

address: Address of the device on the USB bus
speed: of the device: kUSBDeviceSpeedLow, kUSBDeviceSpeedFull or kUSBDeviceSpeedHigh
endpoint: description of endpoint to connect to

Discussion

Open a pipe to the specified device endpoint

Read

public

virtual IOReturn ReadV2(
    IOMemoryDescriptor *buffer, 
    USBDeviceAddress address, 
    Endpoint *endpoint, 
    IOUSBCompletionWithTimeStamp *completion, 
    UInt32 noDataTimeout, 
    UInt32 completionTimeout, 
    IOByteCount reqCount );

Parameters

buffer: place to put the transferred data
address: Address of the device on the USB bus
endpoint: description of endpoint
completion: describes action to take when buffer has been filled
noDataTimeout: number of milliseconds of no data movement before the request is aborted
completionTimeout: number of milliseonds after the command is on the bus in which it must complete
reqCount: number of bytes requested for the transfer (must not be greater than the length of the buffer)

Discussion

Read from an interrupt or bulk endpoint

ReadV2

public

virtual IOReturn ReadV2(
    IOMemoryDescriptor *buffer, 
    USBDeviceAddress address, 
    Endpoint *endpoint, 
    IOUSBCompletionWithTimeStamp *completion, 
    UInt32 noDataTimeout, 
    UInt32 completionTimeout, 
    IOByteCount reqCount );

Parameters

buffer: place to put the transferred data
address: Address of the device on the USB bus
endpoint: description of endpoint
completion: describes action to take when buffer has been filled
noDataTimeout: number of milliseconds of no data movement before the request is aborted
completionTimeout: number of milliseonds after the command is on the bus in which it must complete
reqCount: number of bytes requested for the transfer (must not be greater than the length of the buffer)

Discussion

Read from an interrupt or bulk endpoint

UIMCreateBulkEndpoint

Create an endpoint in the controller to do bulk transactions.

public

virtual IOReturn UIMCreateBulkEndpoint( 
    UInt8 functionNumber, 
    UInt8 endpointNumber, 
    UInt8 direction, 
    UInt8 speed, 
    UInt16 maxPacketSize, 
    USBDeviceAddress highSpeedHub, 
    int highSpeedPort) = 0;

Parameters

functionNumber: USB device ID of device
endpointNumber: endpoint address of the endpoint in the device
direction: Direction of data flow. kUSBIn or kUSBOut
maxPacketSize: maximum packet size of this endpoint
speed: speed of the device kUSBDeviceSpeedFull, kUSBDeviceSpeedHigh
highSpeedHub: If speed is not kUSBDeviceSpeedHigh, the address of the high speed hub to address split transactions to.
highSpeedPort: If speed is not kUSBDeviceSpeedHigh, the hub port to address split transactions to

UIMCreateControlEndpoint

Create an endpoint in the controller to do control transactions.

public

virtual IOReturn UIMCreateControlEndpoint( 
    UInt8 functionNumber, 
    UInt8 endpointNumber, 
    UInt16 maxPacketSize, 
    UInt8 speed, 
    USBDeviceAddress highSpeedHub, 
    int highSpeedPort) = 0;

Parameters

functionNumber: USB device ID of device
endpointNumber: endpoint address of the endpoint in the device
maxPacketSize: maximum packet size of this endpoint
speed: speed of the device kUSBDeviceSpeedLow, kUSBDeviceSpeedFull, kUSBDeviceSpeedHigh
highSpeedHub: If speed is not kUSBDeviceSpeedHigh, the address of the high speed hub to address split transactions to.
highSpeedPort: If speed is not kUSBDeviceSpeedHigh, the hub port to address split transactions to

UIMCreateInterruptEndpoint

Create an endpoint in the controller to do interrupt transactions.

public

virtual IOReturn UIMCreateInterruptEndpoint( 
    short functionAddress, 
    short endpointNumber, 
    UInt8 direction, 
    short speed, 
    UInt16 maxPacketSize, 
    short pollingRate, 
    USBDeviceAddress highSpeedHub, 
    int highSpeedPort) = 0;

Parameters

functionAddress: USB device ID of device
endpointNumber: endpoint address of the endpoint in the device
direction: Direction of data flow. kUSBIn or kUSBOut
speed: speed of the device kUSBDeviceSpeedLow, kUSBDeviceSpeedFull, kUSBDeviceSpeedHigh
maxPacketSize: maximum packet size of this endpoint
pollingRate: The maximum polling interval from the endpoint descriptor.
highSpeedHub: If speed is not kUSBDeviceSpeedHigh, the address of the high speed hub to address split transactions to.
highSpeedPort: If speed is not kUSBDeviceSpeedHigh, the hub port to address split transactions to

UIMCreateIsochEndpoint(short, short, UInt32, UInt8, USBDeviceAddress, int)

Create an endpoint in the controller to do Isochronous transactions.

public

virtual IOReturn UIMCreateIsochEndpoint( 
    short functionAddress, 
    short endpointNumber, 
    UInt32 maxPacketSize, 
    UInt8 direction, 
    USBDeviceAddress highSpeedHub, 
    int highSpeedPort) = 0;

Parameters

functionAddress: USB device ID of device
endpointNumber: endpoint address of the endpoint in the device
maxPacketSize: maximum packet size of this endpoint
direction: Specifies direction for the endpoint. kUSBIn or KUSBOut.
highSpeedHub: If non zero, this is a full speed device, the address of the high speed hub to address split transactions to.
highSpeedPort: If highSpeedHub is non zero, the hub port to address split transactions to

UIMCreateIsochEndpoint(short, short, UInt32, UInt8, USBDeviceAddress, int, UInt8)

Create an endpoint in the controller to do Isochronous transactions.

public

virtual IOReturn UIMCreateIsochEndpoint( 
    short functionAddress, 
    short endpointNumber, 
    UInt32 maxPacketSize, 
    UInt8 direction, 
    USBDeviceAddress highSpeedHub, 
    int highSpeedPort, 
    UInt8 interval);

Parameters

functionAddress: USB device ID of device
endpointNumber: endpoint address of the endpoint in the device
maxPacketSize: maximum packet size of this endpoint
direction: Specifies direction for the endpoint. kUSBIn or KUSBOut.
highSpeedHub: If non zero, this is a full speed device, the address of the high speed hub to address split transactions to.
highSpeedPort: If highSpeedHub is non zero, the hub port to address split transactions to
interval: The encoded interval value from the endpoint descriptor

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