
------------------------------------------------------------------------
This directory contains a basic description of the CFE USB stack,
its current status and features, and what might be done in the 
future to improve it.
------------------------------------------------------------------------

Question: A USB stack in CFE?  But why?

Answer: Why not?  It's not terribly useful on the BCM1250, since we 
        don't expect many of you to use USB in your boards, but there IS
        a USB host controller on the SWARM (BCM1250 reference design).
	Besides, CFE is actually being used for other non-SiByte 
 	Broadcom chips, and some of those _do_ have USB on them.

------------------------------------------------------------------------

Source Files
------------

ohci.c		OHCI USB Host Controller Driver, tested on a BCM1250
		with an Opti FireLink PCI USB controller and on a
		BCM5836 with integrated USB controller.

ohci.h		Register definitions for ohci.c

usbchap9.h	USB "Chapter 9" definitions (Descriptors, etc.)

usbd.c		USB Basic Request and pipe management routines, to
		manage usb devices, do simple requests on the
		control pipe, open and manage pipes, etc.

usbd.h		Prototypes and data structures for usbd.c

usbdebug.c	Some descriptor dump routines live here.

usbdevs.c	USB Device Driver list - devices we recognize
		are listed here - if you add a new USB device,
		you can add its class or vendor ID entries
		into the table here.

usbeth.{h,c}	Driver for USB Ethernet devices based on the 
		ADMtek Pegasus, CATC and Realtek chips.

usbhid.c	Class driver for keyboards and mice.  Right now
		not much is done with them except echo characters.

usbhub.c	Class driver for USB hubs.  Because hubs are also
		a major player in device discovery, much of the
		USB device tree management also lives here.

usbmass.c       Class driver for USB mass-storage devices.  We only
		support the "bulk-only-no-interrupt" protocol.
		This driver also includes a top half so that
		it can be accessed as a CFE mass-storage device.

usbmain.c	Top-level interface into CFE.  The "usb start"
		command is instantiated here, as well as a 
		"usb show" command to display attached USB devices.

usbserial.c	Simple driver for USB serial devices based on the 
	        Prolific PL-2303 and MCT USB-232 chips, including
		CFE UART support.

usbhack.c	Main program for the test harness, which lets you
		develop OHCI code under Linux without hacking on
		either CFE or the kernel.  See the comments in this
		file for more information.

usbhack.h	A dumping ground for CFE definitions not otherwise
		provided by the standard include files.

usbhack.mk	GNU makefile for the test harness

------------------------------------------------------------------------

Overview
--------

The host controller driver is abstracted through a small set of
primitives defined in usbd.h - at present only the OHCI driver
is implemented, but there will eventually be support for the
ScanLogic SL11H part on the BCM1250CPCI board - this is a simple
"generic-bus" (non-pci) host controller.   I doubt we'll ever 
need EHCI/UHCI, since they are present mostly in Intel chipsets.

All events are polled by this driver.  There are two polling functions
that should be called periodically:

     usb_poll(usbbus_t *bus);
     usb_daemon(usbbus_t *bus);

The "poll" routine handles interrupts from the devices themselves.
The "daemon" routine monitors the bus for topology changes and
instantiates an exploration if something changes.  Sometimes "daemon"
needs to do USB I/O, requiring calls to usb_poll() to get the data
to go in/out via the controller, hence the two routines.  You should
be careful not to call usb_poll() during polling.


Device Drivers
--------------

USB Device drivers are currently extremely simple:  There are 
only two methods that need be exported to the device driver table:

attach()	 Called when the device is "discovered"
detach()	 Called when the device is "removed"

When a device is removed, pending transfer requests will be 
canceled with a "canceled" status.

There is no standard for the top side (user API side) of the
device driver, that is up to the device class.  The bottom half
should make use of the calls in usbd.c

When a device driver is attached via its attach() method,
it will be in the "addressed" state according to the USB spec.
The exploration code takes care of assigning the USB address
to the device.  Devices not otherwise recognized by this code will
be left in the addressed state without any active configurations.

The descriptors are read by the exploration code and are made
available to the usb_find_cfg_descr() call - you can use this
function to obtain the endpoint and interface descriptors for
your device and then call usb_set_configuration() to activate
the configuration.

When your detach() method is called, the device should be considered 
already gone, so do not attempt to do any I/O to it.  Just clean
up the mess and return.


------------------------------------------------------------------------

What works?
-----------

* OHCI on a BCM1250 via the Opti Firelink USB controller

* OHCI on a BCM5836 with integrated USB controller core.

* The OHCI root hub emulation

* External hubs, and hubs integrated into other devices like
  keyboards.

* Interrupt transfers

* Transfers (basic requests) on endpoint 0

* Basic device discovery and removal

* Bulk endpoints and transfers

* Some endpoint stalls are handled.


------------------------------------------------------------------------

What doesn't work?  What is not implemented?
--------------------------------------------

* The root hub implementation is really shaky, especially in 
  matters of plug-and-play (device insertion/removal events,
  etc.)  Don't be surprised if removing a device from the 
  root hub causes CFE to freeze.

* There is no error recovery code whatsoever.  This kind of goes
  with the above root hub issue.

* Noncoherent DMA is relatively untested.

* Isochronous endpoints are completely unimplemented (and will probably
  remain that way)

* Power management (for example, power budget in hubs) is unimplemented.
  (this should be easy)

* Interrupt endpoints are all on the 10ms endpoint in the interrupt
  tree (endpoints should be placed at the location to guarantee 
  bandwidth at 'bInterval' ms)  - no bandwidth management is being
  done at the moment, but this is pretty simple.

* The OHCI driver cannot be stopped/unloaded.








