release/src-rt/cfe/cfe/usb/README

   1
   2 ------------------------------------------------------------------------
   3 This directory contains a basic description of the CFE USB stack,
   4 its current status and features, and what might be done in the
   5 future to improve it.
   6 ------------------------------------------------------------------------
   7
   8 Question: A USB stack in CFE?  But why?
   9
  10 Answer: 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
  18 Source Files
  19 ------------
  20
  21 ohci.c          OHCI USB Host Controller Driver, tested on a BCM1250
  22                 with an Opti FireLink PCI USB controller
  23
  24 ohci.h          Register definitions for ohci.c
  25
  26 usbchap9.h      USB "Chapter 9" definitions (Descriptors, etc.)
  27
  28 usbd.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
  32 usbd.h          Prototypes and data structures for usbd.c
  33
  34 usbdevs.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
  39 usbdebug.c      Some descriptor dump routines live here.
  40
  41 usbhub.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
  45 usbhid.c        Class driver for keyboards and mice.  Right now
  46                 not much is done with them except echo characters.
  47
  48 usbmass.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
  53 usbmain.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
  57 usbhack.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
  62 usbhack.h       A dumping ground for CFE definitions not otherwise
  63                 provided by the standard include files.
  64
  65 usbhack.mk      GNU makefile for the test harness
  66
  67 ------------------------------------------------------------------------
  68
  69 Overview
  70 --------
  71
  72 The host controller driver is abstracted through a small set of
  73 primitives defined in usbd.h - at present only the OHCI driver
  74 is implemented, but there will eventually be support for the
  75 ScanLogic SL11H part on the BCM1250CPCI board - this is a simple
  76 "generic-bus" (non-pci) host controller.   I doubt we'll ever
  77 need EHCI/UHCI, since they are present mostly in Intel chipsets.
  78
  79 All events are polled by this driver.  There are two polling functions
  80 that should be called periodically:
  81
  82      usb_poll(usbbus_t *bus);
  83      usb_daemon(usbbus_t *bus);
  84
  85 The "poll" routine handles interrupts from the devices themselves.
  86 The "daemon" routine monitors the bus for topology changes and
  87 instantiates an exploration if something changes.  Sometimes "daemon"
  88 needs to do USB I/O, requiring calls to usb_poll() to get the data
  89 to go in/out via the controller, hence the two routines.  You should
  90 be careful not to all usb_poll() during polling.
  91
  92
  93 Device Drivers
  94 --------------
  95
  96 USB Device drivers are currently extremely simple:  There are
  97 only two methods that need be exported to the device driver table:
  98
  99 attach()         Called when the device is "discovered"
 100 detach()         Called when the device is "removed"
 101
 102 When a device is removed, pending transfer requests will be
 103 canceled with a "canceled" status.
 104
 105 There is no standard for the top side (user API side) of the
 106 device driver, that is up to the device class.  The bottom half
 107 should make use of the calls in usbd.c
 108
 109 When a device driver is attached via its attach() method,
 110 it will be in the "addressed" state according to the USB spec.
 111 The exploration code takes care of assigning the USB address
 112 to the device.  Devices not otherwise recognized by this code will
 113 be left in the addressed state without any active configurations.
 114
 115 The descriptors are read by the exploration code and are made
 116 available to the usb_find_cfg_descr() call - you can use this
 117 function to obtain the endpoint and interface descriptors for
 118 your device and then call usb_set_configuration() to activate
 119 the configuration.
 120
 121 When your detach() method is called, the device should be considered
 122 already gone, so do not attempt to do any I/O to it.  Just clean
 123 up the mess and return.
 124
 125
 126 ------------------------------------------------------------------------
 127
 128 What 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
 151 What 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