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