Comtrol eCos - Manual (Page 695)

Receiving Data from the Host
Name
usbs_start_rx_buffer — Receiving Data from the Host
Synopsis
#include < cyg/io/usb/usbs.h >
void usbs_start_rx_buffer(usbs_rx_endpoint* ep, unsigned char* buffer, int length, void
(*)(void*,int) complete_fn, void * complete_data);
void usbs_start_rx(usbs_rx_endpoint* ep);
Description
usbs_start_rx_buffer is a USB-specific function to accept a transfer from host to peripheral. It can be used
for bulk, interrupt or isochronous transfers, but not for control messages. Instead those involve manipulating the
usbs_control_endpoint data structure directly. The function takes five arguments:
1. The first argument identifies the specific endpoint that should be used. Different USB devices will support
different sets of endpoints and the device driver will provide appropriate data structures. The device driver’s
documentation should be consulted for details of which endpoints are available.
2. The buffer and length arguments control the actual transfer. USB device drivers are not expected to
perform any buffering or to support partial transfers, so the length specified should correspond to the maximum
transfer that is currently possible and the buffer should be at least this large. For isochronous transfers the USB
specification imposes an upper bound of 1023 bytes, and a smaller limit may be set in the
enumeration data .
Interrupt transfers are similarly straightforward with an upper bound of 64 bytes, or less as per the enumeration
data. Bulk transfers are more complicated because they can involve multiple 64-byte packets plus a terminating
packet of less than 64 bytes, so there is no predefined limit on the transfer size. Instead it is left to higher-level
protocols to specify an appropriate upper bound.
One technique that may work for bulk transfers is to exploit the fact that such transfers happen in 64-byte
packets: it may be possible to receive 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 receive 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 this technique should be avoided.
3. usbs_start_rx_buffer is non-blocking. It merely starts the receive operation, and does not wait for com-
pletion. At some later point the USB device driver will invoke the completion function parameter with two
arguments: the completion data defined by the last parameter and a result field. A result >=
0 indicates a
successful transfer of that many bytes, which may be less than the upper bound imposed by the length
argument. A result < 0 indicates an error. The most likely errors are -EPIPE to indicate that the connection
591