packages/devs/usb/sa11x0/v2_0/doc/usbs_sa11x0.sgml

   1 <!-- DOCTYPE refentry  PUBLIC "-//OASIS//DTD DocBook V3.1//EN" -->
   2
   3 <!-- {{{ Banner                         -->
   4
   5 <!-- =============================================================== -->
   6 <!--                                                                 -->
   7 <!--     usbs_sa11x0.sgml                                            -->
   8 <!--                                                                 -->
   9 <!--     Documentation for the SA11x0 USB Device Driver.             -->
  10 <!--                                                                 -->
  11 <!-- =============================================================== -->
  12 <!-- ####COPYRIGHTBEGIN####                                          -->
  13 <!--                                                                 -->
  14 <!-- =============================================================== -->
  15 <!-- Copyright (C) 2001, 2002 Red Hat, Inc.                          -->
  16 <!-- This material may be distributed only subject to the terms      -->
  17 <!-- and conditions set forth in the Open Publication License, v1.0  -->
  18 <!-- or later (the latest version is presently available at          -->
  19 <!-- http://www.opencontent.org/openpub/)                            -->
  20 <!-- Distribution of the work or derivative of the work in any       -->
  21 <!-- standard (paper) book form is prohibited unless prior           -->
  22 <!-- permission obtained from the copyright holder                   -->
  23 <!-- =============================================================== -->
  24 <!--                                                                 -->
  25 <!-- ####COPYRIGHTEND####                                            -->
  26 <!-- =============================================================== -->
  27 <!-- #####DESCRIPTIONBEGIN####                                       -->
  28 <!--                                                                 -->
  29 <!-- Author(s):   bartv                                              -->
  30 <!-- Contact(s):  bartv                                              -->
  31 <!-- Date:        2001/01/11                                         -->
  32 <!-- Version:     0.01                                               -->
  33 <!--                                                                 -->
  34 <!-- ####DESCRIPTIONEND####                                          -->
  35 <!-- =============================================================== -->
  36
  37 <!-- }}} -->
  38
  39 <part id="devs-usb-sa11x0-ref">
  40 <!-- reference id="devs-usb-sa11x0-ref" -->
  41   <title>SA11X0 USB Device Driver</title>
  42
  43 <refentry id="devs-usb-sa11x0">
  44 <refmeta>
  45 <refentrytitle>SA11X0 USB Device Driver</refentrytitle>
  46 </refmeta>
  47 <refnamediv>
  48 <refname>SA11X0 USB Support</refname>
  49 <refpurpose>Device driver for the on-chip SA11X0 USB device</refpurpose>
  50 </refnamediv>
  51
  52 <refsect1><title>SA11X0 USB Hardware</title>
  53 <para>
  54 The Intel StrongARM SA11x0 family of processors is supplied with an
  55 on-chip USB slave device, the UDC (USB Device Controller). This
  56 supports three endpoints. Endpoint 0 can only be used for control
  57 messages. Endpoint 1 can only be used for bulk transfers from host to
  58 peripheral. Endpoint 2 can only be used for bulk transfers from
  59 peripheral to host. Isochronous and interrupt transfers are not
  60 supported.
  61 </para>
  62 <caution>
  63 <para>
  64 Different revisions of the SA11x0 silicon have had various problems
  65 with the USB support. The device driver has been tested primarily
  66 against stepping B4 of the SA1110 processor, and may not function as
  67 expected with other revisions. Application developers should obtain
  68 the manufacturer's current errata sheets and specification updates.
  69 The B4 stepping still has a number of problems, but the device driver
  70 can work around these. However there is a penalty in terms of extra
  71 code, extra cpu cycles, and increased dispatch latency because extra
  72 processing is needed at DSR level. Interrupt latency should not be
  73 affected.
  74 </para>
  75 <para>
  76 There is one specific problem inherent in the UDC design of which
  77 application developers should be aware: the hardware cannot fully
  78 implement the USB standard for bulk transfers. A bulk transfer
  79 typically consists of some number of full-size 64-byte packets and is
  80 terminated by a packet less than the full size. If the amount of data
  81 transferred is an exact multiple of 64 bytes then this requires a
  82 terminating packet of 0 bytes of data (plus header and checksum). The
  83 SA11x0 USB hardware does not allow a 0-byte packet to be transmitted,
  84 so the device driver is forced to substitute a 1-byte packet and the
  85 host receives more data than expected. Protocol support is needed so
  86 that the appropriate host-side device driver can allow buffer space
  87 for the extra byte, detect when it gets sent, and discard it.
  88 Consequently certain standard USB class protocols cannot be
  89 implemented using the SA11x0, and therefore custom host-side device
  90 drivers will generally have to be provided, rather than re-using
  91 existing ones that understand the standard protocol.
  92 </para>
  93 </caution>
  94 </refsect1>
  95
  96 <refsect1><title>Endpoint Data Structures</title>
  97 <para>
  98 The SA11x0 USB device driver can provide up to three data structures
  99 corresponding to the three endpoints: a
 100 <structname>usbs_control_endpoint</structname> structure
 101 <literal>usbs_sa11x0_ep0</literal>; a
 102 <structname>usbs_rx_endpoint</structname>
 103 <literal>usbs_sa11x0_ep1</literal>; and a
 104 <structname>usbs_tx_endpoint</structname>
 105 <literal>usbs_sa11x0_ep2</literal>. The header file
 106 <filename class="headerfile">cyg/io/usb/usbs_sa11x0.h</filename>
 107 provides declarations for these.
 108 </para>
 109 <para>
 110 Not all applications will require support for all the endpoints. For
 111 example, if the intended use of the UDC only involves peripheral to
 112 host transfers then <literal>usbs_sa11x0_ep1</literal> is redundant.
 113 The device driver provides configuration options to control the
 114 presence of each endpoint:
 115 </para>
 116 <orderedlist>
 117 <listitem>
 118 <para>
 119 Endpoint 0 is controlled by
 120 <literal>CYGFUN_DEVS_USB_SA11X0_EP0</literal>. This defaults to
 121 enabled if there are any higher-level packages that require USB
 122 hardware or if the global preference
 123 <literal>CYGGLO_IO_USB_SLAVE_APPLICATION</literal> is enabled,
 124 otherwise it is disabled. Usually this has the desired effect. It may
 125 be necessary to override this in special circumstances, for example if
 126 the target board uses an external USB chip in preference to the UDC
 127 and it is that external chip's device driver that should be used
 128 rather than the on-chip UDC. It is not possible to disable endpoint 0
 129 and at the same time enable one or both of the other endpoints, since
 130 a USB device is only usable if it can process the standard control
 131 messages.
 132 </para>
 133 </listitem>
 134 <listitem>
 135 <para>
 136 Endpoint 1 is controlled by
 137 <literal>CYGPKG_DEVS_USB_SA11X0_EP1</literal>. By default it is
 138 enabled whenever endpoint 0 is enabled, but it can be disabled
 139 manually when not required.
 140 </para>
 141 </listitem>
 142 <listitem>
 143 <para>
 144 Similarly endpoint 2 is controlled by
 145 <literal>CYGPKG_DEVS_USB_SA11X0_EP2</literal>. This is also enabled by
 146 default whenever endpoint 0 is enabled, but it can be disabled manually.
 147 </para>
 148 </listitem>
 149 </orderedlist>
 150 <para>
 151 The SA11X0 USB device driver implements the interface specified by the
 152 common eCos USB Slave Support package. The documentation for that
 153 package should be consulted for further details. There is only one
 154 major deviation: when there is a peripheral to host transfer on
 155 endpoint 2 which is an exact multiple of the bulk transfer packet size
 156 (usually 64 bytes) the device driver has to pad the transfer with one
 157 extra byte. This is because of a hardware limitation: the UDC is
 158 incapable of transmitting 0-byte packets as required by the USB
 159 specification. Higher-level code, including the host-side device
 160 driver, needs to be aware of this and adapt accordingly.
 161 </para>
 162 <para>
 163 The device driver assumes a bulk packet size of 64 bytes, so this
 164 value should be used in the endpoint descriptors in the enumeration
 165 data provided by application code. There is experimental code
 166 for running with <link linkend="usbs-sa11x0-dma">DMA disabled</link>,
 167 in which case the packet size will be 16 bytes rather than 64.
 168 </para>
 169 </refsect1>
 170
 171 <refsect1><title>Devtab Entries</title>
 172 <para>
 173 In addition to the endpoint data structures the SA11X0 USB device
 174 driver can also provide devtab entries for each endpoint. This allows
 175 higher-level code to use traditional I/O operations such as
 176 <function>open</function>/<function>read</function>/<function>write</function>
 177 rather than the USB-specific non-blocking functions like
 178 <function>usbs_start_rx_buffer</function>. These devtab entries are
 179 optional since they are not always required. The relevant
 180 configuration options are
 181 <literal>CYGVAR_DEVS_USB_SA11X0_EP0_DEVTAB_ENTRY</literal>,
 182 <literal>CYGVAR_DEVS_USB_SA11X0_EP1_DEVTAB_ENTRY</literal> and
 183 <literal>CYGVAR_DEVS_USB_SA11X0_EP2_DEVTAB_ENTRY</literal>. By default
 184 these devtab entries are provided if the global preference
 185 <literal>CYGGLO_USB_SLAVE_PROVIDE_DEVTAB_ENTRIES</literal> is enabled,
 186 which is usually the case. Obviously a devtab entry for a given
 187 endpoint will only be provided if the underlying endpoint is enabled.
 188 For example, there will not be a devtab entry for endpoint 1 if
 189 <literal>CYGPKG_DEVS_USB_SA11X0_EP1</literal> is disabled.
 190 </para>
 191 <para>
 192 The names for the three devtab entries are determined by using a
 193 configurable base name and appending <literal>0c</literal>,
 194 <literal>1r</literal> or <literal>2w</literal>. The base name is
 195 determined by the configuration option
 196 <literal>CYGDAT_DEVS_USB_SA11X0_DEVTAB_BASENAME</literal> and has a
 197 default value of <literal>/dev/usbs</literal>, so the devtab entry for
 198 endpoint 1 would default to <literal>/dev/usbs1r</literal>. If the
 199 target hardware involves multiple USB devices then application
 200 developers may have to change the base name to prevent a name clash.
 201 </para>
 202 </refsect1>
 203
 204 <refsect1><title id="usbs-sa11x0-dma">DMA Engines</title>
 205 <para>
 206 The SA11X0 UDC provides only limited fifos for bulk transfers on
 207 endpoints 1 and 2; smaller than the normal 64-byte bulk packet size.
 208 Therefore a typical transfer requires the use of DMA engines. The
 209 SA11x0 provides six DMA engines that can be used for this, and the
 210 endpoints require one each (assuming both endpoints are enabled). At
 211 the time of writing there is no arbitration mechanism to control
 212 access to the DMA engines. By default the device driver will use
 213 DMA engine 4 for endpoint 1 and DMA engine 5 for endpoint 2, and it
 214 assumes that no other code uses these particular engines.
 215 </para>
 216 <para>
 217 The exact DMA engines that will be used are determined by the
 218 configuration options
 219 <literal>CYGNUM_DEVS_USB_SA11X0_EP1_DMA_CHANNEL</literal> and
 220 <literal>CYGNUM_DEVS_USB_SA11X0_EP2_DMA_CHANNEL</literal>. These
 221 options have the booldata flavor, allowing the use of DMA to be
 222 disabled completely in addition to controlling which DMA engines are
 223 used. If DMA is disabled then the device driver will attempt to
 224 work purely using the fifos, and the packet size will be limited to
 225 only 16 bytes. This limit should be reflected in the appropriate
 226 endpoint descriptors in the enumeration data. The code for driving the
 227 endpoints without DMA should be considered experimental. At best it
 228 will be suitable only for applications where the amount of data
 229 transferred is relatively small, because four times as many interrupts
 230 will be raised and performance will suffer accordingly.
 231 </para>
 232 </refsect1>
 233
 234 </refentry>
 235 </part>
 236 <!-- /reference -->