README
1
2------------------------------------------------------------------------
3This directory contains a basic description of the CFE USB stack,
4its current status and features, and what might be done in the
5future to improve it.
6------------------------------------------------------------------------
7
8Question: A USB stack in CFE? But why?
9
10Answer: Why not? It's not terribly useful on the BCM1250, since we
11 don't expect many of you to use USB in your boards, but there IS
12 a USB host controller on the SWARM (BCM1250 reference design).
13 Besides, CFE is actually being used for other non-SiByte
14 Broadcom chips, and some of those _do_ have USB on them.
15
16------------------------------------------------------------------------
17
18Source Files
19------------
20
21ohci.c OHCI USB Host Controller Driver, tested on a BCM1250
22 with an Opti FireLink PCI USB controller
23
24ohci.h Register definitions for ohci.c
25
26usbchap9.h USB "Chapter 9" definitions (Descriptors, etc.)
27
28usbd.c USB Basic Request and pipe management routines, to
29 manage usb devices, do simple requests on the
30 control pipe, open and manage pipes, etc.
31
32usbd.h Prototypes and data structures for usbd.c
33
34usbdevs.c USB Device Driver list - devices we recognize
35 are listed here - if you add a new USB device,
36 you can add its class or vendor ID entries
37 into the table here.
38
39usbdebug.c Some descriptor dump routines live here.
40
41usbhub.c Class driver for USB hubs. Because hubs are also
42 a major player in device discovery, much of the
43 USB device tree management also lives here.
44
45usbhid.c Class driver for keyboards and mice. Right now
46 not much is done with them except echo characters.
47
48usbmass.c Class driver for USB mass-storage devices. We only
49 support the "bulk-only-no-interrupt" protocol.
50 This driver also includes a top half so that
51 it can be accessed as a CFE mass-storage device.
52
53usbmain.c Top-level interface into CFE. The "usb start"
54 command is instantiated here, as well as a
55 "usb show" command to display attached USB devices.
56
57usbhack.c Main program for the test harness, which lets you
58 develop OHCI code under Linux without hacking on
59 either CFE or the kernel. See the comments in this
60 file for more information.
61
62usbhack.h A dumping ground for CFE definitions not otherwise
63 provided by the standard include files.
64
65usbhack.mk GNU makefile for the test harness
66
67------------------------------------------------------------------------
68
69Overview
70--------
71
72The host controller driver is abstracted through a small set of
73primitives defined in usbd.h - at present only the OHCI driver
74is implemented, but there will eventually be support for the
75ScanLogic SL11H part on the BCM1250CPCI board - this is a simple
76"generic-bus" (non-pci) host controller. I doubt we'll ever
77need EHCI/UHCI, since they are present mostly in Intel chipsets.
78
79All events are polled by this driver. There are two polling functions
80that should be called periodically:
81
82 usb_poll(usbbus_t *bus);
83 usb_daemon(usbbus_t *bus);
84
85The "poll" routine handles interrupts from the devices themselves.
86The "daemon" routine monitors the bus for topology changes and
87instantiates an exploration if something changes. Sometimes "daemon"
88needs to do USB I/O, requiring calls to usb_poll() to get the data
89to go in/out via the controller, hence the two routines. You should
90be careful not to all usb_poll() during polling.
91
92
93Device Drivers
94--------------
95
96USB Device drivers are currently extremely simple: There are
97only two methods that need be exported to the device driver table:
98
99attach() Called when the device is "discovered"
100detach() Called when the device is "removed"
101
102When a device is removed, pending transfer requests will be
103canceled with a "canceled" status.
104
105There is no standard for the top side (user API side) of the
106device driver, that is up to the device class. The bottom half
107should make use of the calls in usbd.c
108
109When a device driver is attached via its attach() method,
110it will be in the "addressed" state according to the USB spec.
111The exploration code takes care of assigning the USB address
112to the device. Devices not otherwise recognized by this code will
113be left in the addressed state without any active configurations.
114
115The descriptors are read by the exploration code and are made
116available to the usb_find_cfg_descr() call - you can use this
117function to obtain the endpoint and interface descriptors for
118your device and then call usb_set_configuration() to activate
119the configuration.
120
121When your detach() method is called, the device should be considered
122already gone, so do not attempt to do any I/O to it. Just clean
123up the mess and return.
124
125
126------------------------------------------------------------------------
127
128What works?
129-----------
130
131* OHCI on a BCM1250 via the Opti Firelink USB controller
132
133* The OHCI root hub emulation
134
135* External hubs, and hubs integrated into other devices like
136 keyboards.
137
138* Interrupt transfers
139
140* Transfers (basic requests) on endpoint 0
141
142* Basic device discovery and removal
143
144* Bulk endpoints and transfers
145
146* Some endpoint stalls are handled.
147
148
149------------------------------------------------------------------------
150
151What doesn't work? What is not implemented?
152--------------------------------------------
153
154* The root hub implementation is really shaky, especially in
155 matters of plug-and-play (device insertion/removal events,
156 etc.) Don't be surprised if removing a device from the
157 root hub causes CFE to freeze.
158
159* There is no error recovery code whatsoever. This kind of goes
160 with the above root hub issue.
161
162* Noncoherent DMA is relatively untested.
163
164* Isochronous endpoints are completely unimplemented (and will probably
165 remain that way)
166
167* Power management (for example, power budget in hubs) is unimplemented.
168 (this should be easy)
169
170* Interrupt endpoints are all on the 10ms endpoint in the interrupt
171 tree (endpoints should be placed at the location to guarantee
172 bandwidth at 'bInterval' ms) - no bandwidth management is being
173 done at the moment, but this is pretty simple.
174
175* The OHCI driver cannot be stopped/unloaded.
176
177
178
179
180
181
182
183
184