Merge branch 'master' into next

5 files changed, 254 insertions, 2 deletions

diff --git a/doc/usage/blkmap.rst b/doc/usage/blkmap.rst
new file mode 100644
index 00000000000..dbfa8e5aad7
--- /dev/null
+++ b/doc/usage/blkmap.rst
@@ -0,0 +1,111 @@
+.. SPDX-License-Identifier: GPL-2.0+
+..
+.. Copyright (c) 2023 Addiva Elektronik
+.. Author: Tobias Waldekranz <[email protected]>
+
+Block Maps (blkmap)
+===================
+
+Block maps are a way of looking at various sources of data through the
+lens of a regular block device. It lets you treat devices that are not
+block devices, like RAM, as if they were. It also lets you export a
+slice of an existing block device, which does not have to correspond
+to a partition boundary, as a new block device.
+
+This is primarily useful because U-Boot's filesystem drivers only
+operate on block devices, so a block map lets you access filesystems
+wherever they might be located.
+
+The implementation is loosely modeled on Linux's "Device Mapper"
+subsystem, see `kernel documentation`_ for more information.
+
+.. _kernel documentation: https://docs.kernel.org/admin-guide/device-mapper/index.html
+
+
+Example: Netbooting an Ext4 Image
+---------------------------------
+
+Say that our system is using an Ext4 filesystem as its rootfs, where
+the kernel is stored in ``/boot``. This image is then typically stored
+in an eMMC partition. In this configuration, we can use something like
+``load mmc 0 ${kernel_addr_r} /boot/Image`` to load the kernel image
+into the expected location, and then boot the system. No problems.
+
+Now imagine that during development, or as a recovery mechanism, we
+want to boot the same type of image by downloading it over the
+network. Getting the image to the target is easy enough:
+
+::
+
+   dhcp ${ramdisk_addr_r} rootfs.ext4
+
+But now we are faced with a predicament: how to we extract the kernel
+image? Block maps to the rescue!
+
+We start by creating a new device:
+
+::
+
+   blkmap create netboot
+
+Before setting up the mapping, we figure out the size of the
+downloaded file, in blocks:
+
+::
+
+   setexpr fileblks ${filesize} + 0x1ff
+   setexpr fileblks ${filesize} / 0x200
+
+Then we can add a mapping to the start of our device, backed by the
+memory at `${loadaddr}`:
+
+::
+
+   blkmap map netboot 0 ${fileblks} mem ${fileaddr}
+
+Now we can access the filesystem via the virtual device:
+
+::
+
+   blkmap get netboot dev devnum
+   load blkmap ${devnum} ${kernel_addr_r} /boot/Image
+
+
+Example: Accessing a filesystem inside an FIT image
+---------------------------------------------------
+
+In this example, an FIT image is stored in an eMMC partition. We would
+like to read the file ``/etc/version``, stored inside a Squashfs image
+in the FIT. Since the Squashfs image is not stored on a partition
+boundary, there is no way of accessing it via ``load mmc ...``.
+
+What we can to instead is to first figure out the offset and size of
+the filesystem:
+
+::
+
+   mmc dev 0
+   mmc read ${loadaddr} 0 0x100
+
+   fdt addr ${loadaddr}
+   fdt get value squashaddr /images/ramdisk data-position
+   fdt get value squashsize /images/ramdisk data-size
+
+   setexpr squashblk  ${squashaddr} / 0x200
+   setexpr squashsize ${squashsize} + 0x1ff
+   setexpr squashsize ${squashsize} / 0x200
+
+Then we can create a block map that maps to that slice of the full
+partition:
+
+::
+
+   blkmap create sq
+   blkmap map sq 0 ${squashsize} linear mmc 0 ${squashblk}
+
+Now we can access the filesystem:
+
+::
+
+   blkmap get sq dev devnum
+   load blkmap ${devnum} ${loadaddr} /etc/version
diff --git a/doc/usage/cmd/coninfo.rst b/doc/usage/cmd/coninfo.rst
new file mode 100644
index 00000000000..f913148c44a
--- /dev/null
+++ b/doc/usage/cmd/coninfo.rst
@@ -0,0 +1,55 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+coninfo command
+===============
+
+Synopsis
+--------
+
+::
+
+    coninfo
+
+Description
+-----------
+
+The coninfo command provides a list of available console input and output
+devices and their assignment as stdin, stdout, stderr console devices.
+
+If CONFIG_SYS_CONSOLE_IS_IN_ENV=y, the assignment is controlled by the
+environment variables stdin, stdout, stderr which contain a comma separated
+list of device names.
+
+Example
+--------
+
+.. code-block:: console
+
+    => coninfo
+    List of available devices
+    |-- pl011@9000000 (IO)
+    |   |-- stdin
+    |   |-- stdout
+    |   |-- stderr
+    |-- serial (IO)
+    |-- usbkbd (I)
+    => setenv stdin pl011@9000000,usbkbd
+    => coninfo
+    List of available devices
+    |-- pl011@9000000 (IO)
+    |   |-- stdin
+    |   |-- stdout
+    |   |-- stderr
+    |-- serial (IO)
+    |-- usbkbd (I)
+    |   |-- stdin
+
+Configuration
+-------------
+
+The coninfo command is only available if CONFIG_CMD_CONSOLE=y.
+
+Return value
+------------
+
+The return value $? is always 0 (true).
diff --git a/doc/usage/cmd/cp.rst b/doc/usage/cmd/cp.rst
new file mode 100644
index 00000000000..12a24e19fee
--- /dev/null
+++ b/doc/usage/cmd/cp.rst
@@ -0,0 +1,83 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+cp command
+==========
+
+Synopsis
+--------
+
+::
+
+    cp source target count
+    cp.b source target count
+    cp.w source target count
+    cp.l source target count
+    cp.q source target count
+
+Description
+-----------
+
+The cp command is used to copy *count* chunks of memory from the *source*
+address to the *target* address. If the *target* address points to NOR flash,
+the flash is programmed.
+
+The number bytes in one chunk is defined by the suffix defaulting to 4 bytes:
+
+====== ==========
+suffix chunk size
+====== ==========
+.b     1 byte
+.w     2 bytes
+.l     4 bytes
+.q     8 bytes
+<none> 4 bytes
+====== ==========
+
+source
+        source address, hexadecimal
+
+target
+        target address, hexadecimal
+
+count
+        number of words to be copied, hexadecimal
+
+Examples
+--------
+
+The example device has a NOR flash where the lower part of the flash is
+protected. We first copy to RAM, then to unprotected flash. Last we try to
+write to protectd flash.
+
+::
+
+    => mtd list
+    List of MTD devices:
+    * nor0
+      - device: flash@0
+      - parent: root_driver
+      - driver: cfi_flash
+      - path: /flash@0
+      - type: NOR flash
+      - block size: 0x20000 bytes
+      - min I/O: 0x1 bytes
+      - 0x000000000000-0x000002000000 : "nor0"
+    => cp.b 4020000 5000000 200000
+    => cp.b 4020000 1e00000 20000
+    Copy to Flash... done
+    => cp.b 4020000 0 20000
+    Copy to Flash... Can't write to protected Flash sectors
+    =>
+
+Configuration
+-------------
+
+The cp command is available if CONFIG_CMD_MEMORY=y. Support for 64 bit words
+(cp.q) depends on CONFIG_MEM_SUPPORT_64BIT_DATA=y. Copying to flash depends on
+CONFIG_MTD_NOR_FLASH=y.
+
+Return value
+------------
+
+The return value $? is set to 0 (true) if the command was successfully,
+1 (false) otherwise.
diff --git a/doc/usage/cmd/mmc.rst b/doc/usage/cmd/mmc.rst
index 55e3f9cf98c..71a0303109c 100644
--- a/doc/usage/cmd/mmc.rst
+++ b/doc/usage/cmd/mmc.rst
@@ -213,10 +213,10 @@ The 'mmc info' command displays device's capabilities:
 The raw data can be read/written via 'mmc read/write' command:
 ::
 
-    => mmc read 0x40000000 0x5000 0x100
+    => mmc read 40000000 5000 100
     MMC read: dev # 0, block # 20480, count 256 ... 256 blocks read: OK
 
-    => mmc write 0x40000000 0x5000 0x10
+    => mmc write 40000000 5000 100
     MMC write: dev # 0, block # 20480, count 256 ... 256 blocks written: OK
 
 The partition list can be shown via 'mmc part' command:
diff --git a/doc/usage/index.rst b/doc/usage/index.rst
index bc85e1d49a9..0fde130a548 100644
--- a/doc/usage/index.rst
+++ b/doc/usage/index.rst
@@ -4,6 +4,7 @@ Use U-Boot
 .. toctree::
    :maxdepth: 1
 
+   blkmap
    dfu
    environment
    fdt_overlays
@@ -38,7 +39,9 @@ Shell commands
    cmd/cbsysinfo
    cmd/cls
    cmd/cmp
+   cmd/coninfo
    cmd/conitrace
+   cmd/cp
    cmd/cyclic
    cmd/dm
    cmd/ebtupdate