cmd: add support for a new "extension" command

This patch adds a new "extension" command, which aims at detecting
extension boards connected to the hardware platform, and apply the
Device Tree overlays that describe the hardware present on those
extension boards.

In order to enable this mechanism, board-specific code must implement
the extension_board_scan() function that fills in a linked list of
"struct extension", each describing one extension board. In addition,
the board-specific code must select the SUPPORT_EXTENSION_SCAN Kconfig
boolean.

Based on this:

 - "extension scan" makes the generic code call the board-specific
   extension_board_scan() function to retrieve the list of detected
   extension boards.

 - "extension list" allows to list the detected extension boards.

 - "extension apply <number>|all" allows to apply the Device Tree
   overlay(s) corresponding to one, or all, extension boards

The latter requires two environment variables to exist and set one variable
to run:

 - extension_overlay_addr: the RAM address where to load the Device
   Tree overlays

 - extension_overlay_cmd: the U-Boot command to load one overlay.
   Indeed, the location and mechanism to load DT overlays is very setup
   specific.

 - extension_overlay_name: set by the command: the name of the DT which
   will be load during the execution.

When calling the command described in the extension_overlay_cmd
variable, the variable extension_overlay_name will be defined. So a
typical extension_overlay_cmd will look like this:

  extension_overlay_cmd=load mmc 0:1 $extension_overlay_addr /boot/$extension_overlay_name

Here is an example on how to use it:
=> run loadfdt
=> fdt addr $fdtaddr
=> setenv extension_overlay_addr 0x1000
=> setenv extension_overlay_cmd 'load mmc 0:1 ${extension_overlay_addr} /boot/${extension_overlay_name}'
=> extension scan
Found 1 extension board(s).
=> extension apply 0
519 bytes read in 3 ms (168.9 KiB/s)

Signed-off-by: Kory Maincent <kory.maincent@bootlin.com>
Reviewed-by: Maxime Ripard <maxime@cerno.tech>

1 files changed, 111 insertions, 0 deletions

diff --git a/doc/usage/extension.rst b/doc/usage/extension.rst
new file mode 100644
index 0000000000..2b88398b18
--- /dev/null
+++ b/doc/usage/extension.rst
@@ -0,0 +1,111 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright 2021, Kory Maincent <kory.maincent@bootlin.com>
+
+U-Boot extension board usage (CONFIG_EXTENSION)
+===============================================
+
+Synopsis
+--------
+
+::
+
+    extension scan
+    extension list
+    extension apply <extension number|all>
+
+Description
+-----------
+
+The "extension" command proposes a generic U-Boot mechanism to detect
+extension boards connected to the HW platform, and apply the appropriate
+Device Tree overlays depending on the detected extension boards.
+
+The "extension" command comes with three sub-commands:
+
+ - "extension scan" makes the generic code call the board-specific
+   extension_board_scan() function to retrieve the list of detected
+   extension boards.
+
+ - "extension list" allows to list the detected extension boards.
+
+ - "extension apply <number>|all" allows to apply the Device Tree
+   overlay(s) corresponding to one, or all, extension boards
+
+The latter requires two environment variables to exist:
+
+ - extension_overlay_addr: the RAM address where to load the Device
+   Tree overlays
+
+ - extension_overlay_cmd: the U-Boot command to load one overlay.
+   Indeed, the location and mechanism to load DT overlays is very setup
+   specific.
+
+In order to enable this mechanism, board-specific code must implement
+the extension_board_scan() function that fills in a linked list of
+"struct extension", each describing one extension board. In addition,
+the board-specific code must select the SUPPORT_EXTENSION_SCAN Kconfig
+boolean.
+
+Usage example
+-------------
+
+1. Make sure your devicetree is loaded and set as the working fdt tree.
+
+::
+
+    => run loadfdt
+    => fdt addr $fdtaddr
+
+2. Prepare the environment variables
+
+::
+
+    => setenv extension_overlay_addr 0x88080000
+    => setenv extension_overlay_cmd 'load mmc 0:1 ${extension_overlay_addr} /boot/${extension_overlay_name}'
+
+3. Detect the plugged extension board
+
+::
+
+    => extension scan
+
+4. List the plugged extension board information and the devicetree
+   overlay name
+
+::
+
+    => extension list
+
+5. Apply the appropriate devicetree overlay
+
+For apply the selected overlay:
+
+::
+
+    => extension apply 0
+
+For apply all the overlays:
+
+::
+
+    => extension apply all
+
+Simple extension_board_scan function example
+--------------------------------------------
+
+.. code-block:: c
+
+    int extension_board_scan(struct list_head *extension_list)
+    {
+        struct extension *extension;
+
+        extension = calloc(1, sizeof(struct extension));
+        snprintf(extension->overlay, sizeof(extension->overlay), "overlay.dtbo");
+        snprintf(extension->name, sizeof(extension->name), "extension board");
+        snprintf(extension->owner, sizeof(extension->owner), "sandbox");
+        snprintf(extension->version, sizeof(extension->version), "1.1");
+        snprintf(extension->other, sizeof(extension->other), "Extension board information");
+        list_add_tail(&extension->list, extension_list);
+
+        return 1;
+    }