mail archive of the barebox mailing list
 help / color / mirror / Atom feed
* [PATCH] Documentation: usb chapter of user manual
@ 2014-07-03 12:50 Robert P. J. Day
  2014-07-04  5:33 ` Sascha Hauer
  0 siblings, 1 reply; 2+ messages in thread
From: Robert P. J. Day @ 2014-07-03 12:50 UTC (permalink / raw)
  To: U-Boot Version 2 (barebox)


A number of minor fixes, and including the help output from the
"dfu-util" command for the benefit of the reader.

Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>

---

  i added the output of "dfu-util -h" since it didn't seem onerously
long and i thought it would be useful for the reader.

diff --git a/Documentation/user/usb.rst b/Documentation/user/usb.rst
index 9bbfcca..8b700d3 100644
--- a/Documentation/user/usb.rst
+++ b/Documentation/user/usb.rst
@@ -4,21 +4,21 @@ USB support
 USB host support
 ----------------

-barebox has support for USB host and USB device mode. USB devices
+barebox has support for both USB host and USB device mode. USB devices
 take a long time to probe, so they are not probed automatically. Probing
 has to be triggered using the :ref:`command_usb` or :ref:`command_detect` command.
-USB devices in barebox are not hotpluggable. It is expected that USB
+USB devices in barebox are not hot-pluggable. It is expected that USB
 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
+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.

 To use a USB network device together with the :ref:`command_ifup` command, add the
-following to /env/network/eth0-discover:
+following to ``/env/network/eth0-discover``:

 .. code-block:: sh

@@ -30,7 +30,7 @@ USB mass storage
 ^^^^^^^^^^^^^^^^

 barebox supports USB mass storage devices. After probing them with the :ref:`command_usb`
-they show up as ``/dev/diskx`` and can be used like any other device.
+command, they show up as ``/dev/diskx`` and can be used like any other device.

 USB device support
 ------------------
@@ -39,27 +39,52 @@ DFU
 ^^^

 USB Device Firmware Upgrade (DFU) is an official USB device class specification of the USB
-Implementers Forum. It provides a vendor independent way to update the firmware of embedded
+Implementers Forum. It provides a vendor-independent way to update the firmware of embedded
 devices. The current specification is version 1.1 and can be downloaded here:
 http://www.usb.org/developers/devclass_docs/DFU_1.1.pdf

-On barebox side the update is handled with the :ref:`command_dfu` command. It is passes a list
-of partitions to provide to the host. The partition list has the form ``<file>(<name>)<flags>``.
-``file`` is the path to the device or regular file which shall be updated. ``name`` is the
-name under which the partition shall be provided to the host. For the possible ``flags`` see
+On the barebox side, the update is handled with the :ref:`command_dfu` command.
+It is passed a list of partitions to provide to the host. The partition list
+has the form ``<file>(<name>)<flags>``.  ``file`` is the path to the device or
+regular file which shall be updated. ``name`` is the name under which the partition
+shall be provided to the host. For the possible ``flags`` see
 :ref:`command_dfu`. A typical ``dfu`` command could look like this:

 .. code-block:: sh

   dfu "/dev/nand0.barebox.bb(barebox)sr,/dev/nand0.kernel.bb(kernel)r,/dev/nand0.root.bb(root)r"

-On the host the tool `dfu-util <http://dfu-util.gnumonks.org/>`_ can be used to update the
-partitions. It is available for the most distributions. To update the Kernel for the above
-example the following can be used:
+On the host side, the tool `dfu-util <http://dfu-util.gnumonks.org/>`_ can be used
+to update the partitions. It is available for most distributions and typically
+supports the following options::
+
+  dfu-util -h
+  Usage: dfu-util [options] ...
+    -h --help                     Print this help message
+    -V --version                  Print the version number
+    -v --verbose                  Print verbose debug statements
+    -l --list                     List the currently attached DFU capable USB devices
+    -e --detach                   Detach the currently attached DFU capable USB devices
+    -d --device vendor:product    Specify Vendor/Product ID of DFU device
+    -p --path bus-port. ... .port Specify path to DFU device
+    -c --cfg config_nr            Specify the Configuration of DFU device
+    -i --intf intf_nr             Specify the DFU Interface number
+    -a --alt alt                  Specify the Altsetting of the DFU Interface
+                                  by name or by number
+    -t --transfer-size            Specify the number of bytes per USB Transfer
+    -U --upload file              Read firmware from device into <file>
+    -D --download file            Write firmware from <file> into device
+    -R --reset                    Issue USB Reset signalling once we're finished
+    -s --dfuse-address address    ST DfuSe mode, specify target address for
+                                  raw file download or upload. Not applicable for
+                                  DfuSe file (.dfu) downloads
+
+To update the kernel for the above example, you would use something like
+the following:

 .. code-block:: sh

   dfu-util -D arch/arm/boot/zImage -a kernel

-The dfu-util command automatically finds dfu capable devices. If there are multiple devices
-found it has to be specified with the ``-d``/``-p`` options.
+The ``dfu-util`` command automatically finds DFU-capable devices. If there are
+multiple devices found, you need to identify one with the ``-d``/``-p`` options.

-- 

========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================

_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox

^ permalink raw reply	[flat|nested] 2+ messages in thread

* Re: [PATCH] Documentation: usb chapter of user manual
  2014-07-03 12:50 [PATCH] Documentation: usb chapter of user manual Robert P. J. Day
@ 2014-07-04  5:33 ` Sascha Hauer
  0 siblings, 0 replies; 2+ messages in thread
From: Sascha Hauer @ 2014-07-04  5:33 UTC (permalink / raw)
  To: Robert P. J. Day; +Cc: U-Boot Version 2 (barebox)

On Thu, Jul 03, 2014 at 08:50:36AM -0400, Robert P. J. Day wrote:
> 
> A number of minor fixes, and including the help output from the
> "dfu-util" command for the benefit of the reader.
> 
> Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>

Applied, thanks

Sascha

> 
> ---
> 
>   i added the output of "dfu-util -h" since it didn't seem onerously
> long and i thought it would be useful for the reader.
> 
> diff --git a/Documentation/user/usb.rst b/Documentation/user/usb.rst
> index 9bbfcca..8b700d3 100644
> --- a/Documentation/user/usb.rst
> +++ b/Documentation/user/usb.rst
> @@ -4,21 +4,21 @@ USB support
>  USB host support
>  ----------------
> 
> -barebox has support for USB host and USB device mode. USB devices
> +barebox has support for both USB host and USB device mode. USB devices
>  take a long time to probe, so they are not probed automatically. Probing
>  has to be triggered using the :ref:`command_usb` or :ref:`command_detect` command.
> -USB devices in barebox are not hotpluggable. It is expected that USB
> +USB devices in barebox are not hot-pluggable. It is expected that USB
>  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
> +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.
> 
>  To use a USB network device together with the :ref:`command_ifup` command, add the
> -following to /env/network/eth0-discover:
> +following to ``/env/network/eth0-discover``:
> 
>  .. code-block:: sh
> 
> @@ -30,7 +30,7 @@ USB mass storage
>  ^^^^^^^^^^^^^^^^
> 
>  barebox supports USB mass storage devices. After probing them with the :ref:`command_usb`
> -they show up as ``/dev/diskx`` and can be used like any other device.
> +command, they show up as ``/dev/diskx`` and can be used like any other device.
> 
>  USB device support
>  ------------------
> @@ -39,27 +39,52 @@ DFU
>  ^^^
> 
>  USB Device Firmware Upgrade (DFU) is an official USB device class specification of the USB
> -Implementers Forum. It provides a vendor independent way to update the firmware of embedded
> +Implementers Forum. It provides a vendor-independent way to update the firmware of embedded
>  devices. The current specification is version 1.1 and can be downloaded here:
>  http://www.usb.org/developers/devclass_docs/DFU_1.1.pdf
> 
> -On barebox side the update is handled with the :ref:`command_dfu` command. It is passes a list
> -of partitions to provide to the host. The partition list has the form ``<file>(<name>)<flags>``.
> -``file`` is the path to the device or regular file which shall be updated. ``name`` is the
> -name under which the partition shall be provided to the host. For the possible ``flags`` see
> +On the barebox side, the update is handled with the :ref:`command_dfu` command.
> +It is passed a list of partitions to provide to the host. The partition list
> +has the form ``<file>(<name>)<flags>``.  ``file`` is the path to the device or
> +regular file which shall be updated. ``name`` is the name under which the partition
> +shall be provided to the host. For the possible ``flags`` see
>  :ref:`command_dfu`. A typical ``dfu`` command could look like this:
> 
>  .. code-block:: sh
> 
>    dfu "/dev/nand0.barebox.bb(barebox)sr,/dev/nand0.kernel.bb(kernel)r,/dev/nand0.root.bb(root)r"
> 
> -On the host the tool `dfu-util <http://dfu-util.gnumonks.org/>`_ can be used to update the
> -partitions. It is available for the most distributions. To update the Kernel for the above
> -example the following can be used:
> +On the host side, the tool `dfu-util <http://dfu-util.gnumonks.org/>`_ can be used
> +to update the partitions. It is available for most distributions and typically
> +supports the following options::
> +
> +  dfu-util -h
> +  Usage: dfu-util [options] ...
> +    -h --help                     Print this help message
> +    -V --version                  Print the version number
> +    -v --verbose                  Print verbose debug statements
> +    -l --list                     List the currently attached DFU capable USB devices
> +    -e --detach                   Detach the currently attached DFU capable USB devices
> +    -d --device vendor:product    Specify Vendor/Product ID of DFU device
> +    -p --path bus-port. ... .port Specify path to DFU device
> +    -c --cfg config_nr            Specify the Configuration of DFU device
> +    -i --intf intf_nr             Specify the DFU Interface number
> +    -a --alt alt                  Specify the Altsetting of the DFU Interface
> +                                  by name or by number
> +    -t --transfer-size            Specify the number of bytes per USB Transfer
> +    -U --upload file              Read firmware from device into <file>
> +    -D --download file            Write firmware from <file> into device
> +    -R --reset                    Issue USB Reset signalling once we're finished
> +    -s --dfuse-address address    ST DfuSe mode, specify target address for
> +                                  raw file download or upload. Not applicable for
> +                                  DfuSe file (.dfu) downloads
> +
> +To update the kernel for the above example, you would use something like
> +the following:
> 
>  .. code-block:: sh
> 
>    dfu-util -D arch/arm/boot/zImage -a kernel
> 
> -The dfu-util command automatically finds dfu capable devices. If there are multiple devices
> -found it has to be specified with the ``-d``/``-p`` options.
> +The ``dfu-util`` command automatically finds DFU-capable devices. If there are
> +multiple devices found, you need to identify one with the ``-d``/``-p`` options.
> 
> -- 
> 
> ========================================================================
> Robert P. J. Day                                 Ottawa, Ontario, CANADA
>                         http://crashcourse.ca
> 
> Twitter:                                       http://twitter.com/rpjday
> LinkedIn:                               http://ca.linkedin.com/in/rpjday
> ========================================================================
> 
> _______________________________________________
> barebox mailing list
> barebox@lists.infradead.org
> http://lists.infradead.org/mailman/listinfo/barebox
> 

-- 
Pengutronix e.K.                           |                             |
Industrial Linux Solutions                 | http://www.pengutronix.de/  |
Peiner Str. 6-8, 31137 Hildesheim, Germany | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-5555 |

_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox

^ permalink raw reply	[flat|nested] 2+ messages in thread

end of thread, other threads:[~2014-07-04  5:34 UTC | newest]

Thread overview: 2+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2014-07-03 12:50 [PATCH] Documentation: usb chapter of user manual Robert P. J. Day
2014-07-04  5:33 ` Sascha Hauer

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox