doc: phytec: k3: Add a common part for Environment and EFI Capsules

Provide a common part for our K3 based boards including general details
about environment handling and EFI capsule updates.

Signed-off-by: Wadim Egorov <w.egorov@phytec.de>

diff --git a/board/phytec/phycore_am62x/MAINTAINERS b/board/phytec/phycore_am62x/MAINTAINERS
index 670c74734814e36e74a72f238682aaa61f05d2ea..8f2b8069ad4619028b91e5f22bea6a885af823b2 100644 (file)
--- a/board/phytec/phycore_am62x/MAINTAINERS
+++ b/board/phytec/phycore_am62x/MAINTAINERS
@@ -12,4 +12,5 @@ F:    configs/phycore_am62x_r5_defconfig
 F:     configs/phycore_am62x_r5_usbdfu_defconfig
 F:     include/configs/phycore_am62x.h
 F:     doc/board/phytec/phycore-am62x.rst
+F:     doc/board/phytec/k3-common.rst
 F:     board/phytec/common/k3

diff --git a/doc/board/phytec/k3-common.rst b/doc/board/phytec/k3-common.rst
new file mode 100644 (file)
index 0000000..ffb50b5
--- /dev/null
+++ b/doc/board/phytec/k3-common.rst
@@ -0,0 +1,67 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. sectionauthor:: Wadim Egorov <w.egorov@phytec.de>
+
+Environment
+-----------
+
+
+Variables Set at Runtime
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+At runtime the `boot` environment variable is set to reflect the source from which the board was booted. This ensures that the correct boot path is followed for further system initialization.
+
+
+Environment Storage Selection
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The environment is loaded from a storage location based on the boot device:
+
+* If booted from eMMC or uSD card, the environment is retrieved from FAT or a fixed offset if configured.
+
+* If booted from SPI, the environment is retrieved from SPI flash if enabled.
+
+For all other boot devices, the environment is not stored persistently (ENVL_NOWHERE).
+
+
+Saving the Environment
+~~~~~~~~~~~~~~~~~~~~~~
+
+The `saveenv` command will store the environment on the same device the board was booted from, ensuring consistency between boot sources and stored configurations.
+
+
+Capsule Updates
+---------------
+
+Capsules for each of these binaries are automatically generated as part of the build process and are named `<binary>-capsule.bin`. For example, the capsule for `u-boot.img` is named `uboot-capsule.bin`.
+
+
+
+Performing an Update
+~~~~~~~~~~~~~~~~~~~~
+
+Each board has a dynamically generated GUID. To retrieve it, run:
+
+.. code-block::
+
+ efidebug capsule esrt
+
+To update the firmware, follow these steps on the board. Ensure the capsule binaries are available on a uSD card.
+
+.. code-block:: bash
+
+ load mmc 1:1 $loadaddr tiboot3-capsule.bin
+ efidebug capsule update $loadaddr
+
+ load mmc 1:1 $loadaddr tispl-capsule.bin
+ efidebug capsule update $loadaddr
+
+ load mmc 1:1 $loadaddr uboot-capsule.bin
+ efidebug capsule update $loadaddr
+
+These commands load the capsule binaries into memory and trigger the EFI capsule update process.
+
+
+Important Notes
+~~~~~~~~~~~~~~~
+
+The updates are applied to the boot device from which the board is currently running. For eMMC, updates are always applied to the first boot partition. Capsule updates can be performed on eMMC, OSPI NOR, or a uSD card, depending on the boot device. For any additional configuration or troubleshooting, refer to :ref:`uefi_capsule_update_ref`.

diff --git a/doc/board/phytec/phycore-am62ax.rst b/doc/board/phytec/phycore-am62ax.rst
index 0c5b4814fc2e27d510de0110487a5ef487f239bb..e1f741011e7e527acfc4ed331b24130c58bf040c 100644 (file)
--- a/doc/board/phytec/phycore-am62ax.rst
+++ b/doc/board/phytec/phycore-am62ax.rst
@@ -176,6 +176,8 @@ Boot switches should be changed with power off.
      - 11011100
      - 00000000
 
+.. include:: k3-common.rst
+
 Further Information
 -------------------
 

diff --git a/doc/board/phytec/phycore-am62x.rst b/doc/board/phytec/phycore-am62x.rst
index 56c1fd8354b4fa60eb030dc3c131fe993c1f8cee..36315b4993103db0d45dc0982f6f0cc49049c95b 100644 (file)
--- a/doc/board/phytec/phycore-am62x.rst
+++ b/doc/board/phytec/phycore-am62x.rst
@@ -176,6 +176,8 @@ Boot switches should be changed with power off.
      - 11001010
      - 00100000
 
+.. include:: k3-common.rst
+
 Further Information
 -------------------
 

diff --git a/doc/board/phytec/phycore-am64x.rst b/doc/board/phytec/phycore-am64x.rst
index 01c42b9066078c3bd72456c40a2c1511adc0fe11..71f1fd7b4046a3c01361a83686a1242e22c834d9 100644 (file)
--- a/doc/board/phytec/phycore-am64x.rst
+++ b/doc/board/phytec/phycore-am64x.rst
@@ -175,6 +175,8 @@ Boot switches should be changed with power off.
      - 11011100
      - 00000000
 
+.. include:: k3-common.rst
+
 Further Information
 -------------------