diff options
Diffstat (limited to 'Documentation/user/usb.rst')
| -rw-r--r-- | Documentation/user/usb.rst | 70 |
1 files changed, 60 insertions, 10 deletions
diff --git a/Documentation/user/usb.rst b/Documentation/user/usb.rst index 2479efe9d6..7eb360d629 100644 --- a/Documentation/user/usb.rst +++ b/Documentation/user/usb.rst @@ -13,9 +13,9 @@ devices are not disconnected while barebox is running. USB Networking ^^^^^^^^^^^^^^ -barebox supports ASIX-compatible devices and the SMSC95xx. After -detection, the device shows up as eth0 and can be used like a regular network -device. +barebox supports r8152, ASIX-compatible devices and the SMSC95xx. After +detection, the device shows up as an extra network device (e.g. eth1) and +can be used like a regular network device. To use a USB network device together with the :ref:`command_ifup` command, add the following to ``/env/network/eth0-discover``: @@ -26,6 +26,9 @@ following to ``/env/network/eth0-discover``: usb +Alternatively, a ``detect -a`` (all) can be forced in ``ifup`` by setting +``global.net.ifup_force_detect=1``. + USB mass storage ^^^^^^^^^^^^^^^^ @@ -39,18 +42,21 @@ barebox supports several different USB gadget drivers: - Device Firmware Upgrade (DFU) - Android Fastboot +- USB mass storage - serial gadget The recommended way to use USB gadget is with the :ref:`command_usbgadget` command. While there are individual commands for :ref:`command_dfu` and :ref:`command_usbserial`, -the :ref:`command_usbgadget` commands supports registering composite gadgets. +the :ref:`command_usbgadget` commands supports registering composite gadgets, which +exports multiple functions at once. This happens in the "background" without impacting +use of the shell. Partition description ^^^^^^^^^^^^^^^^^^^^^ -The USB gadget commands for Android Fastboot and DFU take a partition description -which describes which barebox partitions are exported via USB. The partition -description is referred to as ``<desc>`` in the command help texts. It has +The USB gadget commands for Android Fastboot, DFU and the mass storage gadget +take a partition description which describes which barebox partitions are exported via USB. +The partition description is referred to as ``<desc>`` in the command help texts. It has the general form ``partition(name)flags,partition(name)flags,...``. The **partition** field is the partition as accessible in barebox. This can be a @@ -65,6 +71,8 @@ Several **flags** are supported, each denoted by a single character: * ``r`` Readback. The partition is allowed to be read back (DFU specific) * ``c`` The file shall be created if it doesn't exist. Needed when a regular file is exported. * ``u`` The partition is a MTD device and shall be flashed with a UBI image. +* ``o`` The partition is optional, i.e. if it is not available at initialization time, it is skipped + instead of aborting the initialization. This is currently only supported for fastboot. Example: @@ -72,6 +80,22 @@ Example: /dev/nand0.barebox.bb(barebox)sr,/kernel(kernel)rc +Board code authors are encouraged to provide a default environment containing +partitions with descriptive names. For boards where this is not specified, +there exist a number of **partition** specifiers for automatically generating entries: + +* ``block`` exports all registered block devices (e.g. eMMC and SD) +* ``auto`` currently equivalent to ``block``. May be extended to other flashable + devices, like EEPROMs, MTD or UBI volumes in future + +Example usage of exporting registered block devices, barebox update +handlers and a single file that is created on flashing: + +.. code-block:: sh + + detect -a # optional. Detects everything, so auto can register it + usbgadget -A auto,/tmp/fitimage(fitimage)c -b + DFU ^^^ @@ -144,12 +168,13 @@ The Fastboot gadget supports the following commands: ``fastboot flash`` additionally supports image types UBI and Barebox. For UBI Images and a MTD device as target, ubiformat is called. For a Barebox image with an available barebox update handler for the fastboot exported device, the -barebox_update is called. +barebox_update is called (exported as ``bbu-<update_handler_name>`` fastboot +partition). The barebox Fastboot gadget supports the following non standard extensions: - ``fastboot getvar all`` - Shows a list of all variables + Shows a list of all variables, including exported partitions - ``fastboot oem getenv <varname>`` Shows a barebox environment variable - ``fastboot oem setenv <varname>=<value>`` @@ -206,6 +231,16 @@ and initrd: fi timeout -k 5 3 fastboot -i 7531 oem exec -- bootm -o /devicetree -r /initrd /kernel +USB Mass storage gadget +^^^^^^^^^^^^^^^^^^^^^^^ + +Example exporting barebox block devices to a USB host: + +.. code-block:: sh + + usbgadget -S /dev/mmc0(emmc),/dev/mmc1(sd) + + USB Composite Multifunction Gadget ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -227,7 +262,7 @@ after creating the gadget. The gadget can be removed with ``usbgadget -d``. USB OTG support --------------- -barebox does not have USB OTG support. However, barebox supports some USB cores in +barebox does not have true USB OTG support. However, barebox supports some USB cores in both host and device mode. If these are specified for otg in the device tree (dr_mode = "otg";) barebox registers a OTG device which can be used to decide which mode shall be used. The device has a ``mode`` parameter which by default has the @@ -246,6 +281,21 @@ mode. Once a specific mode has been selected it can't be changed later anymore. musb-hdrc: 28/31 max ep, 16384/16384 memory barebox:/ +USB Type-C support +------------------ + +barebox can usually stay oblivious to the type of connector used. Sometimes though, +board code and user scripts may want to base their decisions on how a USB-C connector +is connected. Type C drivers can thus register with the Type C driver core to +export a number of device parameters: + +- ``$typec0.usb_role`` = { ``none``, ``device``, ``host`` } +- ``$typec0.pwr_role`` = { ``sink``, ``source`` } +- ``$typec0.accessory`` = { ``none``, ``audio``, ``debug`` } + +Currently, only the TUSB320 is supported, but it's straight-forward to port more +drivers from Linux. + USB Gadget autostart Support ---------------------------- |