[PATCH v2 29/29] Documentation: boards: imx: add FlexSPI sub-section

[Marco Felsch]

Document the FlexSPI image and boot feature to make it easier for users
to enable the support. Also document the image layout since it became
more complex with FlexSPI and HAB, so a detailed overview is very
helpful.

Signed-off-by: Marco Felsch <m.felsch at pengutronix.de>
---
Changelog:
v2:
- Adapt wording to reflect new CONFIG_HABV4_QSPI config
- v1-link: https://lore.barebox.org/barebox/20231010143314.2031253-1-m.felsch@pengutronix.de/T/#t

 Documentation/boards/imx.rst | 80 ++++++++++++++++++++++++++++++++++++
 1 file changed, 80 insertions(+)

diff --git a/Documentation/boards/imx.rst b/Documentation/boards/imx.rst
index a8f014dd1b91..2a5168190620 100644
--- a/Documentation/boards/imx.rst
+++ b/Documentation/boards/imx.rst
@@ -394,6 +394,86 @@ with only the image name as argument:
 
   scripts/imx/imx-usb-loader images/barebox-freescale-imx51-babbage.img
 
+FlexSPI Boot
+^^^^^^^^^^^^
+
+FlexSPI boot is currently supported on: i.MX8MM, i.MX8MN and i.MX8MP.
+
+To generate FlexSPI/QSPI image(s) the board flash header file must specify:
+``flexspi_ivtofs`` and ``flexspi_fcfbofs``.
+
+It is recommended to do this via the ``include/mach/imx/flexspi-imx8m*-cfg.h``
+header files.
+
+.. code-block:: none
+
+  #include <mach/imx/flexspi-imx8mp-cfg.h>
+
+There are two different headers, one for the i.MX8MM and one for the i.MX8MP/N.
+It's important to use the correct one because the BootROM expects the IVT and
+flash configuration block (FCB) on different offsets.
+
+Barebox doesn't generate a separate FlexSPI image instead the same image used
+for SD/MMC/USB is extended to support FlexSPI boot. This is done by adding a 2nd
+IVT header and the required FCB at the required boot offsets.
+
+Barebox also support `High Assurance Boot`_ images for QSPI boot mediums. This
+feature must be enabled via the ``CONFIG_HABV4_QSPI`` option. The below figures
+show a fully featured MMC/SD/USB/FlexSPI image with enabled HAB support for the
+i.MX8M family.
+
+i.MX8MM layout::
+
+                 0x0 +------------------------------------------+
+                     | Barebox Header                           |
+          header_gap +------------------------------------------+
+                     | FlexSPI Flash Configuration Block (FCFB) |
+  header_gap + 0x400 +------------------------------------------+                            ---
+                     | i.MX MMC/SD/USB IVT Header               |                             |
+                     | Boot Data                                +--.                          |
+                     | CSF Pointer                              +--|--.                       |
+ header_gap + 0x1000 +------------------------------------------+  |  |     ---               |
+                     | i.MX FlexSPI IVT Header                  |  |  |      |                | Signed Area
+                     | Boot Data                                +--+  |      |                |  MMC/SD/
+                     | CSF Pointer                              +--|--|--.   | Signed Area    |    USB
+ header_gap + 0x2000 +------------------------------------------+  |  |  |   |  FlexSPI       |
+                     | Barebox Prebootloader (PBL)              |<-´  |  |   |                |
+                     | Piggydata Hash (SHA256)                  |     |  |   |                |
+                     +------------------------------------------+     |  |  ---              ---
+                     | Command Sequence File (CSF) Slot-0       |<----´  |
+                     +------------------------------------------+        |
+                     | Command Sequence File (CSF) Slot-1       |<-------´
+                     +------------------------------------------+           ---
+                     | Piggydata (Main Barebox Binary)          |            | Hashed Area
+                     +------------------------------------------+           ---
+
+i.MX8MP/N layout::
+
+                 0x0 +------------------------------------------+
+                     | Barebox Header                           |
+          header_gap +------------------------------------------+                            ---
+                     | i.MX MMC/SD/USB IVT Header               |                             |
+                     | Boot Data                                +--.                          |
+                     | CSF Pointer                              +--|--.                       |
+  header_gap + 0x400 +------------------------------------------+  |  |                       |
+                     | FlexSPI Flash Configuration Block (FCFB) |  |  |                       | Signed Area
+ header_gap + 0x1000 +------------------------------------------+  |  |     ---               |  MMC/SD/
+                     | i.MX FlexSPI IVT Header                  |  |  |      |                |    USB
+                     | Boot Data                                +--+  |      |                |
+                     | CSF Pointer                              +--|--|--.   | Signed Area    |
+ header_gap + 0x2000 +------------------------------------------+  |  |  |   |  FlexSPI       |
+                     | Barebox Prebootloader (PBL)              |<-´  |  |   |                |
+                     | Piggydata Hash (SHA256)                  |     |  |   |                |
+                     +------------------------------------------+     |  |  ---              ---
+                     | Command Sequence File (CSF) Slot-0       |<----´  |
+                     +------------------------------------------+        |
+                     | Command Sequence File (CSF) Slot-1       |<-------´
+                     +------------------------------------------+           ---
+                     | Piggydata (Main Barebox Binary)          |            | Hashed Area
+                     +------------------------------------------+           ---
+
+At the moment ``header_gap`` is always 32K for all supported devices.
+
 External Boot Mode
 ------------------
 
-- 
2.39.2