Comtrol eCos - Manual (Page 699)

Sending Data to the Host
Name
usbs_start_tx_buffer — Sending Data to the Host
Synopsis
#include < cyg/io/usb/usbs.h >
void usbs_start_tx_buffer(usbs_tx_endpoint* ep, const unsigned char* buffer, int
length, void (*)(void*,int) complete_fn, void * complete_data);
void usbs_start_tx(usbs_tx_endpoint* ep);
Description
usbs_start_tx_buffer is a USB-specific function to transfer data from peripheral to host. 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 allowed to modify
the buffer during the transfer, so the data can reside in read-only memory. The transfer will be for all the data
specified, and it is the responsibility of higher-level code to make sure that the host is expecting this amount
of data. For isochronous transfers the USB specification imposes an upper bound of 1023 bytes, but a smaller
limit may be set in the
enumeration data . Interrupt transfers have 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 the basic USB specification does not impose an upper limit
on the total transfer size. Instead it is left to higher-level protocols to specify an appropriate upper bound. If
the peripheral attempts to send more data than the host is willing to accept then the resulting behaviour is
undefined and may well depend on the specific host operating system being used.
For bulk transfers, the USB device driver or the underlying hardware will automatically split the transfer up
into the appropriate number of full-size 64-byte packets plus a single terminating packet, which may be 0
bytes.
3. usbs_start_tx_buffer is non-blocking. It merely starts the transmit 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. This result will be either an
error code <
0 , or the amount of data transferred which should correspond to the length argument. The
most likely errors are -EPIPE to indicate that the connection between the host and the target has been broken,
and -EAGAIN for when the endpoint has been halted . Specific USB device drivers may define additional error
conditions.
595