From: Breno Matheus Lima Date: Wed, 10 Oct 2018 01:10:27 +0000 (+0000) Subject: doc: imx: reorganize i.MX documentation X-Git-Tag: v2018.11-rc3~6^2~20 X-Git-Url: https://git.librecmc.org/?a=commitdiff_plain;h=df11b0c4d4e3ca3821cf4cc6b13fb9fee1d5f891;p=oweals%2Fu-boot.git doc: imx: reorganize i.MX documentation Currently the U-Boot doc/ directory contains the following files that are only relevant for i.MX devices: - doc/README.imx25 - doc/README.imx27 - doc/README.imx5 - doc/README.imx6 - doc/README.imximage - doc/README.mxc_hab - doc/README.mxs - doc/README.mxsimage - doc/README.sdp Move all content to a common i.MX folder for a better documentation structure. Signed-off-by: Breno Lima --- diff --git a/doc/README.imx25 b/doc/README.imx25 deleted file mode 100644 index 0ca21b6dfe..0000000000 --- a/doc/README.imx25 +++ /dev/null @@ -1,10 +0,0 @@ -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/doc/README.imx27 b/doc/README.imx27 deleted file mode 100644 index 6f92cb47ce..0000000000 --- a/doc/README.imx27 +++ /dev/null @@ -1,10 +0,0 @@ -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/doc/README.imx5 b/doc/README.imx5 deleted file mode 100644 index ea0e144ced..0000000000 --- a/doc/README.imx5 +++ /dev/null @@ -1,40 +0,0 @@ -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/doc/README.imx6 b/doc/README.imx6 deleted file mode 100644 index b0644f8491..0000000000 --- a/doc/README.imx6 +++ /dev/null @@ -1,115 +0,0 @@ -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 - -2. Using imx_usb_loader for first install with SPL --------------------------------------------------- - -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 sources can be found here: - - https://github.com/boundarydevices/imx_usb_loader.git - -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 - -In order to load SPL and u-boot.img via imx_usb_loader tool, -please refer to doc/README.sdp. - diff --git a/doc/README.imximage b/doc/README.imximage deleted file mode 100644 index 803682f558..0000000000 --- a/doc/README.imximage +++ /dev/null @@ -1,239 +0,0 @@ ---------------------------------------------- -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 - to list the imx image file details - -./tools/mkimage -T imximage \ - -n \ - -e -d - -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: - - cilynder = / / / - -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 diff --git a/doc/README.mxc_hab b/doc/README.mxc_hab deleted file mode 100644 index a40ebf3e84..0000000000 --- a/doc/README.mxc_hab +++ /dev/null @@ -1,144 +0,0 @@ -1. High Assurance Boot (HAB) for i.MX CPUs ------------------------------------------- - -To enable the authenticated or encrypted boot mode of U-Boot, it is -required to set the proper configuration for the target board. This -is done by adding the following configuration in the defconfig file: - -CONFIG_SECURE_BOOT=y - -In addition, 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 itself is generated by the i.MX High Assurance Boot Reference -Code Signing Tool. -https://www.nxp.com/webapp/sps/download/license.jsp?colCode=IMX_CST_TOOL - -More information about the CSF and HAB can be found in the AN4581. -https://www.nxp.com/docs/en/application-note/AN4581.pdf - -We don't want to explain how to create a PKI tree or SRK table as -this is well explained in the Application Note. - -2. Secure Boot on non-SPL targets ---------------------------------- - -On non-SPL targets a singe U-Boot binary is generated, mkimage will -output additional information about "HAB Blocks" which can be used -in the CST to authenticate the U-Boot image (entries in the CSF file). - -Image Type: Freescale IMX Boot Image -Image Ver: 2 (i.MX53/6 compatible) -Data Size: 327680 Bytes = 320.00 kB = 0.31 MB -Load Address: 177ff420 -Entry Point: 17800000 -HAB Blocks: 0x177ff400 0x00000000 0x0004dc00 - ^^^^^^^^^^ ^^^^^^^^^^ ^^^^^^^^^^ - | | | - | | ----- (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 U-Boot itself. -(2) Start of area in u-boot-dtb.imx to sign -(3) Start of area in RAM to authenticate - -CONFIG_SECURE_BOOT currently enables only an additional command -'hab_status' in U-Boot to retrieve the HAB status and events. This -can be useful while developing and testing HAB. - -Commands to generate a signed U-Boot using i.MX HAB CST tool: -# Compile CSF and create signature -cst --o csf-u-boot.bin --i command_sequence_uboot.csf -# Append compiled CSF to Binary -cat u-boot-dtb.imx csf-u-boot.bin > u-boot-signed.imx - -3. Secure Boot on SPL targets ------------------------------ - -This version of U-Boot is able to build a signable version of the SPL -as well as a signable version of the U-Boot image. The signature can -be verified through High Assurance Boot (HAB). - -After building, you need to create a command sequence file and use -i.MX HAB Code Signing Tool to sign both binaries. After creation, -the mkimage tool outputs the required information about the HAB Blocks -parameter for the CSF. During the build, the information is preserved -in log files named as the binaries. (SPL.log and u-boot-ivt.log). - -Example Output of the SPL (imximage) creation: - Image Type: Freescale IMX Boot Image - Image Ver: 2 (i.MX53/6/7 compatible) - Mode: DCD - Data Size: 61440 Bytes = 60.00 kB = 0.06 MB - Load Address: 00907420 - Entry Point: 00908000 - HAB Blocks: 0x00907400 0x00000000 0x0000cc00 - -Example Output of the u-boot-ivt.img (firmware_ivt) creation: - Image Name: U-Boot 2016.11-rc1-31589-g2a4411 - Created: Sat Nov 5 21:53:28 2016 - Image Type: ARM U-Boot Firmware with HABv4 IVT (uncompressed) - Data Size: 352192 Bytes = 343.94 kB = 0.34 MB - Load Address: 17800000 - Entry Point: 00000000 - HAB Blocks: 0x177fffc0 0x0000 0x00054020 - -# Compile CSF and create signature -cst --o csf-u-boot.bin --i command_sequence_uboot.csf -cst --o csf-SPL.bin --i command_sequence_spl.csf -# Append compiled CSF to Binary -cat SPL csf-SPL.bin > SPL-signed -cat u-boot-ivt.img csf-u-boot.bin > u-boot-signed.img - -These two signed binaries can be used on an i.MX in closed -configuration when the according SRK Table Hash has been flashed. - -4. 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_SECURE_BOOT=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 -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 --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/doc/README.mxs b/doc/README.mxs deleted file mode 100644 index e23ab9cc6d..0000000000 --- a/doc/README.mxs +++ /dev/null @@ -1,290 +0,0 @@ -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 ftp://ftp.denx.de/pub/tools/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 _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, 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) - * - * 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 change page size (default 2048 b) - -o change oob size (default 64 b) - -e 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/doc/README.mxsimage b/doc/README.mxsimage deleted file mode 100644 index c3975ee5e6..0000000000 --- a/doc/README.mxsimage +++ /dev/null @@ -1,170 +0,0 @@ -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 \ - - -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" unstruction, 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 form 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 - -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. diff --git a/doc/README.sdp b/doc/README.sdp deleted file mode 100644 index 178ea688a7..0000000000 --- a/doc/README.sdp +++ /dev/null @@ -1,100 +0,0 @@ -------------- -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). - -The host side utilities are typically capable to interpret the i.MX -specific image header (see doc/README.imximage). 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. - -Usage ------ - -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 diff --git a/doc/imx/README.imx25 b/doc/imx/README.imx25 new file mode 100644 index 0000000000..0ca21b6dfe --- /dev/null +++ b/doc/imx/README.imx25 @@ -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/doc/imx/README.imx27 b/doc/imx/README.imx27 new file mode 100644 index 0000000000..6f92cb47ce --- /dev/null +++ b/doc/imx/README.imx27 @@ -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/doc/imx/README.imx5 b/doc/imx/README.imx5 new file mode 100644 index 0000000000..ea0e144ced --- /dev/null +++ b/doc/imx/README.imx5 @@ -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/doc/imx/README.imx6 b/doc/imx/README.imx6 new file mode 100644 index 0000000000..b0644f8491 --- /dev/null +++ b/doc/imx/README.imx6 @@ -0,0 +1,115 @@ +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 + +2. Using imx_usb_loader for first install with SPL +-------------------------------------------------- + +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 sources can be found here: + + https://github.com/boundarydevices/imx_usb_loader.git + +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 + +In order to load SPL and u-boot.img via imx_usb_loader tool, +please refer to doc/README.sdp. + diff --git a/doc/imx/README.imximage b/doc/imx/README.imximage new file mode 100644 index 0000000000..803682f558 --- /dev/null +++ b/doc/imx/README.imximage @@ -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 + to list the imx image file details + +./tools/mkimage -T imximage \ + -n \ + -e -d + +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: + + cilynder = / / / + +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 diff --git a/doc/imx/README.mxc_hab b/doc/imx/README.mxc_hab new file mode 100644 index 0000000000..a40ebf3e84 --- /dev/null +++ b/doc/imx/README.mxc_hab @@ -0,0 +1,144 @@ +1. High Assurance Boot (HAB) for i.MX CPUs +------------------------------------------ + +To enable the authenticated or encrypted boot mode of U-Boot, it is +required to set the proper configuration for the target board. This +is done by adding the following configuration in the defconfig file: + +CONFIG_SECURE_BOOT=y + +In addition, 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 itself is generated by the i.MX High Assurance Boot Reference +Code Signing Tool. +https://www.nxp.com/webapp/sps/download/license.jsp?colCode=IMX_CST_TOOL + +More information about the CSF and HAB can be found in the AN4581. +https://www.nxp.com/docs/en/application-note/AN4581.pdf + +We don't want to explain how to create a PKI tree or SRK table as +this is well explained in the Application Note. + +2. Secure Boot on non-SPL targets +--------------------------------- + +On non-SPL targets a singe U-Boot binary is generated, mkimage will +output additional information about "HAB Blocks" which can be used +in the CST to authenticate the U-Boot image (entries in the CSF file). + +Image Type: Freescale IMX Boot Image +Image Ver: 2 (i.MX53/6 compatible) +Data Size: 327680 Bytes = 320.00 kB = 0.31 MB +Load Address: 177ff420 +Entry Point: 17800000 +HAB Blocks: 0x177ff400 0x00000000 0x0004dc00 + ^^^^^^^^^^ ^^^^^^^^^^ ^^^^^^^^^^ + | | | + | | ----- (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 U-Boot itself. +(2) Start of area in u-boot-dtb.imx to sign +(3) Start of area in RAM to authenticate + +CONFIG_SECURE_BOOT currently enables only an additional command +'hab_status' in U-Boot to retrieve the HAB status and events. This +can be useful while developing and testing HAB. + +Commands to generate a signed U-Boot using i.MX HAB CST tool: +# Compile CSF and create signature +cst --o csf-u-boot.bin --i command_sequence_uboot.csf +# Append compiled CSF to Binary +cat u-boot-dtb.imx csf-u-boot.bin > u-boot-signed.imx + +3. Secure Boot on SPL targets +----------------------------- + +This version of U-Boot is able to build a signable version of the SPL +as well as a signable version of the U-Boot image. The signature can +be verified through High Assurance Boot (HAB). + +After building, you need to create a command sequence file and use +i.MX HAB Code Signing Tool to sign both binaries. After creation, +the mkimage tool outputs the required information about the HAB Blocks +parameter for the CSF. During the build, the information is preserved +in log files named as the binaries. (SPL.log and u-boot-ivt.log). + +Example Output of the SPL (imximage) creation: + Image Type: Freescale IMX Boot Image + Image Ver: 2 (i.MX53/6/7 compatible) + Mode: DCD + Data Size: 61440 Bytes = 60.00 kB = 0.06 MB + Load Address: 00907420 + Entry Point: 00908000 + HAB Blocks: 0x00907400 0x00000000 0x0000cc00 + +Example Output of the u-boot-ivt.img (firmware_ivt) creation: + Image Name: U-Boot 2016.11-rc1-31589-g2a4411 + Created: Sat Nov 5 21:53:28 2016 + Image Type: ARM U-Boot Firmware with HABv4 IVT (uncompressed) + Data Size: 352192 Bytes = 343.94 kB = 0.34 MB + Load Address: 17800000 + Entry Point: 00000000 + HAB Blocks: 0x177fffc0 0x0000 0x00054020 + +# Compile CSF and create signature +cst --o csf-u-boot.bin --i command_sequence_uboot.csf +cst --o csf-SPL.bin --i command_sequence_spl.csf +# Append compiled CSF to Binary +cat SPL csf-SPL.bin > SPL-signed +cat u-boot-ivt.img csf-u-boot.bin > u-boot-signed.img + +These two signed binaries can be used on an i.MX in closed +configuration when the according SRK Table Hash has been flashed. + +4. 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_SECURE_BOOT=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 +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 --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/doc/imx/README.mxs b/doc/imx/README.mxs new file mode 100644 index 0000000000..e23ab9cc6d --- /dev/null +++ b/doc/imx/README.mxs @@ -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 ftp://ftp.denx.de/pub/tools/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 _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, 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) + * + * 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 change page size (default 2048 b) + -o change oob size (default 64 b) + -e 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/doc/imx/README.mxsimage b/doc/imx/README.mxsimage new file mode 100644 index 0000000000..c3975ee5e6 --- /dev/null +++ b/doc/imx/README.mxsimage @@ -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 \ + + +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" unstruction, 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 form 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 + +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. diff --git a/doc/imx/README.sdp b/doc/imx/README.sdp new file mode 100644 index 0000000000..178ea688a7 --- /dev/null +++ b/doc/imx/README.sdp @@ -0,0 +1,100 @@ +------------- +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). + +The host side utilities are typically capable to interpret the i.MX +specific image header (see doc/README.imximage). 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. + +Usage +----- + +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