1 files changed, 164 insertions, 0 deletions
diff --git a/doc/board/siemens/iot2050.rst b/doc/board/siemens/iot2050.rst
new file mode 100644
index 00000000000..ee3c5c95846
--- /dev/null
+++ b/doc/board/siemens/iot2050.rst
@@ -0,0 +1,164 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. sectionauthor:: Jan Kiszka <jan.kiszka@siemens.com>
+
+SIMATIC IOT2050 BASIC and ADVANCED
+==================================
+
+The SIMATIC IOT2050 is an open industrial IoT gateway that is using the TI
+AM6528 GP (Basic variant) or the AM6548 HS (Advanced variant). The Advanced
+variant is prepared for secure boot. M.2 Variant also uses the AM6548 HS.
+Instead of a MiniPCI connector, it comes with two M.2 connectors and can
+support 5G/WIFI/BT applications or connect an SSD.
+
+The IOT2050 starts only from OSPI. It loads a Siemens-provided bootloader
+called SE-Boot for the MCU domain (R5F cores), then hands over to ATF and
+OP-TEE, before booting U-Boot on the A53 cores. This describes how to build all
+open artifacts into a flashable image for the OSPI flash. The flash image will
+work on both variants.
+
+Dependencies
+------------
+
+ATF:    Upstream release 2.4 or newer
+OP-TEE: Upstream release 3.10.0 or newer
+
+Binary dependencies can be found in
+https://github.com/siemens/meta-iot2050/tree/master/recipes-bsp/u-boot/files/prebuild.
+The following binaries from that source need to be present in the build folder:
+
+ - seboot_pg1.bin
+ - seboot_pg2.bin
+
+When using the watchdog, a related firmware for the R5 core(s) is needed, e.g.
+https://github.com/siemens/k3-rti-wdt. The name and location of the image is
+configured via CONFIG_WDT_K3_RTI_FW_FILE.
+
+For building an image containing the OTP key provisioning data, below binary
+needs to be present in the build folder:
+
+ - otpcmd.bin
+
+Regarding how to generating this otpcmd.bin, please refer to:
+https://github.com/siemens/meta-iot2050/tree/master/recipes-bsp/secure-boot-otp-provisioning/files/make-otpcmd.sh
+
+Building
+--------
+
+Make sure that CROSS_COMPILE is set appropriately:
+
+.. code-block:: text
+
+ $ export CROSS_COMPILE=aarch64-linux-gnu-
+
+ATF:
+
+.. code-block:: text
+
+ $ make PLAT=k3 SPD=opteed K3_USART=1
+
+OP-TEE:
+
+.. code-block:: text
+
+ $ make PLATFORM=k3-am65x CFG_ARM64_core=y CFG_TEE_CORE_LOG_LEVEL=2 CFG_CONSOLE_UART=1 CFG_USER_TA_TARGETS="ta_arm64"
+
+U-Boot:
+
+.. code-block:: text
+
+ $ export BL31=/path/to/bl31.bin
+ $ export TEE=/path/to/tee-raw.bin
+ $ make iot2050_defconfig
+
+ $ make
+
+This will generate two different flash images: flash-p1.bin that targets the
+first generation of IOT2050 devices and flash-pg2.bin that runs on PG2
+including M.2 devices.
+
+Flashing
+--------
+
+Via U-Boot:
+
+.. code-block:: text
+
+ IOT2050> sf probe
+ IOT2050> load mmc 0:1 $loadaddr /path/to/flash-pgX.bin
+ IOT2050> sf update $loadaddr 0x0 $filesize
+
+Via external programmer Dediprog SF100 or SF600:
+
+.. code-block:: text
+
+ $ dpcmd --vcc 2 -v -u flash-pgX.bin
+
+Signing (optional)
+------------------
+
+To enable verified boot for the firmware artifacts after the Siemens-managed
+first-stage loader (seboot_pgX.bin), the following steps need to be taken
+before and after the build:
+
+Generate dtsi holding the public key
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: text
+
+ tools/key2dtsi.py -c -s key.pem public-key.dtsi
+
+This will be used to embed the public key into U-Boot SPL and main so that each
+step can validate signatures of the succeeding one.
+
+Adjust U-Boot configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Enabled at least the following options in U-Boot:
+
+.. code-block:: text
+
+ CONFIG_SPL_FIT_SIGNATURE=y
+ CONFIG_DEVICE_TREE_INCLUDES="/path/to/public-key.dtsi"
+ CONFIG_RSA=y
+
+Note that there are more configuration changes needed in order to lock-down
+the command line and the boot process of U-Boot for secure scenarios. These are
+not in scope here.
+
+Build U-Boot
+^^^^^^^^^^^^
+
+See related section above.
+
+Sign flash-pgX.bin
+^^^^^^^^^^^^^^^^^^
+
+In the build folder still containing artifacts from step 3, invoke:
+
+.. code-block:: text
+
+ tools/iot2050-sign-fw.sh /path/to/key.pem
+
+Flash signed flash-pgX.bin
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The signing has happen in-place in flash-pgX.bin, thus the flashing procedure
+described above.
+
+M.2 slot configuration
+----------------------
+
+The M.2 variant of the IOT2050 comes with one B-keyed and one E-keyed slot.
+These are configured by U-Boot depending on the detected usage (auto
+configuration). The device tree loaded later on for the OS will be fixed up
+by U-Boot according to this configuration.
+
+For the case auto configuration does not work reliably, it is possible to set
+the U-Boot environment variable "m2_manual_config" to select the mode manually:
+
+"0"  -  B-key: PCIe x2, USB 2.0
+        E-key: USB 2.0
+"1"  -  B-key: PCIe, USB 2.0
+        E-key: PCIe, USB 2.0
+"2"  -  B-key: USB 3.0,
+        E-key: PCIe, USB 2.0