usbs.sgml

开放源码实时操作系统源码.

</para>
</refsect2>

<refsect2><title><function>read</function> operations</title>
<para>
<function>cyg_io_read</function> 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
<function>read</function> operation should involve at least this
amount of data. The return value will indicate the actual transfer
size, which may be less than requested.
</para>
<para>
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 <function>read</function> 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
<function>read</function> 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.
</para>
<para>
There are two likely error conditions. <literal>EPIPE</literal>
indicates that the connection between host and target has been broken.
<literal>EAGAIN</literal> indicates that the endpoint has been
stalled, either at the request of the host or by other activity
inside the peripheral.
</para>
<para>
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.
</para>
</refsect2>

<refsect2><title><function>select</function> operations</title>
<para>
Typical USB device drivers will not provide any support for
<function>select</function>. 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
<function>read</function>, 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.
</para>
<para>
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  <function>read</function> 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 <function>select</function> for outgoing data, but again
this would not be reliable.
</para>
<para>
Some device drivers may provide partial support for
<function>select</function> 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
<function>select</function>.
</para>
</refsect2>

<refsect2><title><function>get_config</function> and
<function>set_config</function> operations</title>
<para>
There are no <function>set_config</function> or
<function>get_config</function> (also known as
<function>ioctl</function>) operations defined for USB devices.
Some device drivers may provide hardware-specific facilities this way. 
</para>
<note>
<para>
Currently the USB-specific functions related to <link
linkend="usbs-halt">halted endpoints</link> cannot be accessed readily
via devtab entries. This functionality should probably be made
available via <function>set_config</function> and
<function>get_config</function>. It may also prove useful to provide
a <function>get_config</function> operation that maps from the
devtab entries to the underlying endpoint data structures.
</para>
</note>
</refsect2>

<refsect2><title>Presence</title>
<para>
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
<literal>CYGGLO_IO_USB_SLAVE_PROVIDE_DEVTAB_ENTRIES</literal>.
</para>
</refsect2>
</refsect1>
</refentry>

<!-- }}} -->
<!-- {{{ usbs_start_rx_buffer()         -->

<refentry id="usbs-start-rx">
<refmeta>
<refentrytitle>Receiving Data from the Host</refentrytitle>
</refmeta>
<refnamediv>
<refname><function>usbs_start_rx_buffer</function></refname>
<refpurpose>Receiving Data from the Host</refpurpose>
</refnamediv>

<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>
#include &lt;cyg/io/usb/usbs.h&gt;
</funcsynopsisinfo>
<funcprototype>
<funcdef>void <function>usbs_start_rx_buffer</function></funcdef>
<paramdef>usbs_rx_endpoint* <parameter>ep</parameter></paramdef>
<paramdef>unsigned char* <parameter>buffer</parameter></paramdef>
<paramdef>int <parameter>length</parameter></paramdef>
<paramdef>void (*)(void*,int) <parameter>complete_fn</parameter></paramdef>
<paramdef>void * <parameter>complete_data</parameter></paramdef>
</funcprototype>

<funcprototype>
<funcdef>void <function>usbs_start_rx</function></funcdef>
<paramdef>usbs_rx_endpoint* <parameter>ep</parameter></paramdef>
</funcprototype>

</funcsynopsis>
</refsynopsisdiv>

<refsect1><title><function>Description</function></title>
<para>
<function>usbs_start_rx_buffer</function> 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 <link
linkend="usbs-control"><structname>usbs_control_endpoint</structname></link>
data structure directly. The function takes five arguments:
</para>
<orderedlist>
<listitem>
<para>
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.
</para>
</listitem>
<listitem>
<para>
The <parameter>buffer</parameter> and <parameter>length</parameter>
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 <link
linkend="usbs-enum-endpoint">enumeration data</link>. 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.
</para>
<para>
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.
</para>
</listitem>
<listitem>
<para>
<function>usbs_start_rx_buffer</function> is non-blocking. It merely
starts the receive operation, and does not wait for completion. 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 &gt;=
<literal>0</literal> indicates a successful transfer of that many
bytes, which may be less than the upper bound imposed by the
<parameter>length</parameter> argument. A result &lt;
<literal>0</literal> indicates an error. The most likely errors are
<literal>-EPIPE</literal> to indicate that the connection between the
host and the target has been broken, and <literal>-EAGAIN</literal>
for when the endpoint has been <link
linkend="usbs-halt">halted</link>. Specific USB device drivers may
specify additional error conditions.
</para>
</listitem>
</orderedlist>
<para>
The normal sequence of events is that the USB device driver will
update the appropriate hardware registers. At some point after that
the host will attempt to send data by transmitting an OUT token
followed by a data packet, and since a receive operation is now in
progress the data will be accepted and ACK'd. If there were no receive
operation then the peripheral would instead generate a NAK. The USB
hardware will generate an interrupt once the whole packet has been
received, and the USB device driver will service this interrupt and
arrange for a DSR to be called. Isochronous and interrupt transfers
involve just a single packet. However, bulk transfers may involve
multiple packets so the device driver has to check whether the packet
was a full 64 bytes or whether it was a terminating packet of less
than this. When the device driver DSR detects a complete transfer it
will inform higher-level code by invoking the supplied completion
function.
</para>
<para>
This means that the completion function will normally be invoked by a
DSR and not in thread context - although some USB device drivers may
have a different implementation. Therefore the completion function is
restricted in what it can do. In particular it must not make any
calls that will or may block such as locking a mutex or allocating
memory. The kernel documentation should be consulted for more details
of DSR's and interrupt handling generally.
</para>
<para>
It is possible that the completion function will be invoked before
<function>usbs_start_rx_buffer</function> returns. Such an event would
be unusual because the transfer cannot happen until the next time the
host tries to send data to this peripheral, but it may happen if for
example another interrupt happens and a higher priority thread is
scheduled to run. Also, if the endpoint is currently halted then the
completion function will be invoked immediately with
<literal>-EAGAIN</literal>: typically this will happen in the current
thread rather than in a separate DSR. The completion function is
allowed to start another transfer immediately by calling
<function>usbs_start_rx_buffer</function> again.
</para>
<para>
USB device drivers are not expected to perform any locking. It is the
responsibility of higher-level code to ensure that there is only one
receive operation for a given endpoint in progress at any one time. If
there are concurrent calls to
<function>usbs_start_rx_buffer</function> then the resulting behaviour
is undefined. For typical USB applications this does not present any
problems, because only one piece of code will access a given endpoint
at any particular time.
</para>
<para>
The following code fragment illustrates a very simple use of
<function>usbs_start_rx_buffer</function> to implement a blocking
receive, using a semaphore to synchronise between the foreground
thread and the DSR. For a simple example like this no completion data
is needed.
</para>
<programlisting width=72>
static int error_code = 0;
static cyg_sem_t completion_wait;

static void
completion_fn(void* data, int result)
{
    error_code = result;
    cyg_semaphore_post(&amp;completion_wait);
}

int
blocking_receive(usbs_rx_endpoint* ep, unsigned char* buf, int len)
{
    error_code = 0;
    usbs_start_rx_buffer(ep, buf, len, &amp;completion_fn, NULL);
    cyg_semaphore_wait(&amp;completion_wait);
    return error_code;
}
</programlisting>
<para>
There is also a utility function <function>usbs_start_rx</function>. This
can be used by code that wants to manipulate <link