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. -->
12 >Writing a USB Device Driver</TITLE
13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
19 TITLE="eCos Reference Manual"
20 HREF="ecos-ref.html"><LINK
22 TITLE="eCos USB Slave Support"
23 HREF="io-usb-slave.html"><LINK
25 TITLE="Data Endpoints"
26 HREF="usbs-data.html"><LINK
29 HREF="usbs-testing.html"></HEAD
40 SUMMARY="Header navigation table"
49 >eCos Reference Manual</TH
71 HREF="usbs-testing.html"
82 NAME="USBS-WRITING">Writing a USB Device Driver</H1
90 >Writing a USB Device Driver -- USB Device Driver Porting Guide</DIV
99 >Often the best way to write a USB device driver will be to start with
100 an existing one and modify it as necessary. The information given here
101 is intended primarily as an outline rather than as a complete guide.</P
109 >At the time of writing only one USB device driver has been
110 implemented. Hence it is possible, perhaps probable, that some
111 portability issues have not yet been addressed. One issue
112 involves the different types of transfer, for example the initial
113 target hardware had no support for isochronous or interrupt transfers,
114 so additional functionality may be needed to switch between transfer
115 types. Another issue would be hardware where a given endpoint number,
116 say endpoint 1, could be used for either receiving or transmitting
117 data, but not both because a single fifo is used. Issues like these
118 will have to be resolved as and when additional USB device drivers are
129 >The Control Endpoint</H2
131 >A USB device driver should provide a single <A
132 HREF="usbs-control.html"
135 >usbs_control_endpoint</SPAN
138 data structure for every USB device. Typical peripherals will have
139 only one USB port so there will be just one such data structure in the
140 entire system, but theoretically it is possible to have multiple USB
141 devices. These may all involve the same chip, in which case a single
142 device driver should support multiple device instances, or they may
143 involve different chips. The name or names of these data structures
144 are determined by the device driver, but appropriate care should be
145 taken to avoid name clashes. </P
147 >A USB device cannot be used unless the control endpoint data structure
148 exists. However, the presence of USB hardware in the target processor
149 or board does not guarantee that the application will necessarily want
150 to use that hardware. To avoid unwanted code or data overheads, the
151 device driver can provide a configuration option to determine whether
152 or not the endpoint 0 data structure is actually provided. A default
155 >CYGINT_IO_USB_SLAVE_CLIENTS</TT
157 the USB driver will be enabled automatically if higher-level code does
158 require USB support, while leaving ultimate control to the user.</P
160 >The USB device driver is responsible for filling in the
178 > fields. Usually this can
179 be achieved by static initialization. The driver is also largely
180 responsible for maintaining the <TT
192 used to hold the first packet of a control message. The
198 > and other fields related to data
199 transfers will be managed <A
200 HREF="usbs-control.html#AEN16615"
202 > by higher-level code and
203 the device driver. The remaining fields are generally filled in by
204 higher-level code, although the driver should initialize them to NULL
207 >Hardware permitting, the USB device should be inactive until the
213 > is invoked, for example by
214 tristating the appropriate pins. This prevents the host from
215 interacting with the peripheral before all other parts of the system
216 have initialized. It is expected that the
222 > will only be invoked once, shortly
225 >Where possible the device driver should detect state changes, such as
226 when the connection between host and peripheral is established, and
228 HREF="usbs-control.html#AEN16552"
230 > these to higher-level
237 any. The state change to and from configured state cannot easily be
238 handled by the device driver itself, instead higher-level code such as
239 the common USB slave package will take care of this.</P
241 >Once the connection between host and peripheral has been established,
242 the peripheral must be ready to accept control messages at all times,
243 and must respond to these within certain time constraints. For
244 example, the standard set-address control message must be handled
245 within 50ms. The USB specification provides more information on these
246 constraints. The device driver is responsible for receiving the
247 initial packet of a control message. This packet will always be eight
248 bytes and should be stored in the
254 > field. Certain standard
255 control messages should be detected and handled by the device driver
256 itself. The most important is set-address, but usually the get-status,
257 set-feature and clear-feature requests when applied to halted
258 endpoints should also be handled by the driver. Other standard control
259 messages should first be passed on to the
263 >standard_control_fn</I
265 > callback (if any), and
266 finally to the default handler
269 >usbs_handle_standard_control</TT
271 common USB slave package. Class, vendor and reserved control messages
272 should always be dispatched to the appropriate callback and there is
273 no default handler for these.</P
275 >Some control messages will involve further data transfer, not just the
276 initial packet. The device driver must handle this in accordance with
277 the USB specification and the <A
278 HREF="usbs-control.html#AEN16615"
279 >buffer management strategy</A
281 driver is also responsible for keeping track of whether or not the
282 control operation has succeeded and generating an ACK or STALL
285 >The polling support is optional and may not be feasible on all
286 hardware. It is only used in certain specialised environments such as
287 RedBoot. A typical implementation of the polling function would just
288 check whether or not an interrupt would have occurred and, if so, call
289 the same code that the interrupt handler would.</P
299 >In addition to the control endpoint data structure, a USB device
300 driver should also provide appropriate <A
301 HREF="usbs-data.html"
304 > data structures. Obviously this is only relevant if
305 the USB support generally is desired, that is if the control endpoint is
306 provided. In addition, higher-level code may not require all the
307 endpoints, so it may be useful to provide configuration options that
308 control the presence of each endpoint. For example, the intended
309 application might only involve a single transmit endpoint and of
310 course control messages, so supporting receive endpoints might waste
313 >Conceptually, data endpoints are much simpler than the control
314 endpoint. The device driver has to supply two functions, one for
315 data transfers and another to control the halted condition. These
316 implement the functionality for
318 HREF="usbs-start-rx.html"
321 >usbs_start_rx_buffer</TT
325 HREF="usbs-start-tx.html"
328 >usbs_start_tx_buffer</TT
332 HREF="usbs-halt.html"
335 >usbs_set_rx_endpoint_halted</TT
339 HREF="usbs-halt.html"
342 >usbs_set_tx_endpoint_halted</TT
345 The device driver is also responsible for maintaining the
353 >For data transfers, higher-level code will have filled in the
377 > fields. The transfer function
378 should arrange for the transfer to start, allowing the host to send or
379 receive packets. Typically this will result in an interrupt at the end
380 of the transfer or after each packet. Once the entire transfer has
381 been completed, the driver's interrupt handling code should invoke the
382 completion function. This can happen either in DSR context or thread
383 context, depending on the driver's implementation. There are a number
384 of special cases to consider. If the endpoint is halted when the
385 transfer is started then the completion function can be invoked
389 >. If the transfer cannot be
390 completed because the connection is broken then the completion
391 function should be invoked with <TT
395 endpoint is stalled during the transfer, either because of a standard
396 control message or because higher-level code calls the appropriate
402 >, then again the completion
403 function should be invoked with <TT
409 >usbs_start_rx_endpoint_wait</TT
413 >usbs_start_tx_endpoint_wait</TT
415 calling the device driver's data transfer function with a buffer size
424 >Giving a buffer size of 0 bytes a special meaning is problematical
425 because it prevents transfers of that size. Such transfers are allowed
426 by the USB protocol, consisting of just headers and acknowledgements
427 and an empty data phase, although rarely useful. A future modification
428 of the device driver specification will address this issue, although
429 care has to be taken that the functionality remains accessible through
430 devtab entries as well as via low-level accesses.</P
442 >For some applications or higher-level packages it may be more
443 convenient to use traditional open/read/write I/O calls rather than
444 the non-blocking USB I/O calls. To support this the device driver can
445 provide a devtab entry for each endpoint, for example:</P
453 CLASS="PROGRAMLISTING"
454 >#ifdef CYGVAR_DEVS_USB_SA11X0_EP1_DEVTAB_ENTRY
456 static CHAR_DEVIO_TABLE(usbs_sa11x0_ep1_devtab_functions,
457 &cyg_devio_cwrite,
458 &usbs_devtab_cread,
459 &cyg_devio_bwrite,
460 &cyg_devio_bread,
461 &cyg_devio_select,
462 &cyg_devio_get_config,
463 &cyg_devio_set_config);
465 static CHAR_DEVTAB_ENTRY(usbs_sa11x0_ep1_devtab_entry,
466 CYGDAT_DEVS_USB_SA11X0_DEVTAB_BASENAME "1r",
468 &usbs_sa11x0_ep1_devtab_functions,
469 &usbs_sa11x0_devtab_dummy_init,
471 (void*) &usbs_sa11x0_ep1);
477 >Again care must be taken to avoid name clashes. This can be achieved
478 by having a configuration option to control the base name, with a
479 default value of e.g. <TT
483 endpoint-specific string. This gives the application developer
484 sufficient control to eliminate any name clashes. The common USB slave
485 package provides functions <TT
487 >usbs_devtab_cwrite</TT
491 >usbs_devtab_cread</TT
492 >, which can be used in the
493 function tables for transmit and receive endpoints respectively. The
499 > of the devtab entry
500 should be a pointer to the underlying endpoint data structure.</P
502 >Because devtab entries are never accessed directly, only indirectly,
503 they would usually be eliminated by the linker. To avoid this the
504 devtab entries should normally be defined in a separate source file
505 which ends up the special library <TT
509 rather than in the default library <TT
514 >Not all applications or higher-level packages will want to use the
515 devtab entries and the blocking I/O facilities. It may be appropriate
516 for the device driver to provide additional configuration options that
517 control whether or not any or all of the devtab entries should be
518 provided, to avoid unnecessary memory overheads.</P
526 >Interrupt Handling</H2
528 >A typical USB device driver will need to service interrupts for all of
529 the endpoints and possibly for additional USB events such as entering
530 or leaving suspended mode. Usually these interrupts need not be
531 serviced directly by the ISR. Instead, they can be left to a DSR. If
532 the peripheral is not able to accept or send another packet just yet,
533 the hardware will generate a NAK and the host will just retry a little
534 bit later. If high throughput is required then it may be desirable to
535 handle the bulk transfer protocol largely at ISR level, that is take
536 care of each packet in the ISR and only activate the DSR once the
537 whole transfer has completed.</P
539 >Control messages may involve invoking arbitrary callback functions in
540 higher-level code. This should normally happen at DSR level. Doing it
541 at ISR level could seriously affect the system's interrupt latency and
542 impose unacceptable constraints on what operations can be performed by
543 those callbacks. If the device driver requires a thread anyway then it
544 may be appropriate to use this thread for invoking the callbacks, but
545 usually it is not worthwhile to add a new thread to the system just
546 for this; higher-level code is expected to write callbacks that
547 function sensibly at DSR level. Much the same applies to the
548 completion functions associated with data transfers. These should also
549 be invoked at DSR or thread level.</P
557 >Support for USB Testing</H2
559 >Optionally a USB device driver can provide support for the
561 HREF="usbs-testing.html"
562 >USB test software</A
564 defining a number of additional data structures, allowing the
565 generic test code to work out just what the hardware is capable of and
566 hence what testing can be performed.</P
568 >The key data structure is
571 >usbs_testing_endpoint</SPAN
574 >cyg/io/usb/usbs.h</TT
576 commonly required constants are provided by the common USB package in
579 >cyg/io/usb/usb.h</TT
583 >usbs_testing_endpoint</SPAN
584 > structure should be
585 defined for each supported endpoint. The following fields need to be
601 > This specifies the type of endpoint and should be one of
604 >USB_ENDPOINT_DESCRIPTOR_ATTR_CONTROL</TT
628 > This identifies the number that should be used by the host
629 to address this endpoint. For a control endpoint it should
630 be 0. For other types of endpoints it should be between
638 >endpoint_direction</I
643 > For control endpoints this field is irrelevant. For other
644 types of endpoint it should be either
647 >USB_ENDPOINT_DESCRIPTOR_ENDPOINT_IN</TT
651 >USB_ENDPOINT_DESCRIPTOR_ENDPOINT_OUT</TT
653 endpoint number can be used for traffic in both directions then
654 there should be two entries in the array, one for each direction.
666 > This should be a pointer to the appropriate
669 >usbs_control_endpoint</SPAN
673 >usbs_rx_endpoint</SPAN
677 >usbs_tx_endpoint</SPAN
678 > structure, allowing the
679 generic testing code to perform low-level I/O.
691 > If the endpoint also has an entry in the system's device table then
692 this field should give the corresponding string, for example
695 >"/dev/usbs1r"</TT
697 generic testing code to access the device via higher-level
716 > This indicates the smallest transfer size that the hardware can
717 support on this endpoint. Typically this will be one.
726 > Strictly speaking a minimum size of one is not quite right since it
727 is valid for a USB transfer to involve zero bytes, in other words a
728 transfer that involves just headers and acknowledgements and an
729 empty data phase, and that should be tested as well. However current
730 device drivers interpret a transfer size of 0 as special, so that
731 would have to be resolved first.
745 > Similarly, this specifies the largest transfer size. For control
746 endpoints the USB protocol uses only two bytes to hold the transfer
747 length, so there is an upper bound of 65535 bytes. In practice
748 it is very unlikely that any control transfers would ever need to
749 be this large, and in fact such transfers would take a long time
750 and probably violate timing constraints. For other types of endpoint
751 any of the protocol, the hardware, or the device driver may impose
752 size limits. For example a given device driver might be unable to
753 cope with transfers larger than 65535 bytes. If it should be
754 possible to transfer arbitrary amounts of data then a value of
758 > indicates no upper limit, and transfer
759 sizes will be limited by available memory and by the capabilities
772 > This field is needed on some hardware where it is impossible to
773 send packets of a certain size. For example the hardware may be
774 incapable of sending an empty bulk packet to terminate a transfer
775 that is an exact multiple of the 64-byte bulk packet size.
776 Instead the driver has to do some padding and send an extra byte,
777 and the host has to be prepared to receive this extra byte. Such a
778 driver should specify a value of <TT
782 padding field. For most drivers this field should be set to
789 > A better solution would be for the device driver to supply a
790 fragment of Tcl code that would adjust the receive buffer size
791 only when necessary, rather than for every transfer. Forcing
792 receive padding on all transfers when only certain transfers
793 will actually be padded reduces the accuracy of certain tests.
805 > On some hardware data transfers may need to be aligned to certain
806 boundaries, for example a word boundary or a cacheline boundary.
807 Although in theory device drivers could hide such alignment
808 restrictions from higher-level code by having their own buffers and
809 performing appropriate copying, that would be expensive in terms of
810 both memory and cpu cycles. Instead the generic testing code will
811 align any buffers passed to the device driver to the specified
812 boundary. For example, if the driver requires that buffers be
813 aligned to a word boundary then it should specify an alignment
820 >The device driver should provide an array of these structures
823 >usbs_testing_endpoints[]</TT
824 >. The USB testing code
825 examines this array and uses the information to perform appropriate
826 tests. Because different USB devices support different numbers of
827 endpoints the number of entries in the array is not known in advance,
828 so instead the testing code looks for a special terminator
831 >USBS_TESTING_ENDPOINTS_TERMINATOR</TT
833 array, showing just the control endpoint and the terminator, might
842 CLASS="PROGRAMLISTING"
843 >usbs_testing_endpoint usbs_testing_endpoints[] = {
845 endpoint_type : USB_ENDPOINT_DESCRIPTOR_ATTR_CONTROL,
847 endpoint_direction : USB_ENDPOINT_DESCRIPTOR_ENDPOINT_IN,
848 endpoint : (void*) &ep0.common,
849 devtab_entry : (const char*) 0,
856 USBS_TESTING_ENDPOINTS_TERMINATOR
868 >The use of a single array <TT
870 >usbs_testing_endpoints</TT
872 limits USB testing to platforms with a single USB device: if there
873 were multiple devices, each defining their own instance of this array,
874 then there would a collision at link time. In practice this should not
875 be a major problem since typical USB peripherals only interact with a
876 single host machine via a single slave port. In addition, even if a
877 peripheral did have multiple slave ports the current USB testing code
878 would not support this since it would not know which port to use.</P
887 SUMMARY="Footer navigation table"
898 HREF="usbs-data.html"
916 HREF="usbs-testing.html"
932 HREF="io-usb-slave.html"