doc/html/ref/devs-usb-sa11x0.html

   1 <!-- Copyright (C) 2003 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 the work or derivative of the work in any       -->
   7 <!-- standard (paper) book form is prohibited unless prior           -->
   8 <!-- permission is obtained from the copyright holder.               -->
   9 <HTML
  10 ><HEAD
  11 ><TITLE
  12 >SA11X0 USB Device Driver</TITLE
  13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
  14 <META
  15 NAME="GENERATOR"
  16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
  17 "><LINK
  18 REL="HOME"
  19 TITLE="eCos Reference Manual"
  20 HREF="ecos-ref.html"><LINK
  21 REL="UP"
  22 TITLE="SA11X0 USB Device Driver"
  23 HREF="devs-usb-sa11x0-ref.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="SA11X0 USB Device Driver"
  26 HREF="devs-usb-sa11x0-ref.html"><LINK
  27 REL="NEXT"
  28 TITLE="NEC uPD985xx USB Device Driver"
  29 HREF="devs-usb-nec-upd985xx-ref.html"></HEAD
  30 ><BODY
  31 CLASS="REFENTRY"
  32 BGCOLOR="#FFFFFF"
  33 TEXT="#000000"
  34 LINK="#0000FF"
  35 VLINK="#840084"
  36 ALINK="#0000FF"
  37 ><DIV
  38 CLASS="NAVHEADER"
  39 ><TABLE
  40 SUMMARY="Header navigation table"
  41 WIDTH="100%"
  42 BORDER="0"
  43 CELLPADDING="0"
  44 CELLSPACING="0"
  45 ><TR
  46 ><TH
  47 COLSPAN="3"
  48 ALIGN="center"
  49 >eCos Reference Manual</TH
  50 ></TR
  51 ><TR
  52 ><TD
  53 WIDTH="10%"
  54 ALIGN="left"
  55 VALIGN="bottom"
  56 ><A
  57 HREF="devs-usb-sa11x0-ref.html"
  58 ACCESSKEY="P"
  59 >Prev</A
  60 ></TD
  61 ><TD
  62 WIDTH="80%"
  63 ALIGN="center"
  64 VALIGN="bottom"
  65 ></TD
  66 ><TD
  67 WIDTH="10%"
  68 ALIGN="right"
  69 VALIGN="bottom"
  70 ><A
  71 HREF="devs-usb-nec-upd985xx-ref.html"
  72 ACCESSKEY="N"
  73 >Next</A
  74 ></TD
  75 ></TR
  76 ></TABLE
  77 ><HR
  78 ALIGN="LEFT"
  79 WIDTH="100%"></DIV
  80 ><H1
  81 ><A
  82 NAME="DEVS-USB-SA11X0">SA11X0 USB Device Driver</H1
  83 ><DIV
  84 CLASS="REFNAMEDIV"
  85 ><A
  86 NAME="AEN18754"
  87 ></A
  88 ><H2
  89 >Name</H2
  90 >SA11X0 USB Support&nbsp;--&nbsp;Device driver for the on-chip SA11X0 USB device</DIV
  91 ><DIV
  92 CLASS="REFSECT1"
  93 ><A
  94 NAME="AEN18757"
  95 ></A
  96 ><H2
  97 >SA11X0 USB Hardware</H2
  98 ><P
  99 >The Intel StrongARM SA11x0 family of processors is supplied with an
 100 on-chip USB slave device, the UDC (USB Device Controller). This
 101 supports three endpoints. Endpoint 0 can only be used for control
 102 messages. Endpoint 1 can only be used for bulk transfers from host to
 103 peripheral. Endpoint 2 can only be used for bulk transfers from
 104 peripheral to host. Isochronous and interrupt transfers are not
 105 supported.</P
 106 ><DIV
 107 CLASS="CAUTION"
 108 ><P
 109 ></P
 110 ><TABLE
 111 CLASS="CAUTION"
 112 BORDER="1"
 113 WIDTH="100%"
 114 ><TR
 115 ><TD
 116 ALIGN="CENTER"
 117 ><B
 118 >Caution</B
 119 ></TD
 120 ></TR
 121 ><TR
 122 ><TD
 123 ALIGN="LEFT"
 124 ><P
 125 >Different revisions of the SA11x0 silicon have had various problems
 126 with the USB support. The device driver has been tested primarily
 127 against stepping B4 of the SA1110 processor, and may not function as
 128 expected with other revisions. Application developers should obtain
 129 the manufacturer's current errata sheets and specification updates.
 130 The B4 stepping still has a number of problems, but the device driver
 131 can work around these. However there is a penalty in terms of extra
 132 code, extra cpu cycles, and increased dispatch latency because extra
 133 processing is needed at DSR level. Interrupt latency should not be
 134 affected.</P
 135 ><P
 136 >There is one specific problem inherent in the UDC design of which
 137 application developers should be aware: the hardware cannot fully
 138 implement the USB standard for bulk transfers. A bulk transfer
 139 typically consists of some number of full-size 64-byte packets and is
 140 terminated by a packet less than the full size. If the amount of data
 141 transferred is an exact multiple of 64 bytes then this requires a
 142 terminating packet of 0 bytes of data (plus header and checksum). The
 143 SA11x0 USB hardware does not allow a 0-byte packet to be transmitted,
 144 so the device driver is forced to substitute a 1-byte packet and the
 145 host receives more data than expected. Protocol support is needed so
 146 that the appropriate host-side device driver can allow buffer space
 147 for the extra byte, detect when it gets sent, and discard it.
 148 Consequently certain standard USB class protocols cannot be
 149 implemented using the SA11x0, and therefore custom host-side device
 150 drivers will generally have to be provided, rather than re-using
 151 existing ones that understand the standard protocol.</P
 152 ></TD
 153 ></TR
 154 ></TABLE
 155 ></DIV
 156 ></DIV
 157 ><DIV
 158 CLASS="REFSECT1"
 159 ><A
 160 NAME="AEN18763"
 161 ></A
 162 ><H2
 163 >Endpoint Data Structures</H2
 164 ><P
 165 >The SA11x0 USB device driver can provide up to three data structures
 166 corresponding to the three endpoints: a
 167 <SPAN
 168 CLASS="STRUCTNAME"
 169 >usbs_control_endpoint</SPAN
 170 > structure
 171 <TT
 172 CLASS="LITERAL"
 173 >usbs_sa11x0_ep0</TT
 174 >; a
 175 <SPAN
 176 CLASS="STRUCTNAME"
 177 >usbs_rx_endpoint</SPAN
 178 >
 179 <TT
 180 CLASS="LITERAL"
 181 >usbs_sa11x0_ep1</TT
 182 >; and a
 183 <SPAN
 184 CLASS="STRUCTNAME"
 185 >usbs_tx_endpoint</SPAN
 186 >
 187 <TT
 188 CLASS="LITERAL"
 189 >usbs_sa11x0_ep2</TT
 190 >. The header file
 191 <TT
 192 CLASS="FILENAME"
 193 >cyg/io/usb/usbs_sa11x0.h</TT
 194 >
 195 provides declarations for these.</P
 196 ><P
 197 >Not all applications will require support for all the endpoints. For
 198 example, if the intended use of the UDC only involves peripheral to
 199 host transfers then <TT
 200 CLASS="LITERAL"
 201 >usbs_sa11x0_ep1</TT
 202 > is redundant.
 203 The device driver provides configuration options to control the
 204 presence of each endpoint:</P
 205 ><P
 206 ></P
 207 ><OL
 208 TYPE="1"
 209 ><LI
 210 ><P
 211 >Endpoint 0 is controlled by
 212 <TT
 213 CLASS="LITERAL"
 214 >CYGFUN_DEVS_USB_SA11X0_EP0</TT
 215 >. This defaults to
 216 enabled if there are any higher-level packages that require USB
 217 hardware or if the global preference
 218 <TT
 219 CLASS="LITERAL"
 220 >CYGGLO_IO_USB_SLAVE_APPLICATION</TT
 221 > is enabled,
 222 otherwise it is disabled. Usually this has the desired effect. It may
 223 be necessary to override this in special circumstances, for example if
 224 the target board uses an external USB chip in preference to the UDC
 225 and it is that external chip's device driver that should be used
 226 rather than the on-chip UDC. It is not possible to disable endpoint 0
 227 and at the same time enable one or both of the other endpoints, since
 228 a USB device is only usable if it can process the standard control
 229 messages.</P
 230 ></LI
 231 ><LI
 232 ><P
 233 >Endpoint 1 is controlled by
 234 <TT
 235 CLASS="LITERAL"
 236 >CYGPKG_DEVS_USB_SA11X0_EP1</TT
 237 >. By default it is
 238 enabled whenever endpoint 0 is enabled, but it can be disabled
 239 manually when not required.</P
 240 ></LI
 241 ><LI
 242 ><P
 243 >Similarly endpoint 2 is controlled by
 244 <TT
 245 CLASS="LITERAL"
 246 >CYGPKG_DEVS_USB_SA11X0_EP2</TT
 247 >. This is also enabled by
 248 default whenever endpoint 0 is enabled, but it can be disabled manually.</P
 249 ></LI
 250 ></OL
 251 ><P
 252 >The SA11X0 USB device driver implements the interface specified by the
 253 common eCos USB Slave Support package. The documentation for that
 254 package should be consulted for further details. There is only one
 255 major deviation: when there is a peripheral to host transfer on
 256 endpoint 2 which is an exact multiple of the bulk transfer packet size
 257 (usually 64 bytes) the device driver has to pad the transfer with one
 258 extra byte. This is because of a hardware limitation: the UDC is
 259 incapable of transmitting 0-byte packets as required by the USB
 260 specification. Higher-level code, including the host-side device
 261 driver, needs to be aware of this and adapt accordingly.</P
 262 ><P
 263 >The device driver assumes a bulk packet size of 64 bytes, so this
 264 value should be used in the endpoint descriptors in the enumeration
 265 data provided by application code. There is experimental code
 266 for running with <A
 267 HREF="devs-usb-sa11x0.html#AEN18808"
 268 >DMA disabled</A
 269 >,
 270 in which case the packet size will be 16 bytes rather than 64.</P
 271 ></DIV
 272 ><DIV
 273 CLASS="REFSECT1"
 274 ><A
 275 NAME="AEN18789"
 276 ></A
 277 ><H2
 278 >Devtab Entries</H2
 279 ><P
 280 >In addition to the endpoint data structures the SA11X0 USB device
 281 driver can also provide devtab entries for each endpoint. This allows
 282 higher-level code to use traditional I/O operations such as
 283 <TT
 284 CLASS="FUNCTION"
 285 >open</TT
 286 >/<TT
 287 CLASS="FUNCTION"
 288 >read</TT
 289 >/<TT
 290 CLASS="FUNCTION"
 291 >write</TT
 292 >
 293 rather than the USB-specific non-blocking functions like
 294 <TT
 295 CLASS="FUNCTION"
 296 >usbs_start_rx_buffer</TT
 297 >. These devtab entries are
 298 optional since they are not always required. The relevant
 299 configuration options are
 300 <TT
 301 CLASS="LITERAL"
 302 >CYGVAR_DEVS_USB_SA11X0_EP0_DEVTAB_ENTRY</TT
 303 >,
 304 <TT
 305 CLASS="LITERAL"
 306 >CYGVAR_DEVS_USB_SA11X0_EP1_DEVTAB_ENTRY</TT
 307 > and
 308 <TT
 309 CLASS="LITERAL"
 310 >CYGVAR_DEVS_USB_SA11X0_EP2_DEVTAB_ENTRY</TT
 311 >. By default
 312 these devtab entries are provided if the global preference
 313 <TT
 314 CLASS="LITERAL"
 315 >CYGGLO_USB_SLAVE_PROVIDE_DEVTAB_ENTRIES</TT
 316 > is enabled,
 317 which is usually the case. Obviously a devtab entry for a given
 318 endpoint will only be provided if the underlying endpoint is enabled.
 319 For example, there will not be a devtab entry for endpoint 1 if
 320 <TT
 321 CLASS="LITERAL"
 322 >CYGPKG_DEVS_USB_SA11X0_EP1</TT
 323 > is disabled.</P
 324 ><P
 325 >The names for the three devtab entries are determined by using a
 326 configurable base name and appending <TT
 327 CLASS="LITERAL"
 328 >0c</TT
 329 >,
 330 <TT
 331 CLASS="LITERAL"
 332 >1r</TT
 333 > or <TT
 334 CLASS="LITERAL"
 335 >2w</TT
 336 >. The base name is
 337 determined by the configuration option
 338 <TT
 339 CLASS="LITERAL"
 340 >CYGDAT_DEVS_USB_SA11X0_DEVTAB_BASENAME</TT
 341 > and has a
 342 default value of <TT
 343 CLASS="LITERAL"
 344 >/dev/usbs</TT
 345 >, so the devtab entry for
 346 endpoint 1 would default to <TT
 347 CLASS="LITERAL"
 348 >/dev/usbs1r</TT
 349 >. If the
 350 target hardware involves multiple USB devices then application
 351 developers may have to change the base name to prevent a name clash.</P
 352 ></DIV
 353 ><DIV
 354 CLASS="REFSECT1"
 355 ><A
 356 NAME="AEN18808"
 357 ></A
 358 ><H2
 359 >DMA Engines</H2
 360 ><P
 361 >The SA11X0 UDC provides only limited fifos for bulk transfers on
 362 endpoints 1 and 2; smaller than the normal 64-byte bulk packet size.
 363 Therefore a typical transfer requires the use of DMA engines. The
 364 SA11x0 provides six DMA engines that can be used for this, and the
 365 endpoints require one each (assuming both endpoints are enabled). At
 366 the time of writing there is no arbitration mechanism to control
 367 access to the DMA engines. By default the device driver will use
 368 DMA engine 4 for endpoint 1 and DMA engine 5 for endpoint 2, and it
 369 assumes that no other code uses these particular engines.</P
 370 ><P
 371 >The exact DMA engines that will be used are determined by the
 372 configuration options
 373 <TT
 374 CLASS="LITERAL"
 375 >CYGNUM_DEVS_USB_SA11X0_EP1_DMA_CHANNEL</TT
 376 > and
 377 <TT
 378 CLASS="LITERAL"
 379 >CYGNUM_DEVS_USB_SA11X0_EP2_DMA_CHANNEL</TT
 380 >. These
 381 options have the booldata flavor, allowing the use of DMA to be
 382 disabled completely in addition to controlling which DMA engines are
 383 used. If DMA is disabled then the device driver will attempt to
 384 work purely using the fifos, and the packet size will be limited to
 385 only 16 bytes. This limit should be reflected in the appropriate
 386 endpoint descriptors in the enumeration data. The code for driving the
 387 endpoints without DMA should be considered experimental. At best it
 388 will be suitable only for applications where the amount of data
 389 transferred is relatively small, because four times as many interrupts
 390 will be raised and performance will suffer accordingly.</P
 391 ></DIV
 392 ><DIV
 393 CLASS="NAVFOOTER"
 394 ><HR
 395 ALIGN="LEFT"
 396 WIDTH="100%"><TABLE
 397 SUMMARY="Footer navigation table"
 398 WIDTH="100%"
 399 BORDER="0"
 400 CELLPADDING="0"
 401 CELLSPACING="0"
 402 ><TR
 403 ><TD
 404 WIDTH="33%"
 405 ALIGN="left"
 406 VALIGN="top"
 407 ><A
 408 HREF="devs-usb-sa11x0-ref.html"
 409 ACCESSKEY="P"
 410 >Prev</A
 411 ></TD
 412 ><TD
 413 WIDTH="34%"
 414 ALIGN="center"
 415 VALIGN="top"
 416 ><A
 417 HREF="ecos-ref.html"
 418 ACCESSKEY="H"
 419 >Home</A
 420 ></TD
 421 ><TD
 422 WIDTH="33%"
 423 ALIGN="right"
 424 VALIGN="top"
 425 ><A
 426 HREF="devs-usb-nec-upd985xx-ref.html"
 427 ACCESSKEY="N"
 428 >Next</A
 429 ></TD
 430 ></TR
 431 ><TR
 432 ><TD
 433 WIDTH="33%"
 434 ALIGN="left"
 435 VALIGN="top"
 436 >SA11X0 USB Device Driver</TD
 437 ><TD
 438 WIDTH="34%"
 439 ALIGN="center"
 440 VALIGN="top"
 441 ><A
 442 HREF="devs-usb-sa11x0-ref.html"
 443 ACCESSKEY="U"
 444 >Up</A
 445 ></TD
 446 ><TD
 447 WIDTH="33%"
 448 ALIGN="right"
 449 VALIGN="top"
 450 >NEC uPD985xx USB Device Driver</TD
 451 ></TR
 452 ></TABLE
 453 ></DIV
 454 ></BODY
 455 ></HTML
 456 >