docs: board: ti: Fit signature signing

Add documentation for signing secondary platforms as a
part of enabling the fit signature signing in u-boot.

Signed-off-by: Manorit Chawdhry <m-chawdhry@ti.com>

1 files changed, 145 insertions, 0 deletions

diff --git a/doc/board/ti/k3.rst b/doc/board/ti/k3.rst
index 214a22b1ae..ff983748d5 100644
--- a/doc/board/ti/k3.rst
+++ b/doc/board/ti/k3.rst
@@ -240,3 +240,148 @@ wakeup and main domain and to boot to the U-Boot prompt
 
    | `tispl.bin`
    | `u-boot.img`
+
+
+
+Fit Signature Signing
+---------------------
+
+K3 Platforms have fit signature signing enabled by default on their primary
+platforms. Here we'll take an example for creating fit image for J721e platform
+and the same can be extended to other platforms
+
+1. Describing FIT source
+
+  .. code-block:: bash
+
+    /dts-v1/;
+
+    / {
+            description = "Kernel fitImage for j721e-hs-evm";
+            #address-cells = <1>;
+
+            images {
+                    kernel-1 {
+                            description = "Linux kernel";
+                            data = /incbin/("Image");
+                            type = "kernel";
+                            arch = "arm64";
+                            os = "linux";
+                            compression = "none";
+                            load = <0x80080000>;
+                            entry = <0x80080000>;
+                            hash-1 {
+                                    algo = "sha512";
+                            };
+
+                    };
+                    fdt-ti_k3-j721e-common-proc-board.dtb {
+                            description = "Flattened Device Tree blob";
+                            data = /incbin/("k3-j721e-common-proc-board.dtb");
+                            type = "flat_dt";
+                            arch = "arm64";
+                            compression = "none";
+                            load = <0x83000000>;
+                            hash-1 {
+                                    algo = "sha512";
+                            };
+
+                    };
+            };
+
+            configurations {
+                    default = "conf-ti_k3-j721e-common-proc-board.dtb";
+                    conf-ti_k3-j721e-common-proc-board.dtb {
+                            description = "Linux kernel, FDT blob";
+                            fdt = "fdt-ti_k3-j721e-common-proc-board.dtb";
+                            kernel = "kernel-1";
+                            signature-1 {
+                                    algo = "sha512,rsa4096";
+                                    key-name-hint = "custMpk";
+                                    sign-images = "kernel", "fdt";
+                            };
+                    };
+            };
+    };
+
+  You would require to change the '/incbin/' lines to point to the respective
+  files in your local machine and the key-name-hint also needs to be changed
+  if you are using some other key other than the TI dummy key that we are
+  using for this example.
+
+2. Compile U-boot for the respective board
+
+  .. code-block:: bash
+
+     make O=build/a72 CROSS_COMPILE=aarch64-none-linux-gnu- ARCH=arm
+     BL31=/path/to/bl31.bin TEE=/path/to/bl32.bin
+     BINMAN_INDIRS="/path/to/ti-linux-firmware" -j15
+
+  .. note::
+
+    The changes only affect a72 binaries so the example just builds that
+
+3. Sign the fit image and embed the dtb in uboot
+
+  Now once the build is done, you'll have a dtb for your board that you'll
+  be passing to mkimage for signing the fitImage and embedding the key in
+  the u-boot dtb.
+
+  .. code-block:: bash
+
+    mkimage -r -f fitImage.its -k $UBOOT_PATH/board/ti/keys -K
+    $UBOOT_PATH/build/a72/dts/dt.dtb
+
+  For signing a secondary platform, pass the -K parameter to that DTB
+
+  .. code-block:: bash
+
+    mkimage -f fitImage.its -k $UBOOT_PATH/board/ti/keys -K
+    $UBOOT_PATH/build/a72/arch/arm/dts/k3-j721e-sk.dtb
+
+  .. note::
+
+    If changing `CONFIG_DEFAULT_DEVICE_TREE` to the secondary platform,
+    binman changes would also be required so that correct dtb gets packaged.
+
+    .. code-block:: bash
+
+      diff --git a/arch/arm/dts/k3-j721e-binman.dtsi b/arch/arm/dts/k3-j721e-binman.dtsi
+      index 673be646b1e3..752fa805fe8d 100644
+      --- a/arch/arm/dts/k3-j721e-binman.dtsi
+      +++ b/arch/arm/dts/k3-j721e-binman.dtsi
+      @@ -299,8 +299,8 @@
+       #define SPL_J721E_SK_DTB "spl/dts/k3-j721e-sk.dtb"
+
+       #define UBOOT_NODTB "u-boot-nodtb.bin"
+      -#define J721E_EVM_DTB "u-boot.dtb"
+      -#define J721E_SK_DTB "arch/arm/dts/k3-j721e-sk.dtb"
+      +#define J721E_EVM_DTB "arch/arm/dts/k3-j721e-common-proc-board.dtb"
+      +#define J721E_SK_DTB "u-boot.dtb"
+
+5. Rebuilt u-boot
+
+   This is required so that the modified dtb gets updated in u-boot.img
+
+   .. code-block:: bash
+
+     make O=build/a72 CROSS_COMPILE=aarch64-none-linux-gnu- ARCH=arm
+     BL31=/path/to/bl31.bin TEE=/path/to/bl32.bin
+     BINMAN_INDIRS="/path/to/ti-linux-firmware" -j15
+
+6. (Optional) Enabled FIT_SIGNATURE_ENFORCED
+
+   By default u-boot will boot up the fit image without any authentication as
+   such if the public key is not embedded properly, to check if the public key
+   nodes are proper you can enable FIT_SIGNATURE_ENFORCED that would not rely
+   on the dtb for anything else then the signature node for checking the fit
+   image, rest other things will be enforced such as the property of
+   required-keys. This is not an extensive check so do manual checks also
+
+   This is by default enabled for devices with TI_SECURE_DEVICE enabled.
+
+.. note::
+
+   The devices now also have distroboot enabled so if the fit image doesn't
+   work then the fallback to normal distroboot will be there on hs devices,
+   this will need to be explicitly disabled by changing the boot_targets.