Mac Developer Library

Developer

IOUSBControllerV2 Class Reference

Options
Deployment Target:

On This Page
Language:

IOUSBControllerV2

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

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.

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Not Applicable

Objective-C

@import Kernel;

Availability


Available in OS X v10.2 and later.
  • configure pipe zero of device zero, as IOUSBController, but also keeping note of high speed hub device is attached to.

    Declaration

    C++

    virtual IOReturn ConfigureDeviceZero( UInt8maxPacketSize, UInt8speed, USBDeviceAddresshub, intport);

    Parameters

    maxPacketSize

    max packet size for the pipe

    speed

    speed of the device kUSBDeviceSpeedLow, kUSBDeviceSpeedFull, kUSBDeviceSpeedHigh, kUSBDeviceSpeedSuper

    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.

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

    Declaration

    C++

    virtual IOReturn CreateDevice( IOUSBDevice *newDevice, USBDeviceAddressdeviceAddress, UInt8maxPacketSize, UInt8speed, UInt32powerAvailable, USBDeviceAddresshub, intport);

    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, kUSBDeviceSpeedSuper

    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.

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

    Declaration

    C++

    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

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

    Declaration

    C++

    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

  • Declaration

    C++

    virtual IOReturn OpenPipe( USBDeviceAddressaddress, UInt8speed, Endpoint *endpoint );

    Parameters

    address

    Address of the device on the USB bus

    speed

    of the device: kUSBDeviceSpeedLow, kUSBDeviceSpeedFull, kUSBDeviceSpeedHigh or kUSBDeviceSpeedSuper

    endpoint

    description of endpoint to connect to

    Discussion

    Open a pipe to the specified device endpoint

  • Declaration

    C++

    virtual IOReturn OpenPipe( USBDeviceAddressaddress, UInt8speed, Endpoint *endpoint );

    Parameters

    address

    Address of the device on the USB bus

    speed

    of the device: kUSBDeviceSpeedLow, kUSBDeviceSpeedFull, kUSBDeviceSpeedHigh or kUSBDeviceSpeedSuper

    endpoint

    description of endpoint to connect to

    Discussion

    Open a pipe to the specified device endpoint

  • Declaration

    C++

    virtual IOReturn OpenSSPipe( USBDeviceAddressaddress, UInt8speed, Endpoint *endpoint, UInt32maxStreams, UInt32maxBurstAndMult);

    Parameters

    address

    Address of the device on the USB bus

    speed

    of the device: kUSBDeviceSpeedLow, kUSBDeviceSpeedFull, kUSBDeviceSpeedHigh or kUSBDeviceSpeedSuper

    endpoint

    description of endpoint to connect to

    maxStreams

    maximum number of streams pipe supports

    maxBurstAndMult

    maximum number of bursts and burst multiplier

    Discussion

    Open a pipe to the specified device endpoint

  • Declaration

    C++

    virtual IOReturn OpenSSPipe( USBDeviceAddressaddress, UInt8speed, Endpoint *endpoint, UInt32maxStreams, UInt32maxBurstAndMult);

    Parameters

    address

    Address of the device on the USB bus

    speed

    of the device: kUSBDeviceSpeedLow, kUSBDeviceSpeedFull, kUSBDeviceSpeedHigh or kUSBDeviceSpeedSuper

    endpoint

    description of endpoint to connect to

    maxStreams

    maximum number of streams pipe supports

    maxBurstAndMult

    maximum number of bursts and burst multiplier

    Discussion

    Open a pipe to the specified device endpoint

  • Declaration

    C++

    virtual IOReturn ReadV2( IOMemoryDescriptor *buffer, USBDeviceAddressaddress, Endpoint *endpoint, IOUSBCompletionWithTimeStamp *completion, UInt32noDataTimeout, UInt32completionTimeout, IOByteCountreqCount );

    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

  • Declaration

    C++

    virtual IOReturn ReadStream( UInt32streamID, IOMemoryDescriptor *buffer, USBDeviceAddressaddress, Endpoint *endpoint, IOUSBCompletion *completion, UInt32noDataTimeout, UInt32completionTimeout, IOByteCountreqCount );

    Parameters

    streamID

    stream ID of the stream to read from

    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 a stream on a bulk endpoint

  • Declaration

    C++

    virtual IOReturn ReadStream( UInt32streamID, IOMemoryDescriptor *buffer, USBDeviceAddressaddress, Endpoint *endpoint, IOUSBCompletion *completion, UInt32noDataTimeout, UInt32completionTimeout, IOByteCountreqCount );

    Parameters

    streamID

    stream ID of the stream to read from

    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 a stream on a bulk endpoint

  • Declaration

    C++

    virtual IOReturn ReadV2( IOMemoryDescriptor *buffer, USBDeviceAddressaddress, Endpoint *endpoint, IOUSBCompletionWithTimeStamp *completion, UInt32noDataTimeout, UInt32completionTimeout, IOByteCountreqCount );

    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

  • Create an endpoint in the controller to do bulk transactions.

    Declaration

    C++

    virtual IOReturn UIMCreateBulkEndpoint( UInt8functionNumber, UInt8endpointNumber, UInt8direction, UInt8maxPacketSize, UInt16speed, USBDeviceAddresshighSpeedHub, inthighSpeedPort) = 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

  • Create an endpoint in the controller to do control transactions.

    Declaration

    C++

    virtual IOReturn UIMCreateControlEndpoint( UInt8functionNumber, UInt8endpointNumber, UInt16maxPacketSize, UInt8speed, USBDeviceAddresshighSpeedHub, inthighSpeedPort) = 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

  • Create an endpoint in the controller to do interrupt transactions.

    Declaration

    C++

    virtual IOReturn UIMCreateInterruptEndpoint( shortfunctionAddress, shortendpointNumber, UInt8direction, shortspeed, UInt16maxPacketSize, shortpollingRate, USBDeviceAddresshighSpeedHub, inthighSpeedPort) = 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

  • Create an endpoint in the controller to do Isochronous transactions.

    Declaration

    C++

    virtual IOReturn UIMCreateIsochEndpoint( shortfunctionAddress, shortendpointNumber, UInt32maxPacketSize, UInt8direction, USBDeviceAddresshighSpeedHub, inthighSpeedPort) = 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

  • Create an endpoint in the controller to do Isochronous transactions.

    Declaration

    C++

    virtual IOReturn UIMCreateIsochEndpoint( shortfunctionAddress, shortendpointNumber, UInt32maxPacketSize, UInt8direction, USBDeviceAddresshighSpeedHub, inthighSpeedPort, UInt8interval);

    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

  • Declaration

    C++

    virtual IOReturn UpdateDeviceAddress( USBDeviceAddress oldDeviceAddress, USBDeviceAddress newDeviceAddress, UInt8 speed, USBDeviceAddress hubAddress, int port);

    Parameters

    deviceAddress

    Address of the device on the USB bus

    speed

    of the device: kUSBDeviceSpeedLow, kUSBDeviceSpeedFull, kUSBDeviceSpeedHigh or kUSBDeviceSpeedSuper

    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

    Discussion

    Tell the controller about the new address of a device. Used when a device has been reset

  • Declaration

    C++

    virtual IOReturn WriteStream( UInt32streamID, IOMemoryDescriptor *buffer, USBDeviceAddressaddress, Endpoint *endpoint, IOUSBCompletion *completion, UInt32noDataTimeout, UInt32completionTimeout, IOByteCountreqCount );

    Parameters

    streamID

    stream ID of the stream to write to

    buffer

    place to get 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 emptied

    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

    Write to a stream on a bulk endpoint

  • Declaration

    C++

    virtual IOReturn WriteStream( UInt32streamID, IOMemoryDescriptor *buffer, USBDeviceAddressaddress, Endpoint *endpoint, IOUSBCompletion *completion, UInt32noDataTimeout, UInt32completionTimeout, IOByteCountreqCount );

    Parameters

    streamID

    stream ID of the stream to write to

    buffer

    place to get 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 emptied

    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

    Write to a stream on a bulk endpoint