* [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