Merge tag 'doc-2021-04-rc1' of https://gitlab.denx.de/u-boot/custodians/u-boot-efi

Pull request for documentation tag doc-2021-04-rc1

* document man-page base command
* move README.fdt-overlays to HTML documentation
* add synopsis for pstore command

doc/board/freescale/b4860qds.rst

@@ -134,7 +134,7 @@ B4860QDS Default Settings
 -------------------------
 
 Switch Settings
----------------
+^^^^^^^^^^^^^^^
 
 .. code-block:: none
 
@@ -167,7 +167,7 @@ B4420QDS Default Settings
 -------------------------
 
 Switch Settings
----------------
+^^^^^^^^^^^^^^^
 
 .. code-block:: none
 

doc/board/sifive/fu540.rst

@@ -12,6 +12,7 @@ of running Linux.
 
 Mainline support
 ----------------
+
 The support for following drivers are already enabled:
 
 1. SiFive UART Driver.
@@ -24,7 +25,7 @@ Booting from MMC using FSBL
 ---------------------------
 
 Building
---------
+~~~~~~~~
 
 1. Add the RISC-V toolchain to your PATH.
 2. Setup ARCH & cross compilation environment variable:
@@ -37,7 +38,7 @@ Building
 4. make
 
 Flashing
---------
+~~~~~~~~
 
 The current U-Boot port is supported in S-mode only and loaded from DRAM.
 
@@ -63,11 +64,12 @@ copied to the first partition of the sdcard.
     sudo dd if=<prior_stage_firmware_binary> of=/dev/disk2s1 bs=1024
 
 Booting
--------
+~~~~~~~
+
 Once you plugin the sdcard and power up, you should see the U-Boot prompt.
 
 Sample boot log from HiFive Unleashed board
--------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. code-block:: none
 
@@ -417,7 +419,7 @@ Booting from MMC using U-Boot SPL
 ---------------------------------
 
 Building
---------
+~~~~~~~~
 
 Before building U-Boot SPL, OpenSBI must be built first. OpenSBI can be
 cloned and built for FU540 as below:
@@ -441,7 +443,7 @@ This will generate spl/u-boot-spl.bin and FIT image (u-boot.itb)
 
 
 Flashing
---------
+~~~~~~~~
 
 ZSBL loads the U-Boot SPL (u-boot-spl.bin) from a partition with GUID type
 5B193300-FC78-40CD-8002-E86C45580B47
@@ -471,11 +473,12 @@ Program the SD card
 	sudo dd if=u-boot.itb of=/dev/sda seek=2082
 
 Booting
--------
+~~~~~~~
+
 Once you plugin the sdcard and power up, you should see the U-Boot prompt.
 
 Sample boot log from HiFive Unleashed board
--------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. code-block:: none
 

doc/usage/base.rst

+.. SPDX-License-Identifier: GPL-2.0+
+
+base command
+============
+
+Synopsis
+--------
+
+::
+
+    base [address]
+
+Description
+-----------
+
+The *base* command sets or displays the address offset used by the memory
+commands *cmp, cp, md, mdc, mm, ms, mw, mwc*.
+
+All other commands ignore the address defined by *base*.
+
+address
+    new base address as hexadecimal number. If no value is provided, the current
+    value is displayed.

doc/README.fdt-overlays → doc/usage/fdt_overlays.rst

-U-Boot FDT Overlay usage
-=============================================
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright (c) 2017, Pantelis Antoniou <pantelis.antoniou@konsulko.com>
 
-Overlays Syntax
----------------
+Device Tree Overlays
+====================
 
-Overlays require slightly different syntax compared to traditional overlays.
-Please refer to dt-object-internal.txt in the dtc sources for information
-regarding the internal format of overlays:
+Overlay Syntax
+--------------
+
+Device-tree overlays require a slightly different syntax compared to traditional
+device-trees. Please refer to dt-object-internal.txt in the device-tree compiler
+sources for information regarding the internal format of overlays:
 https://git.kernel.org/pub/scm/utils/dtc/dtc.git/tree/Documentation/dt-object-internal.txt
 
 Building Overlays
 -----------------
 
-In a nutshell overlays provides a means to manipulate a symbol a previous dtb
-or overlay has defined. It requires both the base and all the overlays
-to be compiled with the -@ command line switch so that symbol information is
-included.
+In a nutshell overlays provides a means to manipulate a symbol a previous
+device-tree or device-tree overlay has defined. It requires both the base
+device-tree and all the overlays to be compiled with the *-@* command line
+switch of the device-tree compiler so that symbol information is included.
 
-Note support for -@ option can only be found in dtc version 1.4.4 or newer.
-Only version 4.14 or higher of the Linux kernel includes a built in version
-of dtc that meets this requirement.
+Note
+    Support for *-@* option can only be found in dtc version 1.4.4 or newer.
+    Only version 4.14 or higher of the Linux kernel includes a built in version
+    of dtc that meets this requirement.
 
-Building an overlay follows the same process as building a traditional dtb.
+Building a binary device-tree overlay follows the same process as building a
+traditional binary device-tree. For example:
 
-For example:
+**base.dts**
 
-base.dts
---------
+::
 
 	/dts-v1/;
 	/ {
@@ -35,10 +39,13 @@ base.dts
 		};
 	};
 
+.. code-block:: console
+
 	$ dtc -@ -I dts -O dtb -o base.dtb base.dts
 
-bar.dts
--------
+**overlay.dts**
+
+::
 
 	/dts-v1/;
 	/plugin/;
@@ -54,16 +61,19 @@ bar.dts
 		};
 	};
 
-	$ dtc -@ -I dts -O dtb -o bar.dtb bar.dts
+.. code-block:: console
+
+	$ dtc -@ -I dts -O dtb -o overlay.dtbo overlay.dts
 
-Ways to Utilize Overlays in U-boot
+Ways to Utilize Overlays in U-Boot
 ----------------------------------
 
-There are two ways to apply overlays in U-boot.
-1. Include and define overlays within a FIT image and have overlays
-   automatically applied.
+There are two ways to apply overlays in U-Boot.
 
-2. Manually load and apply overlays
+* Include and define overlays within a FIT image and have overlays
+  automatically applied.
+
+* Manually load and apply overlays
 
 The remainder of this document will discuss using overlays via the manual
 approach. For information on using overlays as part of a FIT image please see:
@@ -73,42 +83,52 @@ Manually Loading and Applying Overlays
 --------------------------------------
 
 1. Figure out where to place both the base device tree blob and the
-overlay. Make sure you have enough space to grow the base tree without
-overlapping anything.
+   overlay. Make sure you have enough space to grow the base tree without
+   overlapping anything.
+
+::
+
+    => setenv fdtaddr 0x87f00000
+    => setenv fdtovaddr 0x87fc0000
 
-=> setenv fdtaddr 0x87f00000
-=> setenv fdtovaddr 0x87fc0000
+2. Load the base binary device-tree and the binary device-tree overlay.
 
-2. Load the base blob and overlay blobs
+::
 
-=> load ${devtype} ${bootpart} ${fdtaddr} ${bootdir}/base.dtb
-=> load ${devtype} ${bootpart} ${fdtovaddr} ${bootdir}/overlay.dtb
+    => load ${devtype} ${bootpart} ${fdtaddr} ${bootdir}/base.dtb
+    => load ${devtype} ${bootpart} ${fdtovaddr} ${bootdir}/overlay.dtbo
 
-3. Set it as the working fdt tree.
+3. Set the base binary device-tree as the working fdt tree.
 
-=> fdtaddr $fdtaddr
+::
 
-4. Grow it enough so it can 'fit' all the applied overlays
+    => fdtaddr $fdtaddr
 
-=> fdt resize 8192
+4. Grow it enough so it can encompass all applied overlays
+
+::
+
+    => fdt resize 8192
 
 5. You are now ready to apply the overlay.
 
-=> fdt apply $fdtovaddr
+::
+
+    => fdt apply $fdtovaddr
 
 6. Boot system like you would do with a traditional dtb.
 
 For bootm:
 
-=> bootm ${kerneladdr} - ${fdtaddr}
+::
+
+    => bootm ${kerneladdr} - ${fdtaddr}
 
 For bootz:
 
-=> bootz ${kerneladdr} - ${fdtaddr}
+::
+
+    => bootz ${kerneladdr} - ${fdtaddr}
 
 Please note that in case of an error, both the base and overlays are going
 to be invalidated, so keep copies to avoid reloading.
-
-Pantelis Antoniou
-pantelis.antoniou@konsulko.com
-11/7/2017

doc/usage/index.rst

@@ -2,7 +2,9 @@ Use U-Boot
 ==========
 
 .. toctree::
+   :maxdepth: 1
 
+   fdt_overlays
    netconsole
 
 Shell commands
@@ -11,6 +13,7 @@ Shell commands
 .. toctree::
    :maxdepth: 1
 
+   base
    bootefi
    bootmenu
    button

doc/usage/pstore.rst

 .. SPDX-License-Identifier: GPL-2.0+
 
-PStore command
+pstore command
 ==============
 
+Synopsis
+--------
+
+::
+
+    pstore set <addr> <len> [record-size] [console-size] [ftrace-size] [pmsg_size] [ecc-size]
+    pstore display [record-type] [nb]
+    pstore save <interface> <dev[:part]> <directory-path>
+
 Design
 ------