Eric Lee / smarc-uboot

Download as
Browse Code ยป

Commit 5fd2733e5a821acf0358f51d436b61209deac9a5

Authored by Simon Glass
1 parent e00cb2232b
Exists in v2017.01-smarct4x and in 35 other branches 8qm-imx_v2020.04_5.4.70_2.3.0, emb_lf_v2022.04, emb_lf_v2023.04, pitx_8mp_lf_v2020.04, smarc-8m-android-10.0.0_2.6.0, smarc-8m-android-11.0.0_2.0.0, smarc-8mp-android-11.0.0_2.0.0, smarc-imx6_v2018.03_4.14.98_2.0.0_ga, smarc-imx7_v2017.03_4.9.11_1.0.0_ga, smarc-imx7_v2018.03_4.14.98_2.0.0_ga, smarc-imx_v2017.03_4.9.11_1.0.0_ga, smarc-imx_v2017.03_4.9.88_2.0.0_ga, smarc-imx_v2017.03_o8.1.0_1.3.0_8m, smarc-imx_v2018.03_4.14.78_1.0.0_ga, smarc-n7.1.2_2.0.0-ga, smarc-rel_imx_4.1.15_2.0.0_ga, smarc_8m-imx_v2018.03_4.14.98_2.0.0_ga, smarc_8m-imx_v2019.04_4.19.35_1.1.0, smarc_8m_00d0-imx_v2018.03_4.14.98_2.0.0_ga, smarc_8mm-imx_v2018.03_4.14.98_2.0.0_ga, smarc_8mm-imx_v2019.04_4.19.35_1.1.0, smarc_8mm-imx_v2020.04_5.4.24_2.1.0, smarc_8mp_lf_v2020.04, smarc_8mq-imx_v2020.04_5.4.24_2.1.0, smarc_8mq_lf_v2020.04, ti-u-boot-2015.07, v2015.07-smarct33, v2015.07-smarct33-emmc, v2015.07-smarct4x, v2016.05-dlt, v2016.05-smarct3x, v2016.05-smarct3x-emmc, v2016.05-smarct4x, v2017.01-smarct3x, v2017.01-smarct3x-emmc

dm: usb: Add a README for driver model 

Add some documentation describing how USB is implemented with USB. This
might make things easier for people to understand.

Signed-off-by: Simon Glass <sjg@chromium.org>

Showing 1 changed file with 415 additions and 0 deletions Side-by-side Diff

doc/driver-model/usb-info.txt
Diff comments   View file @ 5fd2733
  1 +How USB works with driver model
  2 +===============================
  3 +
  4 +Introduction
  5 +------------
  6 +
  7 +Driver model USB support makes use of existing features but changes how
  8 +drivers are found. This document provides some information intended to help
  9 +understand how things work with USB in U-Boot when driver model is enabled.
  10 +
  11 +
  12 +Enabling driver model for USB
  13 +-----------------------------
  14 +
  15 +A new CONFIG_DM_USB option is provided to enable driver model for USB. This
  16 +causes the USB uclass to be included, and drops the equivalent code in
  17 +usb.c. In particular the usb_init() function is then implemented by the
  18 +uclass.
  19 +
  20 +
  21 +Support for EHCI and XHCI
  22 +-------------------------
  23 +
  24 +So far OHCI is not supported. Both EHCI and XHCI drivers should be declared
  25 +as drivers in the USB uclass. For example:
  26 +
  27 +static const struct udevice_id ehci_usb_ids[] = {
  28 + { .compatible = "nvidia,tegra20-ehci", .data = USB_CTLR_T20 },
  29 + { .compatible = "nvidia,tegra30-ehci", .data = USB_CTLR_T30 },
  30 + { .compatible = "nvidia,tegra114-ehci", .data = USB_CTLR_T114 },
  31 + { }
  32 +};
  33 +
  34 +U_BOOT_DRIVER(usb_ehci) = {
  35 + .name = "ehci_tegra",
  36 + .id = UCLASS_USB,
  37 + .of_match = ehci_usb_ids,
  38 + .ofdata_to_platdata = ehci_usb_ofdata_to_platdata,
  39 + .probe = tegra_ehci_usb_probe,
  40 + .remove = tegra_ehci_usb_remove,
  41 + .ops = &ehci_usb_ops,
  42 + .platdata_auto_alloc_size = sizeof(struct usb_platdata),
  43 + .priv_auto_alloc_size = sizeof(struct fdt_usb),
  44 + .flags = DM_FLAG_ALLOC_PRIV_DMA,
  45 +};
  46 +
  47 +Here ehci_usb_ids is used to list the controllers that the driver supports.
  48 +Each has its own data value. Controllers must be in the UCLASS_USB uclass.
  49 +
  50 +The ofdata_to_platdata() method allows the controller driver to grab any
  51 +necessary settings from the device tree.
  52 +
  53 +The ops here are ehci_usb_ops. All EHCI drivers will use these same ops in
  54 +most cases, since they are all EHCI-compatible. For EHCI there are also some
  55 +special operations that can be overridden when calling ehci_register().
  56 +
  57 +The driver can use priv_auto_alloc_size to set the size of its private data.
  58 +This can hold run-time information needed by the driver for operation. It
  59 +exists when the device is probed (not when it is bound) and is removed when
  60 +the driver is removed.
  61 +
  62 +Note that usb_platdata is currently only used to deal with setting up a bus
  63 +in USB device mode (OTG operation). It can be omitted if that is not
  64 +supported.
  65 +
  66 +The driver's probe() method should do the basic controller init and then
  67 +call ehci_register() to register itself as an EHCI device. It should call
  68 +ehci_deregister() in the remove() method. Registering a new EHCI device
  69 +does not by itself cause the bus to be scanned.
  70 +
  71 +The old ehci_hcd_init() function is no-longer used. Nor is it necessary to
  72 +set up the USB controllers from board init code. When 'usb start' is used,
  73 +each controller will be probed and its bus scanned.
  74 +
  75 +XHCI works in a similar way.
  76 +
  77 +
  78 +Data structures
  79 +---------------
  80 +
  81 +The following primary data structures are in use:
  82 +
  83 +- struct usb_device
  84 + This holds information about a device on the bus. All devices have
  85 + this structure, even the root hub. The controller itself does not
  86 + have this structure. You can access it for a device 'dev' with
  87 + dev_get_parentdata(dev). It matches the old structure except that the
  88 + parent and child information is not present (since driver model
  89 + handles that). Once the device is set up, you can find the device
  90 + descriptor and current configuration descriptor in this structure.
  91 +
  92 +- struct usb_platdata
  93 + This holds platform data for a controller. So far this is only used
  94 + as a work-around for controllers which can act as USB devices in OTG
  95 + mode, since the gadget framework does not use driver model.
  96 +
  97 +- struct usb_dev_platdata
  98 + This holds platform data for a device. You can access it for a
  99 + device 'dev' with dev_get_parent_platdata(dev). It holds the device
  100 + address and speed - anything that can be determined before the device
  101 + driver is actually set up. When probing the bus this structure is
  102 + used to provide essential information to the device driver.
  103 +
  104 +- struct usb_bus_priv
  105 + This is private information for each controller, maintained by the
  106 + controller uclass. It is mostly used to keep track of the next
  107 + device address to use.
  108 +
  109 +Of these, only struct usb_device was used prior to driver model.
  110 +
  111 +
  112 +USB buses
  113 +---------
  114 +
  115 +Given a controller, you know the bus - it is the one attached to the
  116 +controller. Each controller handles exactly one bus. Every controller has a
  117 +root hub attached to it. This hub, which is itself a USB device, can provide
  118 +one or more 'ports' to which additional devices can be attached. It is
  119 +possible to power up a hub and find out which of its ports have devices
  120 +attached.
  121 +
  122 +Devices are given addresses starting at 1. The root hub is always address 1,
  123 +and from there the devices are numbered in sequence. The USB uclass takes
  124 +care of this numbering automatically during enumeration.
  125 +
  126 +USB devices are enumerated by finding a device on a particular hub, and
  127 +setting its address to the next available address. The USB bus stretches out
  128 +in a tree structure, potentially with multiple hubs each with several ports
  129 +and perhaps other hubs. Some hubs will have their own power since otherwise
  130 +the 5V 500mA power supplied by the controller will not be sufficient to run
  131 +very many devices.
  132 +
  133 +Enumeration in U-Boot takes a long time since devices are probed one at a
  134 +time, and each is given sufficient time to wake up and announce itself. The
  135 +timeouts are set for the slowest device.
  136 +
  137 +Up to 127 devices can be on each bus. USB has four bus speeds: low
  138 +(1.5Mbps), full (12Mbps), high (480Mbps) which is only available with USB2
  139 +and newer (EHCI), and super (5Gbps) which is only available with USB3 and
  140 +newer (XHCI). If you connect a super-speed device to a high-speed hub, you
  141 +will only get high-speed.
  142 +
  143 +
  144 +USB operations
  145 +--------------
  146 +
  147 +As before driver model, messages can be sent using submit_bulk_msg() and the
  148 +like. These are now implemented by the USB uclass and route through the
  149 +controller drivers. Note that messages are not sent to the driver of the
  150 +device itself - i.e. they don't pass down the stack to the controller.
  151 +U-Boot simply finds the controller to which the device is attached, and sends
  152 +the message there with an appropriate 'pipe' value so it can be addressed
  153 +properly. Having said that, the USB device which should receive the message
  154 +is passed in to the driver methods, for use by sandbox. This design decision
  155 +is open for review and the code impact of changing it is small since the
  156 +methods are typically implemented by the EHCI and XHCI stacks.
  157 +
  158 +Controller drivers (in UCLASS_USB) themselves provide methods for sending
  159 +each message type. For XHCI an additional alloc_device() method is provided
  160 +since XHCI needs to allocate a device context before it can even read the
  161 +device's descriptor.
  162 +
  163 +These methods use a 'pipe' which is a collection of bit fields used to
  164 +describe the type of message, direction of transfer and the intended
  165 +recipient (device number).
  166 +
  167 +
  168 +USB Devices
  169 +-----------
  170 +
  171 +USB devices are found using a simple algorithm which works through the
  172 +available hubs in a depth-first search. Devices can be in any uclass, but
  173 +are attached to a parent hub (or controller in the case of the root hub) and
  174 +so have parent data attached to them (this is struct usb_device).
  175 +
  176 +By the time the device's probe() method is called, it is enumerated and is
  177 +ready to talk to the host.
  178 +
  179 +The enumeration process needs to work out which driver to attach to each USB
  180 +device. It does this by examining the device class, interface class, vendor
  181 +ID, product ID, etc. See struct usb_driver_entry for how drivers are matched
  182 +with USB devices - you can use the USB_DEVICE() macro to declare a USB
  183 +driver. For example, usb_storage.c defines a USB_DEVICE() to handle storage
  184 +devices, and it will be used for all USB devices which match.
  185 +
  186 +
  187 +
  188 +Technical details on enumeration flow
  189 +-------------------------------------
  190 +
  191 +It is useful to understand precisely how a USB bus is enumerating to avoid
  192 +confusion when dealing with USB devices.
  193 +
  194 +Device initialisation happens roughly like this:
  195 +
  196 +- At some point the 'usb start' command is run
  197 +- This calls usb_init() which works through each controller in turn
  198 +- The controller is probed(). This does no enumeration.
  199 +- Then usb_scan_bus() is called. This calls usb_scan_device() to scan the
  200 +(only) device that is attached to the controller - a root hub
  201 +- usb_scan_device() sets up a fake struct usb_device and calls
  202 +usb_setup_device(), passing the port number to be scanned, in this case port
  203 +0
  204 +- usb_setup_device() first calls usb_prepare_device() to set the device
  205 +address, then usb_select_config() to select the first configuration
  206 +- at this point the device is enumerated but we do not have a real struct
  207 +udevice for it. But we do have the descriptor in struct usb_device so we can
  208 +use this to figure out what driver to use
  209 +- back in usb_scan_device(), we call usb_find_child() to try to find an
  210 +existing device which matches the one we just found on the bus. This can
  211 +happen if the device is mentioned in the device tree, or if we previously
  212 +scanned the bus and so the device was created before
  213 +- if usb_find_child() does not find an existing device, we call
  214 +usb_find_and_bind_driver() which tries to bind one
  215 +- usb_find_and_bind_driver() searches all available USB drivers (declared
  216 +with USB_DEVICE()). If it finds a match it binds that driver to create a new
  217 +device.
  218 +- If it does not, it binds a generic driver. A generic driver is good enough
  219 +to allow access to the device (sending it packets, etc.) but all
  220 +functionality will need to be implemented outside the driver model.
  221 +- in any case, when usb_find_child() and/or usb_find_and_bind_driver() are
  222 +done, we have a device with the correct uclass. At this point we want to
  223 +probe the device
  224 +- first we store basic information about the new device (address, port,
  225 +speed) in its parent platform data. We cannot store it its private data
  226 +since that will not exist until the device is probed.
  227 +- then we call device_probe() which probes the device
  228 +- the first probe step is actually the USB controller's (or USB hubs's)
  229 +child_pre_probe() method. This gets called before anything else and is
  230 +intended to set up a child device ready to be used with its parent bus. For
  231 +USB this calls usb_child_pre_probe() which grabs the information that was
  232 +stored in the parent platform data and stores it in the parent private data
  233 +(which is struct usb_device, a real one this time). It then calls
  234 +usb_select_config() again to make sure that everything about the device is
  235 +set up
  236 +- note that we have called usb_select_config() twice. This is inefficient
  237 +but the alternative is to store additional information in the platform data.
  238 +The time taken is minimal and this way is simpler
  239 +- at this point the device is set up and ready for use so far as the USB
  240 +subsystem is concerned
  241 +- the device's probe() method is then called. It can send messages and do
  242 +whatever else it wants to make the device work.
  243 +
  244 +Note that the first device is always a root hub, and this must be scanned to
  245 +find any devices. The above steps will have created a hub (UCLASS_USB_HUB),
  246 +given it address 1 and set the configuration.
  247 +
  248 +For hubs, the hub uclass has a post_probe() method. This means that after
  249 +any hub is probed, the uclass gets to do some processing. In this case
  250 +usb_hub_post_probe() is called, and the following steps take place:
  251 +
  252 +- usb_hub_post_probe() calls usb_hub_scan() to scan the hub, which in turn
  253 +calls usb_hub_configure()
  254 +- hub power is enabled
  255 +- we loop through each port on the hub, performing the same steps for each
  256 +- first, check if there is a device present. This happens in
  257 +usb_hub_port_connect_change(). If so, then usb_scan_device() is called to
  258 +scan the device, passing the appropriate port number.
  259 +- you will recognise usb_scan_device() from the steps above. It sets up the
  260 +device ready for use. If it is a hub, it will scan that hub before it
  261 +continues here (recursively, depth-first)
  262 +- once all hub ports are scanned in this way, the hub is ready for use and
  263 +all of its downstream devices also
  264 +- additional controllers are scanned in the same way
  265 +
  266 +The above method has some nice properties:
  267 +
  268 +- the bus enumeration happens by virtue of driver model's natural device flow
  269 +- most logic is in the USB controller and hub uclasses; the actual device
  270 +drivers do not need to know they are on a USB bus, at least so far as
  271 +enumeration goes
  272 +- hub scanning happens automatically after a hub is probed
  273 +
  274 +
  275 +Hubs
  276 +----
  277 +
  278 +USB hubs are scanned as in the section above. While hubs have their own
  279 +uclass, they share some common elements with controllers:
  280 +
  281 +- they both attach private data to their children (struct usb_device,
  282 +accessible for a child with dev_get_parentdata(child))
  283 +- they both use usb_child_pre_probe() to set up their children as proper USB
  284 +devices
  285 +
  286 +
  287 +Example - Mass Storage
  288 +----------------------
  289 +
  290 +As an example of a USB device driver, see usb_storage.c. It uses its own
  291 +uclass and declares itself as follows:
  292 +
  293 +U_BOOT_DRIVER(usb_mass_storage) = {
  294 + .name = "usb_mass_storage",
  295 + .id = UCLASS_MASS_STORAGE,
  296 + .of_match = usb_mass_storage_ids,
  297 + .probe = usb_mass_storage_probe,
  298 +};
  299 +
  300 +static const struct usb_device_id mass_storage_id_table[] = {
  301 + { .match_flags = USB_DEVICE_ID_MATCH_INT_CLASS,
  302 + .bInterfaceClass = USB_CLASS_MASS_STORAGE},
  303 + { } /* Terminating entry */
  304 +};
  305 +
  306 +USB_DEVICE(usb_mass_storage, mass_storage_id_table);
  307 +
  308 +The USB_DEVICE() macro attaches the given table of matching information to
  309 +the given driver. Note that the driver is declared in U_BOOT_DRIVER() as
  310 +'usb_mass_storage' and this must match the first parameter of USB_DEVICE.
  311 +
  312 +When usb_find_and_bind_driver() is called on a USB device with the
  313 +bInterfaceClass value of USB_CLASS_MASS_STORAGE, it will automatically find
  314 +this driver and use it.
  315 +
  316 +
  317 +Counter-example: USB Ethernet
  318 +-----------------------------
  319 +
  320 +As an example of the old way of doing things, see usb_ether.c. When the bus
  321 +is scanned, all Ethernet devices will be created as generic USB devices (in
  322 +uclass UCLASS_USB_DEV_GENERIC). Then, when the scan is completed,
  323 +usb_host_eth_scan() will be called. This looks through all the devices on
  324 +each bus and manually figures out which are Ethernet devices in the ways of
  325 +yore.
  326 +
  327 +In fact, usb_ether should be moved to driver model. Each USB Ethernet driver
  328 +(e.g drivers/usb/eth/asix.c) should include a USB_DEVICE() declaration, so
  329 +that it will be found as part of normal USB enumeration. Then, instead of a
  330 +generic USB driver, a real (driver-model-aware) driver will be used. Since
  331 +Ethernet now supports driver model, this should be fairly easy to achieve,
  332 +and then usb_ether.c and the usb_host_eth_scan() will melt away.
  333 +
  334 +
  335 +Sandbox
  336 +-------
  337 +
  338 +All driver model uclasses must have tests and USB is no exception. To
  339 +achieve this, a sandbox USB controller is provided. This can make use of
  340 +emulation drivers which pretend to be USB devices. Emulations are provided
  341 +for a hub and a flash stick. These are enough to create a pretend USB bus
  342 +(defined by the sandbox device tree sandbox.dts) which can be scanned and
  343 +used.
  344 +
  345 +Tests in test/dm/usb.c make use of this feature. It allows much of the USB
  346 +stack to be tested without real hardware being needed.
  347 +
  348 +Here is an example device tree fragment:
  349 +
  350 + usb@1 {
  351 + compatible = "sandbox,usb";
  352 + hub {
  353 + compatible = "usb-hub";
  354 + usb,device-class = <USB_CLASS_HUB>;
  355 + hub-emul {
  356 + compatible = "sandbox,usb-hub";
  357 + #address-cells = <1>;
  358 + #size-cells = <0>;
  359 + flash-stick {
  360 + reg = <0>;
  361 + compatible = "sandbox,usb-flash";
  362 + sandbox,filepath = "flash.bin";
  363 + };
  364 + };
  365 + };
  366 + };
  367 +
  368 +This defines a single controller, containing a root hub (which is required).
  369 +The hub is emulated by a hub emulator, and the emulated hub has a single
  370 +flash stick to emulate on one of its ports.
  371 +
  372 +When 'usb start' is used, the following 'dm tree' output will be available:
  373 +
  374 + usb [ + ] `-- usb@1
  375 + usb_hub [ + ] `-- hub
  376 + usb_emul [ + ] |-- hub-emul
  377 + usb_emul [ + ] | `-- flash-stick
  378 + usb_mass_st [ + ] `-- usb_mass_storage
  379 +
  380 +
  381 +This may look confusing. Most of it mirrors the device tree, but the
  382 +'usb_mass_storage' device is not in the device tree. This is created by
  383 +usb_find_and_bind_driver() based on the USB_DRIVER in usb_storage.c. While
  384 +'flash-stick' is the emulation device, 'usb_mass_storage' is the real U-Boot
  385 +USB device driver that talks to it.
  386 +
  387 +
  388 +Future work
  389 +-----------
  390 +
  391 +It is pretty uncommon to have a large USB bus with lots of hubs on an
  392 +embedded system. In fact anything other than a root hub is uncommon. Still
  393 +it would be possible to speed up enumeration in two ways:
  394 +
  395 +- breadth-first search would allow devices to be reset and probed in
  396 +parallel to some extent
  397 +- enumeration could be lazy, in the sense that we could enumerate just the
  398 +root hub at first, then only progress to the next 'level' when a device is
  399 +used that we cannot find. This could be made easier if the devices were
  400 +statically declared in the device tree (which is acceptable for production
  401 +boards where the same, known, things are on each bus).
  402 +
  403 +But in common cases the current algorithm is sufficient.
  404 +
  405 +Other things that need doing:
  406 +- Convert usb_ether to use driver model as described above
  407 +- Test that keyboards work (and convert to driver model)
  408 +- Move the USB gadget framework to driver model
  409 +- Implement OHCI in driver model
  410 +- Implement USB PHYs in driver model
  411 +- Work out a clever way to provide lazy init for USB devices
  412 +
  413 +--
  414 +Simon Glass <sjg@chromium.org>
  415 +23-Mar-15