packages/devs/usb/sa11x0/v2_0/doc/devs-usb-sa11x0.html

   1 <!-- Copyright (C) 2001 Red Hat, Inc.                                -->
   2 <!-- This material may be distributed only subject to the terms      -->
   3 <!-- and conditions set forth in the Open Publication License, v1.0  -->
   4 <!-- or later (the latest version is presently available at          -->
   5 <!-- http://www.opencontent.org/openpub/)                            -->
   6 <!-- Distribution of substantively modified versions of this         -->
   7 <!-- document is prohibited without the explicit permission of the   -->
   8 <!-- copyright holder.                                               -->
   9 <!-- Distribution of the work or derivative of the work in any       -->
  10 <!-- standard (paper) book form is prohibited unless prior           -->
  11 <!-- permission obtained from the copyright holder                   -->
  12 <HTML>
  13 <HEAD>
  14 <TITLE>
  15 SA11X0 USB Device Driver</TITLE>
  16 <META
  17 NAME="GENERATOR"
  18 CONTENT="Modular DocBook HTML Stylesheet Version 1.54"></HEAD>
  19 <BODY
  20 CLASS="REFENTRY"
  21 BGCOLOR="#FFFFFF"
  22 TEXT="#000000"
  23 LINK="#0000FF"
  24 VLINK="#840084"
  25 ALINK="#0000FF">
  26 <H1>
  27 <A
  28 NAME="DEVS-USB-SA11X0">
  29 SA11X0 USB Device Driver</A>
  30 </H1>
  31 <DIV
  32 CLASS="REFNAMEDIV">
  33 <A
  34 NAME="AEN4">
  35 </A>
  36 <H2>
  37 Name</H2>
  38 SA11X0 USB Support&nbsp;--&nbsp;Device driver for the on-chip SA11X0 USB device</DIV>
  39 <DIV
  40 CLASS="REFSECT1">
  41 <A
  42 NAME="AEN7">
  43 </A>
  44 <H2>
  45 SA11X0 USB Hardware</H2>
  46 <P>
  47 The Intel StrongARM SA11x0 family of processors is supplied with an
  48 on-chip USB slave device, the UDC (USB Device Controller). This
  49 supports three endpoints. Endpoint 0 can only be used for control
  50 messages. Endpoint 1 can only be used for bulk transfers from host to
  51 peripheral. Endpoint 2 can only be used for bulk transfers from
  52 peripheral to host. Isochronous and interrupt transfers are not
  53 supported.</P>
  54 <DIV
  55 CLASS="CAUTION">
  56 <P>
  57 </P>
  58 <TABLE
  59 CLASS="CAUTION"
  60 BORDER="1"
  61 WIDTH="100%">
  62 <TR>
  63 <TD
  64 ALIGN="CENTER">
  65 <B>
  66 Caution</B>
  67 </TD>
  68 </TR>
  69 <TR>
  70 <TD
  71 ALIGN="LEFT">
  72 <P>
  73 Different revisions of the SA11x0 silicon have had various problems
  74 with the USB support. The device driver has been tested primarily
  75 against stepping B4 of the SA1110 processor, and may not function as
  76 expected with other revisions. Application developers should obtain
  77 the manufacturer's current errata sheets and specification updates.
  78 The B4 stepping still has a number of problems, but the device driver
  79 can work around these. However there is a penalty in terms of extra
  80 code, extra cpu cycles, and increased dispatch latency because extra
  81 processing is needed at DSR level. Interrupt latency should not be
  82 affected.</P>
  83 <P>
  84 There is one specific problem inherent in the UDC design of which
  85 application developers should be aware: the hardware cannot fully
  86 implement the USB standard for bulk transfers. A bulk transfer
  87 typically consists of some number of full-size 64-byte packets and is
  88 terminated by a packet less than the full size. If the amount of data
  89 transferred is an exact multiple of 64 bytes then this requires a
  90 terminating packet of 0 bytes of data (plus header and checksum). The
  91 SA11x0 USB hardware does not allow a 0-byte packet to be transmitted,
  92 so the device driver is forced to substitute a 1-byte packet and the
  93 host receives more data than expected. Protocol support is needed so
  94 that the appropriate host-side device driver can allow buffer space
  95 for the extra byte, detect when it gets sent, and discard it.
  96 Consequently certain standard USB class protocols cannot be
  97 implemented using the SA11x0, and therefore custom host-side device
  98 drivers will generally have to be provided, rather than re-using
  99 existing ones that understand the standard protocol.</P>
 100 </TD>
 101 </TR>
 102 </TABLE>
 103 </DIV>
 104 </DIV>
 105 <DIV
 106 CLASS="REFSECT1">
 107 <A
 108 NAME="AEN13">
 109 </A>
 110 <H2>
 111 Endpoint Data Structures</H2>
 112 <P>
 113 The SA11x0 USB device driver can provide up to three data structures
 114 corresponding to the three endpoints: a
 115 <SPAN
 116 CLASS="STRUCTNAME">
 117 usbs_control_endpoint</SPAN>
 118  structure
 119 <TT
 120 CLASS="LITERAL">
 121 usbs_sa11x0_ep0</TT>
 122 ; a
 123 <SPAN
 124 CLASS="STRUCTNAME">
 125 usbs_rx_endpoint</SPAN>
 126
 127 <TT
 128 CLASS="LITERAL">
 129 usbs_sa11x0_ep1</TT>
 130 ; and a
 131 <SPAN
 132 CLASS="STRUCTNAME">
 133 usbs_tx_endpoint</SPAN>
 134
 135 <TT
 136 CLASS="LITERAL">
 137 usbs_sa11x0_ep2</TT>
 138 . The header file
 139 <TT
 140 CLASS="FILENAME">
 141 cyg/io/usb/usbs_sa11x0.h</TT>
 142
 143 provides declarations for these.</P>
 144 <P>
 145 Not all applications will require support for all the endpoints. For
 146 example, if the intended use of the UDC only involves peripheral to
 147 host transfers then <TT
 148 CLASS="LITERAL">
 149 usbs_sa11x0_ep1</TT>
 150  is redundant.
 151 The device driver provides configuration options to control the
 152 presence of each endpoint:</P>
 153 <P>
 154 </P>
 155 <OL
 156 TYPE="1">
 157 <LI>
 158 <P>
 159 Endpoint 0 is controlled by
 160 <TT
 161 CLASS="LITERAL">
 162 CYGFUN_DEVS_USB_SA11X0_EP0</TT>
 163 . This defaults to
 164 enabled if there are any higher-level packages that require USB
 165 hardware or if the global preference
 166 <TT
 167 CLASS="LITERAL">
 168 CYGGLO_IO_USB_SLAVE_APPLICATION</TT>
 169  is enabled,
 170 otherwise it is disabled. Usually this has the desired effect. It may
 171 be necessary to override this in special circumstances, for example if
 172 the target board uses an external USB chip in preference to the UDC
 173 and it is that external chip's device driver that should be used
 174 rather than the on-chip UDC. It is not possible to disable endpoint 0
 175 and at the same time enable one or both of the other endpoints, since
 176 a USB device is only usable if it can process the standard control
 177 messages.</P>
 178 </LI>
 179 <LI>
 180 <P>
 181 Endpoint 1 is controlled by
 182 <TT
 183 CLASS="LITERAL">
 184 CYGPKG_DEVS_USB_SA11X0_EP1</TT>
 185 . By default it is
 186 enabled whenever endpoint 0 is enabled, but it can be disabled
 187 manually when not required.</P>
 188 </LI>
 189 <LI>
 190 <P>
 191 Similarly endpoint 2 is controlled by
 192 <TT
 193 CLASS="LITERAL">
 194 CYGPKG_DEVS_USB_SA11X0_EP2</TT>
 195 . This is also enabled by
 196 default whenever endpoint 0 is enabled, but it can be disabled manually.</P>
 197 </LI>
 198 </OL>
 199 <P>
 200 The SA11X0 USB device driver implements the interface specified by the
 201 common eCos USB Slave Support package. The documentation for that
 202 package should be consulted for further details. There is only one
 203 major deviation: when there is a peripheral to host transfer on
 204 endpoint 2 which is an exact multiple of the bulk transfer packet size
 205 (usually 64 bytes) the device driver has to pad the transfer with one
 206 extra byte. This is because of a hardware limitation: the UDC is
 207 incapable of transmitting 0-byte packets as required by the USB
 208 specification. Higher-level code, including the host-side device
 209 driver, needs to be aware of this and adapt accordingly.</P>
 210 <P>
 211 The device driver assumes a bulk packet size of 64 bytes, so this
 212 value should be used in the endpoint descriptors in the enumeration
 213 data provided by application code. There is experimental code
 214 for running with <A
 215 HREF="devs-usb-sa11x0.html#AEN58">
 216 DMA disabled</A>
 217 ,
 218 in which case the packet size will be 16 bytes rather than 64.</P>
 219 </DIV>
 220 <DIV
 221 CLASS="REFSECT1">
 222 <A
 223 NAME="AEN39">
 224 </A>
 225 <H2>
 226 Devtab Entries</H2>
 227 <P>
 228 In addition to the endpoint data structures the SA11X0 USB device
 229 driver can also provide devtab entries for each endpoint. This allows
 230 higher-level code to use traditional I/O operations such as
 231 <TT
 232 CLASS="FUNCTION">
 233 open</TT>
 234 /<TT
 235 CLASS="FUNCTION">
 236 read</TT>
 237 /<TT
 238 CLASS="FUNCTION">
 239 write</TT>
 240
 241 rather than the USB-specific non-blocking functions like
 242 <TT
 243 CLASS="FUNCTION">
 244 usbs_start_rx_buffer</TT>
 245 . These devtab entries are
 246 optional since they are not always required. The relevant
 247 configuration options are
 248 <TT
 249 CLASS="LITERAL">
 250 CYGVAR_DEVS_USB_SA11X0_EP0_DEVTAB_ENTRY</TT>
 251 ,
 252 <TT
 253 CLASS="LITERAL">
 254 CYGVAR_DEVS_USB_SA11X0_EP1_DEVTAB_ENTRY</TT>
 255  and
 256 <TT
 257 CLASS="LITERAL">
 258 CYGVAR_DEVS_USB_SA11X0_EP2_DEVTAB_ENTRY</TT>
 259 . By default
 260 these devtab entries are provided if the global preference
 261 <TT
 262 CLASS="LITERAL">
 263 CYGGLO_USB_SLAVE_PROVIDE_DEVTAB_ENTRIES</TT>
 264  is enabled,
 265 which is usually the case. Obviously a devtab entry for a given
 266 endpoint will only be provided if the underlying endpoint is enabled.
 267 For example, there will not be a devtab entry for endpoint 1 if
 268 <TT
 269 CLASS="LITERAL">
 270 CYGPKG_DEVS_USB_SA11X0_EP1</TT>
 271  is disabled.</P>
 272 <P>
 273 The names for the three devtab entries are determined by using a
 274 configurable base name and appending <TT
 275 CLASS="LITERAL">
 276 0c</TT>
 277 ,
 278 <TT
 279 CLASS="LITERAL">
 280 1r</TT>
 281  or <TT
 282 CLASS="LITERAL">
 283 2w</TT>
 284 . The base name is
 285 determined by the configuration option
 286 <TT
 287 CLASS="LITERAL">
 288 CYGDAT_DEVS_USB_SA11X0_DEVTAB_BASENAME</TT>
 289  and has a
 290 default value of <TT
 291 CLASS="LITERAL">
 292 /dev/usbs</TT>
 293 , so the devtab entry for
 294 endpoint 1 would default to <TT
 295 CLASS="LITERAL">
 296 /dev/usbs1r</TT>
 297 . If the
 298 target hardware involves multiple USB devices then application
 299 developers may have to change the base name to prevent a name clash.</P>
 300 </DIV>
 301 <DIV
 302 CLASS="REFSECT1">
 303 <A
 304 NAME="AEN58">
 305 </A>
 306 <H2>
 307 DMA Engines</H2>
 308 <P>
 309 The SA11X0 UDC provides only limited fifos for bulk transfers on
 310 endpoints 1 and 2; smaller than the normal 64-byte bulk packet size.
 311 Therefore a typical transfer requires the use of DMA engines. The
 312 SA11x0 provides six DMA engines that can be used for this, and the
 313 endpoints require one each (assuming both endpoints are enabled). At
 314 the time of writing there is no arbitration mechanism to control
 315 access to the DMA engines. By default the device driver will use
 316 DMA engine 4 for endpoint 1 and DMA engine 5 for endpoint 2, and it
 317 assumes that no other code uses these particular engines.</P>
 318 <P>
 319 The exact DMA engines that will be used are determined by the
 320 configuration options
 321 <TT
 322 CLASS="LITERAL">
 323 CYGNUM_DEVS_USB_SA11X0_EP1_DMA_CHANNEL</TT>
 324  and
 325 <TT
 326 CLASS="LITERAL">
 327 CYGNUM_DEVS_USB_SA11X0_EP2_DMA_CHANNEL</TT>
 328 . These
 329 options have the booldata flavor, allowing the use of DMA to be
 330 disabled completely in addition to controlling which DMA engines are
 331 used. If DMA is disabled then the device driver will attempt to
 332 work purely using the fifos, and the packet size will be limited to
 333 only 16 bytes. This limit should be reflected in the appropriate
 334 endpoint descriptors in the enumeration data. The code for driving the
 335 endpoints without DMA should be considered experimental. At best it
 336 will be suitable only for applications where the amount of data
 337 transferred is relatively small, because four times as many interrupts
 338 will be raised and performance will suffer accordingly.</P>
 339 </DIV>
 340 </BODY>
 341 </HTML>