From 4ecce8da15117d46339c68ee72dd658fa03a071d Mon Sep 17 00:00:00 2001 From: Breno Lima Date: Thu, 20 Sep 2018 19:45:48 -0300 Subject: MLK-19722-8 doc: imx: Improve i.MX documentation naming There is no need to have README in all i.MX documents name. Remove README from i.MX docs name and add .txt file extension. Signed-off-by: Breno Lima Reviewed-by: Ye Li (cherry picked from commit 49f36f64066b6cd9ac23d08b2b7af63b5ed9717d) --- doc/imx/common/README.imx25 | 10 -- doc/imx/common/README.imx27 | 10 -- doc/imx/common/README.imx5 | 40 ------ doc/imx/common/README.imx6 | 90 ------------- doc/imx/common/README.mxs | 290 ---------------------------------------- doc/imx/common/imx25.txt | 10 ++ doc/imx/common/imx27.txt | 10 ++ doc/imx/common/imx5.txt | 40 ++++++ doc/imx/common/imx6.txt | 90 +++++++++++++ doc/imx/common/mxs.txt | 290 ++++++++++++++++++++++++++++++++++++++++ doc/imx/misc/README.sdp | 118 ---------------- doc/imx/misc/sdp.txt | 118 ++++++++++++++++ doc/imx/mkimage/README.imximage | 239 --------------------------------- doc/imx/mkimage/README.mxsimage | 170 ----------------------- doc/imx/mkimage/imximage.txt | 239 +++++++++++++++++++++++++++++++++ doc/imx/mkimage/mxsimage.txt | 170 +++++++++++++++++++++++ 16 files changed, 967 insertions(+), 967 deletions(-) delete mode 100644 doc/imx/common/README.imx25 delete mode 100644 doc/imx/common/README.imx27 delete mode 100644 doc/imx/common/README.imx5 delete mode 100644 doc/imx/common/README.imx6 delete mode 100644 doc/imx/common/README.mxs create mode 100644 doc/imx/common/imx25.txt create mode 100644 doc/imx/common/imx27.txt create mode 100644 doc/imx/common/imx5.txt create mode 100644 doc/imx/common/imx6.txt create mode 100644 doc/imx/common/mxs.txt delete mode 100644 doc/imx/misc/README.sdp create mode 100644 doc/imx/misc/sdp.txt delete mode 100644 doc/imx/mkimage/README.imximage delete mode 100644 doc/imx/mkimage/README.mxsimage create mode 100644 doc/imx/mkimage/imximage.txt create mode 100644 doc/imx/mkimage/mxsimage.txt diff --git a/doc/imx/common/README.imx25 b/doc/imx/common/README.imx25 deleted file mode 100644 index 0ca21b6dfe..0000000000 --- a/doc/imx/common/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/imx/common/README.imx27 b/doc/imx/common/README.imx27 deleted file mode 100644 index 6f92cb47ce..0000000000 --- a/doc/imx/common/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/imx/common/README.imx5 b/doc/imx/common/README.imx5 deleted file mode 100644 index ea0e144ced..0000000000 --- a/doc/imx/common/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/imx/common/README.imx6 b/doc/imx/common/README.imx6 deleted file mode 100644 index eab88353f6..0000000000 --- a/doc/imx/common/README.imx6 +++ /dev/null @@ -1,90 +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 - diff --git a/doc/imx/common/README.mxs b/doc/imx/common/README.mxs deleted file mode 100644 index e23ab9cc6d..0000000000 --- a/doc/imx/common/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/imx/common/imx25.txt b/doc/imx/common/imx25.txt new file mode 100644 index 0000000000..0ca21b6dfe --- /dev/null +++ b/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/doc/imx/common/imx27.txt b/doc/imx/common/imx27.txt new file mode 100644 index 0000000000..6f92cb47ce --- /dev/null +++ b/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/doc/imx/common/imx5.txt b/doc/imx/common/imx5.txt new file mode 100644 index 0000000000..ea0e144ced --- /dev/null +++ b/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/doc/imx/common/imx6.txt b/doc/imx/common/imx6.txt new file mode 100644 index 0000000000..eab88353f6 --- /dev/null +++ b/doc/imx/common/imx6.txt @@ -0,0 +1,90 @@ +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 + diff --git a/doc/imx/common/mxs.txt b/doc/imx/common/mxs.txt new file mode 100644 index 0000000000..e23ab9cc6d --- /dev/null +++ b/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 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/misc/README.sdp b/doc/imx/misc/README.sdp deleted file mode 100644 index 6ea6e41395..0000000000 --- a/doc/imx/misc/README.sdp +++ /dev/null @@ -1,118 +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). - -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/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. - -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/doc/imx/misc/sdp.txt b/doc/imx/misc/sdp.txt new file mode 100644 index 0000000000..6ea6e41395 --- /dev/null +++ b/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/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. + +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/doc/imx/mkimage/README.imximage b/doc/imx/mkimage/README.imximage deleted file mode 100644 index 803682f558..0000000000 --- a/doc/imx/mkimage/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/imx/mkimage/README.mxsimage b/doc/imx/mkimage/README.mxsimage deleted file mode 100644 index c3975ee5e6..0000000000 --- a/doc/imx/mkimage/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/imx/mkimage/imximage.txt b/doc/imx/mkimage/imximage.txt new file mode 100644 index 0000000000..803682f558 --- /dev/null +++ b/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 + 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/mkimage/mxsimage.txt b/doc/imx/mkimage/mxsimage.txt new file mode 100644 index 0000000000..c3975ee5e6 --- /dev/null +++ b/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 \ + + +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. -- cgit v1.2.3