[DistroKit] [PATCH 13/16] v7a: update fastboot documentation

[Roland Hieber <rhi@pengutronix.de>]

The v7a barebox from upstream PTXdist now supports fastboot for all
platforms, not only riotboard. Move the documentation into the v7a
section, rewrite it for clarity, and adapt it to the current situation
(e.g. the -S parameter is no longer required for current setups since
fastboot learned to do chunking on-demand.)

Signed-off-by: Roland Hieber <rhi@pengutronix.de>
---
PATCH v2: new in v2
---
 doc/hardware.rst          | 66 ++++++++++++++++++++++++++++++++++++
 doc/hardware_v7a_riot.rst | 70 ++++-----------------------------------
 doc/testing.rst           |  8 ++---
 3 files changed, 76 insertions(+), 68 deletions(-)

diff --git a/doc/hardware.rst b/doc/hardware.rst
index 50a7de1e6701..bbccb08d5ca2 100644
--- a/doc/hardware.rst
+++ b/doc/hardware.rst
@@ -91,6 +91,72 @@ listed above, here is a short overview of the generic way:
 
 Refer to the :ref:`ptx_dev_manual` for a more thorough documentation.
 
+Fast Development via fastboot
+-----------------------------
+
+For development, the v7a bootloaders are set-up to support :ref:`fast_development`
+out of the box.
+Currently this is supported on all v7a boards except AT91 and AM33xx platforms.
+
+The actual partition names might differ between boards.
+To get a list of exported partitions, connect the USB OTG connector on the
+board, and run on your development host::
+
+   $ fastboot getvar all
+   (bootloader) version: 0.4
+   (bootloader) bootloader-version: barebox-2023.02.1
+   (bootloader) max-download-size: 8388608
+   (bootloader) partition-size:mmc1: 00000000
+   (bootloader) partition-type:mmc1: unavailable
+   (bootloader) partition-size:mmc2: 00000000
+   (bootloader) partition-type:mmc2: unavailable
+   (bootloader) partition-size:mmc3: e5000000
+   (bootloader) partition-type:mmc3: basic
+   (bootloader) partition-size:ram-kernel: 00000000
+   (bootloader) partition-type:ram-kernel: file
+   (bootloader) partition-size:ram-initramfs: 00000000
+   (bootloader) partition-type:ram-initramfs: file
+   (bootloader) partition-size:ram-oftree: 00000000
+   (bootloader) partition-type:ram-oftree: file
+   (bootloader) partition-size:bbu-emmc: 000e0000
+   (bootloader) partition-type:bbu-emmc: basic
+
+In this example, the exported partition names are *mmc1*, *mmc2*, *mmc3*,
+*ram-kernel*, *ram-initramfs*, *ram-oftree* and *bbu-emmc*.
+In this example two of the SD cards (*mmc1* and *mmc2*) are not plugged in (i.e.
+"unavailable").
+Note that the entries starting with *ram-* refer to files in RAM instead of
+persistent storage.
+
+.. note:: You need to restart the fastboot usbgadget in barebox or reset the
+   board if you swap the SD cards later on.
+
+You can write images to the exported fastboot partitions by running the
+``fastboot flash`` command on your development host::
+
+   $ fastboot flash ram-kernel platform-v7a/images/linuximage
+   $ fastboot flash ram-oftree platform-v7a/images/imx6dl-riotboard.dtb
+   $ fastboot flash ram-initramfs platform-v7a/images/root.cpio.gz
+
+(The Device Tree here is exemplary for the RIoT-Board; use the respective DTB
+for your board instead.)
+
+Then instruct barebox to boot from the *ram-fastboot* boot target::
+
+   $ fastboot oem exec -- boot ram-fastboot
+
+You can populate persistent memory like the eMMC as well. But only a whole
+memory device can be written, no single partitions, so your image has to
+include a partition table if needed::
+
+   $ fastboot flash mmc1 platform-v7a/images/riotboard.hdimg
+
+The mapping of *mmc1*, *mmc2* and *mmc3* depends on the board; see the
+documentation for each board above.
+
+.. note:: If you have no USB connection to your board, you can use
+          a network connection instead. Run all the 'fastboot' commands
+          shown above with the additional option '-s udp:<board IP address>'.
 
 v7a_noneon Platform
 -------------------
diff --git a/doc/hardware_v7a_riot.rst b/doc/hardware_v7a_riot.rst
index a6e236502f1a..25c6bae5aab3 100644
--- a/doc/hardware_v7a_riot.rst
+++ b/doc/hardware_v7a_riot.rst
@@ -24,69 +24,11 @@ The serial boot console is available at the debug-header J18 at 115200 Baud and
 * J18.2: RxD
 * J18.3: GND
 
-Fast development
-----------------
+Fastboot
+--------
 
-For development the RIoT-Board bootloader supports 'fastboot'. Refer
-:ref:`fast_development` for Linux and BSP preparation on demand.
+MMC devices are available in fastboot under the following partition names:
 
-RIoT i.MX6S
-~~~~~~~~~~~
-
-The BSP already supports 'fastboot' and prepares the target accordingly.
-The PARTITION names might differ, so you should check first, what PARTITIONs
-are exported.
-
-To get the exported PARTITION names, available via 'fastboot', you can run::
-
-   $ fastboot getvar all
-   (bootloader) version: 0.4
-   (bootloader) bootloader-version: barebox-2023.02.1
-   (bootloader) max-download-size: 8388608
-   (bootloader) partition-size:mmc1: 00000000
-   (bootloader) partition-type:mmc1: unavailable
-   (bootloader) partition-size:mmc2: 00000000
-   (bootloader) partition-type:mmc2: unavailable
-   (bootloader) partition-size:mmc3: e5000000
-   (bootloader) partition-type:mmc3: basic
-   (bootloader) partition-size:ram-kernel: 00000000
-   (bootloader) partition-type:ram-kernel: file
-   (bootloader) partition-size:ram-initramfs: 00000000
-   (bootloader) partition-type:ram-initramfs: file
-   (bootloader) partition-size:ram-oftree: 00000000
-   (bootloader) partition-type:ram-oftree: file
-   (bootloader) partition-size:bbu-emmc: 000e0000
-   (bootloader) partition-type:bbu-emmc: basic
-
-In this example, the PARTITION names are 'mmc1', 'mmc2', 'mmc3', 'ram-kernel',
-'ram-initramfs', 'ram-oftree' and 'bbu-emmc'. In this example the two possible
-SD cards are not plugged in (e.g. "unavailable").
-
-.. note:: You need to restart the fastboot usbgadget, if you probe the SD cards
-          later on.
-
-Just connect the USB OTG connector to your host and run::
-
-   $ fastboot flash ram-kernel platform-v7a/images/linuximage -S 1
-   $ fastboot flash ram-oftree platform-v7a/images/imx6dl-riotboard.dtb -S 1
-   $ fastboot flash ram-initramfs platform-v7a/images/root.cpio.gz -S 1
-   $ fastboot oem exec -- boot ram-fastboot
-
-You can populate local memory like the eMMC as well. But only full memory
-devices and no particular partitions.
-
-If inserted, the regular SD card::
-
-   $ fastboot flash mmc1 platform-v7a/images/riotboard.hdimg -S 1
-
-If inserted, the µSD card::
-
-   $ fastboot flash mmc2 platform-v7a/images/riotboard.hdimg -S 1
-
-The built-in eMMC::
-
-   $ fastboot flash mmc3 platform-v7a/images/riotboard.hdimg -S 1
-
-.. note:: If you have no USB connection to the RIoT i.MX6S, you can use
-          a network connection instead. Just run all the 'fastboot' commands
-          shown above with the additional option '-s udp:<RIoT i.MX6S IP address>'.
+* *mmc1* is the full-size SD Card
+* *mmc2* is the µSD Card
+* *mmc3* is the built-in eMMC
diff --git a/doc/testing.rst b/doc/testing.rst
index ef477cb3cb16..9f1562865b0b 100644
--- a/doc/testing.rst
+++ b/doc/testing.rst
@@ -26,12 +26,12 @@ Since we want to use an initramfs as the kernel's root filesystem, we
 have some requirements to the target system's free memory. The bootloader
 keeps up to 512 MiB of memory to add files to its own RAM disk. The
 512 MiB is valid for a physical memory size of 1 GiB and above. With less
-physical memory it is always 50 % of the available physical memory.
+physical memory it is always 50% of the available physical memory.
 Keep an eye on the size of the initramfs file if it fits onto the
 bootloader's RAM disk. Reduce its size on demand.
 
-Note: the 50 % rule is only valid for the time the bootloader runs. After
-      starting the Linux kernel, 100 % of the physical memory is available.
+Note: the 50% rule is only valid for the time the bootloader runs. After
+      starting the Linux kernel, 100% of the physical memory is available.
 
 Some settings are required to make it work smoothly.
 
@@ -98,7 +98,7 @@ to '/sbin/init via:
 Optimisation
 ------------
 
-Some BPS settings do not make sense regarding used in an initramfs instead
+Some BSP settings do not make sense regarding used in an initramfs instead
 of a persistent target system local memory. For development or testing some
 settings should be changed, to reduce the file sizes and boot time.
 
-- 
2.39.5