[PATCH 04/13] doc: phytec: k3: Add a common part for Environment and EFI Capsules

[Wadim Egorov]

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 at phytec.de>
---
 board/phytec/phycore_am62x/MAINTAINERS |  1 +
 doc/board/phytec/k3-common.rst         | 67 ++++++++++++++++++++++++++
 doc/board/phytec/phycore-am62ax.rst    |  2 +
 doc/board/phytec/phycore-am62x.rst     |  2 +
 doc/board/phytec/phycore-am64x.rst     |  2 +
 5 files changed, 74 insertions(+)
 create mode 100644 doc/board/phytec/k3-common.rst

diff --git a/board/phytec/phycore_am62x/MAINTAINERS b/board/phytec/phycore_am62x/MAINTAINERS
index 670c7473481..8f2b8069ad4 100644
--- 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
index 00000000000..ffb50b51ad6
--- /dev/null
+++ b/doc/board/phytec/k3-common.rst
@@ -0,0 +1,67 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. sectionauthor:: Wadim Egorov <w.egorov at 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 0c5b4814fc2..e1f741011e7 100644
--- 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 56c1fd8354b..36315b49931 100644
--- 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 01c42b90660..71f1fd7b404 100644
--- 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
 -------------------
 
-- 
2.34.1