usbs-writing.html

ecos 文档

></TR
></TABLE
><P
>Again care must be taken to avoid name clashes. This can be achieved
by having a configuration option to control the base name, with a
default value of e.g. <TT
CLASS="LITERAL"
>/dev/usbs</TT
>, and appending an
endpoint-specific string. This gives the application developer
sufficient control to eliminate any name clashes. The common USB slave
package provides functions <TT
CLASS="FUNCTION"
>usbs_devtab_cwrite</TT
> and
<TT
CLASS="FUNCTION"
>usbs_devtab_cread</TT
>, which can be used in the
function tables for transmit and receive endpoints respectively. The
private field <TT
CLASS="STRUCTFIELD"
><I
>priv</I
></TT
> of the devtab entry
should be a pointer to the underlying endpoint data structure.</P
><P
>Because devtab entries are never accessed directly, only indirectly,
they would usually be eliminated by the linker. To avoid this the
devtab entries should normally be defined in a separate source file
which ends up the special library <TT
CLASS="FILENAME"
>libextras.a</TT
>
rather than in the default library <TT
CLASS="FILENAME"
>libtarget.a</TT
>.</P
><P
>Not all applications or higher-level packages will want to use the
devtab entries and the blocking I/O facilities. It may be appropriate
for the device driver to provide additional configuration options that
control whether or not any or all of the devtab entries should be
provided, to avoid unnecessary memory overheads.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN16785"
></A
><H2
>Interrupt Handling</H2
><P
>A typical USB device driver will need to service interrupts for all of
the endpoints and possibly for additional USB events such as entering
or leaving suspended mode. Usually these interrupts need not be
serviced directly by the ISR. Instead, they can be left to a DSR. If
the peripheral is not able to accept or send another packet just yet,
the hardware will generate a NAK and the host will just retry a little
bit later. If high throughput is required then it may be desirable to
handle the bulk transfer protocol largely at ISR level, that is take
care of each packet in the ISR and only activate the DSR once the
whole transfer has completed.</P
><P
>Control messages may involve invoking arbitrary callback functions in
higher-level code. This should normally happen at DSR level. Doing it
at ISR level could seriously affect the system's interrupt latency and
impose unacceptable constraints on what operations can be performed by
those callbacks. If the device driver requires a thread anyway then it
may be appropriate to use this thread for invoking the callbacks, but
usually it is not worthwhile to add a new thread to the system just
for this; higher-level code is expected to write callbacks that
function sensibly at DSR level. Much the same applies to the
completion functions associated with data transfers. These should also
be invoked at DSR or thread level.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN16789"
></A
><H2
>Support for USB Testing</H2
><P
>Optionally a USB device driver can provide support for the
<A
HREF="usbs-testing.html"
>USB test software</A
>. This requires
defining a number of additional data structures, allowing the
generic test code to work out just what the hardware is capable of and
hence what testing can be performed.</P
><P
>The key data structure is
<SPAN
CLASS="STRUCTNAME"
>usbs_testing_endpoint</SPAN
>, defined in <TT
CLASS="FILENAME"
>cyg/io/usb/usbs.h</TT
>. In addition some
commonly required constants are provided by the common USB package in
<TT
CLASS="FILENAME"
>cyg/io/usb/usb.h</TT
>. One
<SPAN
CLASS="STRUCTNAME"
>usbs_testing_endpoint</SPAN
> structure should be
defined for each supported endpoint. The following fields need to be
filled in:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><TT
CLASS="STRUCTFIELD"
><I
>endpoint_type</I
></TT
></DT
><DD
><P
>    This specifies the type of endpoint and should be one of
    <TT
CLASS="LITERAL"
>USB_ENDPOINT_DESCRIPTOR_ATTR_CONTROL</TT
>,
    <TT
CLASS="LITERAL"
>BULK</TT
>, <TT
CLASS="LITERAL"
>ISOCHRONOUS</TT
> or
    <TT
CLASS="LITERAL"
>INTERRUPT</TT
>.
  </P
></DD
><DT
><TT
CLASS="STRUCTFIELD"
><I
>endpoint_number</I
></TT
></DT
><DD
><P
>    This identifies the number that should be used by the host
    to address this endpoint. For a control endpoint it should
    be 0. For other types of endpoints it should be between
    1 and 15.
  </P
></DD
><DT
><TT
CLASS="STRUCTFIELD"
><I
>endpoint_direction</I
></TT
></DT
><DD
><P
>    For control endpoints this field is irrelevant. For other
    types of endpoint it should be either
    <TT
CLASS="LITERAL"
>USB_ENDPOINT_DESCRIPTOR_ENDPOINT_IN</TT
> or
    <TT
CLASS="LITERAL"
>USB_ENDPOINT_DESCRIPTOR_ENDPOINT_OUT</TT
>. If a given
    endpoint number can be used for traffic in both directions then
    there should be two entries in the array, one for each direction.
  </P
></DD
><DT
><TT
CLASS="STRUCTFIELD"
><I
>endpoint</I
></TT
></DT
><DD
><P
>    This should be a pointer to the appropriate
    <SPAN
CLASS="STRUCTNAME"
>usbs_control_endpoint</SPAN
>,
    <SPAN
CLASS="STRUCTNAME"
>usbs_rx_endpoint</SPAN
> or
    <SPAN
CLASS="STRUCTNAME"
>usbs_tx_endpoint</SPAN
> structure, allowing the
    generic testing code to perform low-level I/O.
  </P
></DD
><DT
><TT
CLASS="STRUCTFIELD"
><I
>devtab_entry</I
></TT
></DT
><DD
><P
>    If the endpoint also has an entry in the system's device table then
    this field should give the corresponding string, for example
    <TT
CLASS="LITERAL"
>&quot;/dev/usbs1r&quot;</TT
>. This allows the
    generic testing code to access the device via higher-level
    calls like <TT
CLASS="FUNCTION"
>open</TT
> and <TT
CLASS="FUNCTION"
>read</TT
>. 
  </P
></DD
><DT
><TT
CLASS="STRUCTFIELD"
><I
>min_size</I
></TT
></DT
><DD
><P
>    This indicates the smallest transfer size that the hardware can
    support on this endpoint. Typically this will be one.
  </P
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Note: </B
>    Strictly speaking a minimum size of one is not quite right since it
    is valid for a USB transfer to involve zero bytes, in other words a
    transfer that involves just headers and acknowledgements and an
    empty data phase, and that should be tested as well. However current
    device drivers interpret a transfer size of 0 as special, so that
    would have to be resolved first.
  </P
></BLOCKQUOTE
></DIV
></DD
><DT
><TT
CLASS="STRUCTFIELD"
><I
>max_size</I
></TT
></DT
><DD
><P
>    Similarly, this specifies the largest transfer size. For control
    endpoints the USB protocol uses only two bytes to hold the transfer
    length, so there is an upper bound of 65535 bytes. In practice
    it is very unlikely that any control transfers would ever need to
    be this large, and in fact such transfers would take a long time
    and probably violate timing constraints. For other types of endpoint
    any of the protocol, the hardware, or the device driver may impose
    size limits. For example a given device driver might be unable to
    cope with transfers larger than 65535 bytes. If it should be
    possible to transfer arbitrary amounts of data then a value of
    <TT
CLASS="LITERAL"
>-1</TT
> indicates no upper limit, and transfer
    sizes will be limited by available memory and by the capabilities
    of the host machine.
  </P
></DD
><DT
><TT
CLASS="STRUCTFIELD"
><I
>max_in_padding</I
></TT
></DT
><DD
><P
>    This field is needed on some hardware where it is impossible to
    send packets of a certain size. For example the hardware may be
    incapable of sending an empty bulk packet to terminate a transfer
    that is an exact multiple of the 64-byte bulk packet size.
    Instead the driver has to do some padding and send an extra byte,
    and the host has to be prepared to receive this extra byte. Such a
    driver should specify a value of <TT
CLASS="LITERAL"
>1</TT
> for the
    padding field. For most drivers this field should be set to
  <TT
CLASS="LITERAL"
>0</TT
>.
  </P
><P
>    A better solution would be for the device driver to supply a
    fragment of Tcl code that would adjust the receive buffer size
    only when necessary, rather than for every transfer. Forcing
    receive padding on all transfers when only certain transfers
    will actually be padded reduces the accuracy of certain tests.
  </P
></DD
><DT
><TT
CLASS="STRUCTFIELD"
><I
>alignment</I
></TT
></DT
><DD
><P
>    On some hardware data transfers may need to be aligned to certain
    boundaries, for example a word boundary or a cacheline boundary.
    Although in theory device drivers could hide such alignment
    restrictions from higher-level code by having their own buffers and
    performing appropriate copying, that would be expensive in terms of
    both memory and cpu cycles. Instead the generic testing code will
    align any buffers passed to the device driver to the specified
    boundary. For example, if the driver requires that buffers be
    aligned to a word boundary then it should specify an alignment
    value of 4.
  </P
></DD
></DL
></DIV
><P
>The device driver should provide an array of these structures
<TT
CLASS="VARNAME"
>usbs_testing_endpoints[]</TT
>. The USB testing code
examines this array and uses the information to perform appropriate
tests. Because different USB devices support different numbers of
endpoints the number of entries in the array is not known in advance,
so instead the testing code looks for a special terminator
<TT
CLASS="VARNAME"
>USBS_TESTING_ENDPOINTS_TERMINATOR</TT
>. An example
array, showing just the control endpoint and the terminator, might
look like this:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>usbs_testing_endpoint usbs_testing_endpoints[] = {
    {
        endpoint_type       : USB_ENDPOINT_DESCRIPTOR_ATTR_CONTROL, 
        endpoint_number     : 0,
        endpoint_direction  : USB_ENDPOINT_DESCRIPTOR_ENDPOINT_IN,
        endpoint            : (void*) &amp;ep0.common,
        devtab_entry        : (const char*) 0,
        min_size            : 1,
        max_size            : 0x0FFFF,
        max_in_padding      : 0,
        alignment           : 0
    },
    &#8230;,
    USBS_TESTING_ENDPOINTS_TERMINATOR
};</PRE
></TD
></TR
></TABLE
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Note: </B
>The use of a single array <TT
CLASS="VARNAME"
>usbs_testing_endpoints</TT
>
limits USB testing to platforms with a single USB device: if there
were multiple devices, each defining their own instance of this array,
then there would a collision at link time. In practice this should not
be a major problem since typical USB peripherals only interact with a
single host machine via a single slave port. In addition, even if a
peripheral did have multiple slave ports the current USB testing code
would not support this since it would not know which port to use.</P
></BLOCKQUOTE
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="usbs-data.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="ecos-ref.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="usbs-testing.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Data Endpoints</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="io-usb-slave.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Testing</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>