doc/html/ref/devs-usb-nec-upd985xx.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 >NEC uPD985xx 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="NEC uPD985xx USB Device Driver"
  23 HREF="devs-usb-nec-upd985xx-ref.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="NEC uPD985xx USB Device Driver"
  26 HREF="devs-usb-nec-upd985xx-ref.html"><LINK
  27 REL="NEXT"
  28 TITLE="Synthetic Target Ethernet Driver"
  29 HREF="devs-eth-synth-ecosynth-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-nec-upd985xx-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-eth-synth-ecosynth-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-NEC-UPD985XX">NEC uPD985xx USB Device Driver</H1
  83 ><DIV
  84 CLASS="REFNAMEDIV"
  85 ><A
  86 NAME="AEN18819"
  87 ></A
  88 ><H2
  89 >Name</H2
  90 >NEC uPD985xx USB Support&nbsp;--&nbsp;Device driver for the on-chip NEC uPD985xx USB device</DIV
  91 ><DIV
  92 CLASS="REFSECT1"
  93 ><A
  94 NAME="AEN18822"
  95 ></A
  96 ><H2
  97 >NEC uPD985xx USB Hardware</H2
  98 ><P
  99 >The NEC uPD985xx family of processors is supplied with an on-chip USB
 100 slave device, the UDC (USB Device Controller). This supports seven
 101 endpoints. Endpoint 0 can only be used for control messages. Endpoints
 102 1 and 2 are for isochronous transmits and receives respectively.
 103 Endpoints 3 and 4 support bulk transmits and receives. Endpoints 5 and
 104 6 normally support interrupt transmits and receives, but endpoint 5 can
 105 also be configured to support bulk transmits. At this time only the
 106 control endpoint 0, the bulk endpoints 3 and 4, and the interrupt
 107 endpoint 5 are supported.</P
 108 ></DIV
 109 ><DIV
 110 CLASS="REFSECT1"
 111 ><A
 112 NAME="AEN18825"
 113 ></A
 114 ><H2
 115 >Endpoint Data Structures</H2
 116 ><P
 117 >The uPD985xx USB device driver can provide up to four data structures
 118 corresponding to the four supported endpoints: a
 119 <SPAN
 120 CLASS="STRUCTNAME"
 121 >usbs_control_endpoint</SPAN
 122 > structure
 123 <TT
 124 CLASS="VARNAME"
 125 >usbs_upd985xx_ep0</TT
 126 >;
 127 <SPAN
 128 CLASS="STRUCTNAME"
 129 >usbs_tx_endpoint</SPAN
 130 > structures
 131 <TT
 132 CLASS="VARNAME"
 133 >usbs_upd985xx_ep3</TT
 134 > and
 135 <TT
 136 CLASS="VARNAME"
 137 >usbs_upd985xx_ep5</TT
 138 >; and a
 139 <SPAN
 140 CLASS="STRUCTNAME"
 141 >usbs_rx_endpoint</SPAN
 142 >
 143 <TT
 144 CLASS="VARNAME"
 145 >usbs_upd985xx_ep4</TT
 146 >. The header file
 147 <TT
 148 CLASS="FILENAME"
 149 >cyg/io/usb/usbs_nec_upd985xx.h</TT
 150 >
 151 provides declarations for these.</P
 152 ><P
 153 >Not all applications will require support for all the endpoints. For
 154 example, if the intended use of the UDC only involves peripheral to
 155 host transfers then <TT
 156 CLASS="LITERAL"
 157 >usbs_upd985xx_ep4</TT
 158 > is redundant.
 159 The device driver provides configuration options to control the
 160 presence of each endpoint:</P
 161 ><P
 162 ></P
 163 ><OL
 164 TYPE="1"
 165 ><LI
 166 ><P
 167 >Endpoint 0 is controlled by
 168 <TT
 169 CLASS="LITERAL"
 170 >CYGFUN_DEVS_USB_UPD985XX_EP0</TT
 171 >. This defaults to
 172 enabled if there are any higher-level packages that require USB
 173 hardware or if the global preference
 174 <TT
 175 CLASS="LITERAL"
 176 >CYGGLO_IO_USB_SLAVE_APPLICATION</TT
 177 > is enabled,
 178 otherwise it is disabled. Usually this has the desired effect. It may
 179 be necessary to override this in special circumstances, for example if
 180 the target board uses an external USB chip in preference to the UDC
 181 and it is that external chip's device driver that should be used
 182 rather than the on-chip UDC. It is not possible to disable endpoint 0
 183 and at the same time enable one or both of the other endpoints, since
 184 a USB device is only usable if it can process the standard control
 185 messages.</P
 186 ></LI
 187 ><LI
 188 ><P
 189 >Endpoint 3 is controlled by
 190 <TT
 191 CLASS="LITERAL"
 192 >CYGPKG_DEVS_USB_UPD985XX_EP3</TT
 193 >. By default this
 194 endpoint is disabled: according to NEC erratum U3 there may be
 195 problems when attempting bulk transfers of 192 bytes or greater. As an
 196 alternative the device driver provides support for endpoint 5,
 197 configured to allow bulk transfers. Endpoint 3 can be enabled if the
 198 application only requires bulk transfers of less than 192 bytes, or if
 199 this erratum is not applicable to the system being developed for other
 200 reasons.</P
 201 ></LI
 202 ><LI
 203 ><P
 204 >Endpoint 4 is controlled by
 205 <TT
 206 CLASS="LITERAL"
 207 >CYGPKG_DEVS_USB_UPD985XX_EP4</TT
 208 >. This is enabled by
 209 default whenever endpoint 0 is enabled, but it can be disabled
 210 manually.</P
 211 ></LI
 212 ><LI
 213 ><P
 214 >Endpoint 5 is controlled by
 215 <TT
 216 CLASS="LITERAL"
 217 >CYGPKG_DEVS_USB_UPD985XX_EP5</TT
 218 >. This is enabled by
 219 default whenever endpoint 0 is enabled, but it can be disabled
 220 manually. There is also a configuration option
 221 <TT
 222 CLASS="LITERAL"
 223 >CYGIMP_DEVS_USB_UPD985XX_EP5_BULK</TT
 224 >, enabled by
 225 default. This option allows the endpoint to be used for bulk
 226 transfers rather than interrupt transfers.</P
 227 ></LI
 228 ></OL
 229 ><P
 230 >The uPD985xx USB device driver implements the interface specified by the
 231 common eCos USB Slave Support package. The documentation for that
 232 package should be consulted for further details. </P
 233 ><P
 234 >The device driver assumes a bulk packet size of 64 bytes, so this
 235 value should be used in the endpoint descriptors in the enumeration
 236 data provided by application code. The device driver also assumes
 237 a control packet size of eight bytes, and again this should be
 238 reflected in the enumeration data. If endpoint 5 is configured for
 239 interrupt rather than bulk transfers then the maximum packet size is
 240 limited to 64 bytes by the USB standard.</P
 241 ></DIV
 242 ><DIV
 243 CLASS="REFSECT1"
 244 ><A
 245 NAME="AEN18855"
 246 ></A
 247 ><H2
 248 >Devtab Entries</H2
 249 ><P
 250 >In addition to the endpoint data structures the uPD985xx USB device
 251 driver can also provide devtab entries for each endpoint. This allows
 252 higher-level code to use traditional I/O operations such as
 253 <TT
 254 CLASS="FUNCTION"
 255 >open</TT
 256 >/<TT
 257 CLASS="FUNCTION"
 258 >read</TT
 259 >/<TT
 260 CLASS="FUNCTION"
 261 >write</TT
 262 >
 263 rather than the USB-specific non-blocking functions like
 264 <TT
 265 CLASS="FUNCTION"
 266 >usbs_start_rx_buffer</TT
 267 >. These devtab entries are
 268 optional since they are not always required. The relevant
 269 configuration options are
 270 <TT
 271 CLASS="LITERAL"
 272 >CYGVAR_DEVS_USB_UPD985XX_EP0_DEVTAB_ENTRY</TT
 273 >,
 274 <TT
 275 CLASS="LITERAL"
 276 >CYGVAR_DEVS_USB_UPD985XX_EP3_DEVTAB_ENTRY</TT
 277 >,
 278 <TT
 279 CLASS="LITERAL"
 280 >CYGVAR_DEVS_USB_UPD985XX_EP4_DEVTAB_ENTRY</TT
 281 >, and
 282 <TT
 283 CLASS="LITERAL"
 284 >CYGVAR_DEVS_USB_UPD985XX_EP5_DEVTAB_ENTRY</TT
 285 >. By
 286 default these devtab entries are provided if the global preference
 287 <TT
 288 CLASS="LITERAL"
 289 >CYGGLO_USB_SLAVE_PROVIDE_DEVTAB_ENTRIES</TT
 290 > is enabled,
 291 which is usually the case. Obviously a devtab entry for a given
 292 endpoint will only be provided if the underlying endpoint is enabled.
 293 For example, there will not be a devtab entry for endpoint 4 if
 294 <TT
 295 CLASS="LITERAL"
 296 >CYGPKG_DEVS_USB_UPD985XX_EP4</TT
 297 > is disabled.</P
 298 ><P
 299 >The names for the devtab entries are determined by using a
 300 configurable base name and appending <TT
 301 CLASS="LITERAL"
 302 >0c</TT
 303 >,
 304 <TT
 305 CLASS="LITERAL"
 306 >3w</TT
 307 >, <TT
 308 CLASS="LITERAL"
 309 >4r</TT
 310 > or <TT
 311 CLASS="LITERAL"
 312 >5w</TT
 313 >.
 314 The base name is determined by the configuration option
 315 <TT
 316 CLASS="LITERAL"
 317 >CYGDAT_DEVS_USB_UPD985XX_DEVTAB_BASENAME</TT
 318 > and has a
 319 default value of <TT
 320 CLASS="LITERAL"
 321 >/dev/usbs</TT
 322 >, so the devtab entry for
 323 endpoint 4 would default to <TT
 324 CLASS="LITERAL"
 325 >/dev/usbs4r</TT
 326 >. If the
 327 target hardware involves multiple USB devices then application
 328 developers may have to change the base name to prevent a name clash
 329 with other USB device drivers.</P
 330 ></DIV
 331 ><DIV
 332 CLASS="REFSECT1"
 333 ><A
 334 NAME="AEN18876"
 335 ></A
 336 ><H2
 337 >Restrictions</H2
 338 ><P
 339 >The current device driver imposes a restriction on certain bulk
 340 receives on endpoint 4. If the protocol being used involves
 341 variable-length transfers, in other words if the host is allowed to
 342 send less data than a maximum-sized transfer, then the buffer passed
 343 to the device driver for receives must be aligned to a 16-byte
 344 cacheline boundary and it must be a multiple of this 16-byte cacheline
 345 size. This restriction does not apply if the protocol only involves
 346 fixed-size transfers.</P
 347 ></DIV
 348 ><DIV
 349 CLASS="REFSECT1"
 350 ><A
 351 NAME="AEN18879"
 352 ></A
 353 ><H2
 354 >Optional Hardware Workarounds</H2
 355 ><P
 356 >The NEC errata list a number of other problems that affect the USB
 357 device driver. The device driver contains workarounds for these, which
 358 are enabled by default but can be disabled if the application
 359 developer knows that the errata are not relevant to the system being
 360 developed.</P
 361 ><P
 362 >Erratum S1 lists a possible problem if the device driver attempts
 363 multiple writes to the USB hardware. This is circumvented by a
 364 dummy read operation after every write. If the workaround is not
 365 required then the configuration option
 366 <TT
 367 CLASS="LITERAL"
 368 >CYGIMP_DEVS_USB_UPD985XX_IBUS_WRITE_LIMIT</TT
 369 > can be disabled.</P
 370 ><P
 371 >Errata U3 and U4 describe various problems related to concurrent
 372 transmissions on different endpoints. By default the device driver
 373 works around this by serializing all transmit operations. For example
 374 if the device driver needs to send a response to a control message on
 375 endpoint 0 while there is an ongoing bulk transfer on endpoint 5, the
 376 response is delayed until the bulk transfer has completed. Under
 377 typical operating conditions this does not cause any problems:
 378 endpoint 0 traffic usually happens only during initialization, when
 379 the target is connected to the host, while endpoint 5 traffic only
 380 happens after initialization. However if transmit serialization is
 381 inappropriate for the system being developed then it can be disabled
 382 using the configuration option
 383 <TT
 384 CLASS="LITERAL"
 385 >CYGIMP_DEVS_USB_UPD985XX_SERIALIZE_TRANSMITS</TT
 386 >. </P
 387 ></DIV
 388 ><DIV
 389 CLASS="REFSECT1"
 390 ><A
 391 NAME="AEN18886"
 392 ></A
 393 ><H2
 394 >Platform Dependencies</H2
 395 ><P
 396 >On some platforms it is necessary for the low-level USB device driver
 397 to perform some additional operations during start-up. For example it
 398 may be necessary to manipulate one of the processor's GPIO lines
 399 before the host can detect a new USB peripheral and attempt to
 400 communicate with it. This avoids problems if the target involves a
 401 significant amount of work prior to device driver initialization, for
 402 example a power-on self-test sequence. If the USB host attempted to
 403 contact the target before the USB device driver had been initialized,
 404 it would fail to get the expected responses and conclude that the
 405 target was not a functional USB peripheral.</P
 406 ><P
 407 >Platform-specific initialization code can be provided via a macro
 408 <TT
 409 CLASS="FUNCTION"
 410 >UPD985XX_USB_PLATFORM_INIT</TT
 411 >. Typically this macro
 412 would be defined in the platform HAL's header file
 413 <TT
 414 CLASS="FILENAME"
 415 >cyg/hal/plf_io.h</TT
 416 >. If the
 417 current platform defines such a macro, the USB device driver will
 418 invoke it during the endpoint 0 start-up operation.</P
 419 ></DIV
 420 ><DIV
 421 CLASS="NAVFOOTER"
 422 ><HR
 423 ALIGN="LEFT"
 424 WIDTH="100%"><TABLE
 425 SUMMARY="Footer navigation table"
 426 WIDTH="100%"
 427 BORDER="0"
 428 CELLPADDING="0"
 429 CELLSPACING="0"
 430 ><TR
 431 ><TD
 432 WIDTH="33%"
 433 ALIGN="left"
 434 VALIGN="top"
 435 ><A
 436 HREF="devs-usb-nec-upd985xx-ref.html"
 437 ACCESSKEY="P"
 438 >Prev</A
 439 ></TD
 440 ><TD
 441 WIDTH="34%"
 442 ALIGN="center"
 443 VALIGN="top"
 444 ><A
 445 HREF="ecos-ref.html"
 446 ACCESSKEY="H"
 447 >Home</A
 448 ></TD
 449 ><TD
 450 WIDTH="33%"
 451 ALIGN="right"
 452 VALIGN="top"
 453 ><A
 454 HREF="devs-eth-synth-ecosynth-ref.html"
 455 ACCESSKEY="N"
 456 >Next</A
 457 ></TD
 458 ></TR
 459 ><TR
 460 ><TD
 461 WIDTH="33%"
 462 ALIGN="left"
 463 VALIGN="top"
 464 >NEC uPD985xx USB Device Driver</TD
 465 ><TD
 466 WIDTH="34%"
 467 ALIGN="center"
 468 VALIGN="top"
 469 ><A
 470 HREF="devs-usb-nec-upd985xx-ref.html"
 471 ACCESSKEY="U"
 472 >Up</A
 473 ></TD
 474 ><TD
 475 WIDTH="33%"
 476 ALIGN="right"
 477 VALIGN="top"
 478 >Synthetic Target Ethernet Driver</TD
 479 ></TR
 480 ></TABLE
 481 ></DIV
 482 ></BODY
 483 ></HTML
 484 >