packages/devs/usb/nec_upd985xx/v2_0/doc/devs-usb-nec-upd985xx.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 is obtained from the copyright holder.               -->
  12 <HTML
  13 ><HEAD
  14 ><TITLE
  15 >NEC uPD985xx USB Device Driver</TITLE
  16 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
  17 <META
  18 NAME="GENERATOR"
  19 CONTENT="Modular DocBook HTML Stylesheet Version 1.64
  20 "></HEAD
  21 ><BODY
  22 CLASS="REFENTRY"
  23 BGCOLOR="#FFFFFF"
  24 TEXT="#000000"
  25 LINK="#0000FF"
  26 VLINK="#840084"
  27 ALINK="#0000FF"
  28 ><H1
  29 ><A
  30 NAME="DEVS-USB-NEC-UPD985XX"
  31 >NEC uPD985xx USB Device Driver</A
  32 ></H1
  33 ><DIV
  34 CLASS="REFNAMEDIV"
  35 ><A
  36 NAME="AEN4"
  37 ></A
  38 ><H2
  39 >Name</H2
  40 >NEC uPD985xx USB Support&nbsp;--&nbsp;Device driver for the on-chip NEC uPD985xx USB device</DIV
  41 ><DIV
  42 CLASS="REFSECT1"
  43 ><A
  44 NAME="AEN7"
  45 ></A
  46 ><H2
  47 >NEC uPD985xx USB Hardware</H2
  48 ><P
  49 >The NEC uPD985xx family of processors is supplied with an on-chip USB
  50 slave device, the UDC (USB Device Controller). This supports seven
  51 endpoints. Endpoint 0 can only be used for control messages. Endpoints
  52 1 and 2 are for isochronous transmits and receives respectively.
  53 Endpoints 3 and 4 support bulk transmits and receives. Endpoints 5 and
  54 6 normally support interrupt transmits and receives,but endpoint 5 can
  55 also be configured to support bulk transmits. At this time only the
  56 control endpoint 0, the bulk endpoints 3 and 4, and the interrupt
  57 endpoint 5 are supported.</P
  58 ></DIV
  59 ><DIV
  60 CLASS="REFSECT1"
  61 ><A
  62 NAME="AEN10"
  63 ></A
  64 ><H2
  65 >Endpoint Data Structures</H2
  66 ><P
  67 >The uPD985xx USB device driver can provide up to four data structures
  68 corresponding to the four supported endpoints: a
  69 <SPAN
  70 CLASS="STRUCTNAME"
  71 >usbs_control_endpoint</SPAN
  72 > structure
  73 <TT
  74 CLASS="VARNAME"
  75 >usbs_upd985xx_ep0</TT
  76 >;
  77 <SPAN
  78 CLASS="STRUCTNAME"
  79 >usbs_tx_endpoint</SPAN
  80 > structures
  81 <TT
  82 CLASS="VARNAME"
  83 >usbs_upd985xx_ep3</TT
  84 > and
  85 <TT
  86 CLASS="VARNAME"
  87 >usbs_upd985xx_ep5</TT
  88 >; and a
  89 <SPAN
  90 CLASS="STRUCTNAME"
  91 >usbs_rx_endpoint</SPAN
  92 >
  93 <TT
  94 CLASS="VARNAME"
  95 >usbs_upd985xx_ep4</TT
  96 >. The header file
  97 <TT
  98 CLASS="FILENAME"
  99 >cyg/io/usb/usbs_nec_upd985xx.h</TT
 100 >
 101 provides declarations for these.</P
 102 ><P
 103 >Not all applications will require support for all the endpoints. For
 104 example, if the intended use of the UDC only involves peripheral to
 105 host transfers then <TT
 106 CLASS="LITERAL"
 107 >usbs_upd985xx_ep4</TT
 108 > is redundant.
 109 The device driver provides configuration options to control the
 110 presence of each endpoint:</P
 111 ><P
 112 ></P
 113 ><OL
 114 TYPE="1"
 115 ><LI
 116 ><P
 117 >Endpoint 0 is controlled by
 118 <TT
 119 CLASS="LITERAL"
 120 >CYGFUN_DEVS_USB_UPD985XX_EP0</TT
 121 >. This defaults to
 122 enabled if there are any higher-level packages that require USB
 123 hardware or if the global preference
 124 <TT
 125 CLASS="LITERAL"
 126 >CYGGLO_IO_USB_SLAVE_APPLICATION</TT
 127 > is enabled,
 128 otherwise it is disabled. Usually this has the desired effect. It may
 129 be necessary to override this in special circumstances, for example if
 130 the target board uses an external USB chip in preference to the UDC
 131 and it is that external chip's device driver that should be used
 132 rather than the on-chip UDC. It is not possible to disable endpoint 0
 133 and at the same time enable one or both of the other endpoints, since
 134 a USB device is only usable if it can process the standard control
 135 messages.</P
 136 ></LI
 137 ><LI
 138 ><P
 139 >Endpoint 3 is controlled by
 140 <TT
 141 CLASS="LITERAL"
 142 >CYGPKG_DEVS_USB_UPD985XX_EP3</TT
 143 >. By default this
 144 endpoint is disabled: according to NEC erratum U3 there may be
 145 problems when attempting bulk transfers of 192 bytes or greater. As an
 146 alternative the device driver provides endpoint 5 configured to
 147 support bulk transfers. Endpoint 3 can be enabled if the application
 148 only requires bulk transfers of less than 192 bytes, or if this
 149 erratum is not applicable to the system being developed for other
 150 reasons.</P
 151 ></LI
 152 ><LI
 153 ><P
 154 >Similarly endpoint 4 is controlled by
 155 <TT
 156 CLASS="LITERAL"
 157 >CYGPKG_DEVS_USB_UPD985XX_EP4</TT
 158 >. This is enabled by
 159 default whenever endpoint 0 is enabled, but it can be disabled
 160 manually.</P
 161 ></LI
 162 ><LI
 163 ><P
 164 >Endpoint 5 is controlled by
 165 <TT
 166 CLASS="LITERAL"
 167 >CYGPKG_DEVS_USB_UPD985XX_EP5</TT
 168 >. This is enabled by
 169 default whenever endpoint 0 is enabled, but it can be disabled
 170 manually. There is also a configuration option
 171 <TT
 172 CLASS="LITERAL"
 173 >CYGIMP_DEVS_USB_UPD985XX_EP5_BULK</TT
 174 >, enabled by
 175 default. This option allows the endpoint to be used for bulk
 176 transfers rather than interrupt transfers.</P
 177 ></LI
 178 ></OL
 179 ><P
 180 >The uPD985xx USB device driver implements the interface specified by the
 181 common eCos USB Slave Support package. The documentation for that
 182 package should be consulted for further details. </P
 183 ><P
 184 >The device driver assumes a bulk packet size of 64 bytes, so this
 185 value should be used in the endpoint descriptors in the enumeration
 186 data provided by application code. The device driver also assumes
 187 a control packet size of eight bytes, and again this should be
 188 reflected in the enumeration data. If endpoint 5 is configured for
 189 interrupt rather than bulk transfers then the maximum packet size is
 190 limited to 64 bytes by the USB standard.</P
 191 ></DIV
 192 ><DIV
 193 CLASS="REFSECT1"
 194 ><A
 195 NAME="AEN40"
 196 ></A
 197 ><H2
 198 >Devtab Entries</H2
 199 ><P
 200 >In addition to the endpoint data structures the uPD985xx USB device
 201 driver can also provide devtab entries for each endpoint. This allows
 202 higher-level code to use traditional I/O operations such as
 203 <TT
 204 CLASS="FUNCTION"
 205 >open</TT
 206 >/<TT
 207 CLASS="FUNCTION"
 208 >read</TT
 209 >/<TT
 210 CLASS="FUNCTION"
 211 >write</TT
 212 >
 213 rather than the USB-specific non-blocking functions like
 214 <TT
 215 CLASS="FUNCTION"
 216 >usbs_start_rx_buffer</TT
 217 >. These devtab entries are
 218 optional since they are not always required. The relevant
 219 configuration options are
 220 <TT
 221 CLASS="LITERAL"
 222 >CYGVAR_DEVS_USB_UPD985XX_EP0_DEVTAB_ENTRY</TT
 223 >,
 224 <TT
 225 CLASS="LITERAL"
 226 >CYGVAR_DEVS_USB_UPD985XX_EP3_DEVTAB_ENTRY</TT
 227 >,
 228 <TT
 229 CLASS="LITERAL"
 230 >CYGVAR_DEVS_USB_UPD985XX_EP4_DEVTAB_ENTRY</TT
 231 >, and
 232 <TT
 233 CLASS="LITERAL"
 234 >CYGVAR_DEVS_USB_UPD985XX_EP5_DEVTAB_ENTRY</TT
 235 >. By
 236 default these devtab entries are provided if the global preference
 237 <TT
 238 CLASS="LITERAL"
 239 >CYGGLO_USB_SLAVE_PROVIDE_DEVTAB_ENTRIES</TT
 240 > is enabled,
 241 which is usually the case. Obviously a devtab entry for a given
 242 endpoint will only be provided if the underlying endpoint is enabled.
 243 For example, there will not be a devtab entry for endpoint 4 if
 244 <TT
 245 CLASS="LITERAL"
 246 >CYGPKG_DEVS_USB_UPD985XX_EP4</TT
 247 > is disabled.</P
 248 ><P
 249 >The names for the devtab entries are determined by using a
 250 configurable base name and appending <TT
 251 CLASS="LITERAL"
 252 >0c</TT
 253 >,
 254 <TT
 255 CLASS="LITERAL"
 256 >3w</TT
 257 >, <TT
 258 CLASS="LITERAL"
 259 >4r</TT
 260 > or <TT
 261 CLASS="LITERAL"
 262 >5w</TT
 263 >.
 264 The base name is determined by the configuration option
 265 <TT
 266 CLASS="LITERAL"
 267 >CYGDAT_DEVS_USB_UPD985XX_DEVTAB_BASENAME</TT
 268 > and has a
 269 default value of <TT
 270 CLASS="LITERAL"
 271 >/dev/usbs</TT
 272 >, so the devtab entry for
 273 endpoint 4 would default to <TT
 274 CLASS="LITERAL"
 275 >/dev/usbs4r</TT
 276 >. If the
 277 target hardware involves multiple USB devices then application
 278 developers may have to change the base name to prevent a name clash
 279 with other USB device drivers.</P
 280 ></DIV
 281 ><DIV
 282 CLASS="REFSECT1"
 283 ><A
 284 NAME="AEN61"
 285 ></A
 286 ><H2
 287 >Restrictions</H2
 288 ><P
 289 >The current device driver imposes a restriction on certain bulk
 290 receives on endpoint 4. If the protocol being used involves
 291 variable-length transfers, in other words if the host is allowed to
 292 send less data than a maximum-sized transfer, then the buffer passed
 293 to the device driver for receives must be aligned to a 16-byte
 294 cacheline boundary and it must be a multiple of this 16-byte cacheline
 295 size. This restriction does not apply if the protocol only involves
 296 fixed-size transfers.</P
 297 ></DIV
 298 ><DIV
 299 CLASS="REFSECT1"
 300 ><A
 301 NAME="AEN64"
 302 ></A
 303 ><H2
 304 >Optional Hardware Workarounds</H2
 305 ><P
 306 >The NEC errata list a number of other problems that affect the
 307 USB device driver. The device driver contains workarounds for these,
 308 which are enabled by default but can be disabled if the application
 309 developer knows that the relevant errata are not relevant to the
 310 system being developed.</P
 311 ><P
 312 >Erratum S1 lists a possible problem if the device driver attempts
 313 multiple writes to the USB hardware. This is circumvented by a
 314 dummy read operation after every write. If this workaround is not
 315 required then the configuration option
 316 <TT
 317 CLASS="LITERAL"
 318 >CYGIMP_DEVS_USB_UPD985XX_IBUS_WRITE_LIMIT</TT
 319 > can be disabled.</P
 320 ><P
 321 >Errata U3 and U4 describe various problems related to concurrent
 322 transmissions on different endpoints. By default the device driver
 323 works around this by serializing all transmit operations. For example
 324 if the device driver needs to send a response to a control message on
 325 endpoint 0 while there is an ongoing bulk transfer on endpoint 5, the
 326 response is delayed until the bulk transfer has completed. Under
 327 typical operating conditions this does not cause any problems:
 328 endpoint 0 traffic usually happens only during initialization, when
 329 the target is connected to the host, while endpoint 5 traffic only
 330 happens after initialization. However if transmit serialization is
 331 inappropriate for the system being developed then it can be disabled
 332 using the configuration option
 333 <TT
 334 CLASS="LITERAL"
 335 >CYGIMP_DEVS_USB_UPD985XX_SERIALIZE_TRANSMITS</TT
 336 >. </P
 337 ></DIV
 338 ><DIV
 339 CLASS="REFSECT1"
 340 ><A
 341 NAME="AEN71"
 342 ></A
 343 ><H2
 344 >Platform Dependencies</H2
 345 ><P
 346 >On some platforms it is necessary for the low-level USB device driver
 347 to perform some additional operations during start-up. For example it
 348 may be necessary to manipulate one of the processor's GPIO lines
 349 before the host can detect a new USB peripheral and attempt to
 350 communicate with it. This avoids problems if the target involves a
 351 significant amount of work prior to device driver initialization, for
 352 example a power-on self-test sequence. If the USB host attempted to
 353 contact the target before the USB device driver had been initialized,
 354 it would fail to get the expected responses and conclude that the
 355 target was not a functional USB peripheral.</P
 356 ><P
 357 >Platform-specific initialization code can be provided via a macro
 358 <TT
 359 CLASS="FUNCTION"
 360 >UPD985XX_USB_PLATFORM_INIT</TT
 361 >. Typically this macro
 362 would be defined in the platform HAL's header file
 363 <TT
 364 CLASS="FILENAME"
 365 >cyg/hal/plf_io.h</TT
 366 >. If the
 367 current platform defines such a macro, the USB device driver will
 368 invoke it during the endpoint 0 start-up operation.</P
 369 ></DIV
 370 ></BODY
 371 ></HTML
 372 >