packages/devs/usb/nec_upd985xx/v2_0/doc/usbs_upd985xx.sgml

   1 <!-- DOCTYPE refentry  PUBLIC "-//OASIS//DTD DocBook V3.1//EN" -->
   2
   3 <!-- {{{ Banner                         -->
   4
   5 <!-- =============================================================== -->
   6 <!--                                                                 -->
   7 <!--     usbs_nec_upd9850x.sgml                                      -->
   8 <!--                                                                 -->
   9 <!--     Documentation for the NEC uPD9850x 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/05/22                                         -->
  32 <!-- Version:     0.01                                               -->
  33 <!--                                                                 -->
  34 <!-- ####DESCRIPTIONEND####                                          -->
  35 <!-- =============================================================== -->
  36
  37 <!-- }}} -->
  38
  39 <part id="devs-usb-nec-upd985xx-ref">
  40 <!-- reference id="devs-usb-nec-upd985xx-ref" -->
  41   <title>NEC uPD985xx USB Device Driver</title>
  42
  43 <refentry id="devs-usb-nec-upd985xx">
  44 <refmeta>
  45 <refentrytitle>NEC uPD985xx USB Device Driver</refentrytitle>
  46 </refmeta>
  47 <refnamediv>
  48 <refname>NEC uPD985xx USB Support</refname>
  49 <refpurpose>Device driver for the on-chip NEC uPD985xx USB device</refpurpose>
  50 </refnamediv>
  51
  52 <refsect1><title>NEC uPD985xx USB Hardware</title>
  53 <para>
  54 The NEC uPD985xx family of processors is supplied with an on-chip USB
  55 slave device, the UDC (USB Device Controller). This supports seven
  56 endpoints. Endpoint 0 can only be used for control messages. Endpoints
  57 1 and 2 are for isochronous transmits and receives respectively.
  58 Endpoints 3 and 4 support bulk transmits and receives. Endpoints 5 and
  59 6 normally support interrupt transmits and receives, but endpoint 5 can
  60 also be configured to support bulk transmits. At this time only the
  61 control endpoint 0, the bulk endpoints 3 and 4, and the interrupt
  62 endpoint 5 are supported.
  63 </para>
  64 </refsect1>
  65
  66 <refsect1><title>Endpoint Data Structures</title>
  67 <para>
  68 The uPD985xx USB device driver can provide up to four data structures
  69 corresponding to the four supported endpoints: a
  70 <structname>usbs_control_endpoint</structname> structure
  71 <varname>usbs_upd985xx_ep0</varname>;
  72 <structname>usbs_tx_endpoint</structname> structures
  73 <varname>usbs_upd985xx_ep3</varname> and
  74 <varname>usbs_upd985xx_ep5</varname>; and a
  75 <structname>usbs_rx_endpoint</structname>
  76 <varname>usbs_upd985xx_ep4</varname>. The header file
  77 <filename class="headerfile">cyg/io/usb/usbs_nec_upd985xx.h</filename>
  78 provides declarations for these.
  79 </para>
  80 <para>
  81 Not all applications will require support for all the endpoints. For
  82 example, if the intended use of the UDC only involves peripheral to
  83 host transfers then <literal>usbs_upd985xx_ep4</literal> is redundant.
  84 The device driver provides configuration options to control the
  85 presence of each endpoint:
  86 </para>
  87 <orderedlist>
  88 <listitem>
  89 <para>
  90 Endpoint 0 is controlled by
  91 <literal>CYGFUN_DEVS_USB_UPD985XX_EP0</literal>. This defaults to
  92 enabled if there are any higher-level packages that require USB
  93 hardware or if the global preference
  94 <literal>CYGGLO_IO_USB_SLAVE_APPLICATION</literal> is enabled,
  95 otherwise it is disabled. Usually this has the desired effect. It may
  96 be necessary to override this in special circumstances, for example if
  97 the target board uses an external USB chip in preference to the UDC
  98 and it is that external chip's device driver that should be used
  99 rather than the on-chip UDC. It is not possible to disable endpoint 0
 100 and at the same time enable one or both of the other endpoints, since
 101 a USB device is only usable if it can process the standard control
 102 messages.
 103 </para>
 104 </listitem>
 105 <listitem>
 106 <para>
 107 Endpoint 3 is controlled by
 108 <literal>CYGPKG_DEVS_USB_UPD985XX_EP3</literal>. By default this
 109 endpoint is disabled: according to NEC erratum U3 there may be
 110 problems when attempting bulk transfers of 192 bytes or greater. As an
 111 alternative the device driver provides support for endpoint 5,
 112 configured to allow bulk transfers. Endpoint 3 can be enabled if the
 113 application only requires bulk transfers of less than 192 bytes, or if
 114 this erratum is not applicable to the system being developed for other
 115 reasons.
 116 </para>
 117 </listitem>
 118 <listitem>
 119 <para>
 120 Endpoint 4 is controlled by
 121 <literal>CYGPKG_DEVS_USB_UPD985XX_EP4</literal>. This is enabled by
 122 default whenever endpoint 0 is enabled, but it can be disabled
 123 manually.
 124 </para>
 125 </listitem>
 126 <listitem>
 127 <para>
 128 Endpoint 5 is controlled by
 129 <literal>CYGPKG_DEVS_USB_UPD985XX_EP5</literal>. This is enabled by
 130 default whenever endpoint 0 is enabled, but it can be disabled
 131 manually. There is also a configuration option
 132 <literal>CYGIMP_DEVS_USB_UPD985XX_EP5_BULK</literal>, enabled by
 133 default. This option allows the endpoint to be used for bulk
 134 transfers rather than interrupt transfers.
 135 </para>
 136 </listitem>
 137 </orderedlist>
 138 <para>
 139 The uPD985xx USB device driver implements the interface specified by the
 140 common eCos USB Slave Support package. The documentation for that
 141 package should be consulted for further details.
 142 </para>
 143 <para>
 144 The device driver assumes a bulk packet size of 64 bytes, so this
 145 value should be used in the endpoint descriptors in the enumeration
 146 data provided by application code. The device driver also assumes
 147 a control packet size of eight bytes, and again this should be
 148 reflected in the enumeration data. If endpoint 5 is configured for
 149 interrupt rather than bulk transfers then the maximum packet size is
 150 limited to 64 bytes by the USB standard.
 151 </para>
 152 </refsect1>
 153
 154 <refsect1><title>Devtab Entries</title>
 155 <para>
 156 In addition to the endpoint data structures the uPD985xx USB device
 157 driver can also provide devtab entries for each endpoint. This allows
 158 higher-level code to use traditional I/O operations such as
 159 <function>open</function>/<function>read</function>/<function>write</function>
 160 rather than the USB-specific non-blocking functions like
 161 <function>usbs_start_rx_buffer</function>. These devtab entries are
 162 optional since they are not always required. The relevant
 163 configuration options are
 164 <literal>CYGVAR_DEVS_USB_UPD985XX_EP0_DEVTAB_ENTRY</literal>,
 165 <literal>CYGVAR_DEVS_USB_UPD985XX_EP3_DEVTAB_ENTRY</literal>,
 166 <literal>CYGVAR_DEVS_USB_UPD985XX_EP4_DEVTAB_ENTRY</literal>, and
 167 <literal>CYGVAR_DEVS_USB_UPD985XX_EP5_DEVTAB_ENTRY</literal>. By
 168 default these devtab entries are provided if the global preference
 169 <literal>CYGGLO_USB_SLAVE_PROVIDE_DEVTAB_ENTRIES</literal> is enabled,
 170 which is usually the case. Obviously a devtab entry for a given
 171 endpoint will only be provided if the underlying endpoint is enabled.
 172 For example, there will not be a devtab entry for endpoint 4 if
 173 <literal>CYGPKG_DEVS_USB_UPD985XX_EP4</literal> is disabled.
 174 </para>
 175 <para>
 176 The names for the devtab entries are determined by using a
 177 configurable base name and appending <literal>0c</literal>,
 178 <literal>3w</literal>, <literal>4r</literal> or <literal>5w</literal>.
 179 The base name is determined by the configuration option
 180 <literal>CYGDAT_DEVS_USB_UPD985XX_DEVTAB_BASENAME</literal> and has a
 181 default value of <literal>/dev/usbs</literal>, so the devtab entry for
 182 endpoint 4 would default to <literal>/dev/usbs4r</literal>. If the
 183 target hardware involves multiple USB devices then application
 184 developers may have to change the base name to prevent a name clash
 185 with other USB device drivers.
 186 </para>
 187 </refsect1>
 188
 189 <refsect1><title>Restrictions</title>
 190 <para>
 191 The current device driver imposes a restriction on certain bulk
 192 receives on endpoint 4. If the protocol being used involves
 193 variable-length transfers, in other words if the host is allowed to
 194 send less data than a maximum-sized transfer, then the buffer passed
 195 to the device driver for receives must be aligned to a 16-byte
 196 cacheline boundary and it must be a multiple of this 16-byte cacheline
 197 size. This restriction does not apply if the protocol only involves
 198 fixed-size transfers.
 199 </para>
 200 </refsect1>
 201
 202 <refsect1><title>Optional Hardware Workarounds</title>
 203 <para>
 204 The NEC errata list a number of other problems that affect the USB
 205 device driver. The device driver contains workarounds for these, which
 206 are enabled by default but can be disabled if the application
 207 developer knows that the errata are not relevant to the system being
 208 developed.
 209 </para>
 210 <para>
 211 Erratum S1 lists a possible problem if the device driver attempts
 212 multiple writes to the USB hardware. This is circumvented by a
 213 dummy read operation after every write. If the workaround is not
 214 required then the configuration option
 215 <literal>CYGIMP_DEVS_USB_UPD985XX_IBUS_WRITE_LIMIT</literal> can be disabled.
 216 </para>
 217 <para>
 218 Errata U3 and U4 describe various problems related to concurrent
 219 transmissions on different endpoints. By default the device driver
 220 works around this by serializing all transmit operations. For example
 221 if the device driver needs to send a response to a control message on
 222 endpoint 0 while there is an ongoing bulk transfer on endpoint 5, the
 223 response is delayed until the bulk transfer has completed. Under
 224 typical operating conditions this does not cause any problems:
 225 endpoint 0 traffic usually happens only during initialization, when
 226 the target is connected to the host, while endpoint 5 traffic only
 227 happens after initialization. However if transmit serialization is
 228 inappropriate for the system being developed then it can be disabled
 229 using the configuration option
 230 <literal>CYGIMP_DEVS_USB_UPD985XX_SERIALIZE_TRANSMITS</literal>.
 231 </para>
 232 </refsect1>
 233
 234 <refsect1><title>Platform Dependencies</title>
 235 <para>
 236 On some platforms it is necessary for the low-level USB device driver
 237 to perform some additional operations during start-up. For example it
 238 may be necessary to manipulate one of the processor's GPIO lines
 239 before the host can detect a new USB peripheral and attempt to
 240 communicate with it. This avoids problems if the target involves a
 241 significant amount of work prior to device driver initialization, for
 242 example a power-on self-test sequence. If the USB host attempted to
 243 contact the target before the USB device driver had been initialized,
 244 it would fail to get the expected responses and conclude that the
 245 target was not a functional USB peripheral.
 246 </para>
 247 <para>
 248 Platform-specific initialization code can be provided via a macro
 249 <function>UPD985XX_USB_PLATFORM_INIT</function>. Typically this macro
 250 would be defined in the platform HAL's header file
 251 <filename class="headerfile">cyg/hal/plf_io.h</filename>. If the
 252 current platform defines such a macro, the USB device driver will
 253 invoke it during the endpoint 0 start-up operation.
 254 </para>
 255 </refsect1>
 256
 257 </refentry>
 258 </part>
 259 <!-- /reference -->