From: Heinrich Schuchardt <heinrich.schuchardt@canonical.com>
Date: Sat, 18 Oct 2025 11:07:44 +0000 (+0200)
Subject: doc: separate read and write command documentation
X-Git-Tag: v2026.01-rc1~3^2~15
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=3cb97f929338f9373de6b41c4f2010357dd20778;p=thirdparty%2Fu-boot.git

doc: separate read and write command documentation

* Avoid two step navigation to get to the description of the write command.
* Add missing index entries
* Correct formatting of the examples.
* Describe configuration and return value.

Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt@canonical.com>
---

diff --git a/doc/usage/cmd/read.rst b/doc/usage/cmd/read.rst
index 840846728fc..9045a7e7e31 100644
--- a/doc/usage/cmd/read.rst
+++ b/doc/usage/cmd/read.rst
@@ -1,7 +1,10 @@
-.. SPDX-License-Identifier: GPL-2.0-or-later:
+.. SPDX-License-Identifier: GPL-2.0-or-later
 
-read and write commands
-=======================
+.. index::
+   single: read (command)
+
+read command
+============
 
 Synopsis
 --------
@@ -9,14 +12,12 @@ Synopsis
 ::
 
     read <interface> <dev[:part|#partname]> <addr> <blk#> <cnt>
-    write <interface> <dev[:part|#partname]> <addr> <blk#> <cnt>
 
-The read and write commands can be used for raw access to data in
-block devices (or partitions therein), i.e. without going through a
-file system.
+Description
+-----------
 
-read
-----
+The read command can be used for raw reading data from a block device
+(or a partition therein), i.e. without going through a file system.
 
 The block device is specified using the <interface> (e.g. "mmc") and
 <dev> parameters. If the block device has a partition table, one can
@@ -25,20 +26,24 @@ partition name (using the #partname syntax). The command then reads
 the <cnt> blocks of data starting at block number <blk#> of the given
 device/partition to the memory address <addr>.
 
-write
------
-
-The write command is completely equivalent to the read command, except
-of course that the transfer direction is reversed.
-
 Examples
 --------
 
+.. code-block:: bash
+
     # Read 2 MiB from partition 3 of mmc device 2 to $loadaddr
     read mmc 2.3 $loadaddr 0 0x1000
 
     # Read 16 MiB from the partition named 'kernel' of mmc device 1 to $loadaddr
     read mmc 1#kernel $loadaddr 0 0x8000
 
-    # Write to the third sector of the partition named 'bootdata' of mmc device 0
-    write mmc 0#bootdata $loadaddr 2 1
+Configuration
+-------------
+
+The read command is only available if CONFIG_CMD_READ=y.
+
+Return value
+------------
+
+The command sets the return value $? to 0 (true) on success or to 1 (false) in
+case of an error.
diff --git a/doc/usage/cmd/write.rst b/doc/usage/cmd/write.rst
index f42dc003dd4..737eb28c069 100644
--- a/doc/usage/cmd/write.rst
+++ b/doc/usage/cmd/write.rst
@@ -1,4 +1,4 @@
-.. SPDX-License-Identifier: GPL-2.0-or-later:
+.. SPDX-License-Identifier: GPL-2.0-or-later
 
 .. index::
    single: write (command)
@@ -6,4 +6,41 @@
 write command
 =============
 
-See :doc:`read`.
+Synopsis
+--------
+
+::
+
+    write <interface> <dev[:part|#partname]> <addr> <blk#> <cnt>
+
+Description
+-----------
+
+The write command can be used for raw writing data to a block device
+(or partition therein), i.e. without going through a file system.
+
+The block device is specified using the <interface> (e.g. "mmc") and
+<dev> parameters. If the block device has a partition table, one can
+optionally specify a partition number (using the :part syntax) or
+partition name (using the #partname syntax). The command then reads
+the <cnt> blocks of data starting at block number <blk#> of the given
+device/partition to the memory address <addr>.
+
+Examples
+--------
+
+.. code-block:: bash
+
+    # Write to the third sector of the partition named 'bootdata' of mmc device 0
+    write mmc 0#bootdata $loadaddr 2 1
+
+Configuration
+-------------
+
+The write command is only available if CONFIG_CMD_WRITE=y.
+
+Return value
+------------
+
+The command sets the return value $? to 0 (true) on success and to 1 (false) in
+case of an error.