1 |
27 |
unneback |
<!-- 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 -- 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 |
|
|
>
|