OpenCores
URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [rtos/] [ecos-2.0/] [packages/] [io/] [usb/] [slave/] [v2_0/] [doc/] [usbs-writing.html] - Blame information for rev 174

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 27 unneback 
<!-- Copyright (C) 2002 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 
>Writing a 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 
"><LINK
21 
REL="HOME"
22 
TITLE="eCos USB Slave Support"
23 
HREF="io-usb-slave.html"><LINK
24 
REL="PREVIOUS"
25 
TITLE="Data Endpoints"
26 
HREF="usbs-data.html"><LINK
27 
REL="NEXT"
28 
TITLE="Testing"
29 
HREF="usbs-testing.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 
WIDTH="100%"
41 
BORDER="0"
42 
CELLPADDING="0"
43 
CELLSPACING="0"
44 
><TR
45 
><TH
46 
COLSPAN="3"
47 
ALIGN="center"
48 
>eCos USB Slave Support</TH
49 
></TR
50 
><TR
51 
><TD
52 
WIDTH="10%"
53 
ALIGN="left"
54 
VALIGN="bottom"
55 
><A
56 
HREF="usbs-data.html"
57 
>Prev</A
58 
></TD
59 
><TD
60 
WIDTH="80%"
61 
ALIGN="center"
62 
VALIGN="bottom"
63 
></TD
64 
><TD
65 
WIDTH="10%"
66 
ALIGN="right"
67 
VALIGN="bottom"
68 
><A
69 
HREF="usbs-testing.html"
70 
>Next</A
71 
></TD
72 
></TR
73 
></TABLE
74 
><HR
75 
ALIGN="LEFT"
76 
WIDTH="100%"></DIV
77 
><H1
78 
><A
79 
NAME="USBS-WRITING"
80 
>Writing a USB Device Driver</A
81 
></H1
82 
><DIV
83 
CLASS="REFNAMEDIV"
84 
><A
85 
NAME="AEN668"
86 
></A
87 
><H2
88 
>Name</H2
89 
>Writing a USB Device Driver&nbsp;--&nbsp;USB Device Driver Porting Guide</DIV
90 
><DIV
91 
CLASS="REFSECT1"
92 
><A
93 
NAME="AEN671"
94 
></A
95 
><H2
96 
>Introduction</H2
97 
><P
98 
>Often the best way to write a USB device driver will be to start with
99 
an existing one and modify it as necessary. The information given here
100 
is intended primarily as an outline rather than as a complete guide.</P
101 
><DIV
102 
CLASS="NOTE"
103 
><BLOCKQUOTE
104 
CLASS="NOTE"
105 
><P
106 
><B
107 
>Note: </B
108 
>At the time of writing only one USB device driver has been
109 
implemented. Hence it is possible, perhaps probable, that some
110 
portability issues have not yet been addressed. One issue
111 
involves the different types of transfer, for example the initial
112 
target hardware had no support for isochronous or interrupt transfers,
113 
so additional functionality may be needed to switch between transfer
114 
types. Another issue would be hardware where a given endpoint number,
115 
say endpoint 1, could be used for either receiving or transmitting
116 
data, but not both because a single fifo is used. Issues like these
117 
will have to be resolved as and when additional USB device drivers are
118 
written.</P
119 
></BLOCKQUOTE
120 
></DIV
121 
></DIV
122 
><DIV
123 
CLASS="REFSECT1"
124 
><A
125 
NAME="AEN676"
126 
></A
127 
><H2
128 
>The Control Endpoint</H2
129 
><P
130 
>A USB device driver should provide a single <A
131 
HREF="usbs-control.html"
132 
><SPAN
133 
CLASS="STRUCTNAME"
134 
>usbs_control_endpoint</SPAN
135 
></A
136 
>
137 
data structure for every USB device. Typical peripherals will have
138 
only one USB port so there will be just one such data structure in the
139 
entire system, but theoretically it is possible to have multiple USB
140 
devices. These may all involve the same chip, in which case a single
141 
device driver should support multiple device instances, or they may
142 
involve different chips. The name or names of these data structures
143 
are determined by the device driver, but appropriate care should be
144 
taken to avoid name clashes. </P
145 
><P
146 
>A USB device cannot be used unless the control endpoint data structure
147 
exists. However, the presence of USB hardware in the target processor
148 
or board does not guarantee that the application will necessarily want
149 
to use that hardware. To avoid unwanted code or data overheads, the
150 
device driver can provide a configuration option to determine whether
151 
or not the endpoint 0 data structure is actually provided. A default
152 
value of <TT
153 
CLASS="LITERAL"
154 
>CYGINT_IO_USB_SLAVE_CLIENTS</TT
155 
> ensures that
156 
the USB driver will be enabled automatically if higher-level code does
157 
require USB support, while leaving ultimate control to the user.</P
158 
><P
159 
>The USB device driver is responsible for filling in the
160 
<TT
161 
CLASS="STRUCTFIELD"
162 
><I
163 
>start_fn</I
164 
></TT
165 
>,
166 
<TT
167 
CLASS="STRUCTFIELD"
168 
><I
169 
>poll_fn</I
170 
></TT
171 
> and
172 
<TT
173 
CLASS="STRUCTFIELD"
174 
><I
175 
>interrupt_vector</I
176 
></TT
177 
> fields. Usually this can
178 
be achieved by static initialization. The driver is also largely
179 
responsible for maintaining the <TT
180 
CLASS="STRUCTFIELD"
181 
><I
182 
>state</I
183 
></TT
184 
>
185 
field. The <TT
186 
CLASS="STRUCTFIELD"
187 
><I
188 
>control_buffer</I
189 
></TT
190 
> array should be
191 
used to hold the first packet of a control message. The
192 
<TT
193 
CLASS="STRUCTFIELD"
194 
><I
195 
>buffer</I
196 
></TT
197 
> and other fields related to data
198 
transfers will be managed <A
199 
HREF="usbs-control.html#AEN578"
200 
>jointly</A
201 
> by higher-level code and
202 
the device driver. The remaining fields are generally filled in by
203 
higher-level code, although the driver should initialize them to NULL
204 
values.</P
205 
><P
206 
>Hardware permitting, the USB device should be inactive until the
207 
<TT
208 
CLASS="STRUCTFIELD"
209 
><I
210 
>start_fn</I
211 
></TT
212 
> is invoked, for example by
213 
tristating the appropriate pins. This prevents the host from
214 
interacting with the peripheral before all other parts of the system
215 
have initialized. It is expected that the
216 
<TT
217 
CLASS="STRUCTFIELD"
218 
><I
219 
>start_fn</I
220 
></TT
221 
> will only be invoked once, shortly
222 
after power-up.</P
223 
><P
224 
>Where possible the device driver should detect state changes, such as
225 
when the connection between host and peripheral is established, and
226 
<A
227 
HREF="usbs-control.html#AEN515"
228 
>report</A
229 
> these to higher-level
230 
code via the <TT
231 
CLASS="STRUCTFIELD"
232 
><I
233 
>state_change_fn</I
234 
></TT
235 
> callback, if
236 
any. The state change to and from configured state cannot easily be
237 
handled by the device driver itself, instead higher-level code such as
238 
the common USB slave package will take care of this.</P
239 
><P
240 
>Once the connection between host and peripheral has been established,
241 
the peripheral must be ready to accept control messages at all times,
242 
and must respond to these within certain time constraints. For
243 
example, the standard set-address control message must be handled
244 
within 50ms. The USB specification provides more information on these
245 
constraints. The device driver is responsible for receiving the
246 
initial packet of a control message. This packet will always be eight
247 
bytes and should be stored in the
248 
<TT
249 
CLASS="STRUCTFIELD"
250 
><I
251 
>control_buffer</I
252 
></TT
253 
> field. Certain standard
254 
control messages should be detected and handled by the device driver
255 
itself. The most important is set-address, but usually the get-status,
256 
set-feature and clear-feature requests when applied to halted
257 
endpoints should also be handled by the driver. Other standard control
258 
messages should first be passed on to the
259 
<TT
260 
CLASS="STRUCTFIELD"
261 
><I
262 
>standard_control_fn</I
263 
></TT
264 
> callback (if any), and
265 
finally to the default handler
266 
<TT
267 
CLASS="FUNCTION"
268 
>usbs_handle_standard_control</TT
269 
> provided by the
270 
common USB slave package. Class, vendor and reserved control messages
271 
should always be dispatched to the appropriate callback and there is
272 
no default handler for these.</P
273 
><P
274 
>Some control messages will involve further data transfer, not just the
275 
initial packet. The device driver must handle this in accordance with
276 
the USB specification and the <A
277 
HREF="usbs-control.html#AEN578"
278 
>buffer management strategy</A
279 
>. The
280 
driver is also responsible for keeping track of whether or not the
281 
control operation has succeeded and generating an ACK or STALL
282 
handshake. </P
283 
><P
284 
>The polling support is optional and may not be feasible on all
285 
hardware. It is only used in certain specialised environments such as
286 
RedBoot. A typical implementation of the polling function would just
287 
check whether or not an interrupt would have occurred and, if so, call
288 
the same code that the interrupt handler would.</P
289 
></DIV
290 
><DIV
291 
CLASS="REFSECT1"
292 
><A
293 
NAME="AEN704"
294 
></A
295 
><H2
296 
>Data Endpoints</H2
297 
><P
298 
>In addition to the control endpoint data structure, a USB device
299 
driver should also provide appropriate <A
300 
HREF="usbs-data.html"
301 
>data
302 
endpoint</A
303 
> data structures. Obviously this is only relevant if
304 
the USB support generally is desired, that is if the control endpoint is
305 
provided. In addition, higher-level code may not require all the
306 
endpoints, so it may be useful to provide configuration options that
307 
control the presence of each endpoint. For example, the intended
308 
application might only involve a single transmit endpoint and of
309 
course control messages, so supporting receive endpoints might waste
310 
memory.</P
311 
><P
312 
>Conceptually, data endpoints are much simpler than the control
313 
endpoint. The device driver has to supply two functions, one for
314 
data transfers and another to control the halted condition. These
315 
implement the functionality for
316 
<A
317 
HREF="usbs-start-rx.html"
318 
><TT
319 
CLASS="FUNCTION"
320 
>usbs_start_rx_buffer</TT
321 
></A
322 
>,
323 
<A
324 
HREF="usbs-start-tx.html"
325 
><TT
326 
CLASS="FUNCTION"
327 
>usbs_start_tx_buffer</TT
328 
></A
329 
>,
330 
<A
331 
HREF="usbs-halt.html"
332 
><TT
333 
CLASS="FUNCTION"
334 
>usbs_set_rx_endpoint_halted</TT
335 
></A
336 
> and
337 
<A
338 
HREF="usbs-halt.html"
339 
><TT
340 
CLASS="FUNCTION"
341 
>usbs_set_tx_endpoint_halted</TT
342 
></A
343 
>.
344 
The device driver is also responsible for maintaining the
345 
<TT
346 
CLASS="STRUCTFIELD"
347 
><I
348 
>halted</I
349 
></TT
350 
> status.</P
351 
><P
352 
>For data transfers, higher-level code will have filled in the
353 
<TT
354 
CLASS="STRUCTFIELD"
355 
><I
356 
>buffer</I
357 
></TT
358 
>,
359 
<TT
360 
CLASS="STRUCTFIELD"
361 
><I
362 
>buffer_size</I
363 
></TT
364 
>,
365 
<TT
366 
CLASS="STRUCTFIELD"
367 
><I
368 
>complete_fn</I
369 
></TT
370 
> and
371 
<TT
372 
CLASS="STRUCTFIELD"
373 
><I
374 
>complete_data</I
375 
></TT
376 
> fields. The transfer function
377 
should arrange for the transfer to start, allowing the host to send or
378 
receive packets. Typically this will result in an interrupt at the end
379 
of the transfer or after each packet. Once the entire transfer has
380 
been completed, the driver's interrupt handling code should invoke the
381 
completion function. This can happen either in DSR context or thread
382 
context, depending on the driver's implementation. There are a number
383 
of special cases to consider. If the endpoint is halted when the
384 
transfer is started then the completion function can be invoked
385 
immediately with <TT
386 
CLASS="LITERAL"
387 
>-EAGAIN</TT
388 
>. If the transfer cannot be
389 
completed because the connection is broken then the completion
390 
function should be invoked with <TT
391 
CLASS="LITERAL"
392 
>-EPIPE</TT
393 
>. If the
394 
endpoint is stalled during the transfer, either because of a standard
395 
control message or because higher-level code calls the appropriate
396 
<TT
397 
CLASS="STRUCTFIELD"
398 
><I
399 
>set_halted_fn</I
400 
></TT
401 
>, then again the completion
402 
function should be invoked with <TT
403 
CLASS="LITERAL"
404 
>-EAGAIN</TT
405 
>. Finally,
406 
the &#60;<TT
407 
CLASS="FUNCTION"
408 
>usbs_start_rx_endpoint_wait</TT
409 
> and
410 
<TT
411 
CLASS="FUNCTION"
412 
>usbs_start_tx_endpoint_wait</TT
413 
> functions involve
414 
calling the device driver's data transfer function with a buffer size
415 
of 0 bytes.</P
416 
><DIV
417 
CLASS="NOTE"
418 
><BLOCKQUOTE
419 
CLASS="NOTE"
420 
><P
421 
><B
422 
>Note: </B
423 
>Giving a buffer size of 0 bytes a special meaning is problematical
424 
because it prevents transfers of that size. Such transfers are allowed
425 
by the USB protocol, consisting of just headers and acknowledgements
426 
and an empty data phase, although rarely useful. A future modification
427 
of the device driver specification will address this issue, although
428 
care has to be taken that the functionality remains accessible through
429 
devtab entries as well as via low-level accesses.</P
430 
></BLOCKQUOTE
431 
></DIV
432 
></DIV
433 
><DIV
434 
CLASS="REFSECT1"
435 
><A
436 
NAME="AEN731"
437 
></A
438 
><H2
439 
>Devtab Entries</H2
440 
><P
441 
>For some applications or higher-level packages it may be more
442 
convenient to use traditional open/read/write I/O calls rather than
443 
the non-blocking USB I/O calls. To support this the device driver can
444 
provide a devtab entry for each endpoint, for example:</P
445 
><TABLE
446 
BORDER="0"
447 
BGCOLOR="#E0E0E0"
448 
WIDTH="100%"
449 
><TR
450 
><TD
451 
><PRE
452 
CLASS="PROGRAMLISTING"
453 
>#ifdef CYGVAR_DEVS_USB_SA11X0_EP1_DEVTAB_ENTRY
454 
 
455 
static CHAR_DEVIO_TABLE(usbs_sa11x0_ep1_devtab_functions,
456 
                        &amp;cyg_devio_cwrite,
457 
                        &amp;usbs_devtab_cread,
458 
                        &amp;cyg_devio_bwrite,
459 
                        &amp;cyg_devio_bread,
460 
                        &amp;cyg_devio_select,
461 
                        &amp;cyg_devio_get_config,
462 
                        &amp;cyg_devio_set_config);
463 
 
464 
static CHAR_DEVTAB_ENTRY(usbs_sa11x0_ep1_devtab_entry,
465 
                         CYGDAT_DEVS_USB_SA11X0_DEVTAB_BASENAME "1r",
466 
                         0,
467 
                         &amp;usbs_sa11x0_ep1_devtab_functions,
468 
                         &amp;usbs_sa11x0_devtab_dummy_init,
469 
                         0,
470 
                         (void*) &amp;usbs_sa11x0_ep1);
471 
#endif</PRE
472 
></TD
473 
></TR
474 
></TABLE
475 
><P
476 
>Again care must be taken to avoid name clashes. This can be achieved
477 
by having a configuration option to control the base name, with a
478 
default value of e.g. <TT
479 
CLASS="LITERAL"
480 
>/dev/usbs</TT
481 
>, and appending an
482 
endpoint-specific string. This gives the application developer
483 
sufficient control to eliminate any name clashes. The common USB slave
484 
package provides functions <TT
485 
CLASS="FUNCTION"
486 
>usbs_devtab_cwrite</TT
487 
> and
488 
<TT
489 
CLASS="FUNCTION"
490 
>usbs_devtab_cread</TT
491 
>, which can be used in the
492 
function tables for transmit and receive endpoints respectively. The
493 
private field <TT
494 
CLASS="STRUCTFIELD"
495 
><I
496 
>priv</I
497 
></TT
498 
> of the devtab entry
499 
should be a pointer to the underlying endpoint data structure.</P
500 
><P
501 
>Because devtab entries are never accessed directly, only indirectly,
502 
they would usually be eliminated by the linker. To avoid this the
503 
devtab entries should normally be defined in a separate source file
504 
which ends up the special library <TT
505 
CLASS="FILENAME"
506 
>libextras.a</TT
507 
>
508 
rather than in the default library <TT
509 
CLASS="FILENAME"
510 
>libtarget.a</TT
511 
>.</P
512 
><P
513 
>Not all applications or higher-level packages will want to use the
514 
devtab entries and the blocking I/O facilities. It may be appropriate
515 
for the device driver to provide additional configuration options that
516 
control whether or not any or all of the devtab entries should be
517 
provided, to avoid unnecessary memory overheads.</P
518 
></DIV
519 
><DIV
520 
CLASS="REFSECT1"
521 
><A
522 
NAME="AEN744"
523 
></A
524 
><H2
525 
>Interrupt Handling</H2
526 
><P
527 
>A typical USB device driver will need to service interrupts for all of
528 
the endpoints and possibly for additional USB events such as entering
529 
or leaving suspended mode. Usually these interrupts need not be
530 
serviced directly by the ISR. Instead, they can be left to a DSR. If
531 
the peripheral is not able to accept or send another packet just yet,
532 
the hardware will generate a NAK and the host will just retry a little
533 
bit later. If high throughput is required then it may be desirable to
534 
handle the bulk transfer protocol largely at ISR level, that is take
535 
care of each packet in the ISR and only activate the DSR once the
536 
whole transfer has completed.</P
537 
><P
538 
>Control messages may involve invoking arbitrary callback functions in
539 
higher-level code. This should normally happen at DSR level. Doing it
540 
at ISR level could seriously affect the system's interrupt latency and
541 
impose unacceptable constraints on what operations can be performed by
542 
those callbacks. If the device driver requires a thread anyway then it
543 
may be appropriate to use this thread for invoking the callbacks, but
544 
usually it is not worthwhile to add a new thread to the system just
545 
for this; higher-level code is expected to write callbacks that
546 
function sensibly at DSR level. Much the same applies to the
547 
completion functions associated with data transfers. These should also
548 
be invoked at DSR or thread level.</P
549 
></DIV
550 
><DIV
551 
CLASS="REFSECT1"
552 
><A
553 
NAME="AEN748"
554 
></A
555 
><H2
556 
>Support for USB Testing</H2
557 
><P
558 
>Optionally a USB device driver can provide support for the
559 
<A
560 
HREF="usbs-testing.html"
561 
>USB test software</A
562 
>. This requires
563 
defining a number of additional data structures, allowing the
564 
generic test code to work out just what the hardware is capable of and
565 
hence what testing can be performed.</P
566 
><P
567 
>The key data structure is
568 
<SPAN
569 
CLASS="STRUCTNAME"
570 
>usbs_testing_endpoint</SPAN
571 
>, defined in <TT
572 
CLASS="FILENAME"
573 
>cyg/io/usb/usbs.h</TT
574 
>. In addition some
575 
commonly required constants are provided by the common USB package in
576 
<TT
577 
CLASS="FILENAME"
578 
>cyg/io/usb/usb.h</TT
579 
>. One
580 
<SPAN
581 
CLASS="STRUCTNAME"
582 
>usbs_testing_endpoint</SPAN
583 
> structure should be
584 
defined for each supported endpoint. The following fields need to be
585 
filled in:</P
586 
><P
587 
></P
588 
><DIV
589 
CLASS="VARIABLELIST"
590 
><DL
591 
><DT
592 
><TT
593 
CLASS="STRUCTFIELD"
594 
><I
595 
>endpoint_type</I
596 
></TT
597 
></DT
598 
><DD
599 
><P
600 
>    This specifies the type of endpoint and should be one of
601 
    <TT
602 
CLASS="LITERAL"
603 
>USB_ENDPOINT_DESCRIPTOR_ATTR_CONTROL</TT
604 
>,
605 
    <TT
606 
CLASS="LITERAL"
607 
>BULK</TT
608 
>, <TT
609 
CLASS="LITERAL"
610 
>ISOCHRONOUS</TT
611 
> or
612 
    <TT
613 
CLASS="LITERAL"
614 
>INTERRUPT</TT
615 
>.
616 
  </P
617 
></DD
618 
><DT
619 
><TT
620 
CLASS="STRUCTFIELD"
621 
><I
622 
>endpoint_number</I
623 
></TT
624 
></DT
625 
><DD
626 
><P
627 
>    This identifies the number that should be used by the host
628 
    to address this endpoint. For a control endpoint it should
629 
    be 0. For other types of endpoints it should be between
630 
    1 and 15.
631 
  </P
632 
></DD
633 
><DT
634 
><TT
635 
CLASS="STRUCTFIELD"
636 
><I
637 
>endpoint_direction</I
638 
></TT
639 
></DT
640 
><DD
641 
><P
642 
>    For control endpoints this field is irrelevant. For other
643 
    types of endpoint it should be either
644 
    <TT
645 
CLASS="LITERAL"
646 
>USB_ENDPOINT_DESCRIPTOR_ENDPOINT_IN</TT
647 
> or
648 
    <TT
649 
CLASS="LITERAL"
650 
>USB_ENDPOINT_DESCRIPTOR_ENDPOINT_OUT</TT
651 
>. If a given
652 
    endpoint number can be used for traffic in both directions then
653 
    there should be two entries in the array, one for each direction.
654 
  </P
655 
></DD
656 
><DT
657 
><TT
658 
CLASS="STRUCTFIELD"
659 
><I
660 
>endpoint</I
661 
></TT
662 
></DT
663 
><DD
664 
><P
665 
>    This should be a pointer to the appropriate
666 
    <SPAN
667 
CLASS="STRUCTNAME"
668 
>usbs_control_endpoint</SPAN
669 
>,
670 
    <SPAN
671 
CLASS="STRUCTNAME"
672 
>usbs_rx_endpoint</SPAN
673 
> or
674 
    <SPAN
675 
CLASS="STRUCTNAME"
676 
>usbs_tx_endpoint</SPAN
677 
> structure, allowing the
678 
    generic testing code to perform low-level I/O.
679 
  </P
680 
></DD
681 
><DT
682 
><TT
683 
CLASS="STRUCTFIELD"
684 
><I
685 
>devtab_entry</I
686 
></TT
687 
></DT
688 
><DD
689 
><P
690 
>    If the endpoint also has an entry in the system's device table then
691 
    this field should give the corresponding string, for example
692 
    <TT
693 
CLASS="LITERAL"
694 
>&quot;/dev/usbs1r&quot;</TT
695 
>. This allows the
696 
    generic testing code to access the device via higher-level
697 
    calls like <TT
698 
CLASS="FUNCTION"
699 
>open</TT
700 
> and <TT
701 
CLASS="FUNCTION"
702 
>read</TT
703 
>.
704 
  </P
705 
></DD
706 
><DT
707 
><TT
708 
CLASS="STRUCTFIELD"
709 
><I
710 
>min_size</I
711 
></TT
712 
></DT
713 
><DD
714 
><P
715 
>    This indicates the smallest transfer size that the hardware can
716 
    support on this endpoint. Typically this will be one.
717 
  </P
718 
><DIV
719 
CLASS="NOTE"
720 
><BLOCKQUOTE
721 
CLASS="NOTE"
722 
><P
723 
><B
724 
>Note: </B
725 
>    Strictly speaking a minimum size of one is not quite right since it
726 
    is valid for a USB transfer to involve zero bytes, in other words a
727 
    transfer that involves just headers and acknowledgements and an
728 
    empty data phase, and that should be tested as well. However current
729 
    device drivers interpret a transfer size of 0 as special, so that
730 
    would have to be resolved first.
731 
  </P
732 
></BLOCKQUOTE
733 
></DIV
734 
></DD
735 
><DT
736 
><TT
737 
CLASS="STRUCTFIELD"
738 
><I
739 
>max_size</I
740 
></TT
741 
></DT
742 
><DD
743 
><P
744 
>    Similarly, this specifies the largest transfer size. For control
745 
    endpoints the USB protocol uses only two bytes to hold the transfer
746 
    length, so there is an upper bound of 65535 bytes. In practice
747 
    it is very unlikely that any control transfers would ever need to
748 
    be this large, and in fact such transfers would take a long time
749 
    and probably violate timing constraints. For other types of endpoint
750 
    any of the protocol, the hardware, or the device driver may impose
751 
    size limits. For example a given device driver might be unable to
752 
    cope with transfers larger than 65535 bytes. If it should be
753 
    possible to transfer arbitrary amounts of data then a value of
754 
    <TT
755 
CLASS="LITERAL"
756 
>-1</TT
757 
> indicates no upper limit, and transfer
758 
    sizes will be limited by available memory and by the capabilities
759 
    of the host machine.
760 
  </P
761 
></DD
762 
><DT
763 
><TT
764 
CLASS="STRUCTFIELD"
765 
><I
766 
>max_in_padding</I
767 
></TT
768 
></DT
769 
><DD
770 
><P
771 
>    This field is needed on some hardware where it is impossible to
772 
    send packets of a certain size. For example the hardware may be
773 
    incapable of sending an empty bulk packet to terminate a transfer
774 
    that is an exact multiple of the 64-byte bulk packet size.
775 
    Instead the driver has to do some padding and send an extra byte,
776 
    and the host has to be prepared to receive this extra byte. Such a
777 
    driver should specify a value of <TT
778 
CLASS="LITERAL"
779 
>1</TT
780 
> for the
781 
    padding field. For most drivers this field should be set to
782 
  <TT
783 
CLASS="LITERAL"
784 
>0</TT
785 
>.
786 
  </P
787 
><P
788 
>    A better solution would be for the device driver to supply a
789 
    fragment of Tcl code that would adjust the receive buffer size
790 
    only when necessary, rather than for every transfer. Forcing
791 
    receive padding on all transfers when only certain transfers
792 
    will actually be padded reduces the accuracy of certain tests.
793 
  </P
794 
></DD
795 
><DT
796 
><TT
797 
CLASS="STRUCTFIELD"
798 
><I
799 
>alignment</I
800 
></TT
801 
></DT
802 
><DD
803 
><P
804 
>    On some hardware data transfers may need to be aligned to certain
805 
    boundaries, for example a word boundary or a cacheline boundary.
806 
    Although in theory device drivers could hide such alignment
807 
    restrictions from higher-level code by having their own buffers and
808 
    performing appropriate copying, that would be expensive in terms of
809 
    both memory and cpu cycles. Instead the generic testing code will
810 
    align any buffers passed to the device driver to the specified
811 
    boundary. For example, if the driver requires that buffers be
812 
    aligned to a word boundary then it should specify an alignment
813 
    value of 4.
814 
  </P
815 
></DD
816 
></DL
817 
></DIV
818 
><P
819 
>The device driver should provide an array of these structures
820 
<TT
821 
CLASS="VARNAME"
822 
>usbs_testing_endpoints[]</TT
823 
>. The USB testing code
824 
examines this array and uses the information to perform appropriate
825 
tests. Because different USB devices support different numbers of
826 
endpoints the number of entries in the array is not known in advance,
827 
so instead the testing code looks for a special terminator
828 
<TT
829 
CLASS="VARNAME"
830 
>USBS_TESTING_ENDPOINTS_TERMINATOR</TT
831 
>. An example
832 
array, showing just the control endpoint and the terminator, might
833 
look like this:</P
834 
><TABLE
835 
BORDER="0"
836 
BGCOLOR="#E0E0E0"
837 
WIDTH="100%"
838 
><TR
839 
><TD
840 
><PRE
841 
CLASS="PROGRAMLISTING"
842 
>usbs_testing_endpoint usbs_testing_endpoints[] = {
843 
    {
844 
        endpoint_type       : USB_ENDPOINT_DESCRIPTOR_ATTR_CONTROL,
845 
        endpoint_number     : 0,
846 
        endpoint_direction  : USB_ENDPOINT_DESCRIPTOR_ENDPOINT_IN,
847 
        endpoint            : (void*) &amp;ep0.common,
848 
        devtab_entry        : (const char*) 0,
849 
        min_size            : 1,
850 
        max_size            : 0x0FFFF,
851 
        max_in_padding      : 0,
852 
        alignment           : 0
853 
    },
854 
    &#8230;,
855 
    USBS_TESTING_ENDPOINTS_TERMINATOR
856 
};</PRE
857 
></TD
858 
></TR
859 
></TABLE
860 
><DIV
861 
CLASS="NOTE"
862 
><BLOCKQUOTE
863 
CLASS="NOTE"
864 
><P
865 
><B
866 
>Note: </B
867 
>The use of a single array <TT
868 
CLASS="VARNAME"
869 
>usbs_testing_endpoints</TT
870 
>
871 
limits USB testing to platforms with a single USB device: if there
872 
were multiple devices, each defining their own instance of this array,
873 
then there would a collision at link time. In practice this should not
874 
be a major problem since typical USB peripherals only interact with a
875 
single host machine via a single slave port. In addition, even if a
876 
peripheral did have multiple slave ports the current USB testing code
877 
would not support this since it would not know which port to use.</P
878 
></BLOCKQUOTE
879 
></DIV
880 
></DIV
881 
><DIV
882 
CLASS="NAVFOOTER"
883 
><HR
884 
ALIGN="LEFT"
885 
WIDTH="100%"><TABLE
886 
WIDTH="100%"
887 
BORDER="0"
888 
CELLPADDING="0"
889 
CELLSPACING="0"
890 
><TR
891 
><TD
892 
WIDTH="33%"
893 
ALIGN="left"
894 
VALIGN="top"
895 
><A
896 
HREF="usbs-data.html"
897 
>Prev</A
898 
></TD
899 
><TD
900 
WIDTH="34%"
901 
ALIGN="center"
902 
VALIGN="top"
903 
><A
904 
HREF="io-usb-slave.html"
905 
>Home</A
906 
></TD
907 
><TD
908 
WIDTH="33%"
909 
ALIGN="right"
910 
VALIGN="top"
911 
><A
912 
HREF="usbs-testing.html"
913 
>Next</A
914 
></TD
915 
></TR
916 
><TR
917 
><TD
918 
WIDTH="33%"
919 
ALIGN="left"
920 
VALIGN="top"
921 
>Data Endpoints</TD
922 
><TD
923 
WIDTH="34%"
924 
ALIGN="center"
925 
VALIGN="top"
926 
>&nbsp;</TD
927 
><TD
928 
WIDTH="33%"
929 
ALIGN="right"
930 
VALIGN="top"
931 
>Testing</TD
932 
></TR
933 
></TABLE
934 
></DIV
935 
></BODY
936 
></HTML
937 
>

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.