/dev/usb0c +/dev/usb1r +/dev/usb2w |
USB device drivers provide two ways of transferring data between host +and peripheral. The first involves USB-specific functionality such as +usbs_start_rx_buffer. +This provides non-blocking I/O: a transfer is started, and some time +later the device driver will call a supplied completion function. The +second uses the conventional I/O model: there are entries in the +device table corresponding to the various endpoints. Standard calls +such as open can then be used to get a suitable +handle. Actual I/O happens via blocking read and +write calls. In practice the blocking operations +are simply implemented using the underlying non-blocking +functionality.
Each endpoint will have its own devtab entry. The exact names are +controlled by the device driver package, but typically the root will +be /dev/usb. This is followed by one or more +decimal digits giving the endpoint number, followed by +c for a control endpoint, r for +a receive endpoint (host to peripheral), and w for +a transmit endpoint (peripheral to host). If the target hardware +involves more than one USB device then different roots should be used, +for example /dev/usb0c and +/dev/usb1_0c. This may require explicit +manipulation of device driver configuration options by the application +developer.
At present the devtab entry for a control endpoint does not support +any I/O operations.
cyg_io_write and similar functions in +higher-level packages can be used to perform a transfer from +peripheral to host. Successive write operations will not be coalesced. +For example, when doing a 1000 byte write to an endpoint that uses the +bulk transfer protocol this will involve 15 full-size 64-byte packets +and a terminating 40-byte packet. USB device drivers are not expected +to do any locking, and if higher-level code performs multiple +concurrent write operations on a single endpoint then the resulting +behaviour is undefined.
A USB write operation will never transfer less +data than specified. It is the responsibility of higher-level code to +ensure that the amount of data being transferred is acceptable to the +host-side code. Usually this will be defined by a higher-level +protocol. If an attempt is made to transfer more data than the host +expects then the resulting behaviour is undefined.
There are two likely error conditions. EPIPE +indicates that the connection between host and target has been broken. +EAGAIN indicates that the endpoint has been +stalled, either at the request of the host or by other activity +inside the peripheral.
cyg_io_read and similar functions in higher-level +packages can be used to perform a transfer from host to peripheral. +This should be a complete transfer: higher-level protocols should +define an upper bound on the amount of data being transferred, and the +read operation should involve at least this +amount of data. The return value will indicate the actual transfer +size, which may be less than requested.
Some device drivers may support partial reads, but USB device drivers +are not expected to perform any buffering because that involves both +memory and code overheads. One technique that may work for bulk +transfers is to exploit the fact that such transfers happen in 64-byte +packets. It is possible to read an initial 64 +bytes, corresponding to the first packet in the transfer. These 64 +bytes can then be examined to determine the total transfer size, and +the remaining data can be transferred in another +read operation. This technique is not guaranteed +to work with all USB hardware. Also, if the delay between accepting +the first packet and the remainder of the transfer is excessive then +this could cause timeout problems for the host-side software. For +these reasons the use of partial reads should be avoided.
There are two likely error conditions. EPIPE +indicates that the connection between host and target has been broken. +EAGAIN indicates that the endpoint has been +stalled, either at the request of the host or by other activity +inside the peripheral.
USB device drivers are not expected to do any locking. If higher-level +code performs multiple concurrent read operations on a single endpoint +then the resulting behaviour is undefined.
Typical USB device drivers will not provide any support for +select. Consider bulk transfers from the host to +the peripheral. At the USB device driver level there is no way of +knowing in advance how large a transfer will be, so it is not feasible +for the device driver to buffer the entire transfer. It may be +possible to buffer part of the transfer, for example the first 64-byte +packet, and copy this into application space at the start of a +read, but this adds code and memory overheads. +Worse, it means that there is an unknown but potentially long delay +between a peripheral accepting the first packet of a transfer and the +remaining packets, which could confuse or upset the host-side +software.
With some USB hardware it may be possible for the device driver to +detect OUT tokens from the host without actually accepting the data, +and this would indicate that a read is likely to +succeed. However, it would not be reliable since the host-side I/O +operation could time out. A similar mechanism could be used to +implement select for outgoing data, but again +this would not be reliable.
Some device drivers may provide partial support for +select anyway, possibly under the control of a +configuration option. The device driver's documentation should be +consulted for further information. It is also worth noting that the +USB-specific non-blocking API can often be used as an alternative to +select.
There are no set_config or +get_config (also known as +ioctl) operations defined for USB devices. +Some device drivers may provide hardware-specific facilities this way.
Note: Currently the USB-specific functions related to halted endpoints cannot be accessed readily +via devtab entries. This functionality should probably be made +available via set_config and +get_config. It may also prove useful to provide +a get_config operation that maps from the +devtab entries to the underlying endpoint data structures.
The devtab entries are optional. If the USB device is accessed +primarily by class-specific code such as the USB-ethernet package and +that package uses the USB-specific API directly, the devtab entries +are redundant. Even if application code does need to access the USB +device, the non-blocking API may be more convenient than the blocking +I/O provided via the devtab entries. In these cases the devtab entries +serve no useful purpose, but they still impose a memory overhead. It +is possible to suppress the presence of these entries by disabling the +configuration option +CYGGLO_IO_USB_SLAVE_PROVIDE_DEVTAB_ENTRIES.