diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/README.sha1 | 58 | ||||
| -rw-r--r-- | doc/board/ti/k3.rst | 313 | ||||
| -rw-r--r-- | doc/develop/bloblist.rst | 4 | ||||
| -rw-r--r-- | doc/develop/release_cycle.rst | 2 | ||||
| -rw-r--r-- | doc/usage/cmd/cli.rst | 74 | ||||
| -rw-r--r-- | doc/usage/cmd/wget.rst | 3 | ||||
| -rw-r--r-- | doc/usage/environment.rst | 4 | ||||
| -rw-r--r-- | doc/usage/index.rst | 1 |
8 files changed, 299 insertions, 160 deletions
diff --git a/doc/README.sha1 b/doc/README.sha1 deleted file mode 100644 index f178f372643..00000000000 --- a/doc/README.sha1 +++ /dev/null @@ -1,58 +0,0 @@ -SHA1 usage: ------------ - -In the U-Boot Image for the pcs440ep board is a SHA1 checksum integrated. -This SHA1 sum is used, to check, if the U-Boot Image in Flash is not -corrupted. - -The following command is available: - -=> help sha1 -sha1 address len [addr] calculate the SHA1 sum [save at addr] - -p calculate the SHA1 sum from the U-Boot image in flash and print - -c check the U-Boot image in flash - -"sha1 -p" - calculates and prints the SHA1 sum, from the Image stored in Flash - -"sha1 -c" - check, if the SHA1 sum from the Image stored in Flash is correct - - -It is possible to calculate a SHA1 checksum from a memoryrange with: - -"sha1 address len" - -If you want to store a new Image in Flash for the pcs440ep board, -which has no SHA1 sum, you can do the following: - -a) cp the new Image on a position in RAM (here 0x300000) - (for this example we use the Image from Flash, stored at 0xfffa0000 and - 0x60000 Bytes long) - -"cp.b fffa0000 300000 60000" - -b) Initialize the SHA1 sum in the Image with 0x00 - The SHA1 sum is stored in Flash at: - CONFIG_SYS_MONITOR_BASE + CONFIG_SYS_MONITOR_LEN + SHA1_SUM_POS - for the pcs440ep Flash: 0xfffa0000 + 0x60000 + -0x20 - = 0xffffffe0 - for the example in RAM: 0x300000 + 0x60000 + -0x20 - = 0x35ffe0 - - note: a SHA1 checksum is 20 bytes long. - -"mw.b 35ffe0 0 14" - -c) now calculate the SHA1 sum from the memoryrange and write - the calculated checksum at the right place: - -"sha1 300000 60000 35ffe0" - -Now you have a U-Boot-Image for the pcs440ep board with the correct SHA1 sum. - -If you do a "buildman -k pcs440ep" or a "make all" to get the U-Boot image, -which will be found in ../current/ipam390/ - the correct SHA1 sum will be -automagically included in the U-Boot image. - -Heiko Schocher, 11 Jul 2007 diff --git a/doc/board/ti/k3.rst b/doc/board/ti/k3.rst index f19ee56f296..7dfe39c5fa5 100644 --- a/doc/board/ti/k3.rst +++ b/doc/board/ti/k3.rst @@ -104,6 +104,49 @@ firmware can be loaded on the now free core in the wakeup domain. For more information on the bootup process of your SoC, consult the device specific boot flow documentation. +Secure Boot +----------- + +K3 HS-SE (High Security - Security Enforced) devices enforce an +authenticated boot flow for secure boot. HS-FS (High Security - Field +Securable) is the state of a K3 device before it has been eFused with +customer security keys. In the HS-FS state the authentication still can +function as in HS-SE but as there are no customer keys to verify the +signatures against the authentication will pass for certificates signed +with any key. + +Chain of trust +^^^^^^^^^^^^^^ + +1) Public ROM loads the tiboot3.bin (R5 SPL, TIFS) +2) R5 SPL loads tispl.bin (ATF, OP-TEE, DM, SPL) +3) SPL loads u-boot.img (U-Boot) +4) U-Boot loads fitImage (Linux and DTBs) + +Steps 1-3 are all authenticated by either the Secure ROM or TIFS as the +authenticating entity and step 4 uses U-boot standard mechanism for +authenticating. + +All the authentication that are done for ROM/TIFS are done through x509 +certificates that are signed. + +Firewalls +^^^^^^^^^ + +1) Secure ROM comes up and sets up firewalls that are needed by itself +2) TIFS will setup it's own firewalls to protect core system resources +3) R5 SPL will remove any firewalls that are leftover from the Secure ROM stage + that are no longer required. +4) Each stage beyond this: such as tispl.bin containing TFA/OPTEE uses OIDs to + set up firewalls to protect themselves (enforced by TIFS) +5) TFA/OP-TEE can configure other firewalls at runtime if required as they + are already authenticated and firewalled off from illegal access. +6) All later stages can setup or remove firewalls that have not been already + configured by previous stages, such as those created by TIFS, TFA, and OP-TEE. + +Futhur, firewalls have a lockdown bit in hardware that enforces the setting +(and cannot be over-ridden) until the full system is reset. + Software Sources ---------------- @@ -248,6 +291,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 $ @@ -312,6 +357,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 $ @@ -337,144 +384,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 - .. code-block:: bash +Describing FIT source +^^^^^^^^^^^^^^^^^^^^^ + +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"; }; }; - 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. +.. 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>". + +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: -3. Sign the fit image and embed the dtb in uboot + .. prompt:: bash $ - 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. + 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 - .. prompt:: bash $ +Generating the fitImage +^^^^^^^^^^^^^^^^^^^^^^^ - mkimage -r -f fitImage.its -k $UBOOT_PATH/board/ti/keys -K - $UBOOT_PATH/build/a72/dts/dt.dtb +.. note:: - For signing a secondary platform, pass the -K parameter to that DTB + For signing a secondary platform like SK boards, you'll require + additional steps - .. prompt:: bash $ + - Change the CONFIG_DEFAULT_DEVICE_TREE - mkimage -f fitImage.its -k $UBOOT_PATH/board/ti/keys -K - $UBOOT_PATH/build/a72/arch/arm/dts/k3-j721e-sk.dtb + For e.g - .. note:: + .. code-block:: - If changing `CONFIG_DEFAULT_DEVICE_TREE` to the secondary platform, - binman changes would also be required so that correct dtb gets packaged. + 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 - .. code-block:: bash + - Change the binman nodes to package u-boot.dtb for the correct set of platform - 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" + For e.g - #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" + .. code-block:: -5. Rebuilt u-boot + 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" - This is required so that the modified dtb gets updated in u-boot.img + #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" -.. include:: k3.rst - :start-after: .. k3_rst_include_start_build_steps_uboot - :end-before: .. k3_rst_include_end_build_steps_uboot +This step will embed the public key in the u-boot.dtb file that was already +built during the initial u-boot build. -6. (Optional) Enabled FIT_SIGNATURE_ENFORCED +.. prompt:: bash $ + + mkimage -r -f fitImage.its -k $UBOOT_PATH/board/ti/keys -K $UBOOT_PATH/build/$ARMV8/dts/dt.dtb fitImage + +.. note:: + + 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 ------------------ diff --git a/doc/develop/bloblist.rst b/doc/develop/bloblist.rst index 81643c7674b..28431039adc 100644 --- a/doc/develop/bloblist.rst +++ b/doc/develop/bloblist.rst @@ -14,6 +14,8 @@ structure defined by the code that owns it. For the design goals of bloblist, please see the comments at the top of the `bloblist.h` header file. +Bloblist is an implementation with the `Firmware Handoff`_ protocol. + Passing state through the boot process -------------------------------------- @@ -99,7 +101,7 @@ API documentation ----------------- .. kernel-doc:: include/bloblist.h - +.. _`Firmware Handoff`: https://github.com/FirmwareHandoff/firmware_handoff Simon Glass sjg@chromium.org diff --git a/doc/develop/release_cycle.rst b/doc/develop/release_cycle.rst index 8fe77f23b6e..0cd83df8b74 100644 --- a/doc/develop/release_cycle.rst +++ b/doc/develop/release_cycle.rst @@ -74,7 +74,7 @@ For the next scheduled release, release candidates were made on:: * U-Boot v2024.01-rc5 was released on Mon 18 December 2023. -.. * U-Boot v2024.01-rc6 was released on Tue 02 January 2024. +* U-Boot v2024.01-rc6 was released on Wed 03 January 2024. Please note that the following dates are planned only and may be deviated from as needed. diff --git a/doc/usage/cmd/cli.rst b/doc/usage/cmd/cli.rst new file mode 100644 index 00000000000..a0cf5958fb9 --- /dev/null +++ b/doc/usage/cmd/cli.rst @@ -0,0 +1,74 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +cli command +=========== + +Synopis +------- + +:: + + cli get + cli set cli_flavor + +Description +----------- + +The cli command permits getting and changing the current parser at runtime. + +cli get +~~~~~~~ + +It shows the current value of the parser used by the CLI. + +cli set +~~~~~~~ + +It permits setting the value of the parser used by the CLI. + +Possible values are old and modern. +Note that, to use a specific parser its code should have been compiled, that +is to say you need to enable the corresponding CONFIG_HUSH*. +Otherwise, an error message is printed. + +Examples +-------- + +Get the current parser:: + + => cli get + old + +Change the current parser:: + + => cli get + old + => cli set modern + => cli get + modern + => cli set old + => cli get + old + +Trying to set the current parser to an unknown value:: + + => cli set foo + Bad value for parser name: foo + cli - cli + + Usage: + cli get - print current cli + set - set the current cli, possible values are: old, modern + +Trying to set the current parser to a correct value but its code was not +compiled:: + + => cli get + modern + => cli set old + Want to set current parser to old, but its code was not compiled! + +Return value +------------ + +The return value $? indicates whether the command succeeded. diff --git a/doc/usage/cmd/wget.rst b/doc/usage/cmd/wget.rst index e1e7f8d8145..8e7383b6c60 100644 --- a/doc/usage/cmd/wget.rst +++ b/doc/usage/cmd/wget.rst @@ -16,7 +16,8 @@ Description The wget command is used to download a file from an HTTP server. wget command will use HTTP over TCP to download files from an HTTP server. -Currently it can only download image from an HTTP server hosted on port 80. +By default the destination port is 80 and the source port is pseudo-random. +The environment variable *httpdstp* can be used to set the destination port. address memory address for the data downloaded diff --git a/doc/usage/environment.rst b/doc/usage/environment.rst index c57b717caaf..82b6ea7b6e7 100644 --- a/doc/usage/environment.rst +++ b/doc/usage/environment.rst @@ -306,6 +306,10 @@ ethrotate anything other than "no", U-Boot does go through all available network interfaces. +httpdstp + If this is set, the value is used for HTTP's TCP + destination port instead of the default port 80. + netretry When set to "no" each network operation will either succeed or fail without retrying. diff --git a/doc/usage/index.rst b/doc/usage/index.rst index 1a626c03c23..c171c029b80 100644 --- a/doc/usage/index.rst +++ b/doc/usage/index.rst @@ -43,6 +43,7 @@ Shell commands cmd/cat cmd/cbsysinfo cmd/cedit + cmd/cli cmd/cls cmd/cmp cmd/coninfo |