diff options
Diffstat (limited to 'roms/u-boot/doc/imx')
23 files changed, 2714 insertions, 0 deletions
diff --git a/roms/u-boot/doc/imx/ahab/csf_examples/csf_enc_boot_image.txt b/roms/u-boot/doc/imx/ahab/csf_examples/csf_enc_boot_image.txt new file mode 100644 index 000000000..6c70db657 --- /dev/null +++ b/roms/u-boot/doc/imx/ahab/csf_examples/csf_enc_boot_image.txt @@ -0,0 +1,27 @@ +[Header] +Target = AHAB +Version = 1.0 + +[Install SRK] +# SRK table generated by srktool +File = "./release/crts/SRK_1_2_3_4_table.bin" +# Public key certificate in PEM format +Source = "./release/crts/SRK1_sha384_secp384r1_v3_usr_crt.pem" +# Index of the public key certificate within the SRK table (0 .. 3) +Source index = 0 +# Type of SRK set (NXP or OEM) +Source set = OEM +# bitmask of the revoked SRKs +Revocations = 0x0 + +[Authenticate Data] +# Binary to be signed generated by mkimage +File = "flash.bin" +# Offsets = Container header Signature block (printed out by mkimage) +Offsets = 0x400 0x590 + +[Install Secret Key] +Key = "dek.bin" +Key Length = 128 +#Key Identifier = 0x1234CAFE +Image Indexes = 0xFFFFFFFE diff --git a/roms/u-boot/doc/imx/ahab/guides/mx8_mx8x_encrypted_boot.txt b/roms/u-boot/doc/imx/ahab/guides/mx8_mx8x_encrypted_boot.txt new file mode 100644 index 000000000..dfea4c827 --- /dev/null +++ b/roms/u-boot/doc/imx/ahab/guides/mx8_mx8x_encrypted_boot.txt @@ -0,0 +1,293 @@ + +=========================================================+ + + i.MX 8, i.MX 8X Encrypted Boot guide using AHAB + + +=========================================================+ + +1. AHAB Encrypted Boot process +------------------------------- + +This document describes a step-by-step procedure on how to encrypt and sign a +bootloader image for i.MX8/8x family devices. It is assumed that the reader +is familiar with basic AHAB concepts and has already closed the device, +step-by-step procedure can be found in mx8_mx8x_secure_boot.txt and +mx8_mx8x_spl_secure_boot.txt guides. + +The steps described in this document were based in i.MX8QM device, the same +concept can be applied to others processors in i.MX8/8X family devices. + +1.1 Understanding the encrypted image signature block +------------------------------------------------------ + +As described in mx8_mx8x_secure_boot.txt guide a single binary is used to boot +the device. The imx-mkimage tool combines all the input images in a container +structure, generating a flash.bin binary. + +AHAB is able to decrypt image containers by calling SECO authentication +functions, the image must be encrypted by CST and the resulting DEK (Data +Encryption Key) must be encapsulated and included into the container signature +block: + + +----------------------------+ + | | ^ + | | | + | Container header | | + | | | + | | | + +---+------------------------+ | + | S | Signature block header | | Signed + | i +------------------------+ | + | g | | | + | n | | | + | a | SRK table | | + | t | | | + | u | | v + | r +------------------------+ + | e | Signature | + | +------------------------+ + | B | | + | l | SGK Key | + | o | Certificate (optional) | + | c | | + | k +------------------------+ + | | DEK Blob | + +---+------------------------+ + +1.1.1 Understanding and generating the DEK blob +------------------------------------------------ + +The encrypted boot image requires a DEK blob on each time AHAB is used to +decrypt an image. The DEK blob is used as a security layer to wrap and store +the DEK off-chip using the OTPMK which is unique per device. + +On i.MX8/8x devices the DEK blob is generated using the SECO API, the following +funtion is available in U-Boot and can be executed through dek_blob command: + +- sc_seco_gen_key_blob(sc_ipc_t ipc, uint32_t id, sc_faddr_t load_addr, + sc_faddr_t export_addr, uint16_t max_size) + +Details in API usage can be found in SCFW API guide [1]. + +1.2 Enabling the encrypted boot support in U-Boot +-------------------------------------------------- + +For deploying an encrypted boot image additional U-Boot tools are needed, +please be sure to have the following features enabled, this can be achieved +by following one of the methods below: + +- Defconfig: + + CONFIG_AHAB_BOOT=y + CONFIG_CMD_DEKBLOB=y + CONFIG_IMX_SECO_DEK_ENCAP=y + CONFIG_FAT_WRITE=y + +- Kconfig: + + ARM architecture -> Support i.MX8 AHAB features + ARM architecture -> Support the 'dek_blob' command + File systems -> Enable FAT filesystem support-> Enable FAT filesystem + write support + +1.3 Enabling the encrypted boot support in CST +----------------------------------------------- + +The encryption feature is not enabled by default in Code Signing tools (CST). +The CST backend must be recompiled, execute the following commands to enable +encryption support in CST: + + $ sudo apt-get install libssl-dev openssl + $ cd <CST install directory>/code/back_end/src + $ gcc -o cst_encrypted -I ../hdr -L ../../../linux64/lib *.c + -lfrontend -lcrypto + $ cp cst_encrypted ../../../linux64/bin/ + +1.4 Preparing the image container +---------------------------------- + +The container generation is explained in and mx8_mx8x_secure_boot.txt and +mx8_mx8x_spl_secure_boot.txt guides. This document is based in imx-mkimage +flash target (2 containers in flash.bin). + +- Assembly flash.bin binary: + + $ make SOC=<SoC Name> flash + +The mkimage log is used during the encrypted boot procedure to create the +Command Sequence File (CSF): + + CST: CONTAINER 0 offset: 0x400 + CST: CONTAINER 0: Signature Block: offset is at 0x590 + DONE. + Note: Please copy image to offset: IVT_OFFSET + IMAGE_OFFSET + +1.6 Creating the CSF description to encrypt the 2nd container +-------------------------------------------------------------- + +The csf_enc_boot_image.txt available under ahab/csf_examples/ can be used as +example for encrypting the flash.bin binary, the main change is the Install +Secret Key command that must be added after Authenticate Data command. + + [Install Secret Key] + Key = "dek.bin" + Key Length = 128 + #Key Identifier = 0x1234CAFE + Image Indexes = 0xFFFFFFFE + +By default all images are encrypted and image indexes parameter can be used +to mask the images indexes that must be encrypted, on this example only the +2nd container will be encrypted. + +Optionally users can provide a key identifier that must match the value +provided during the blob generation, by default its value is zero. + +1.7 Encrypting the 2nd container +--------------------------------- + +The image is encrypted using the Code Signing Tool. The tool generates the +encrypted image and a random dek.bin file. + +- Encrypt flash.bin binary: + + $ ./cst_encrypted -i csf_enc_boot_image.txt -o enc_flash.bin + The DEK BLOB must be inserted at offset 0x7c0 (its expected size is 72 bytes) + CSF Processed successfully and signed image available in enc_boot_image.bin + +The output log will be used in a later step to insert the DEK blob into the +signature block. + +1.8 Generating the DEK Blob +---------------------------- + +The DEK must be encapsulated into a CAAM blob so it can be included into the +final encrypted binary. The U-Boot provides a tool called dek_blob which is +calling the SECO blob encapsulation API. + +Copy the dek.bin in SDCard FAT partition and run the following commands from +U-Boot prompt: + + => mmc list + FSL_SDHC: 1 (SD) + FSL_SDHC: 2 + => fatload mmc 1:1 0x80280000 dek.bin + => dek_blob 0x80280000 0x80280100 128 + => fatwrite mmc 1:1 0x80280100 dek_blob.bin 0x48 + +In host PC copy the generated dek_blob.bin to the CST directory. + +1.9 Assembling the encrypted image +----------------------------------- + +The DEK blob generated in the step above have to be inserted into the container +signature block. + +The CSF log is used to determine the DEK Blob offset: + + The DEK BLOB must be inserted at offset 0x7c0 (its expected size is 72 bytes) + CSF Processed successfully and signed image available in enc_boot_image.bin + +- Insert DEK Blob into container signature block: + + $ dd if=dek_blob.bin of=enc_flash.bin bs=1 seek=$((0x7c0)) conv=notrunc + +1.10 Flashing the encrypted boot image +--------------------------------------- + +The same offset is used for encrypted boot images, in case booting from +eMMC/SDCard the offset is 32K. + +- Flash encrypted image in SDCard: + + $ sudo dd if=enc_flash.bin of=/dev/sd<x> bs=1K seek=32 && sync + +2.0 Encrypting a standalone container +-------------------------------------- + +CST is also able to encrypt additional images containers, the steps documented +in this section are based in OS container but can be also applied to SPL +targets and 3rd containers. + +2.1 Creating the OS container +------------------------------ + +As explained in mx8_mx8x_secure_boot.txt guide the imx-mkimage tool is used to +generate an image container for OS images, the mkimage log is used during the +encrypted boot procedure to create the Command Sequence File (CSF). + +- Creating OS container: + + $ make SOC=<SoC Name> flash_kernel + ... + CST: CONTAINER 0 offset: 0x0 + CST: CONTAINER 0: Signature Block: offset is at 0x110 + +2.2 Creating the CSF description file for standalone container +--------------------------------------------------------------- + +The Image Indexes parameter is used to mask the images that are encrypted by +CST, as a single container is used for OS images the Image Indexes command can +be commented or set to 0xFFFFFFFF. + + [Install Secret Key] + Key = "dek_os.bin" + Key Length = 128 + #Key Identifier = 0x1234CAFE + Image Indexes = 0xFFFFFFFF + +2.3 Encrypting the standalone container +---------------------------------------- + +As explained in section 1.7 the CST generates the encrypted image and a random +dek.bin file. + +- Encrypt the standalone container: + + $ ./cst_encrypted -i csf_linux_img.txt -o enc_flash_os.bin + The DEK BLOB must be inserted at offset 0x340 (its expected size is 72 bytes) + CSF Processed successfully and signed image available in enc_flash_os.bin + +The output log will be used in a later step to insert the DEK blob into the +signature block. + +2.4 Generating the DEK Blob for standalone container +---------------------------------------------------- + +Similar to section 1.8 the DEK must be encapsulated into a CAAM blob so it can +be included into the final encrypted binary. + +Copy the dek_os.bin in SDCard FAT partition and run the following commands from +U-Boot prompt: + + => mmc list + FSL_SDHC: 1 (SD) + FSL_SDHC: 2 + => fatload mmc 1:1 0x80280000 dek_os.bin + => dek_blob 0x80280000 0x80280100 128 + => fatwrite mmc 1:1 0x80280100 dek_blob_os.bin 0x48 + +In host PC copy the generated dek_blob_os.bin to the CST directory. + +2.5 Assembling the encrypted image +----------------------------------- + +The DEK blob generated in the step above have to be inserted into the container +signature block. + +The CSF log is used to determine the DEK Blob offset: + + The DEK BLOB must be inserted at offset 0x340 (its expected size is 72 bytes) + CSF Processed successfully and signed image available in enc_flash_os.bin + +- Insert DEK Blob into container signature block: + + $ dd if=dek_blob_os.bin of=enc_flash_os.bin bs=1 seek=$((0x340)) conv=notrunc + +2.6 Copy encrypted image to SDCard +----------------------------------- + +The encrypted container can be copied to SDCard FAT partition, please note +that U-Boot requires signed and encrypted containers to be named as +os_cntr_signed.bin. + + $ sudo cp enc_flash_os.bin /media/UserID/Boot\ imx8/os_cntr_signed.bin + +References: +[1] SCFW API guide: "System Controller Firmware API Reference Guide - Rev 1.5" diff --git a/roms/u-boot/doc/imx/clk/ccf.txt b/roms/u-boot/doc/imx/clk/ccf.txt new file mode 100644 index 000000000..f47ca8832 --- /dev/null +++ b/roms/u-boot/doc/imx/clk/ccf.txt @@ -0,0 +1,102 @@ +Introduction: +============= + +This documentation entry describes the Common Clock Framework [CCF] port from +Linux kernel (v5.1.12) to U-Boot. + +This code is supposed to bring CCF to IMX based devices (imx6q, imx7 imx8). +Moreover, it also provides some common clock code, which would allow easy +porting of CCF Linux code to other platforms. + +Design decisions: +================= + +* U-Boot's driver model [DM] for clk differs from Linux CCF. The most notably + difference is the lack of support for hierarchical clocks and "clock as a + manager driver" (single clock DTS node acts as a starting point for all other + clocks). + +* The clk_get_rate() caches the previously read data if CLK_GET_RATE_NOCACHE is + not set (no need for recursive access). + +* On purpose the "manager" clk driver (clk-imx6q.c) is not using large table to + store pointers to clocks - e.g. clk[IMX6QDL_CLK_USDHC2_SEL] = .... Instead we + use udevice's linked list for the same class (UCLASS_CLK). + + Rationale: + ---------- + When porting the code as is from Linux, one would need ~1KiB of RAM to store + it. This is way too much if we do plan to use this driver in SPL. + +* The "central" structure of this patch series is struct udevice and its + uclass_priv field contains the struct clk pointer (to the originally created + one). + +* To keep things simple the struct udevice's uclass_priv pointer is used to + store back pointer to corresponding struct clk. However, it is possible to + modify clk-uclass.c file and add there struct uc_clk_priv, which would have + clock related members (like pointer to clk). As of this writing there is no + such need, so to avoid extra allocations (as it can be auto allocated by + setting .per_device_auto = sizeof(struct uc_clk_priv)) the + uclass_priv stores the pointer to struct clk. + +* Non-CCF clocks do not have a pointer to a clock in clk->dev->priv. In the case + of composite clocks, clk->dev->priv may not match clk. Drivers should always + use the struct clk which is passed to them, and not clk->dev->priv. + +* It is advised to add common clock code (like already added rate and flags) to + the struct clk, which is a top level description of the clock. + +* U-Boot's driver model already provides the facility to automatically allocate + (via private_alloc_size) device private data (accessible via dev->priv). It + may look appealing to use this feature to allocate private structures for CCF + clk devices e.g. divider (struct clk_divider *divider) for IMX6Q clock. + + The above feature had not been used for following reasons: + - The original CCF Linux kernel driver is the "manager" for clocks - it + decides when clock is instantiated (and when memory for it is allocated). + + - Using it would change the original structure of the CCF code. + + - To bind (via clk_register()) the clock device with U-Boot driver model we + first need udevice for it (the "chicken and egg problem"). + +* I've added the clk_get_parent(), which reads parent's dev->uclass_priv to + provide parent's struct clk pointer. This seems the easiest way to get + child/parent relationship for struct clk in U-Boot's udevice based clocks. In + the future arbitrary parents may be supported by adding a get_parent function + to clk_ops. + +* Linux's CCF 'struct clk_core' corresponds to U-Boot's udevice in 'struct clk'. + Clock IP block agnostic flags from 'struct clk_core' (e.g. NOCACHE) have been + moved from this struct one level up to 'struct clk'. Many flags are + unimplemented at the moment. + +* For tests the new ./test/dm/clk_ccf.c and ./drivers/clk/clk_sandbox_ccf.c + files have been introduced. The latter setups the CCF clock structure for + sandbox by reusing, if possible, generic clock primitives - like divier and + mux. The former file provides code to tests this setup. + + For sandbox new CONFIG_SANDBOX_CLK_CCF Kconfig define has been introduced. + All new primitives added for new architectures must have corresponding test in + the two aforementioned files. + +Testing (sandbox): +================== + +make mrproper; make sandbox_defconfig; make -j4 +./u-boot -i -d arch/sandbox/dts/test.dtb +=> ut dm clk + +or in a more "scriptable" way (with -v to print debug output): +./u-boot --fdt arch/sandbox/dts/test.dtb --command "ut dm clk_ccf" -v + +To do: +------ + +* Use of OF_PLATDATA in the SPL setup for CCF - as it is now - the SPL grows + considerably and using CCF in boards with tiny resources (OCRAM) is + problematic. + +* On demand port other parts of CCF to U-Boot - as now only features _really_ + needed by DM/DTS converted drivers are used. diff --git a/roms/u-boot/doc/imx/common/imx25.txt b/roms/u-boot/doc/imx/common/imx25.txt new file mode 100644 index 000000000..0ca21b6df --- /dev/null +++ b/roms/u-boot/doc/imx/common/imx25.txt @@ -0,0 +1,10 @@ +U-Boot for Freescale i.MX25 + +This file contains information for the port of U-Boot to the Freescale i.MX25 +SoC. + +1. CONVENTIONS FOR FUSE ASSIGNMENTS +----------------------------------- + +1.1 MAC Address: It is stored in the words 26 to 31 of fuse bank 0, using the + natural MAC byte order (i.e. MSB first). diff --git a/roms/u-boot/doc/imx/common/imx27.txt b/roms/u-boot/doc/imx/common/imx27.txt new file mode 100644 index 000000000..6f92cb47c --- /dev/null +++ b/roms/u-boot/doc/imx/common/imx27.txt @@ -0,0 +1,10 @@ +U-Boot for Freescale i.MX27 + +This file contains information for the port of U-Boot to the Freescale i.MX27 +SoC. + +1. CONVENTIONS FOR FUSE ASSIGNMENTS +----------------------------------- + +1.1 MAC Address: It is stored in the words 4 to 9 of fuse bank 0, using the + reversed MAC byte order (i.e. LSB first). diff --git a/roms/u-boot/doc/imx/common/imx5.txt b/roms/u-boot/doc/imx/common/imx5.txt new file mode 100644 index 000000000..ea0e144ce --- /dev/null +++ b/roms/u-boot/doc/imx/common/imx5.txt @@ -0,0 +1,40 @@ +U-Boot for Freescale i.MX5x + +This file contains information for the port of U-Boot to the Freescale +i.MX5x SoCs. + +1. CONFIGURATION OPTIONS/SETTINGS +--------------------------------- + +1.1 CONFIG_MX51_PLL_ERRATA: Workaround for i.MX51 PLL errata. + This option should be enabled by all boards using the i.MX51 silicon + version up until (including) 3.0 running at 800MHz. + The PLL's in the i.MX51 processor can go out of lock due to a metastable + condition in an analog flip-flop when used at high frequencies. + This workaround implements an undocumented feature in the PLL (dither + mode), which causes the effect of this failure to be much lower (in terms + of frequency deviation), avoiding system failure, or at least decreasing + the likelihood of system failure. + +1.2 CONFIG_SYS_MAIN_PWR_ON: Trigger MAIN_PWR_ON upon startup. + This option should be enabled for boards having a SYS_ON_OFF_CTL signal + connected to GPIO1[23] and triggering the MAIN_PWR_ON signal like in the + reference designs. + +2. CONVENTIONS FOR FUSE ASSIGNMENTS +----------------------------------- + +2.1 MAC Address: It is stored in the words 9 to 14 of fuse bank 1, using the + natural MAC byte order (i.e. MSB first). + + This is an example how to program an example MAC address 01:23:45:67:89:ab + into the eFuses. Assure that the programming voltage is available and then + execute: + + => fuse prog -y 1 9 01 23 45 67 89 ab + + After programming a MAC address, consider locking the MAC fuses. This is + done by programming the MAC_ADDR_LOCK fuse, which is bit 4 of word 0 in + bank 1: + + => fuse prog -y 1 0 10 diff --git a/roms/u-boot/doc/imx/common/imx6.txt b/roms/u-boot/doc/imx/common/imx6.txt new file mode 100644 index 000000000..0b5061128 --- /dev/null +++ b/roms/u-boot/doc/imx/common/imx6.txt @@ -0,0 +1,164 @@ +U-Boot for Freescale i.MX6 + +This file contains information for the port of U-Boot to the Freescale i.MX6 +SoC. + +1. CONVENTIONS FOR FUSE ASSIGNMENTS +----------------------------------- + +1.1 MAC Address: It is stored in fuse bank 4, with the 32 lsbs in word 2 and the + 16 msbs in word 3[15:0]. + For i.MX6SX and i.MX6UL, they have two MAC addresses. The second MAC address + is stored in fuse bank 4, with the 16 lsb in word 3[31:16] and the 32 msbs in + word 4. + +Example: + +For reading the MAC address fuses on a MX6Q: + +- The MAC address is stored in two fuse addresses (the fuse addresses are +described in the Fusemap Descriptions table from the mx6q Reference Manual): + +0x620[31:0] - MAC_ADDR[31:0] +0x630[15:0] - MAC_ADDR[47:32] + +In order to use the fuse API, we need to pass the bank and word values, which +are calculated as below: + +Fuse address for the lower MAC address: 0x620 +Base address for the fuses: 0x400 + +(0x620 - 0x400)/0x10 = 0x22 = 34 decimal + +As the fuses are arranged in banks of 8 words: + +34 / 8 = 4 and the remainder is 2, so in this case: + +bank = 4 +word = 2 + +And the U-Boot command would be: + +=> fuse read 4 2 +Reading bank 4: + +Word 0x00000002: 9f027772 + +Doing the same for the upper MAC address: + +Fuse address for the upper MAC address: 0x630 +Base address for the fuses: 0x400 + +(0x630 - 0x400)/0x10 = 0x23 = 35 decimal + +As the fuses are arranged in banks of 8 words: + +35 / 8 = 4 and the remainder is 3, so in this case: + +bank = 4 +word = 3 + +And the U-Boot command would be: + +=> fuse read 4 3 +Reading bank 4: + +Word 0x00000003: 00000004 + +,which matches the ethaddr value: +=> echo ${ethaddr} +00:04:9f:02:77:72 + +Some other useful hints: + +- The 'bank' and 'word' numbers can be easily obtained from the mx6 Reference +Manual. For the mx6quad case, please check the "46.5 OCOTP Memory Map/Register +Definition" from the "i.MX 6Dual/6Quad Applications Processor Reference Manual, +Rev. 1, 04/2013" document. For example, for the MAC fuses we have: + +Address: +21B_C620 Value of OTP Bank4 Word2 (MAC Address)(OCOTP_MAC0) + +21B_C630 Value of OTP Bank4 Word3 (MAC Address)(OCOTP_MAC1) + +- The command '=> fuse read 4 2 2' reads the whole MAC addresses at once: + +=> fuse read 4 2 2 +Reading bank 4: + +Word 0x00000002: 9f027772 00000004 + +NAND Boot on i.MX6 with SPL support +-------------------------------------- + +Writing/updating boot image in nand device is not straight forward in +i.MX6 platform and it requires boot control block(BCB) to be configured. + +BCB contains two data structures, Firmware Configuration Block(FCB) and +Discovered Bad Block Table(DBBT). FCB has nand timings, DBBT search area, +and firmware. See IMX6DQRM Section 8.5.2.2 +for more information. + +We can't use 'nand write' command to write SPL/firmware image directly +like other platforms does. So we need special setup to write BCB block +as per IMX6QDL reference manual 'nandbcb update' command do that job. + +for nand boot, up on reset bootrom look for FCB structure in +first block's if FCB found the nand timings are loaded for +further reads. once FCB read done, DTTB will be loaded and +finally firmware will be loaded which is boot image. + +cmd_nandbcb will create FCB these structures +by taking mtd partition as an example. +- initial code will erase entire partition +- followed by FCB setup, like first 2 blocks for FCB/DBBT write, + and next block for FW1/SPL +- write firmware at FW1 block and +- finally write fcb/dttb in first 2 block. + +Typical NAND BCB layout: +======================= + + no.of blocks = partition size / erasesize + no.of fcb/dbbt blocks = 2 + FW1 offset = no.of fcb/dbbt + +block 0 1 2 + ------------------------------- + |FCB/DBBT 0|FCB/DBBT 1| FW 1 | + -------------------------------- + +On summary, nandbcb update will +- erase the entire partition +- create BCB by creating 2 FCB/BDDT block followed by + 1 FW blocks based on partition size and erasesize. +- fill FCB/DBBT structures +- write FW/SPL in FW1 +- write FCB/DBBT in first 2 blocks + +step-1: write SPL + +icorem6qdl> ext4load mmc 0:1 $loadaddr SPL +39936 bytes read in 10 ms (3.8 MiB/s) + +icorem6qdl> nandbcb update $loadaddr spl $filesize +device 0 offset 0x0, size 0x9c00 +Erasing at 0x1c0000 -- 100% complete. +NAND fw write: 0x80000 offset, 0xb000 bytes written: OK + +step-2: write u-boot-dtb.img + +icorem6qdl> nand erase.part uboot + +NAND erase.part: device 0 offset 0x200000, size 0x200000 +Erasing at 0x3c0000 -- 100% complete. +OK + +icorem6qdl> ext4load mmc 0:1 $loadaddr u-boot-dtb.img +589094 bytes read in 37 ms (15.2 MiB/s) + +icorem6qdl> nand write ${loadaddr} uboot ${filesize} + +NAND write: device 0 offset 0x200000, size 0x8fd26 + 589094 bytes written: OK +icorem6qdl> diff --git a/roms/u-boot/doc/imx/common/mxs.txt b/roms/u-boot/doc/imx/common/mxs.txt new file mode 100644 index 000000000..372062c0e --- /dev/null +++ b/roms/u-boot/doc/imx/common/mxs.txt @@ -0,0 +1,290 @@ +Booting U-Boot on a MXS processor +================================= + +This document describes the MXS U-Boot port. This document mostly covers topics +related to making the module/board bootable. + +Terminology +----------- + +The term "MXS" refers to a family of Freescale SoCs that is composed by MX23 +and MX28. + +The dollar symbol ($) introduces a snipped of shell code. This shall be typed +into the unix command prompt in U-Boot source code root directory. + +The (=>) introduces a snipped of code that should by typed into U-Boot command +prompt + +Contents +-------- + +1) Prerequisites +2) Compiling U-Boot for a MXS based board +3) Installation of U-Boot for a MXS based board to SD card +4) Installation of U-Boot into NAND flash on a MX28 based board +5) Installation of U-Boot into SPI NOR flash on a MX28 based board + +1) Prerequisites +---------------- + +To make a MXS based board bootable, some tools are necessary. The only +mandatory tool is the "mxsboot" tool found in U-Boot source tree. The +tool is built automatically when compiling U-Boot for i.MX23 or i.MX28. + +The production of BootStream image is handled via "mkimage", which is +also part of the U-Boot source tree. The "mkimage" requires OpenSSL +development libraries to be installed. In case of Debian and derivates, +this is installed by running: + + $ sudo apt-get install libssl-dev + +NOTE: The "elftosb" tool distributed by Freescale Semiconductor is no + longer necessary for general use of U-Boot on i.MX23 and i.MX28. + The mkimage supports generation of BootStream images encrypted + with a zero key, which is the vast majority of use-cases. In + case you do need to produce image encrypted with non-zero key + or other special features, please use the "elftosb" tool, + otherwise continue to section 2). The installation procedure of + the "elftosb" is outlined below: + +Firstly, obtain the elftosb archive from the following location: + + ftp://ftp.denx.de/pub/tools/elftosb-10.12.01.tar.gz + +We use a $VER variable here to denote the current version. At the time of +writing of this document, that is "10.12.01". To obtain the file from command +line, use: + + $ VER="10.12.01" + $ wget http://repository.timesys.com/buildsources/e/elftosb/elftosb-10.12.01/elftosb-${VER}.tar.gz + +Extract the file: + + $ tar xzf elftosb-${VER}.tar.gz + +Compile the file. We need to manually tell the linker to use also libm: + + $ cd elftosb-${VER}/ + $ make LIBS="-lstdc++ -lm" elftosb + +Optionally, remove debugging symbols from elftosb: + + $ strip bld/linux/elftosb + +Finally, install the "elftosb" binary. The "install" target is missing, so just +copy the binary by hand: + + $ sudo cp bld/linux/elftosb /usr/local/bin/ + +Make sure the "elftosb" binary can be found in your $PATH, in this case this +means "/usr/local/bin/" has to be in your $PATH. + +2) Compiling U-Boot for a MXS based board +------------------------------------------- + +Compiling the U-Boot for a MXS board is straightforward and done as compiling +U-Boot for any other ARM device. For cross-compiler setup, please refer to +ELDK5.0 documentation. First, clean up the source code: + + $ make mrproper + +Next, configure U-Boot for a MXS based board + + $ make <mxs_based_board_name>_config + +Examples: + +1. For building U-Boot for Aries M28EVK board: + + $ make m28evk_config + +2. For building U-Boot for Freescale MX28EVK board: + + $ make mx28evk_config + +3. For building U-Boot for Freescale MX23EVK board: + + $ make mx23evk_config + +4. For building U-Boot for Olimex MX23 Olinuxino board: + + $ make mx23_olinuxino_config + +Lastly, compile U-Boot and prepare a "BootStream". The "BootStream" is a special +type of file, which MXS CPUs can boot. This is handled by the following +command: + + $ make u-boot.sb + +HINT: To speed-up the build process, you can add -j<N>, where N is number of + compiler instances that'll run in parallel. + +The code produces "u-boot.sb" file. This file needs to be augmented with a +proper header to allow successful boot from SD or NAND. Adding the header is +discussed in the following chapters. + +NOTE: The process that produces u-boot.sb uses the mkimage to generate the + BootStream. The BootStream is encrypted with zero key. In case you need + some special features of the BootStream and plan on using the "elftosb" + tool instead, the invocation to produce a compatible BootStream with the + one produced by mkimage is outlined below. For further details, refer to + the documentation bundled with the "elftosb" package. + + $ elftosb -zf imx23 -c arch/arm/cpu/arm926ejs/mxs/u-boot-imx23.bd \ + -o u-boot.sb + $ elftosb -zf imx28 -c arch/arm/cpu/arm926ejs/mxs/u-boot-imx28.bd \ + -o u-boot.sb + +3) Installation of U-Boot for a MXS based board to SD card +---------------------------------------------------------- + +To boot a MXS based board from SD, set the boot mode DIP switches according to +to MX28 manual, section 12.2.1 (Table 12-2) or MX23 manual, section 35.1.2 +(Table 35-3). + +The SD card used to boot U-Boot must contain a DOS partition table, which in +turn carries a partition of special type and which contains a special header. +The rest of partitions in the DOS partition table can be used by the user. + +To prepare such partition, use your favourite partitioning tool. The partition +must have the following parameters: + + * Start sector .......... sector 2048 + * Partition size ........ at least 1024 kb + * Partition type ........ 0x53 (sometimes "OnTrack DM6 Aux3") + +For example in Linux fdisk, the sequence for a clear card follows. Be sure to +run fdisk with the option "-u=sectors" to set units to sectors: + + * o ..................... create a clear partition table + * n ..................... create new partition + * p ............. primary partition + * 1 ............. first partition + * 2048 .......... first sector is 2048 + * +1M ........... make the partition 1Mb big + * t 1 ................... change first partition ID + * 53 ............ change the ID to 0x53 (OnTrack DM6 Aux3) + * <create other partitions> + * w ..................... write partition table to disk + +The partition layout is ready, next the special partition must be filled with +proper contents. The contents is generated by running the following command +(see chapter 2)): + + $ ./tools/mxsboot sd u-boot.sb u-boot.sd + +The resulting file, "u-boot.sd", shall then be written to the partition. In this +case, we assume the first partition of the SD card is /dev/mmcblk0p1: + + $ dd if=u-boot.sd of=/dev/mmcblk0p1 + +Last step is to insert the card into the MXS based board and boot. + +NOTE: If the user needs to adjust the start sector, the "mxsboot" tool contains + a "-p" switch for that purpose. The "-p" switch takes the sector number as + an argument. + +4) Installation of U-Boot into NAND flash on a MX28 based board +--------------------------------------------------------------- + +To boot a MX28 based board from NAND, set the boot mode DIP switches according +to MX28 manual section 12.2.1 (Table 12-2), PORT=GPMI, NAND 1.8 V. + +There are two possibilities when preparing an image writable to NAND flash. + + I) The NAND wasn't written at all yet or the BCB is broken + ---------------------------------------------------------- + In this case, both BCB (FCB and DBBT) and firmware needs to be + written to NAND. To generate NAND image containing all these, + there is a tool called "mxsboot" in the "tools/" directory. The tool + is invoked on "u-boot.sb" file from chapter 2): + + $ ./tools/mxsboot nand u-boot.sb u-boot.nand + + NOTE: The above invokation works for NAND flash with geometry of + 2048b per page, 64b OOB data, 128kb erase size. If your chip + has a different geometry, please use: + + -w <size> change page size (default 2048 b) + -o <size> change oob size (default 64 b) + -e <size> change erase size (default 131072 b) + + The geometry information can be obtained from running U-Boot + on the MX28 board by issuing the "nand info" command. + + The resulting file, "u-boot.nand" can be written directly to NAND + from the U-Boot prompt. To simplify the process, the U-Boot default + environment contains script "update_nand_full" to update the system. + + This script expects a working TFTP server containing the file + "u-boot.nand" in it's root directory. This can be changed by + adjusting the "update_nand_full_filename" variable. + + To update the system, run the following in U-Boot prompt: + + => run update_nand_full + + In case you would only need to update the bootloader in future, + see II) below. + + II) The NAND was already written with a good BCB + ------------------------------------------------ + This part applies after the part I) above was done at least once. + + If part I) above was done correctly already, there is no need to + write the FCB and DBBT parts of NAND again. It's possible to upgrade + only the bootloader image. + + To simplify the process of firmware update, the U-Boot default + environment contains script "update_nand_firmware" to update only + the firmware, without rewriting FCB and DBBT. + + This script expects a working TFTP server containing the file + "u-boot.sb" in it's root directory. This can be changed by + adjusting the "update_nand_firmware_filename" variable. + + To update the system, run the following in U-Boot prompt: + + => run update_nand_firmware + + III) Special settings for the update scripts + -------------------------------------------- + There is a slight possibility of the user wanting to adjust the + STRIDE and COUNT options of the NAND boot. For description of these, + see MX28 manual section 12.12.1.2 and 12.12.1.3. + + The update scripts take this possibility into account. In case the + user changes STRIDE by blowing fuses, the user also has to change + "update_nand_stride" variable. In case the user changes COUNT by + blowing fuses, the user also has to change "update_nand_count" + variable for the update scripts to work correctly. + + In case the user needs to boot a firmware image bigger than 1Mb, the + user has to adjust the "update_nand_firmware_maxsz" variable for the + update scripts to work properly. + +5) Installation of U-Boot into SPI NOR flash on a MX28 based board +------------------------------------------------------------------ + +The u-boot.sb file can be directly written to SPI NOR from U-Boot prompt. + +Load u-boot.sb into RAM, this can be done in several ways and one way is to use +tftp: + => tftp u-boot.sb 0x42000000 + +Probe the SPI NOR flash: + => sf probe + +(SPI NOR should be succesfully detected in this step) + +Erase the blocks where U-Boot binary will be written to: + => sf erase 0x0 0x80000 + +Write u-boot.sb to SPI NOR: + => sf write 0x42000000 0 0x80000 + +Power off the board and set the boot mode DIP switches to boot from the SPI NOR +according to MX28 manual section 12.2.1 (Table 12-2) + +Last step is to power up the board and U-Boot should start from SPI NOR. diff --git a/roms/u-boot/doc/imx/habv4/csf_examples/additional_images/csf_additional_images.txt b/roms/u-boot/doc/imx/habv4/csf_examples/additional_images/csf_additional_images.txt new file mode 100644 index 000000000..bbe489714 --- /dev/null +++ b/roms/u-boot/doc/imx/habv4/csf_examples/additional_images/csf_additional_images.txt @@ -0,0 +1,34 @@ +[Header] + Version = 4.2 + Hash Algorithm = sha256 + Engine Configuration = 0 + Certificate Format = X509 + Signature Format = CMS + Engine = CAAM + +[Install SRK] + # Index of the key location in the SRK table to be installed + File = "../crts/SRK_1_2_3_4_table.bin" + Source index = 0 + +[Install CSFK] + # Key used to authenticate the CSF data + File = "../crts/CSF1_1_sha256_2048_65537_v3_usr_crt.pem" + +[Authenticate CSF] + +[Install Key] + # Key slot index used to authenticate the key to be installed + Verification index = 0 + # Target key slot in HAB key store where key will be installed + Target Index = 2 + # Key to install + File= "../crts/IMG1_1_sha256_2048_65537_v3_usr_crt.pem" + +[Authenticate Data] + # Key slot index used to authenticate the image data + Verification index = 2 + # Authenticate Start Address, Offset, Length and file + Blocks = 0x80800000 0x00000000 0x80EEA020 "zImage", \ + 0x83800000 0x00000000 0x8380B927 "imx7d-sdb.dtb", \ + 0x84000000 0x00000000 0x840425B8 "uTee-7dsdb" diff --git a/roms/u-boot/doc/imx/habv4/csf_examples/mx6_mx7/csf_uboot.txt b/roms/u-boot/doc/imx/habv4/csf_examples/mx6_mx7/csf_uboot.txt new file mode 100644 index 000000000..39986243e --- /dev/null +++ b/roms/u-boot/doc/imx/habv4/csf_examples/mx6_mx7/csf_uboot.txt @@ -0,0 +1,32 @@ +[Header] + Version = 4.2 + Hash Algorithm = sha256 + Engine Configuration = 0 + Certificate Format = X509 + Signature Format = CMS + Engine = CAAM + +[Install SRK] + # Index of the key location in the SRK table to be installed + File = "../crts/SRK_1_2_3_4_table.bin" + Source index = 0 + +[Install CSFK] + # Key used to authenticate the CSF data + File = "../crts/CSF1_1_sha256_2048_65537_v3_usr_crt.pem" + +[Authenticate CSF] + +[Install Key] + # Key slot index used to authenticate the key to be installed + Verification index = 0 + # Target key slot in HAB key store where key will be installed + Target Index = 2 + # Key to install + File= "../crts/IMG1_1_sha256_2048_65537_v3_usr_crt.pem" + +[Authenticate Data] + # Key slot index used to authenticate the image data + Verification index = 2 + # Authenticate Start Address, Offset, Length and file + Blocks = 0x877ff400 0x00000000 0x0009ec00 "u-boot-dtb.imx" diff --git a/roms/u-boot/doc/imx/habv4/csf_examples/mx6_mx7/csf_uboot_fast_authentication.txt b/roms/u-boot/doc/imx/habv4/csf_examples/mx6_mx7/csf_uboot_fast_authentication.txt new file mode 100644 index 000000000..cdb34bcf7 --- /dev/null +++ b/roms/u-boot/doc/imx/habv4/csf_examples/mx6_mx7/csf_uboot_fast_authentication.txt @@ -0,0 +1,23 @@ +[Header] + Version = 4.2 + Hash Algorithm = sha256 + Engine Configuration = 0 + Certificate Format = X509 + Signature Format = CMS + Engine = CAAM + +[Install SRK] + # Index of the key location in the SRK table to be installed + File = "../crts/SRK_1_2_3_4_table.bin" + Source index = 0 + +[Install NOCAK] + File = "../crts/SRK1_sha256_2048_65537_v3_usr_crt.pem" + +[Authenticate CSF] + +[Authenticate Data] + # Key slot index 0 used to authenticate the image data + Verification index = 0 + # Authenticate Start Address, Offset, Length and file + Blocks = 0x877ff400 0x00000000 0x0009ec00 "u-boot-dtb.imx" diff --git a/roms/u-boot/doc/imx/habv4/guides/encrypted_boot.txt b/roms/u-boot/doc/imx/habv4/guides/encrypted_boot.txt new file mode 100644 index 000000000..e2b435749 --- /dev/null +++ b/roms/u-boot/doc/imx/habv4/guides/encrypted_boot.txt @@ -0,0 +1,43 @@ +1. Setup U-Boot Image for Encrypted Boot +---------------------------------------- +An authenticated U-Boot image is used as starting point for +Encrypted Boot. The image is encrypted by i.MX Code Signing +Tool (CST). The CST replaces only the image data of +u-boot-dtb.imx with the encrypted data. The Initial Vector Table, +DCD, and Boot data, remains in plaintext. + +The image data is encrypted with a Encryption Key (DEK). +Therefore, this key is needed to decrypt the data during the +booting process. The DEK is protected by wrapping it in a Blob, +which needs to be appended to the U-Boot image and specified in +the CSF file. + +The DEK blob is generated by an authenticated U-Boot image with +the dek_blob cmd enabled. The image used for DEK blob generation +needs to have the following configurations enabled in Kconfig: + +CONFIG_IMX_HAB=y +CONFIG_CMD_DEKBLOB=y + +Note: The encrypted boot feature is only supported by HABv4 or +greater. + +The dek_blob command then can be used to generate the DEK blob of +a DEK previously loaded in memory. The command is used as follows: + +dek_blob <DEK address> <Output Address> <Key Size in Bits> +example: dek_blob 0x10800000 0x10801000 192 + +The resulting DEK blob then is used to construct the encrypted +U-Boot image. Note that the blob needs to be transferred back +to the host.Then the following commands are used to construct +the final image. + +cat u-boot-dtb.imx csf-u-boot.bin > u-boot-signed.imx +objcopy -I binary -O binary --pad-to <blob_dst> --gap-fill=0x00 \ + u-boot-signed.imx u-boot-signed-pad.bin +cat u-boot-signed-pad.imx DEK_blob.bin > u-boot-encrypted.imx + + NOTE: u-boot-signed.bin needs to be padded to the value + equivalent to the address in which the DEK blob is specified + in the CSF. diff --git a/roms/u-boot/doc/imx/habv4/guides/mx6_mx7_secure_boot.txt b/roms/u-boot/doc/imx/habv4/guides/mx6_mx7_secure_boot.txt new file mode 100644 index 000000000..53f71fbc3 --- /dev/null +++ b/roms/u-boot/doc/imx/habv4/guides/mx6_mx7_secure_boot.txt @@ -0,0 +1,427 @@ + +=======================================================+ + + i.MX6, i.MX7 U-Boot Secure Boot guide using HABv4 + + +=======================================================+ + +1. HABv4 secure boot process +----------------------------- + +This document describes a step-by-step procedure on how to sign and securely +boot an U-Boot image for non-SPL targets. It is assumed that the reader is +familiar with basic HAB concepts and with the PKI tree generation. + +Details about HAB can be found in the application note AN4581[1] and in the +introduction_habv4.txt document. + +1.1 Building a u-boot-dtb.imx image supporting secure boot +----------------------------------------------------------- + +The U-Boot provides support to secure boot configuration and also provide +access to the HAB APIs exposed by the ROM vector table, the support is +enabled by selecting the CONFIG_IMX_HAB option. + +When built with this configuration, the U-Boot provides extra functions for +HAB, such as the HAB status logs retrievement through the hab_status command +and support for extending the root of trust. + +The U-Boot also correctly pads the final image by aligning to the next 0xC00 +address, so the CSF signature data generated by CST can be concatenated to +image. + +The diagram below illustrate a signed u-boot-dtb.imx image layout: + + ------- +-----------------------------+ <-- *start + ^ | Image Vector Table | + | +-----------------------------+ <-- *boot_data + | | Boot Data | + | +-----------------------------+ <-- *dcd + | | DCD Table | + | +-----------------------------+ + Signed | | Padding | + Data | +-----------------------------+ <-- *entry + | | | + | | | + | | u-boot-dtb.bin | + | | | + | | | + | +-----------------------------+ + v | Padding | + ------- +-----------------------------+ <-- *csf + | | + | Command Sequence File (CSF) | + | | + +-----------------------------+ + | Padding (optional) | + +-----------------------------+ + +1.2 Enabling the secure boot support +------------------------------------- + +The first step is to generate an U-Boot image supporting the HAB features +mentioned above, this can be achieved by adding CONFIG_IMX_HAB to the +build configuration: + +- Defconfig: + + CONFIG_IMX_HAB=y + +- Kconfig: + + ARM architecture -> Support i.MX HAB features + +1.3 Creating the CSF description file +-------------------------------------- + +The CSF contains all the commands that the HAB executes during the secure +boot. These commands instruct the HAB on which memory areas of the image +to authenticate, which keys to install, use and etc. + +CSF examples are available under doc/imx/habv4/csf_examples/ directory. + +A build log containing the "Authenticate Data" parameters is available after +the U-Boot build, the example below is a log for mx7dsabresd_defconfig target: + +- mkimage build log: + + $ cat u-boot-dtb.imx.log + + Image Type: Freescale IMX Boot Image + Image Ver: 2 (i.MX53/6/7 compatible) + Mode: DCD + Data Size: 667648 Bytes = 652.00 KiB = 0.64 MiB + Load Address: 877ff420 + Entry Point: 87800000 + HAB Blocks: 0x877ff400 0x00000000 0x0009ec00 + ^^^^^^^^^^ ^^^^^^^^^^ ^^^^^^^^^^ + | | | + | | ------- (1) + | | + | ------------------ (2) + | + ----------------------------- (3) + + (1) Size of area in file u-boot-dtb.imx to sign. + This area should include the IVT, the Boot Data the DCD + and the U-Boot itself. + (2) Start of area in u-boot-dtb.imx to sign. + (3) Start of area in RAM to authenticate. + +- In "Authenticate Data" CSF command users can copy and past the output + addresses: + + Block = 0x877ff400 0x00000000 0x0009ec00 "u-boot-dtb.imx" + +1.4 Signing the U-Boot binary +------------------------------ + +The CST tool is used for singing the U-Boot binary and generating a CSF binary, +users should input the CSF description file created in the step above and +should receive a CSF binary, which contains the CSF commands, SRK table, +signatures and certificates. + +- Create CSF binary file: + + $ ./cst -i csf_uboot.txt -o csf_uboot.bin + +- Append CSF signature to the end of U-Boot image: + + $ cat u-boot-dtb.imx csf_uboot.bin > u-boot-signed.imx + +The u-boot-signed.imx is the signed binary and should be flashed into the boot +media. + +- Flash signed U-Boot binary: + + $ sudo dd if=u-boot-signed.imx of=/dev/sd<x> bs=1K seek=1 && sync + +1.5 Programming SRK Hash +------------------------- + +As explained in AN4581[1] and in introduction_habv4.txt document the SRK Hash +fuse values are generated by the srktool and should be programmed in the +SoC SRK_HASH[255:0] fuses. + +Be careful when programming these values, as this data is the basis for the +root of trust. An error in SRK Hash results in a part that does not boot. + +The U-Boot fuse tool can be used for programming eFuses on i.MX SoCs. + +- Dump SRK Hash fuses values in host machine: + + $ hexdump -e '/4 "0x"' -e '/4 "%X""\n"' SRK_1_2_3_4_fuse.bin + 0x20593752 + 0x6ACE6962 + 0x26E0D06C + 0xFC600661 + 0x1240E88F + 0x1209F144 + 0x831C8117 + 0x1190FD4D + +- Program SRK_HASH[255:0] fuses, using i.MX6 series as example: + + => fuse prog 3 0 0x20593752 + => fuse prog 3 1 0x6ACE6962 + => fuse prog 3 2 0x26E0D06C + => fuse prog 3 3 0xFC600661 + => fuse prog 3 4 0x1240E88F + => fuse prog 3 5 0x1209F144 + => fuse prog 3 6 0x831C8117 + => fuse prog 3 7 0x1190FD4D + +The table below lists the SRK_HASH bank and word according to the i.MX device: + + +-------------------+---------------+---------------+---------------+ + | | i.MX6 Series | i.MX7D/S | i.MX7ULP | + +-------------------+---------------+---------------+---------------+ + | SRK_HASH[31:00] | bank 3 word 0 | bank 6 word 0 | bank 5 word 0 | + +-------------------+---------------+---------------+---------------+ + | SRK_HASH[63:32] | bank 3 word 1 | bank 6 word 1 | bank 5 word 1 | + +-------------------+---------------+---------------+---------------+ + | SRK_HASH[95:64] | bank 3 word 2 | bank 6 word 2 | bank 5 word 2 | + +-------------------+---------------+---------------+---------------+ + | SRK_HASH[127:96] | bank 3 word 3 | bank 6 word 3 | bank 5 word 3 | + +-------------------+---------------+---------------+---------------+ + | SRK_HASH[159:128] | bank 3 word 4 | bank 7 word 0 | bank 5 word 4 | + +-------------------+---------------+---------------+---------------+ + | SRK_HASH[191:160] | bank 3 word 5 | bank 7 word 1 | bank 5 word 5 | + +-------------------+---------------+---------------+---------------+ + | SRK_HASH[223:192] | bank 3 word 6 | bank 7 word 2 | bank 5 word 6 | + +-------------------+---------------+---------------+---------------+ + | SRK_HASH[255:224] | bank 3 word 7 | bank 7 word 3 | bank 5 word 7 | + +-------------------+---------------+---------------+---------------+ + +1.6 Verifying HAB events +------------------------- + +The next step is to verify that the signature attached to U-Boot is +successfully processed without errors. HAB generates events when processing +the commands if it encounters issues. + +The hab_status U-Boot command call the hab_report_event() and hab_status() +HAB API functions to verify the processor security configuration and status. +This command displays any events that were generated during the process. + +Prior to closing the device users should ensure no HAB events were found, as +the example below: + +- Verify HAB events: + + => hab_status + + Secure boot disabled + + HAB Configuration: 0xf0, HAB State: 0x66 + No HAB Events Found! + +1.6.1 Verifying HAB events in i.MX7ULP +--------------------------------------- + +When booting i.MX7ULP in low power or dual boot modes the M4 binary is +authenticated by an independent HAB in M4 ROM code using a +different SRK key set. + +The U-Boot provides a M4 option in hab_status command so users can retrieve +M4 HAB failure and warning events. + +- Verify HAB M4 events: + + => hab_status m4 + + Secure boot disabled + + HAB Configuration: 0xf0, HAB State: 0x66 + No HAB Events Found! + +As HAB M4 API cannot be called from A7 core the command is parsing the M4 HAB +persistent memory region, M4 software should not modify this reserved region. + +Details about HAB persistent memory region can be found in AN12263[2]. + +1.7 Closing the device +----------------------- + +After the device successfully boots a signed image without generating any HAB +events, it is safe to close the device. This is the last step in the HAB +process, and is achieved by programming the SEC_CONFIG[1] fuse bit. + +Once the fuse is programmed, the chip does not load an image that has not been +signed using the correct PKI tree. + +- Program SEC_CONFIG[1] fuse, using i.MX6 series as example: + + => fuse prog 0 6 0x00000002 + +The table below list the SEC_CONFIG[1] bank and word according to the i.MX +device: + + +--------------+-----------------+------------+ + | Device | Bank and Word | Value | + +--------------+-----------------+------------+ + | i.MX6 Series | bank 0 word 6 | 0x00000002 | + +--------------+-----------------+------------+ + | i.MX7D/S | bank 1 word 3 | 0x02000000 | + +--------------+-----------------+------------+ + | i.MX7ULP | bank 29 word 6 | 0x80000000 | + +--------------+-----------------+------------+ + +1.8 Completely secure the device +--------------------------------- + +Additional fuses can be programmed for completely secure the device, more +details about these fuses and their possible impact can be found at AN4581[1]. + +- Program SRK_LOCK, using i.MX6 series as example: + + => fuse prog 0 0 0x4000 + +- Program DIR_BT_DIS, using i.MX6 series as example: + + => fuse prog 0 6 0x8 + +- Program SJC_DISABLE, using i.MX6 series as example: + + => fuse prog 0 6 0x100000 + +- JTAG_SMODE, using i.MX6 series as example: + + => fuse prog 0 6 0xC00000 + +The table below list the SRK_LOCK, DIR_BT_DIS, SJC_DISABLE, and JTAG_SMODE bank +and word according to the i.MX device: + + +--------------+---------------+------------+ + | Device | Bank and Word | Value | + +--------------+---------------+------------+ + | SRK_LOCK | + +-------------------------------------------+ + | i.MX6 Series | bank 0 word 0 | 0x00004000 | + +--------------+---------------+------------+ + | i.MX7D/S | bank 0 word 0 | 0x00000200 | + +--------------+---------------+------------+ + | i.MX7ULP | bank 1 word 1 | 0x00000080 | + +--------------+---------------+------------+ + | DIR_BT_DIS | + +-------------------------------------------+ + | i.MX6 Series | bank 0 word 6 | 0x00000008 | + +--------------+---------------+------------+ + | i.MX7D/S | bank 1 word 3 | 0x08000000 | + +--------------+---------------+------------+ + | i.MX7ULP | bank 1 word 1 | 0x00002000 | + +--------------+---------------+------------+ + | SJC_DISABLE | + +-------------------------------------------+ + | i.MX6 Series | bank 0 word 6 | 0x00100000 | + +--------------+---------------+------------+ + | i.MX7D/S | bank 1 word 3 | 0x00200000 | + +--------------+---------------+------------+ + | i.MX7ULP | bank 1 word 1 | 0x00000020 | + +--------------+---------------+------------+ + | JTAG_SMODE | + +-------------------------------------------+ + | i.MX6 Series | bank 0 word 6 | 0x00C00000 | + +--------------+---------------+------------+ + | i.MX7D/S | bank 1 word 3 | 0x00C00000 | + +--------------+---------------+------------+ + | i.MX7ULP | bank 1 word 1 | 0x000000C0 | + +--------------+---------------+------------+ + +2. Extending the root of trust +------------------------------- + +The High Assurance Boot (HAB) code located in the on-chip ROM provides an +Application Programming Interface (API) making it possible to call back +into the HAB code for authenticating additional boot images. + +The U-Boot supports this feature and can be used to authenticate the Linux +Kernel Image. + +The process of signing an additional image is similar to the U-Boot. +The diagram below illustrate the zImage layout: + + ------- +-----------------------------+ <-- *load_address + ^ | | + | | | + | | | + | | | + | | zImage | + Signed | | | + Data | | | + | | | + | +-----------------------------+ + | | Padding Next Boundary | + | +-----------------------------+ <-- *ivt + v | Image Vector Table | + ------- +-----------------------------+ <-- *csf + | | + | Command Sequence File (CSF) | + | | + +-----------------------------+ + | Padding (optional) | + +-----------------------------+ + +2.1 Padding the image +---------------------- + +The zImage must be padded to the next boundary address (0x1000), for instance +if the image size is 0x649920 it must be padded to 0x64A000. + +The tool objcopy can be used for padding the image. + +- Pad the zImage: + + $ objcopy -I binary -O binary --pad-to 0x64A000 --gap-fill=0x00 \ + zImage zImage_pad.bin + +2.2 Generating Image Vector Table +---------------------------------- + +The HAB code requires an Image Vector Table (IVT) for determining the image +length and the CSF location. Since zImage does not include an IVT this has +to be manually created and appended to the end of the padded zImage, the +script genIVT.pl in script_examples directory can be used as reference. + +- Generate IVT: + + $ genIVT.pl + +Note: The load Address may change depending on the device. + +- Append the ivt.bin at the end of the padded zImage: + + $ cat zImage_pad.bin ivt.bin > zImage_pad_ivt.bin + +2.3 Signing the image +---------------------- + +A CSF file has to be created to sign the image. HAB does not allow to change +the SRK once the first image is authenticated, so the same SRK key used in +U-Boot must be used when extending the root of trust. + +CSF examples are available in ../csf_examples/additional_images/ +directory. + +- Create CSF binary file: + + $ ./cst --i csf_additional_images.txt --o csf_zImage.bin + +- Attach the CSF binary to the end of the image: + + $ cat zImage_pad_ivt.bin csf_zImage.bin > zImage_signed.bin + +2.4 Verifying HAB events +------------------------- + +The U-Boot includes the hab_auth_img command which can be used for +authenticating and troubleshooting the signed image, zImage must be +loaded at the load address specified in the IVT. + +- Authenticate additional image: + + => hab_auth_img <Load Address> <Image Size> <IVT Offset> + +If no HAB events were found the zImage is successfully signed. + +References: +[1] AN4581: "Secure Boot on i.MX 50, i.MX 53, i.MX 6 and i.MX 7 Series using + HABv4" - Rev 2. +[2] AN12263: "HABv4 RVT Guidelines and Recommendations" - Rev 0. diff --git a/roms/u-boot/doc/imx/habv4/guides/mx6_mx7_spl_secure_boot.txt b/roms/u-boot/doc/imx/habv4/guides/mx6_mx7_spl_secure_boot.txt new file mode 100644 index 000000000..fde0f27ef --- /dev/null +++ b/roms/u-boot/doc/imx/habv4/guides/mx6_mx7_spl_secure_boot.txt @@ -0,0 +1,181 @@ + +===============================================================+ + + i.MX6, i.MX7 U-Boot HABv4 Secure Boot guide for SPL targets + + +===============================================================+ + +1. HABv4 secure boot process +----------------------------- + +This document is an addendum of mx6_mx7_secure_boot.txt guide describing a +step-by-step procedure on how to sign and securely boot an U-Boot image for +SPL targets. + +Details about HAB can be found in the application note AN4581[1] and in the +introduction_habv4.txt document. + +1.1 Building a SPL target supporting secure boot +------------------------------------------------- + +The U-Boot provides Second Program Loader (SPL) support which generates two +final images, SPL and U-Boot proper. The HABv4 can be used to authenticate +both binaries. + +Out of reset the ROM code authenticates the SPL which is responsible for +initializing essential features such as DDR, UART, PMIC and clock +enablement. Once the DDR is available, the SPL code loads the U-Boot proper +image to its specific execution address and call the HAB APIs to extend the +root of trust. + +The U-Boot provides support to secure boot configuration and also provide +access to the HAB APIs exposed by the ROM vector table, the support is +enabled by selecting the CONFIG_IMX_HAB option. + +When built with this configuration the U-Boot correctly pads the final SPL +image by aligning to the next 0xC00 address, so the CSF signature data +generated by CST can be concatenated to the image. + +The U-Boot also append an Image Vector Table (IVT) in the final U-Boot proper +binary (u-boot-ivt.img) so it can be used by HAB API in a post ROM stage. + +The diagram below illustrate a signed SPL image layout: + + ------- +-----------------------------+ <-- *start + ^ | Image Vector Table | + | +-----------------------------+ <-- *boot_data + | | Boot Data | + | +-----------------------------+ + Signed | | Padding | + Data | +-----------------------------+ <-- *entry + | | | + | | SPL | + | | | + | +-----------------------------+ + v | Padding | + ------- +-----------------------------+ <-- *csf + | | + | Command Sequence File (CSF) | + | | + +-----------------------------+ + | Padding (optional) | + +-----------------------------+ + +The diagram below illustrate a signed u-boot-ivt.img image layout: + + ------- +-----------------------------+ <-- *load_address + ^ | | + | | | + | | u-boot.img | + Signed | | | + Data | | | + | +-----------------------------+ + | | Padding Next Boundary | + | +-----------------------------+ <-- *ivt + v | Image Vector Table | + ------- +-----------------------------+ <-- *csf + | | + | Command Sequence File (CSF) | + | | + +-----------------------------+ + | Padding (optional) | + +-----------------------------+ + +1.2 Enabling the secure boot support +------------------------------------- + +The first step is to generate an U-Boot image supporting the HAB features +mentioned above, this can be achieved by adding CONFIG_IMX_HAB to the +build configuration: + +- Defconfig: + + CONFIG_IMX_HAB=y + +- Kconfig: + + ARM architecture -> Support i.MX HAB features + +1.3 Creating the CSF description file +-------------------------------------- + +The CSF contains all the commands that the HAB executes during the secure +boot. These commands instruct the HAB code on which memory areas of the image +to authenticate, which keys to install, use and etc. + +CSF examples are available under doc/imx/habv4/csf_examples/ directory. + +Build logs containing the "Authenticate Data" parameters are available after +the U-Boot build, the example below is a log for mx6sabresd_defconfig target: + +- SPL build log: + + $ cat SPL.log + Image Type: Freescale IMX Boot Image + Image Ver: 2 (i.MX53/6/7 compatible) + Mode: DCD + Data Size: 69632 Bytes = 68.00 KiB = 0.07 MiB + Load Address: 00907420 + Entry Point: 00908000 + HAB Blocks: 0x00907400 0x00000000 0x0000ec00 + +- u-boot-ivt.img build log: + + $ cat u-boot-ivt.img.log + Image Name: U-Boot 2019.01-00003-g78ee492eb3 + Created: Mon Jan 14 17:58:10 2019 + Image Type: ARM U-Boot Firmware with HABv4 IVT (uncompressed) + Data Size: 458688 Bytes = 447.94 KiB = 0.44 MiB + Load Address: 17800000 + Entry Point: 00000000 + HAB Blocks: 0x177fffc0 0x0000 0x0006e020 + +As explained in section above the SPL is first authenticated by the ROM code +and the root of trust is extended to the U-Boot image, hence two CSF files are +necessary to completely sign a bootloader image. + +In "Authenticate Data" CSF command users can copy and past the output +addresses, the csf_uboot.txt can be used as example: + +- In csf_SPL.txt: + + Block = 0x00907400 0x00000000 0x0000ec00 "SPL" + +- In csf_uboot-ivt.txt: + + Block = 0x177fffc0 0x0000 0x0006e020 "u-boot-ivt.img" + +1.4 Signing the images +----------------------- + +The CST tool is used for singing the U-Boot binary and generating a CSF binary, +users should input the CSF description file created in the step above and +receive a CSF binary, which contains the CSF commands, SRK table, signatures +and certificates. + +- Create SPL CSF binary file: + + $ ./cst -i csf_SPL.txt -o csf_SPL.bin + +- Append CSF signature to the end of SPL image: + + $ cat SPL csf_SPL.bin > SPL-signed + +- Create U-Boot proper CSF binary file: + + $ ./cst -i csf_uboot-ivt.txt -o csf_uboot-ivt.bin + +- Append CSF signature to the end of U-Boot proper image: + + $ cat u-boot-ivt.img csf_uboot-ivt.bin > u-boot-signed.img + +The bootloader is signed and can be flashed into the boot media. + +1.5 Closing the device +----------------------- + +The procedure for closing the device is similar as in Non-SPL targets, for a +complete procedure please refer to section "1.5 Programming SRK Hash" in +mx6_mx7_secure_boot.txt document available under doc/imx/habv4/guides/ +directory. + +References: +[1] AN4581: "Secure Boot on i.MX 50, i.MX 53, i.MX 6 and i.MX 7 Series using + HABv4" - Rev 2. diff --git a/roms/u-boot/doc/imx/habv4/introduction_habv4.txt b/roms/u-boot/doc/imx/habv4/introduction_habv4.txt new file mode 100644 index 000000000..25711bbe9 --- /dev/null +++ b/roms/u-boot/doc/imx/habv4/introduction_habv4.txt @@ -0,0 +1,262 @@ + +=======================================================+ + + i.MX Secure and Encrypted Boot using HABv4 + + +=======================================================+ + +1. Introduction +---------------- + +The i.MX family of applications processors provides the High Assurance Boot +(HAB) feature in the on-chip ROM. The ROM is responsible for loading the +initial program image (U-Boot) from the boot media and HAB enables the ROM +to authenticate and/or decrypt the program image by using cryptography +operations. + +This feature is supported in i.MX 50, i.MX 53, i.MX 6, i.MX 7 series and + i.MX 8M, i.MX 8MM devices. + +Step-by-step guides are available under doc/imx/habv4/guides/ directory, +users familiar with HAB and CST PKI tree generation should refer to these +documents instead. + +1.1 The HABv4 Secure Boot Architecture +--------------------------------------- + +The HABv4 secure boot feature uses digital signatures to prevent unauthorized +software execution during the device boot sequence. In case a malware takes +control of the boot sequence, sensitive data, services and network can be +impacted. + +The HAB authentication is based on public key cryptography using the RSA +algorithm in which image data is signed offline using a series of private +keys. The resulting signed image data is then verified on the i.MX processor +using the corresponding public keys. The public keys are included in the CSF +binary and the SRK Hash is programmed in the SoC fuses for establishing the +root of trust. + +The diagram below illustrate the secure boot process overview: + + Host PC + CST i.MX + HAB + +----------+ +----------+ + ---> | U-Boot | | Compare | + | +----------+ +----------+ + | | ^ ^ + | v Reference / \ Generated + | +----------+ Hash / \ Hash + | | Hash | Private / \ + | +----------+ Key / \ + | | | +----------+ +----------+ + | v | | Verify | | Hash | + | +----------+ | +----------+ +----------+ + | | Sign | <--- SRK ^ ^ + | +----------+ HASH \ / + | | | CSF \ / U-Boot + | v v \ / + | +----------+ +----------+ +----------+ + | | U-Boot | | | | U-Boot | + ---> | + | -----> | i.MX | -----> | + | + | CSF | | | | CSF | + +----------+ +----------+ +----------+ + +The U-Boot image to be programmed into the boot media needs to be properly +constructed i.e. it must contain a proper Command Sequence File (CSF). + +The CSF is a binary data structure interpreted by the HAB to guide +authentication process, this is generated by the Code Signing Tool[1]. +The CSF structure contains the commands, SRK table, signatures and +certificates. + +Details about the Secure Boot and Code Signing Tool (CST) can be found in +the application note AN4581[2] and in the secure boot guides. + +1.2 The HABv4 Encrypted Boot Architecture +------------------------------------------ + +The HAB Encrypted Boot feature available in CAAM supported devices adds an +extra security operation to the bootloading sequence. It uses cryptographic +techniques (AES-CCM) to obscure the U-Boot data, so it cannot be seen or used +by unauthorized users. This mechanism protects the U-Boot code residing on +flash or external memory and also ensures that the final image is unique +per device. + +The process can be divided into two protection mechanisms. The first mechanism +is the bootloader code encryption which provides data confidentiality and the +second mechanism is the digital signature, which authenticates the encrypted +image. + +Keep in mind that the encrypted boot makes use of both mechanisms whatever the +order is (sign and then encrypt, or encrypt and then sign), both operations +can be applied on the same region with exception of the U-Boot Header (IVT, +boot data and DCD) which can only be signed, not encrypted. + +The diagram below illustrate the encrypted boot process overview: + + Host PC + CST i.MX + HAB + +------------+ +--------------+ + | U-Boot | | U-Boot | + +------------+ +--------------+ + | ^ + | | + v DEK +--------------+ + +------------+ | ----> | Decrypt | + | Encrypt | <--- | +--------------+ + +------------+ DEK | ^ + | | | + | Private | | + v Key +------+ +--------------+ + +------------+ | | CAAM | | Authenticate | + | Sign | <--- +------+ +--------------+ + +------------+ DEK ^ ^ + | + OTPMK DEK \ / U-Boot + | | Blob \ / + CSF + v v \ / + +------------+ +----------+ +------------+ + | Enc U-Boot | | | | Enc U-Boot | + | + CSF | ----> | i.MX | -------> | + CSF | + | + DEK Blob | | | | + DEK Blob | + +------------+ +----------+ +------------+ + ^ | + | | + --------------------- + DEK Blob + (CAAM) + +The Code Signing Tool automatically generates a random AES Data Encryption Key +(DEK) when encrypting an image. This key is used in both encrypt and decrypt +operations and should be present in the final image structure encapsulated +by a CAAM blob. + +The OTP Master Key (OTPMK) is used to encrypt and wrap the DEK in a blob +structure. The OTPMK is unique per device and can be accessed by CAAM only. +To further add to the security of the DEK, the blob is decapsulated and +decrypted inside a secure memory partition that can only be accessed by CAAM. + +During the design of encrypted boot using DEK blob, it is necessary to inhibit +any modification or replacement of DEK blob with a counterfeit one allowing +execution of malicious code. The PRIBLOB setting in CAAM allows secure boot +software to have its own private blobs that cannot be decapsulated or +encapsulated by any other user code, including any software running in trusted +mode. + +Details about DEK Blob generation and PRIBLOB setting can be found in the +encrypted boot guide and application note AN12056[3] . + +2. Generating a PKI tree +------------------------- + +The first step is to generate the private keys and public keys certificates. +The HAB architecture is based in a Public Key Infrastructure (PKI) tree. + +The Code Signing Tools package contains an OpenSSL based key generation script +under keys/ directory. The hab4_pki_tree.sh script is able to generate a PKI +tree containing up to 4 Super Root Keys (SRK) as well as their subordinated +IMG and CSF keys. + +A new PKI tree can be generated by following the example below: + +- Generating 2048-bit PKI tree on CST v3.1.0: + + $ ./hab4_pki_tree.sh + ... + Do you want to use an existing CA key (y/n)?: n + Do you want to use Elliptic Curve Cryptography (y/n)?: n + Enter key length in bits for PKI tree: 2048 + Enter PKI tree duration (years): 5 + How many Super Root Keys should be generated? 4 + Do you want the SRK certificates to have the CA flag set? (y/n)?: y + +The diagram below illustrate the PKI tree: + + +---------+ + | CA | + +---------+ + | + | + --------------------------------------------------- + | | | | + | | | | + v v v v + +--------+ +--------+ +--------+ +--------+ + | SRK1 | | SRK2 | | SRK3 | | SRK4 | + +--------+ +--------+ +--------+ +--------+ + / \ / \ / \ / \ + v v v v v v v v + +----+ +----+ +----+ +----+ +----+ +----+ +----+ +----+ + |CSF1| |IMG1| |CSF2| |IMG2| |CSF3| |IMG3| |CSF4| |IMG4| + +----+ +----+ +----+ +----+ +----+ +----+ +----+ +----+ + +After running the script users can check the private keys under keys/ directory +and their respective X.509v3 public key certificates under crts/ directory. +Those files will be used during the signing and authentication process. + +2.1 Generating a fast authentication PKI tree +---------------------------------------------- + +Starting in HAB v4.1.2 users can use a single SRK key to authenticate the both +CSF and IMG contents. This reduces the number of key pair authentications that +must occur during the ROM/HAB boot stage, thus providing a faster boot process. + +The script hab4_pki_tree.sh is also able to generate a Public Key Infrastructure +(PKI) tree which only contains SRK Keys, users should not set the CA flag when +generating the SRK certificates. + +- Generating 2048-bit fast authentication PKI tree on CST v3.1.0: + + $ ./hab4_pki_tree.sh + ... + Do you want to use an existing CA key (y/n)?: n + Do you want to use Elliptic Curve Cryptography (y/n)?: n + Enter key length in bits for PKI tree: 2048 + Enter PKI tree duration (years): 5 + How many Super Root Keys should be generated? 4 + Do you want the SRK certificates to have the CA flag set? (y/n)?: n + +The diagram below illustrate the PKI tree generated: + + +---------+ + | CA | + +---------+ + | + | + --------------------------------------------------- + | | | | + | | | | + v v v v + +--------+ +--------+ +--------+ +--------+ + | SRK1 | | SRK2 | | SRK3 | | SRK4 | + +--------+ +--------+ +--------+ +--------+ + +2.2 Generating a SRK Table and SRK Hash +---------------------------------------- + +The next step is to generated the SRK Table and its respective SRK Table Hash +from the SRK public key certificates created in one of the steps above. + +In the HAB architecture, the SRK Table is included in the CSF binary and the +SRK Hash is programmed in the SoC SRK_HASH[255:0] fuses. + +On the target device during the authentication process the HAB code verify the +SRK Table against the SoC SRK_HASH fuses, in case the verification success the +root of trust is established and the HAB code can progress with the image +authentication. + +The srktool can be used for generating the SRK Table and its respective SRK +Table Hash. + +- Generating SRK Table and SRK Hash in Linux 64-bit machines: + + $ ../linux64/bin/srktool -h 4 -t SRK_1_2_3_4_table.bin -e \ + SRK_1_2_3_4_fuse.bin -d sha256 -c \ + SRK1_sha256_2048_65537_v3_ca_crt.pem,\ + SRK2_sha256_2048_65537_v3_ca_crt.pem,\ + SRK3_sha256_2048_65537_v3_ca_crt.pem,\ + SRK4_sha256_2048_65537_v3_ca_crt.pem + +The SRK_1_2_3_4_table.bin and SRK_1_2_3_4_fuse.bin files can be used in further +steps as explained in HAB guides available under doc/imx/habv4/guides/ +directory. + +References: +[1] CST: i.MX High Assurance Boot Reference Code Signing Tool. +[2] AN4581: "Secure Boot on i.MX 50, i.MX 53, i.MX 6 and i.MX 7 Series using + HABv4" - Rev 2. +[3] AN12056: "Encrypted Boot on HABv4 and CAAM Enabled Devices" - Rev. 1 diff --git a/roms/u-boot/doc/imx/habv4/script_examples/genIVT.pl b/roms/u-boot/doc/imx/habv4/script_examples/genIVT.pl new file mode 100644 index 000000000..84a4fcb16 --- /dev/null +++ b/roms/u-boot/doc/imx/habv4/script_examples/genIVT.pl @@ -0,0 +1,12 @@ +#! /usr/bin/perl -w +use strict; +open(my $out, '>:raw', 'ivt.bin') or die "Unable to open: $!"; +print $out pack("V", 0x412000D1); # Signature +print $out pack("V", 0x80800000); # Load Address (*load_address) +print $out pack("V", 0x0); # Reserved +print $out pack("V", 0x0); # DCD pointer +print $out pack("V", 0x0); # Boot Data +print $out pack("V", 0x80EEA000); # Self Pointer (*ivt) +print $out pack("V", 0x80EEA020); # CSF Pointer (*csf) +print $out pack("V", 0x0); # Reserved +close($out); diff --git a/roms/u-boot/doc/imx/index.rst b/roms/u-boot/doc/imx/index.rst new file mode 100644 index 000000000..b225b1d18 --- /dev/null +++ b/roms/u-boot/doc/imx/index.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +NXP i.MX Machine-specific doc +============================= + +.. toctree:: + :maxdepth: 2 + + misc/index diff --git a/roms/u-boot/doc/imx/misc/index.rst b/roms/u-boot/doc/imx/misc/index.rst new file mode 100644 index 000000000..85fbdb658 --- /dev/null +++ b/roms/u-boot/doc/imx/misc/index.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Miscellaneous +============= + +.. toctree:: + :maxdepth: 2 + + psb diff --git a/roms/u-boot/doc/imx/misc/psb.rst b/roms/u-boot/doc/imx/misc/psb.rst new file mode 100644 index 000000000..71ac09fac --- /dev/null +++ b/roms/u-boot/doc/imx/misc/psb.rst @@ -0,0 +1,174 @@ +i.MX7D/i.MX8MM SRC_GPR10 PERSIST_SECONDARY_BOOT for bootloader A/B switching +============================================================================ + +Introduction +------------ +Since at least iMX53 until iMX8MM, it is possible to have two copies of +bootloader in SD/eMMC and switch between them. The switch is triggered +either by the BootROM in case the bootloader image is faulty OR can be +enforced by the user. + +Operation +--------- + #. Upon Power-On Reset (POR) + + - SRC_GPR10 bit PERSIST_SECONDARY_BOOT is set to 0 + - BootROM attempts to start bootloader A-copy + + - if A-copy valid + + - BootROM starts A-copy + - END + + - if A-copy NOT valid + + - BootROM sets SRC_GPR10 bit PERSIST_SECONDARY_BOOT to 1 + - BootROM triggers WARM reset, GOTO 1) + - END + + #. Upon COLD Reset + + - GOTO 1) + - END + + #. Upon WARM Reset + + - SRC_GPR10 bit PERSIST_SECONDARY_BOOT is retained + + - if SRC_GPR10 bit PERSIST_SECONDARY_BOOT is 0 + + - BootROM attempts to start bootloader A-copy + + - if A-copy valid + + - BootROM starts A-copy + - END + + - if A-copy NOT valid + + - BootROM sets SRC_GPR10 bit PERSIST_SECONDARY_BOOT to 1 + - BootROM triggers WARM reset. GOTO 1.3) + - END + + - if SRC_GPR10 bit PERSIST_SECONDARY_BOOT is 1 + + - BootROM attempts to start bootloader B-copy + + - if B-copy valid + + - BootROM starts B-copy + - END + + - if B-copy NOT valid + - System hangs + - END + +Setup +----- +The bootloader A-copy must be placed at predetermined offset in SD/eMMC. The +bootloader B-copy area offset is determined by an offset stored in Secondary +Image Table (SIT). The SIT must be placed at predetermined offset in SD/eMMC. + +The following table contains offset of SIT, bootloader A-copy and recommended +bootloader B-copy offset. The offsets are in 512 Byte sector units (that is +offset 0x1 means 512 Bytes from the start of SD/eMMC card data partition). +For details on the addition of two numbers in recommended B-copy offset, see +SIT format below. + ++----------+--------------------+-----------------------+-----------------------------+ +| SoC | SIT offset (fixed) | A-copy offset (fixed) | B-copy offset (recommended) | ++----------+--------------------+-----------------------+-----------------------------+ +| iMX7D | 0x1 | 0x2 | 0x800+0x2 | ++----------+--------------------+-----------------------+-----------------------------+ +| iMX8MM | 0x41 | 0x42 | 0x1000+0x42 | ++----------+--------------------+-----------------------+-----------------------------+ + +SIT format +~~~~~~~~~~ +SIT is a 20 byte long structure containing of 5 32-bit words. Those encode +bootloader B-copy area offset (called "firstSectorNumber"), magic value +(called "tag") that is always 0x00112233, and three unused words set to 0. +SIT is documented in [1]_ and [2]_. Example SIT are below:: + + $ hexdump -vC sit-mx7d.bin + 00000000 00 00 00 00 + 00000004 00 00 00 00 + 00000008 33 22 11 00 <--- This is the "tag" + 0000000c 00 08 00 00 <--- This is the "firstSectorNumber" + 00000010 00 00 00 00 + + $ hexdump -vC sit-mx8mm.bin + 00000000 00 00 00 00 + 00000004 00 00 00 00 + 00000008 33 22 11 00 <--- This is the "tag" + 0000000c 00 10 00 00 <--- This is the "firstSectorNumber" + 00000010 00 00 00 00 + +B-copy area offset ("firstSectorNumber") is offset, in units of 512 Byte +sectors, that is added to the start of boot media when switching between +A-copy and B-copy. For A-copy, this offset is 0x0. For B-copy, this offset +is determined by SIT (e.g. if firstSectorNumber is 0x1000 as it is above +in sit-mx8mm.bin, then the B-copy offset is 0x1000 sectors = 2 MiB). + +Bootloader A-copy (e.g. u-boot.imx or flash.bin) is placed at fixed offset +from A-copy area offset (e.g. 0x2 sectors from sector 0x0 for iMX7D, which +means u-boot.imx A-copy must be written to sector 0x2). + +The same applies to bootloader B-copy, which is placed at fixed offset from +B-copy area offset determined by SIT (e.g. 0x2 sectors from sector 0x800 [see +sit-mx7d.bin example above, this can be changed in SIT firstSectorNumber] for +iMX7D, which means u-boot.imx B-copy must be written to sector 0x802) + +**WARNING:** +B-copy area offset ("firstSectorNumber") is NOT equal to bootloader +(image, which is u-boot.imx or flash.bin) B-copy offset. + +To generate SIT, use for example the following bourne shell printf command:: + +$ printf '\x0\x0\x0\x0\x0\x0\x0\x0\x33\x22\x11\x00\x00\x08\x00\x00\x0\x0\x0\x0' > sit-mx7d.bin +$ printf '\x0\x0\x0\x0\x0\x0\x0\x0\x33\x22\x11\x00\x00\x10\x00\x00\x0\x0\x0\x0' > sit-mx8mm.bin + +Write bootloader A/B copy and SIT to SD/eMMC +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Examples of writing SIT and two copies of bootloader to SD or eMMC: + +- iMX8MM, SD card at /dev/sdX, Linux command line + :: + + $ dd if=sit-mx8mm.bin of=/dev/sdX bs=512 seek=65 + $ dd if=flash.bin of=/dev/sdX bs=512 seek=66 + $ dd if=flash.bin of=/dev/sdX bs=512 seek=4162 + +- iMX8MM, eMMC 1 data partition, U-Boot command line + :: + + => mmc partconf 1 0 0 0 + + => dhcp ${loadaddr} sit-mx8mm.bin + => mmc dev 1 + => mmc write ${loadaddr} 0x41 0x1 + + => dhcp ${loadaddr} flash.bin + => setexpr blkcnt ${filesize} + 0x1ff && setexpr blkcnt ${blkcnt} / 0x200 + => mmc dev 1 + => mmc write ${loadaddr} 0x42 ${blkcnt} + => mmc write ${loadaddr} 0x1042 ${blkcnt} + +WARM reset into B-copy using WDT +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To perform a reboot into B-copy, the PERSIST_SECONDARY_BOOT must be set +in SRC_GPR0 register. Example on iMX8MM:: + + => mw 0x30390098 0x40000000 + +A WARM reset can be triggered using WDT as follows:: + + => mw.w 0x30280000 0x25 + +References +---------- + +.. [1] i.MX 7Dual Applications Processor Reference Manual, Rev. 1, 01/2018 ; section 6.6.5.3.5 Redundant boot support for expansion device +.. [2] i.MX 8M Mini Applications Processor Reference Manual, Rev. 3, 11/2020 ; section 6.1.5.4.5 Redundant boot support for expansion device diff --git a/roms/u-boot/doc/imx/misc/sdp.txt b/roms/u-boot/doc/imx/misc/sdp.txt new file mode 100644 index 000000000..49b281234 --- /dev/null +++ b/roms/u-boot/doc/imx/misc/sdp.txt @@ -0,0 +1,118 @@ +------------- +SDP in U-Boot +------------- + +SDP stands for serial download protocol. It is the protocol used in NXP's +i.MX SoCs ROM Serial Downloader and provides means to download a program +image to the chip over USB and UART serial connection. + +The implementation in U-Boot uses the USB Downloader Gadget (g_dnl) to +provide a SDP implementation over USB. This allows to download program +images to the target in SPL/U-Boot using the same protocol/tooling the +SoC's recovery mechanism is using. + +The SDP protocol over USB is a USB HID class protocol. USB HID class +protocols allow to access a USB device without OS specific drivers. The +U-Boot implementation has primarly been tested using the open source +imx_loader utility (https://github.com/boundarydevices/imx_usb_loader). + +imx_usb_loader is a very nice tool by Boundary Devices that allow to +install U-Boot without a JTAG debugger, using the USB boot mode as +described in the manual. It is a replacement for Freescale's +MFGTOOLS. + +The host side utilities are typically capable to interpret the i.MX +specific image header (see doc/imx/mkimage/imximage.txt). There are extensions +for imx_loader's imx_usb utility which allow to interpret the U-Boot +specific legacy image format (see mkimage(1)). Also the U-Boot side +support beside the i.MX specific header the U-Boot legacy header. + +1. Using imx_usb_loader for first install with SPL +-------------------------------------------------- + +This implementation can be started in U-Boot using the sdp command +(CONFIG_CMD_USB_SDP) or in SPL if Serial Downloader boot mode has been +detected (CONFIG_SPL_USB_SDP_SUPPORT). + +A typical use case is downloading full U-Boot after SPL has been +downloaded through the boot ROM's Serial Downloader. Using boot mode +detection the SPL will run the SDP implementation automatically in +this case: + + # imx_usb SPL + +Targets Serial Console: + + Trying to boot from USB SDP + SDP: initialize... + SDP: handle requests... + +At this point the SPL reenumerated as a new HID device and emulating +the boot ROM's SDP protocol. The USB VID/PID will depend on standard +U-Boot configurations CONFIG_G_DNL_(VENDOR|PRODUCT)_NUM. Make sure +imx_usb is aware of the USB VID/PID for your device by adding a +configuration entry in imx_usb.conf: + + 0x1b67:0x4fff, mx6_usb_sdp_spl.conf + +And the device specific configuration file mx6_usb_sdp_spl.conf: + + mx6_spl_sdp + hid,uboot_header,1024,0x910000,0x10000000,1G,0x00900000,0x40000 + +This allows to download the regular U-Boot with legacy image headers +(u-boot.img) using a second invocation of imx_usb: + + # imx_usb u-boot.img + +Furthermore, when U-Boot is running the sdp command can be used to +download and run scripts: + + # imx_usb script.scr + +imx_usb configuration files can be also used to download multiple +files and of arbitrary types, e.g. + + mx6_usb_sdp_uboot + hid,1024,0x10000000,1G,0x00907000,0x31000 + full.itb:load 0x12100000 + boot.scr:load 0x12000000,jump 0x12000000 + +There is also a batch mode which allows imx_usb to handle multiple +consecutive reenumerations by adding multiple VID/PID specifications +in imx_usb.conf: + + 0x15a2:0x0061, mx6_usb_rom.conf, 0x1b67:0x4fff, mx6_usb_sdp_spl.conf + +In this mode the file to download (imx_usb job) needs to be specified +in the configuration files. + +mx6_usb_rom.conf: + + mx6_qsb + hid,1024,0x910000,0x10000000,1G,0x00900000,0x40000 + SPL:jump header2 + +mx6_usb_sdp_spl.conf: + + mx6_spl_sdp + hid,uboot_header,1024,0x10000000,1G,0x00907000,0x31000 + u-boot.img:jump header2 + +With that SPL and U-Boot can be downloaded with a single invocation +of imx_usb without arguments: + + # imx_usb + +2. Using imx_usb_loader non-SPL images +--------------------------------------- + +Booting in USB mode, the i.MX6 announces itself to the Linux Host as: + +Bus 001 Device 111: ID 15a2:0061 Freescale Semiconductor, Inc. + +imx_usb_loader is able to download a single file (u-boot.imx) +to the board. For boards without SPL support, it is enough to +issue the command: + + sudo ../imx_usb_loader/imx_usb -v u-boot.imx diff --git a/roms/u-boot/doc/imx/mkimage/imx8image.txt b/roms/u-boot/doc/imx/mkimage/imx8image.txt new file mode 100644 index 000000000..76664a86f --- /dev/null +++ b/roms/u-boot/doc/imx/mkimage/imx8image.txt @@ -0,0 +1,45 @@ +Introduction: +============= + +This documentation entry describes the i.MX8 container format and how +to use. + +A Boot image consists of: + - Primary Boot Container Set + - Optional Secondary Boot Container Set + +The imx8image only support the Primary Boot Container Set. + +The Primary Boot Container Set contains two containers. The 1st container +only contain the SECO firmware image, the 2nd container can contain +multiple images and typically have: + - SCF FW image + - M4 FW image + - AP FW image + +For more details, refer i.MX8 Reference Mannual Chapter 5 +"System Boot and section", "5.9 (Boot image) of the processor's manual" + +Configuration file: +================== +BOOT_FROM [sd|emmc_fastboot|fspi|nand_4k|nand_8k|nand_16k] [sector_size] + - indicates the boot media +SOC_TYPE [IMX8QM|IMX8QX] + - indicates the soc +APPEND [ahab container image] + - indicates the ahah image that will be put in the 1st container + When creating container image will be loaded by SPL, this entry + should not this included +CONTAINER + - indicates to create the 2nd container +IMAGE [SCU|M40|M41|A35|A53|A72] [image file] [load address] + - indicates images will be put in the 2nd container + +Example: +======= +BOOT_FROM SD 0x400 +SOC_TYPE IMX8QM +APPEND mx8qm-ahab-container.img +CONTAINER +IMAGE SCU mx8qm-mek-scfw-tcm.bin +IMAGE A35 spl/u-boot-spl.bin 0x00100000 diff --git a/roms/u-boot/doc/imx/mkimage/imximage.txt b/roms/u-boot/doc/imx/mkimage/imximage.txt new file mode 100644 index 000000000..f2cf23c5d --- /dev/null +++ b/roms/u-boot/doc/imx/mkimage/imximage.txt @@ -0,0 +1,239 @@ +--------------------------------------------- +Imximage Boot Image generation using mkimage +--------------------------------------------- + +This document describes how to set up a U-Boot image that can be booted +by Freescale MX25, MX35, MX51, MX53 and MX6 processors via internal boot +mode. + +These processors can boot directly from NAND, SPI flash and SD card flash +using its internal boot ROM support. MX6 processors additionally support +boot from NOR flash and SATA disks. All processors can boot from an internal +UART, if booting from device media fails. +Booting from NOR flash does not require to use this image type. + +For more details refer Chapter 2 - System Boot and section 2.14 +(flash header description) of the processor's manual. + +Command syntax: +-------------- +./tools/mkimage -l <mx u-boot_file> + to list the imx image file details + +./tools/mkimage -T imximage \ + -n <board specific configuration file> \ + -e <execution address> -d <u-boot binary> <output image file> + +For example, for the mx51evk board: +./tools/mkimage -n ./board/freescale/mx51evk/imximage.cfg \ + -T imximage -e 0x97800000 \ + -d u-boot.bin u-boot.imx + +You can generate directly the image when you compile u-boot with: + +$ make u-boot.imx + +The output image can be flashed on the board SPI flash or on a SD card. +In both cases, you have to copy the image at the offset required for the +chosen media devices (0x400 for both SPI flash or SD card). + +Please check Freescale documentation for further details. + +Board specific configuration file specifications: +------------------------------------------------- +1. This file must present in the $(BOARDDIR) and the name should be + imximage.cfg (since this is used in Makefile). +2. This file can have empty lines and lines starting with "#" as first + character to put comments. +3. This file can have configuration command lines as mentioned below, + any other information in this file is treated as invalid. + +Configuration command line syntax: +--------------------------------- +1. Each command line is must have two strings, first one command or address + and second one data string +2. Following are the valid command strings and associated data strings:- + Command string data string + -------------- ----------- + IMXIMAGE_VERSION 1/2 + 1 is for mx25/mx35/mx51 compatible, + 2 is for mx53/mx6 compatible, + others is invalid and error is generated. + This command need appear the fist before + other valid commands in configuration file. + + BOOT_OFFSET value + + This command is parallel to BOOT_FROM and + is preferred over BOOT_FROM. + + value: Offset of the image header, this + value shall be set to one of the + values found in the file: + arch/arm/include/asm/\ + mach-imx/imximage.cfg + Example: + BOOT_OFFSET FLASH_OFFSET_STANDARD + + BOOT_FROM nand/spi/sd/onenand/nor/sata + + This command is parallel to BOOT_OFFSET and + is to be deprecated in favor of BOOT_OFFSET. + + Example: + BOOT_FROM spi + + CSF value + + Total size of CSF (Command Sequence File) + used for Secure Boot/ High Assurance Boot + (HAB). + + Using this command will populate the IVT + (Initial Vector Table) CSF pointer and adjust + the length fields only. The CSF itself needs + to be generated with Freescale tools and + 'manually' appended to the u-boot.imx file. + + The CSF is then simply concatenated + to the u-boot image, making a signed bootloader, + that the processor can verify + if the fuses for the keys are burned. + + Further infos how to configure the SOC to verify + the bootloader can be found in the "High + Assurance Boot Version Application Programming + Interface Reference Manual" as part of the + Freescale Code Signing Tool, available on the + manufacturer's website. + + Example: + CSF 0x2000 + + DATA type address value + + type: word=4, halfword=2, byte=1 + address: physycal register address + value: value to be set in register + All values are in in hexadecimal. + Example (write to IOMUXC): + DATA 4 0x73FA88a0 0x200 + +The processor support up to 60 register programming commands for IMXIMAGE_VERSION 1 +and 220 register programming commands for IMXIMAGE_VERSION 2. +An error is generated if more commands are found in the configuration file. + +3. All commands are optional to program. + +Setup a SD Card for booting +-------------------------------- + +The following example prepare a SD card with u-boot and a FAT partition +to be used to stored the kernel to be booted. +I will set the SD in the most compatible mode, setting it with +255 heads and 63 sectors, as suggested from several documentation and +howto on line (I took as reference the preparation of a SD Card for the +Beagleboard, running u-boot as bootloader). + +You should start clearing the partitions table on the SD card. Because +the u-boot image must be stored at the offset 0x400, it must be assured +that there is no partition at that address. A new SD card is already +formatted with FAT filesystem and the partition starts from the first +cylinder, so we need to change it. + +You can do all steps with fdisk. If the device for the SD card is +/dev/mmcblk0, the following commands make the job: + +1. Start the fdisk utility (as superuser) + fdisk /dev/mmcblk0 + +2. Clear the actual partition + +Command (m for help): o + +3. Print card info: + +Command (m for help): p +Disk /dev/mmcblk0: 1981 MB, 1981284352 bytes + +In my case, I have a 2 GB card. I need the size to set later the correct value +for the cylinders. + +4. Go to expert mode: + +Command (m for help): x + +5. Set card geometry + +Expert command (m for help): h +Number of heads (1-256, default 4): 255 + +Expert command (m for help): s +Number of sectors (1-63, default 16): 63 +Warning: setting sector offset for DOS compatiblity + +We have set 255 heads, 63 sector. We have to set the cylinder. +The value to be set can be calculated with: + + cylinder = <total size> / <heads> / <sectors> / <blocksize> + +in this example, + 1981284352 / 255 / 63 / 512 = 239.x = 239 + + +Expert command (m for help): c +Number of cylinders (1-1048576, default 60032): 239 + +6. Leave the expert mode +Expert command (m for help): r + +7. Set up a partition + +Now set a partition table to store the kernel or whatever you want. Of course, +you can set additional partitions to store rootfs, data, etc. +In my example I want to set a single partition. I must take care +to not overwrite the space where I will put u-boot. + +Command (m for help): n +Command action + e extended + p primary partition (1-4) +p +Partition number (1-4): 1 +First cylinder (1-239, default 1): 3 +Last cylinder, +cylinders or +size{K,M,G} (3-239, default 239): +100M + +Command (m for help): p + +Disk /dev/mmcblk0: 1967 MB, 1967128576 bytes +255 heads, 63 sectors/track, 239 cylinders +Units = cylinders of 16065 * 512 = 8225280 bytes +Disk identifier: 0xb712a870 + + Device Boot Start End Blocks Id System +/dev/mmcblk0p1 3 16 112455 83 Linux + +I have set 100MB, leaving the first 2 sectors free. I will copy u-boot +there. + +8. Write the partition table and exit. + +Command (m for help): w +The partition table has been altered! + +Calling ioctl() to re-read partition table. + +9. Copy u-boot.imx on the SD card + +I use dd: + +dd if=u-boot.imx of=/dev/mmcblk0 bs=512 seek=2 + +This command copies the u-boot image at the address 0x400, as required +by the processor. + +Now remove your card from the PC and go to the target. If evrything went right, +the u-boot prompt should come after power on. + +------------------------------------------------ +Author: Stefano babic <sbabic@denx.de> diff --git a/roms/u-boot/doc/imx/mkimage/mxsimage.txt b/roms/u-boot/doc/imx/mkimage/mxsimage.txt new file mode 100644 index 000000000..9159f93a9 --- /dev/null +++ b/roms/u-boot/doc/imx/mkimage/mxsimage.txt @@ -0,0 +1,170 @@ +Freescale i.MX233/i.MX28 SB image generator via mkimage +======================================================= + +This tool allows user to produce SB BootStream encrypted with a zero key. +Such a BootStream is then bootable on i.MX23/i.MX28. + +Usage -- producing image: +========================= +The mxsimage tool is targeted to be a simple replacement for the elftosb2 . +To generate an image, write an image configuration file and run: + + mkimage -A arm -O u-boot -T mxsimage -n <path to configuration file> \ + <output bootstream file> + +The output bootstream file is usually using the .sb file extension. Note +that the example configuration files for producing bootable BootStream with +the U-Boot bootloader can be found under arch/arm/boot/cpu/arm926ejs/mxs/ +directory. See the following files: + + mxsimage.mx23.cfg -- This is an example configuration for i.MX23 + mxsimage.mx28.cfg -- This is an example configuration for i.MX28 + +Each configuration file uses very simple instruction semantics and a few +additional rules have to be followed so that a useful image can be produced. +These semantics and rules will be outlined now. + +- Each line of the configuration file contains exactly one instruction. +- Every numeric value must be encoded in hexadecimal and in format 0xabcdef12 . +- The configuration file is a concatenation of blocks called "sections" and + optionally "DCD blocks" (see below), and optional flags lines. + - Each "section" is started by the "SECTION" instruction. + - The "SECTION" instruction has the following semantics: + + SECTION u32_section_number [BOOTABLE] + - u32_section_number :: User-selected ID of the section + - BOOTABLE :: Sets the section as bootable + + - A bootable section is one from which the BootROM starts executing + subsequent instructions or code. Exactly one section must be selected + as bootable, usually the one containing the instructions and data to + load the bootloader. + + - A "SECTION" must be immediatelly followed by a "TAG" instruction. + - The "TAG" instruction has the following semantics: + + TAG [LAST] + - LAST :: Flag denoting the last section in the file + + - After a "TAG" instruction, any of the following instructions may follow + in any order and any quantity: + + NOOP + - This instruction does nothing + + LOAD u32_address string_filename + - Instructs the BootROM to load file pointed by "string_filename" onto + address "u32_address". + + LOAD IVT u32_address u32_IVT_entry_point + - Crafts and loads IVT onto address "u32_address" with the entry point + of u32_IVT_entry_point. + - i.MX28-specific instruction! + + LOAD DCD u32_address u32_DCD_block_ID + - Loads the DCD block with ID "u32_DCD_block_ID" onto address + "u32_address" and executes the contents of this DCD block + - i.MX28-specific instruction! + + FILL u32_address u32_pattern u32_length + - Starts to write memory from addres "u32_address" with a pattern + specified by "u32_pattern". Writes exactly "u32_length" bytes of the + pattern. + + JUMP [HAB] u32_address [u32_r0_arg] + - Jumps onto memory address specified by "u32_address" by setting this + address in PT. The BootROM will pass the "u32_r0_arg" value in ARM + register "r0" to the executed code if this option is specified. + Otherwise, ARM register "r0" will default to value 0x00000000. The + optional "HAB" flag is i.MX28-specific flag turning on the HAB boot. + + CALL [HAB] u32_address [u32_r0_arg] + - See JUMP instruction above, as the operation is exactly the same with + one difference. The CALL instruction does allow returning into the + BootROM from the executed code. U-Boot makes use of this in it's SPL + code. + + MODE string_mode + - Restart the CPU and start booting from device specified by the + "string_mode" argument. The "string_mode" differs for each CPU + and can be: + i.MX23, string_mode = USB/I2C/SPI1_FLASH/SPI2_FLASH/NAND_BCH + JTAG/SPI3_EEPROM/SD_SSP0/SD_SSP1 + i.MX28, string_mode = USB/I2C/SPI2_FLASH/SPI3_FLASH/NAND_BCH + JTAG/SPI2_EEPROM/SD_SSP0/SD_SSP1 + + - An optional "DCD" blocks can be added at the begining of the configuration + file. Note that the DCD is only supported on i.MX28. + - The DCD blocks must be inserted before the first "section" in the + configuration file. + - The DCD block has the following semantics: + + DCD u32_DCD_block_ID + - u32_DCD_block_ID :: The ID number of the DCD block, must match + the ID number used by "LOAD DCD" instruction. + + - The DCD block must be followed by one of the following instructions. All + of the instructions operate either on 1, 2 or 4 bytes. This is selected by + the 'n' suffix of the instruction: + + WRITE.n u32_address u32_value + - Write the "u32_value" to the "u32_address" address. + + ORR.n u32_address u32_value + - Read the "u32_address", perform a bitwise-OR with the "u32_value" and + write the result back to "u32_address". + + ANDC.n u32_address u32_value + - Read the "u32_address", perform a bitwise-AND with the complement of + "u32_value" and write the result back to "u32_address". + + EQZ.n u32_address u32_count + - Read the "u32_address" at most "u32_count" times and test if the value + read is zero. If it is, break the loop earlier. + + NEZ.n u32_address u32_count + - Read the "u32_address" at most "u32_count" times and test if the value + read is non-zero. If it is, break the loop earlier. + + EQ.n u32_address u32_mask + - Read the "u32_address" in a loop and test if the result masked with + "u32_mask" equals the "u32_mask". If the values are equal, break the + reading loop. + + NEQ.n u32_address u32_mask + - Read the "u32_address" in a loop and test if the result masked with + "u32_mask" does not equal the "u32_mask". If the values are not equal, + break the reading loop. + + NOOP + - This instruction does nothing. + + - An optional flags lines can be one of the following: + + DISPLAYPROGRESS + - Enable boot progress output from the BootROM. + +- If the boot progress output from the BootROM is enabled, the BootROM will + produce a letter on the Debug UART for each instruction it started processing. + Here is a mapping between the above instructions and the BootROM output: + + H -- SB Image header loaded + T -- TAG instruction + N -- NOOP instruction + L -- LOAD instruction + F -- FILL instruction + J -- JUMP instruction + C -- CALL instruction + M -- MODE instruction + +Usage -- verifying image: +========================= + +The mxsimage can also verify and dump contents of an image. Use the following +syntax to verify and dump contents of an image: + + mkimage -l <input bootstream file> + +This will output all the information from the SB image header and all the +instructions contained in the SB image. It will also check if the various +checksums in the SB image are correct. |