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:
| P1 | Address of buffer in which to store results | ||
| P2 | Size of buffer in bytes | ||
| P3 | Flag USB$_SHORT_XFER_OK allows fewer bytes than requested to complete the I/O | ||
| P4 | Pipe 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 bytes | OpenVMS 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:
| P1 | Address of buffer from which to read date | ||
| P2 | Size of buffer in bytes | ||
| P3 | Flag USB$_SHORT_XFER_OK allows fewer bytes than requested to complete the I/O | ||
| P4 | Pipe 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:
| P1 | AST routine address | ||
| P2 | AST parameter | ||
| P3 | UG$_ENABLE_AST | ||
| P4 | Access 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:
| P1 | Unused | ||
| P2 | Unused | ||
| P3 | UG$_ASSOCIATE associates a channel to a pipe; UG$_DISASSOCIATE breaks an association | ||
| P4 | Pipe 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:
| P1 | Unused | ||
| P2 | Pipe state values are UG$_PIPE_STATE_ACTIVE, UG$_PIPE_STATE_STALED, and UG$_PIPE_STATE_IDLE. | ||
| P3 | UG$_SET_PIPE_STATE | ||
| P4 | Pipe 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:
| P1 | Address of setup data; see the following table. |
| P2 | Must be 8. |
| P3 | UG$_DEVICE_REQUEST. |
| P4 | Pipe handle. |
| P5 | Address of buffer to receive data if there is a data phase. |
| P6 | Flag USB$_SHORT_XFER_OK allows fewer bytes than requested to complete the I/O. |
The following table shows the P1 buffer:
| Offset | Field | Size | Description | ||||||||||||||||||||||||||||
| 0 | bmRequestType | 1 | Characteristics of the request:
| ||||||||||||||||||||||||||||
| 1 | bRequest | 1 | See Table 9–3 in the USB Specification. | ||||||||||||||||||||||||||||
| 2 | wValue | 2 | Word sized field varies according to the request. | ||||||||||||||||||||||||||||
| 4 | wIndex | 2 | Word sized field varies according to the request. | ||||||||||||||||||||||||||||
| 6 | wlength | 2 | Number 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:
| P1 | Address of longword to store the number of pipes |
| P2 | Size of buffer in bytes must be 4. |
| P3 | UG$_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:
| P1 | Address of buffer to hold pipe handles |
| P2 | Size of buffer in bytes |
| P3 | UG$_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:
| P1 | Address of buffer to store pipe direction. Legal returns are USB$_XFER_OUT, USB$XFER_IN, and USB$XFER_SETUP. |
| P2 | Must be 4. |
| P3 | UG$_GET_PIPE_TYPE |
| P4 | Pipe 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:
| P1 | Address 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.). |
| P2 | Must be 4. |
| P3 | UG$_GET_PIPE_TYPE |
| P4 | Pipe 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:
| P1 | Address 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. |
| P2 | Must be 4. |
| P3 | UG$_GET_PIPE_STATE |
| P4 | Pipe 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:
| P1 | Address of buffer to hold pipe size |
| P2 | Must be 4. |
| P3 | UG$_GET_PIPE_SIZE |
| P4 | Pipe 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:
| P1 | Address of buffer to receive the device descriptor. The format of the buffer is shown in the table, Format of the Device Descriptor. |
| P2 | Size of buffer in bytes. |
| P3 | UG$_GET_PIPE_SIZE |
| P4 | UG$_GET_DEVICE_DESCRIPTOR |
Table E-1 Format of the Device Descriptor
| unsigned char | ug$b_blength | Descriptor length in bytes |
| unsigned char | ug$b_bdescriptortype | Descriptor type constant 0X01 |
| unsigned short int | ug$w_bcdusb | BCD-encoded specification release number |
| unsigned char | ug$b_bdeviceclass | Device class code |
| unsigned char | ug$b_bdevicesubclass | Device sub class code |
| unsigned char | ug$b_bdeviceprotocol | Device protocol |
| unsigned char | ug$b_bmaxpacket | Maximum packet size for control pipe; 8, 16, 32, 64 are valid. |
| unsigned short int | ug$w_idvendor | Vendor ID |
| unsigned short int | ug$w_idproduct | Product ID |
| unsigned short int | ug$w_bcddevice | BCD encoded device release number. |
| unsigned char | ug$b_imanufacturer | Index of string descriptor that describes the manufacturer. |
| unsigned char | ug$b_iproduct | Index of string descriptor that describes the product. |
| unsigned char | ug$b_iserailnumber | ndex of string descriptor of device serial number. |
| unsigned char | ug$b_bnumconfigurations | Number 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:
| P1 | Address of buffer to receive the interface descriptor. The format of the buffer is shown in the table, Format of the Interface Descriptor. |
| P2 | Size of buffer in bytes. |
| P3 | UUG$_GET_INTERFACE_DESCRIPTOR |
Table E-2 Format of the Interface Descriptor
| unsigned char | ug$b_blength | Descriptor length in bytes |
| unsigned char | ug$b_bdescriptortype | Descriptor type constant 0X04 |
| unsigned char | ug$b_binterfacenumber | Zero-based count of this interface |
| unsigned char | ug$b_balternatesetting | Used to select alternate setting for the interface |
| unsigned char | ug$b_bnumendpoints | Number of endpoints for the interface |
| unsigned char | ug$b_binterfaceclass | Interface class code |
| unsigned char | ug$b_binterfacesubclass | Interface subclass code |
| unsigned char | ug$b_binterfaceprotocol | Interface protocol |
| unsigned char | ug$b_iinterface | Index of string descriptor that describes this interface |