doc/driver-model/UDM-usb.txt

   1 The U-Boot Driver Model Project
   2 ===============================
   3 USB analysis
   4 ============
   5 Marek Vasut <marek.vasut@gmail.com>
   6 2012-02-16
   7
   8 I) Overview
   9 -----------
  10
  11   1) The USB Host driver
  12   ----------------------
  13   There are basically four or five USB host drivers. All such drivers currently
  14   provide at least the following fuctions:
  15
  16     usb_lowlevel_init() ... Do the initialization of the USB controller hardware
  17     usb_lowlevel_stop() ... Do the shutdown of the USB controller hardware
  18
  19     usb_event_poll() ...... Poll interrupt from USB device, often used by KBD
  20
  21     submit_control_msg() .. Submit message via Control endpoint
  22     submit_int_msg() ...... Submit message via Interrupt endpoint
  23     submit_bulk_msg() ..... Submit message via Bulk endpoint
  24
  25
  26     This allows for the host driver to be easily abstracted.
  27
  28   2) The USB hierarchy
  29   --------------------
  30
  31   In the current implementation, the USB Host driver provides operations to
  32   communicate via the USB bus. This is realised by providing access to a USB
  33   root port to which an USB root hub is attached. The USB bus is scanned and for
  34   each newly found device, a struct usb_device is allocated. See common/usb.c
  35   and include/usb.h for details.
  36
  37 II) Approach
  38 ------------
  39
  40   1) The USB Host driver
  41   ----------------------
  42
  43   Converting the host driver will follow the classic driver model consideration.
  44   Though, the host driver will have to call a function that registers a root
  45   port with the USB core in it's probe() function, let's call this function
  46
  47     usb_register_root_port(&ops);
  48
  49   This will allow the USB core to track all available root ports. The ops
  50   parameter will contain structure describing operations supported by the root
  51   port:
  52
  53   struct usb_port_ops {
  54     void   (*usb_event_poll)();
  55     int    (*submit_control_msg)();
  56     int    (*submit_int_msg)();
  57     int    (*submit_bulk_msg)();
  58   }
  59
  60   2) The USB hierarchy and hub drivers
  61   ------------------------------------
  62
  63   Converting the USB heirarchy should be fairy simple, considering the already
  64   dynamic nature of the implementation. The current usb_hub_device structure
  65   will have to be converted to a struct instance. Every such instance will
  66   contain components of struct usb_device and struct usb_hub_device in it's
  67   private data, providing only accessors in order to properly encapsulate the
  68   driver.
  69
  70   By registering the root port, the USB framework will instantiate a USB hub
  71   driver, which is always present, the root hub. The root hub and any subsequent
  72   hub instance is represented by struct instance and it's private data contain
  73   amongst others common bits from struct usb_device.
  74
  75   Note the USB hub driver is partly defying the usual method of registering a
  76   set of callbacks to a particular core driver. Instead, a static set of
  77   functions is defined and the USB hub instance is passed to those. This creates
  78   certain restrictions as of how the USB hub driver looks, but considering the
  79   specification for USB hub is given and a different type of USB hub won't ever
  80   exist, this approach is ok:
  81
  82   - Report how many ports does this hub have:
  83       uint get_nr_ports(struct instance *hub);
  84   - Get pointer to device connected to a port:
  85       struct instance *(*get_child)(struct instance *hub, int port);
  86   - Instantiate and configure device on port:
  87       struct instance *(*enum_dev_on_port)(struct instance *hub, int port);
  88
  89   3) USB device drivers
  90   ---------------------
  91
  92   The USB device driver, in turn, will have to register various ops structures
  93   with certain cores. For example, USB disc driver will have to register it's
  94   ops with core handling USB discs etc.