[PATCH v5 7/8] docs: k3: Cleanup FIT signature documentation
Manorit Chawdhry
m-chawdhry at ti.com
Mon Nov 13 11:19:06 CET 2023
The previous documentation had been very crude so refactor it to make it
cleaner and concise.
Signed-off-by: Manorit Chawdhry <m-chawdhry at ti.com>
---
doc/board/ti/k3.rst | 270 +++++++++++++++++++++++++++++++++-------------------
1 file changed, 171 insertions(+), 99 deletions(-)
diff --git a/doc/board/ti/k3.rst b/doc/board/ti/k3.rst
index 5167925c9c60..3c4dbe1af545 100644
--- a/doc/board/ti/k3.rst
+++ b/doc/board/ti/k3.rst
@@ -246,6 +246,8 @@ Building tiboot3.bin
the final `tiboot3.bin` binary. (or the `sysfw.itb` if your device
uses the split binary flow)
+.. _k3_rst_include_start_build_steps_spl_r5:
+
.. k3_rst_include_start_build_steps_spl_r5
.. prompt:: bash $
@@ -310,6 +312,8 @@ use the `lite` option.
finished, we can jump back into U-Boot again, this time running on a
64bit core in the main domain.
+.. _k3_rst_include_start_build_steps_uboot:
+
.. k3_rst_include_start_build_steps_uboot
.. prompt:: bash $
@@ -328,144 +332,212 @@ wakeup and main domain and to boot to the U-Boot prompt
| `tispl.bin` for HS devices or `tispl.bin_unsigned` for GP devices
| `u-boot.img` for HS devices or `u-boot.img_unsigned` for GP devices
-Fit Signature Signing
+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
+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
+Pre-requisites:
+
+* U-boot build (:ref:`U-boot build <k3_rst_include_start_build_steps_spl_r5>`)
+* Linux Image and Linux DTB prebuilt
+
+Describing FIT source
+^^^^^^^^^^^^^^^^^^^^^
- .. code-block:: bash
+FIT Image is a packed structure containing binary blobs and configurations.
+The Kernel FIT Image that we have has Kernel Image, DTB and the DTBOs. It
+supports packing multiple images and configurations that allow you to
+choose any configuration at runtime to boot from.
+
+.. code-block::
/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";
- };
-
- };
+ description = "FIT Image description";
+ #address-cells = <1>;
+
+ images {
+ [image-1]
+ [image-2]
+ [fdt-1]
+ [fdt-2]
+ }
+
+ configurations {
+ default = <conf-1>
+ [conf-1: image-1,fdt-1]
+ [conf-2: image-2,fdt-1]
+ }
+ }
+
+* Sample Images
+
+.. code-block::
+
+ kernel-1 {
+ description = "Linux kernel";
+ data = /incbin/("linux.bin");
+ type = "kernel";
+ arch = "arm64";
+ os = "linux";
+ compression = "gzip";
+ load = <0x81000000>;
+ entry = <0x81000000>;
+ 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";
- };
- };
+ };
+ fdt-ti_k3-j721e-common-proc-board.dtb {
+ description = "Flattened Device Tree blob";
+ data = /incbin/("arch/arm64/boot/dts/ti/k3-j721e-common-proc-board.dtb");
+ type = "flat_dt";
+ arch = "arm64";
+ compression = "none";
+ load = <0x83000000>;
+ hash-1 {
+ algo = "sha512";
};
};
+ # Optional images
+ fdt-ti_k3-j721e-evm-virt-mac-client.dtbo {
+ description = "Flattened Device Tree blob";
+ data = /incbin/("arch/arm64/boot/dts/ti/k3-j721e-evm-virt-mac-client.dtbo");
+ type = "flat_dt";
+ arch = "arm64";
+ compression = "none";
+ load = <0x83080000>;
+ hash-1 {
+ algo = "sha512";
+ };
+ };
+
+.. note::
+
+ Change the path in data variables to point to the respective files in your
+ local machine. For e.g change "linux.bin" to "<path-to-kernel-image>".
- 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.
+For enabling usage of FIT signature, add the signature node to the
+corresponding configuration node as follows.
-2. Compile U-boot for the respective board
+* Sample Configurations
-.. include:: k3.rst
- :start-after: .. k3_rst_include_start_build_steps_uboot
- :end-before: .. k3_rst_include_end_build_steps_uboot
+.. code-block::
+
+ 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";
+ };
+ };
+ # Optional configurations
+ conf-ti_k3-j721e-evm-virt-mac-client.dtbo {
+ description = "FDTO blob";
+ fdt = "fdt-ti_k3-j721e-evm-virt-mac-client.dtbo";
+
+ signature-1 {
+ algo = "sha512,rsa4096";
+ key-name-hint = "custMpk";
+ sign-images = "fdt";
+ };
+ };
+
+Specify all images you need the signature to authenticate as a part of
+sign-images. The key-name-hint needs to be changed if you are using some
+other key other than the TI dummy key that we are using for this example.
+It should be the name of the file containing the keys.
.. note::
- The changes only affect a72 binaries so the example just builds that
+ Generating new set of keys:
+
+ .. prompt:: bash $
-3. Sign the fit image and embed the dtb in uboot
+ mkdir keys
+ openssl genpkey -algorithm RSA -out keys/dev.key \
+ -pkeyopt rsa_keygen_bits:4096 -pkeyopt rsa_keygen_pubexp:65537
+ openssl req -batch -new -x509 -key keys/dev.key -out keys/dev.crt
- 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.
+Generating the fitImage
+^^^^^^^^^^^^^^^^^^^^^^^
- .. prompt:: bash $
+.. note::
+
+ For signing a secondary platform like SK boards, you'll require
+ additional steps
+
+ - Change the CONFIG_DEFAULT_DEVICE_TREE
- mkimage -r -f fitImage.its -k $UBOOT_PATH/board/ti/keys -K
- $UBOOT_PATH/build/a72/dts/dt.dtb
+ For e.g
- For signing a secondary platform, pass the -K parameter to that DTB
+ .. code-block::
- .. prompt:: bash $
+ diff --git a/configs/j721e_evm_a72_defconfig b/configs/j721e_evm_a72_defconfig
+ index a5c1df7e0054..6d0126d955ef 100644
+ --- a/configs/j721e_evm_a72_defconfig
+ +++ b/configs/j721e_evm_a72_defconfig
+ @@ -13,7 +13,7 @@ CONFIG_CUSTOM_SYS_INIT_SP_ADDR=0x80480000
+ CONFIG_ENV_SIZE=0x20000
+ CONFIG_DM_GPIO=y
+ CONFIG_SPL_DM_SPI=y
+ -CONFIG_DEFAULT_DEVICE_TREE="k3-j721e-common-proc-board"
+ +CONFIG_DEFAULT_DEVICE_TREE="k3-j721e-sk"
+ CONFIG_SPL_TEXT_BASE=0x80080000
+ CONFIG_DM_RESET=y
+ CONFIG_SPL_MMC=y
- mkimage -f fitImage.its -k $UBOOT_PATH/board/ti/keys -K
- $UBOOT_PATH/build/a72/arch/arm/dts/k3-j721e-sk.dtb
+ - Change the binman nodes to package u-boot.dtb for the correct set of platform
- .. note::
+ For e.g
- If changing `CONFIG_DEFAULT_DEVICE_TREE` to the secondary platform,
- binman changes would also be required so that correct dtb gets packaged.
+ .. code-block::
- .. 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"
- 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"
- #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"
+This step will embed the public key in the u-boot.dtb file that was already
+built during the initial u-boot build.
-5. Rebuilt u-boot
+.. prompt:: bash $
- This is required so that the modified dtb gets updated in u-boot.img
+ mkimage -r -f fitImage.its -k $UBOOT_PATH/board/ti/keys -K $UBOOT_PATH/build/$ARMV8/dts/dt.dtb fitImage
-.. include:: k3.rst
- :start-after: .. k3_rst_include_start_build_steps_uboot
- :end-before: .. k3_rst_include_end_build_steps_uboot
+.. note::
-6. (Optional) Enabled FIT_SIGNATURE_ENFORCED
+ If you have another set of keys then change the -k argument to point to
+ the folder where your keys are present, the build requires the presence
+ of both .key and .crt file.
- 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
+Build u-boot again
+^^^^^^^^^^^^^^^^^^
- This is by default enabled for devices with TI_SECURE_DEVICE enabled.
+The updated u-boot.dtb needs to be packed in u-boot.img for authentication
+so rebuild U-boot ARMV8 without changing any parameters.
+Refer (:ref:`U-boot ARMV8 build <k3_rst_include_start_build_steps_uboot>`)
.. 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.
+ 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 to
+ disallow fallback during testing.
Saving environment
------------------
--
2.41.0
More information about the U-Boot
mailing list