HP OpenVMS I/O User’s Reference Manual: OpenVMS Version 8.4 > Appendix E Programming USB Generic Drivers

E.3 Supported $QIO Functions

This section describes the $QIO function codes that the generic driver supports.

IO$_READxBLK

The driver treats read virtual, logical, and physical in the same way. Note that normal $QIO processing rules for logical and physical block I/O still apply and are enforced by the $QIO dispatching code. When a read is queued to a pipe, the driver checks to see if there is an outstanding I/O for that pipe. If one is found, the request is placed in the I/O queue of the pipe. If no I/O is outstanding, the driver starts the I/O queue for that pipe.

The driver treats parameters from the $QIO P1-P6 as follows:

P1Address of buffer in which to store results
P2Size of buffer in bytes
P3Flag USB$_SHORT_XFER_OK allows fewer bytes than requested to complete the I/O
P4Pipe handle

Status return codes are the usual OpenVMS ones for I/O devices. Because USB device status codes are a longword in length, after first checking the status word of the I/O status block, the application must check the second longword of the I/O status block. The second longword contains the USB status code for the request. The status word in the IOSB can indicate success but have a USB error in the second longword, shown as follows:

Xfer size bytesOpenVMS Status
USB Status

IO$_WRITExBLK

The driver treats virtual, logical, and physical writes in the same way. Note that normal $QIO processing rules for logical and physical block I/O still apply and are enforced by the $QIO dispatching code.

When a write is queued to a pipe, the driver checks to see if there is an outstanding I/O for that pipe. If one is found, the request is placed in the I/O queue of the pipe. If no I/O is outstanding, the driver starts an I/O queue for that pipe.

The driver treats parameters from the $QIO P1-P6 as follows:

P1Address of buffer from which to read date
P2Size of buffer in bytes
P3Flag USB$_SHORT_XFER_OK allows fewer bytes than requested to complete the I/O
P4Pipe handle

Status return codes are the usual OpenVMS ones for I/O devices. Because USB device status codes are a longword in length, after first checking the status word of the I/O status block, the application must check the second longword of the I/O status block. The second longword contains the USB status code for the request. (The status word in the IOSB can indicate success but have a USB error in the second longword.)

IO$_SETMODE/CHAR

Enable Unplug notification AST: This item allows an application to associate an AST that is delivered if a device is unplugged. You can use any channel to enable this AST. HP recommends that you use the control channel for this AST. To cancel the AST, do not supply an AST routine address and parameter.

The driver treats parameters from the $QIO P1-P6 as follows:

P1AST routine address
P2AST parameter
P3UG$_ENABLE_AST
P4Access mode

Associate channel: Use this command to associate an OpenVMS channel to a pipe and to break the association of a channel to a pipe.

The driver treats parameters from the $QIO P1-P6 as follows:

P1Unused
P2Unused
P3UG$_ASSOCIATE associates a channel to a pipe; UG$_DISASSOCIATE breaks an association
P4Pipe handle

Set pipe state: Use this command to set the state of a pipe.

The driver treats parameters from the $QIO P1-P6 as follows:

P1Unused
P2Pipe state values are UG$_PIPE_STATE_ACTIVE, UG$_PIPE_STATE_STALED, and UG$_PIPE_STATE_IDLE.
P3UG$_SET_PIPE_STATE
P4Pipe handle

Send a control request:Use this command to send a device request to the device control pipe. For more details about device requests, see section 9.3 USB 1.1 or 2.0 specifications at http://www.usb.org/developers/docs/.

The driver treats parameters from the $QIO P1-P6 as follows:

P1Address of setup data; see the following table.
P2Must be 8.
P3UG$_DEVICE_REQUEST.
P4Pipe handle.
P5Address of buffer to receive data if there is a data phase.
P6Flag USB$_SHORT_XFER_OK allows fewer bytes than requested to complete the I/O.

The following table shows the P1 buffer:

OffsetFieldSizeDescription
0bmRequestType1Characteristics of the request:
B7: 
 0–Host to device
 1–Device to host

B6..5Type
 0–Standard
 1–Class
 2–Vendor
 3–Reserved

B4..0Recipient
 0–Device
 1–Interface
 2–Endpoint
 3–Other
 4...31–Reserved

1bRequest1See Table 9–3 in the USB Specification.
2wValue2Word sized field varies according to the request.
4wIndex2Word sized field varies according to the request.
6wlength2Number of bytes to transfer if there is a data phase.

IO$_SENSEMODE/CHAR

Get number of pipes

Use this command to obtain the number of pipes. Make this the first operation that an application performs using the driver. Use the channel for the control connection for this operation.

The driver treats parameters from the $QIO P1-P6 as follows:

P1Address of longword to store the number of pipes
P2Size of buffer in bytes must be 4.
P3UG$_GET_PIPE_COUNT

Get pipe handles

Use this command to obtain all the pipe handles. The buffer must have one quadword for each pipe of the device.

The driver treats parameters from the $QIO P1-P6 as follows:

P1Address of buffer to hold pipe handles
P2Size of buffer in bytes
P3UG$_GET_PIPE_HANDLES

Get pipe direction

Use this command to obtain the direction of a pipe associated with its handle.

The driver treats parameters from the $QIO P1-P6 as follows:

P1Address of buffer to store pipe direction. Legal returns are USB$_XFER_OUT, USB$XFER_IN, and USB$XFER_SETUP.
P2Must be 4.
P3UG$_GET_PIPE_TYPE
P4Pipe handle

Get pipe type

Use this command to obtain the type of pipe associated with its handle.

The driver treats parameters from the $QIO P1-P6 as follows:

P1Address of buffer to store pipe type. Types are UG$_PIPE_TYPE_CONTROL, UG$_PIPE_TYPE_BULK, UG$_PIPE_TYPE_INTERRUPT, UG$_PIPE_TYPE_ISOCHRONOUS (The last type is currently not supported.).
P2Must be 4.
P3UG$_GET_PIPE_TYPE
P4Pipe handle

Get pipe state

Use this command to obtain the state of the pipe.

The driver treats parameters from the $QIO P1-P6 as follows:

P1Address of buffer to hold the pipe state. Values of the pipe state are UG$_PIPE_STATE_ACTIVE, UG$_PIPE_STATE_STALLED, UG$_PIPE_STATE_IDLE.
P2Must be 4.
P3UG$_GET_PIPE_STATE
P4Pipe handle

Get pipe size

Use this command to obtain the size of the largest transfer on the pipe. (This is really the largest size that is sent on the bus in one transfer.) Actual requests can be larger. The driver takes care of splitting the transfer up into appropriately sized bus transfers.

The driver treats parameters from the $QIO P1-P6 as follows:

P1Address of buffer to hold pipe size
P2Must be 4.
P3UG$_GET_PIPE_SIZE
P4Pipe handle

Get pipe descriptor

Use this routine is used to obtain the device descriptor from the device.

The driver treats parameters from the $QIO P1-P6 as follows:

P1Address of buffer to receive the device descriptor. The format of the buffer is shown in the table, Format of the Device Descriptor.
P2Size of buffer in bytes.
P3UG$_GET_PIPE_SIZE
P4UG$_GET_DEVICE_DESCRIPTOR

Table E-1 Format of the Device Descriptor

unsigned charug$b_blengthDescriptor length in bytes
unsigned charug$b_bdescriptortypeDescriptor type constant 0X01
unsigned short intug$w_bcdusbBCD-encoded specification release number
unsigned charug$b_bdeviceclassDevice class code
unsigned charug$b_bdevicesubclassDevice sub class code
unsigned charug$b_bdeviceprotocolDevice protocol
unsigned charug$b_bmaxpacketMaximum packet size for control pipe; 8, 16, 32, 64 are valid.
unsigned short intug$w_idvendorVendor ID
unsigned short intug$w_idproductProduct ID
unsigned short intug$w_bcddeviceBCD encoded device release number.
unsigned charug$b_imanufacturerIndex of string descriptor that describes the manufacturer.
unsigned charug$b_iproductIndex of string descriptor that describes the product.
unsigned charug$b_iserailnumberndex of string descriptor of device serial number.
unsigned charug$b_bnumconfigurationsNumber of possible device configurations.

 

Get interface descriptor

Use this command to obtain the interface descriptor from the device.

The driver treats parameters from the $QIO P1-P6 as follows:

P1Address of buffer to receive the interface descriptor. The format of the buffer is shown in the table, Format of the Interface Descriptor.
P2Size of buffer in bytes.
P3UUG$_GET_INTERFACE_DESCRIPTOR

Table E-2 Format of the Interface Descriptor

unsigned charug$b_blengthDescriptor length in bytes
unsigned charug$b_bdescriptortypeDescriptor type constant 0X04
unsigned charug$b_binterfacenumberZero-based count of this interface
unsigned charug$b_balternatesettingUsed to select alternate setting for the interface
unsigned charug$b_bnumendpointsNumber of endpoints for the interface
unsigned charug$b_binterfaceclassInterface class code
unsigned charug$b_binterfacesubclassInterface subclass code
unsigned charug$b_binterfaceprotocolInterface protocol
unsigned charug$b_iinterfaceIndex of string descriptor that describes this interface