Documentation/usb/ohci.txt

   1
   2 The OHCI HCD layer is a simple but nearly complete implementation of what the
   3 USB people would call a HCD  for the OHCI.
   4  (ISO coming soon, Bulk, INT u. CTRL transfers enabled)
   5 It is based on Linus Torvalds UHCI code and Gregory Smith OHCI fragments (0.03 source tree).
   6 The layer (functions) on top of it, is for interfacing to the alternate-usb device-drivers.
   7
   8 - Roman Weissgaerber <weissg@vienna.at>
   9
  10  * v4.0 1999/08/18 removed all dummy eds, unlink unused eds, code cleanup, bulk transfers
  11  * v2.1 1999/05/09 ep_addr correction, code cleanup
  12  * v0.2.0 1999/05/04
  13  * everything has been moved into 2 files (ohci-hcd.c, ohci-hub-root.c and headers)
  14  * virtual root hub is now an option,
  15  * memory allocation based on kmalloc and kfree now, simple Bus error handling,
  16  * INT and CTRL transfers enabled, Bulk included but disabled, ISO needs completion
  17  *
  18  * from Linus Torvalds (uhci.c): APM (not tested); hub, usb_device, bus and related stuff
  19  * from Greg Smith (ohci.c): better reset ohci-controller handling, hub
  20  *
  21  * v0.1.0 1999/04/27 initial release
  22
  23 to remove the module try:
  24 rmmod usb-ohci
  25
  26 Features:
  27 - virtual root hub, all basic hub descriptors and commands (state: complete)
  28   this is an option now (v0.2.0)
  29   #define  CONFIG_USB_OHCI_VROOTHUB includes the virtual hub code, (VROOTHUB)
  30   default is with.
  31   (at the moment: the Virtual Root Hub is included automatically)
  32
  33   files: ohci-root-hub.c, ohci-root-hub.h
  34
  35
  36 - Endpoint Descriptor (ED) handling more static approach
  37  (EDs should be allocated in parallel to the SET CONFIGURATION command and they live
  38  as long as the function (device) is alive or another configuration is chosen.
  39  In the HCD layer the EDs has to be allocated manually either by calling a subroutine
  40  or by sending a USB root hub vendor specific command to the virtual root hub.
  41  At the alternate linux usb stack EDs will be added (allocated) at their first use.
  42  ED will be unlinked from the HC chains if they are not busy.
  43
  44  files: ohci-hcd.c ohci-hcd.h
  45  routines:   (do not use for drivers, use the top layer alternate usb commands instead)
  46
  47  int usb_ohci_add_ep(struct ohci * ohci, unsigned int ep_addr1,
  48             int interval, int load, f_handler handler, int ep_size, int speed)
  49        adds an endpoint, (if the endpoint already exists some parameters will be updated)
  50
  51  int usb_ohci_rm_ep( )
  52        removes an endpoint and all pending TDs of that EP
  53
  54   usb_ohci_rm_function( )
  55        removes all Endpoints of a function (device)
  56
  57 - Transfer Descriptors (TD): handling and allocation of TDs is transparent to the upper layers
  58   The HCD takes care of TDs and EDs memory allocation whereas the upper layers (UBSD ...) has
  59   to take care of buffer allocation.
  60   files: ohci-hcd.c ohci-hcd.h
  61
  62   There is one basic command for all types of bus transfers (INT, BULK, ISO, CTRL):
  63
  64   int ohci_trans_req(struct ohci * ohci, hcd_ed, int ctrl_len, void  *ctrl, void * data, int data_len, __OHCI_BAG lw0, __OHCI_BAG lw1)
  65
  66   CTRL: ctrl, ctrl_len ... cmd buffer
  67         data, data_len ... data buffer (in or out)
  68   INT, BULK:  ctrl = NULL, ctrl_len=0,
  69                 data, data_len ... data buffer (in or out)
  70   ISO: tbd
  71
  72   There is no buffer reinsertion done by the internal HCD function.
  73   (The interface layer does this for a INT-pipe on request.)
  74   If you want a transfer then you have to
  75   provide buffers by sending ohci_trans_req requests. As they are queued as TDs on an ED
  76   you can send as many as you like. They should come back by the callback f_handler in
  77   the same order (for each endpoint, not globally) If an error occurs all
  78   queued transfers of an endpoint will return unsent. They will be marked with an error status.
  79
  80   e.g double-buffering for int transfers:
  81
  82         ohci_trans_req(ohci, ep_addr, 0, NULL, data0, data0_len, 0,0)
  83         ohci_trans_req(ohci, ep_addr, 0, NULL, data1, data1_len, 0,0)
  84
  85   and when a data0 packet returns by the callback f_handler requeue it:
  86         ohci_trans_req(ohci, ep_addr, 0, NULL, data0, data0_len, 0,0)
  87   and when a data1 packet returns by the callback f_handler requeue it:
  88         ohci_trans_req(ohci, ep_addr, 0, NULL, data1, data1_len, 0,0)
  89
  90   lw0, lw1 are private fields for upper layers for ids or fine grained handlers.
  91   The alternate usb uses them for dev_id and usb_device_irq handler.
  92
  93
  94 - Done list handling: returns the requests (callback f_handler in ED) and does
  95   some error handling, root-hub request dequeuing
  96   (files: ohci-done-list.c in ohci-hcd.c now(v0.2.0))
  97
  98