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

4 files changed, 170 insertions, 1 deletions

diff --git a/doc/usage/base.rst b/doc/usage/base.rst
new file mode 100644
index 0000000..db9cd4d
--- /dev/null
+++ b/doc/usage/base.rst
@@ -0,0 +1,23 @@
+.. 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.
diff --git a/doc/usage/fdt_overlays.rst b/doc/usage/fdt_overlays.rst
new file mode 100644
index 0000000..ea39713
--- /dev/null
+++ b/doc/usage/fdt_overlays.rst
@@ -0,0 +1,134 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright (c) 2017, Pantelis Antoniou <pantelis.antoniou@konsulko.com>
+
+Device Tree 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
+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.
+
+Building a binary device-tree overlay follows the same process as building a
+traditional binary device-tree. For example:
+
+**base.dts**
+
+::
+
+	/dts-v1/;
+	/ {
+		foo: foonode {
+			foo-property;
+		};
+	};
+
+.. code-block:: console
+
+	$ dtc -@ -I dts -O dtb -o base.dtb base.dts
+
+**overlay.dts**
+
+::
+
+	/dts-v1/;
+	/plugin/;
+	/ {
+		fragment@1 {
+			target = <&foo>;
+			__overlay__ {
+				overlay-1-property;
+				bar: barnode {
+					bar-property;
+				};
+			};
+		};
+	};
+
+.. code-block:: console
+
+	$ dtc -@ -I dts -O dtb -o overlay.dtbo overlay.dts
+
+Ways to Utilize Overlays in U-Boot
+----------------------------------
+
+There are two ways to apply overlays in U-Boot.
+
+* 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:
+doc/uImage.FIT/overlay-fdt-boot.txt
+
+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.
+
+::
+
+    => setenv fdtaddr 0x87f00000
+    => setenv fdtovaddr 0x87fc0000
+
+2. Load the base binary device-tree and the binary device-tree overlay.
+
+::
+
+    => load ${devtype} ${bootpart} ${fdtaddr} ${bootdir}/base.dtb
+    => load ${devtype} ${bootpart} ${fdtovaddr} ${bootdir}/overlay.dtbo
+
+3. Set the base binary device-tree as the working fdt tree.
+
+::
+
+    => fdtaddr $fdtaddr
+
+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
+
+6. Boot system like you would do with a traditional dtb.
+
+For bootm:
+
+::
+
+    => bootm ${kerneladdr} - ${fdtaddr}
+
+For bootz:
+
+::
+
+    => 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.
diff --git a/doc/usage/index.rst b/doc/usage/index.rst
index 5869fba..6def250 100644
--- a/doc/usage/index.rst
+++ b/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
diff --git a/doc/usage/pstore.rst b/doc/usage/pstore.rst
index 8c4e527..1c83745 100644
--- a/doc/usage/pstore.rst
+++ b/doc/usage/pstore.rst
@@ -1,8 +1,17 @@
 .. 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
 ------