doc/README.imximage

   1 ---------------------------------------------
   2 Imximage Boot Image generation using mkimage
   3 ---------------------------------------------
   4
   5 This document describes how to set up a U-Boot image that can be booted
   6 by Freescale MX25, MX35, MX51, MX53 and MX6 processors via internal boot
   7 mode.
   8
   9 These processors can boot directly from NAND, SPI flash and SD card flash
  10 using its internal boot ROM support. MX6 processors additionally support
  11 boot from NOR flash and SATA disks. All processors can boot from an internal
  12 UART, if booting from device media fails.
  13 Booting from NOR flash does not require to use this image type.
  14
  15 For more details refer Chapter 2 - System Boot and section 2.14
  16 (flash header description) of the processor's manual.
  17
  18 Command syntax:
  19 --------------
  20 ./tools/mkimage -l <mx u-boot_file>
  21                 to list the imx image file details
  22
  23 ./tools/mkimage -T imximage \
  24                 -n <board specific configuration file> \
  25                 -e <execution address> -d <u-boot binary>  <output image file>
  26
  27 For example, for the mx51evk board:
  28 ./tools/mkimage -n ./board/freescale/mx51evk/imximage.cfg \
  29                 -T imximage -e 0x97800000  \
  30                 -d u-boot.bin u-boot.imx
  31
  32 You can generate directly the image when you compile u-boot with:
  33
  34 $ make u-boot.imx
  35
  36 The output image can be flashed on the board SPI flash or on a SD card.
  37 In both cases, you have to copy the image at the offset required for the
  38 chosen media devices (0x400 for both SPI flash or SD card).
  39
  40 Please check Freescale documentation for further details.
  41
  42 Board specific configuration file specifications:
  43 -------------------------------------------------
  44 1. This file must present in the $(BOARDDIR) and the name should be
  45         imximage.cfg (since this is used in Makefile).
  46 2. This file can have empty lines and lines starting with "#" as first
  47         character to put comments.
  48 3. This file can have configuration command lines as mentioned below,
  49         any other information in this file is treated as invalid.
  50
  51 Configuration command line syntax:
  52 ---------------------------------
  53 1. Each command line is must have two strings, first one command or address
  54         and second one data string
  55 2. Following are the valid command strings and associated data strings:-
  56         Command string          data string
  57         --------------          -----------
  58         IMXIMAGE_VERSION        1/2
  59                                 1 is for mx25/mx35/mx51 compatible,
  60                                 2 is for mx53/mx6 compatible,
  61                                 others is invalid and error is generated.
  62                                 This command need appear the fist before
  63                                 other valid commands in configuration file.
  64
  65         BOOT_OFFSET             value
  66
  67                                 This command is parallel to BOOT_FROM and
  68                                 is preferred over BOOT_FROM.
  69
  70                                 value:  Offset of the image header, this
  71                                         value shall be set to one of the
  72                                         values found in the file:
  73                                                 arch/arm/include/asm/\
  74                                                 mach-imx/imximage.cfg
  75                                 Example:
  76                                 BOOT_OFFSET FLASH_OFFSET_STANDARD
  77
  78         BOOT_FROM               nand/spi/sd/onenand/nor/sata
  79
  80                                 This command is parallel to BOOT_OFFSET and
  81                                 is to be deprecated in favor of BOOT_OFFSET.
  82
  83                                 Example:
  84                                 BOOT_FROM spi
  85
  86         CSF                     value
  87
  88                                 Total size of CSF (Command Sequence File)
  89                                 used for Secure Boot/ High Assurance Boot
  90                                 (HAB).
  91
  92                                 Using this command will populate the IVT
  93                                 (Initial Vector Table) CSF pointer and adjust
  94                                 the length fields only. The CSF itself needs
  95                                 to be generated with Freescale tools and
  96                                 'manually' appended to the u-boot.imx file.
  97
  98                                 The CSF is then simply concatenated
  99                                 to the u-boot image, making a signed bootloader,
 100                                 that the processor can verify
 101                                 if the fuses for the keys are burned.
 102
 103                                 Further infos how to configure the SOC to verify
 104                                 the bootloader can be found in the "High
 105                                 Assurance Boot Version Application Programming
 106                                 Interface Reference Manual" as part of the
 107                                 Freescale Code Signing Tool, available on the
 108                                 manufacturer's website.
 109
 110                                 Example:
 111                                 CSF 0x2000
 112
 113         DATA                    type address value
 114
 115                                 type: word=4, halfword=2, byte=1
 116                                 address: physycal register address
 117                                 value: value to be set in register
 118                                 All values are in in hexadecimal.
 119                                 Example (write to IOMUXC):
 120                                 DATA 4 0x73FA88a0 0x200
 121
 122 The processor support up to 60 register programming commands for IMXIMAGE_VERSION 1
 123 and 220 register programming commands for IMXIMAGE_VERSION 2.
 124 An error is generated if more commands are found in the configuration file.
 125
 126 3. All commands are optional to program.
 127
 128 Setup a SD Card for booting
 129 --------------------------------
 130
 131 The following example prepare a SD card with u-boot and a FAT partition
 132 to be used to stored the kernel to be booted.
 133 I will set the SD in the most compatible mode, setting it with
 134 255 heads and 63 sectors, as suggested from several documentation and
 135 howto on line (I took as reference the preparation of a SD Card for the
 136 Beagleboard, running u-boot as bootloader).
 137
 138 You should start clearing the partitions table on the SD card. Because
 139 the u-boot image must be stored at the offset 0x400, it must be assured
 140 that there is no partition at that address. A new SD card is already
 141 formatted with FAT filesystem and the partition starts from the first
 142 cylinder, so we need to change it.
 143
 144 You can do all steps with fdisk. If the device for the SD card is
 145 /dev/mmcblk0, the following commands make the job:
 146
 147 1. Start the fdisk utility (as superuser)
 148         fdisk /dev/mmcblk0
 149
 150 2. Clear the actual partition
 151
 152 Command (m for help): o
 153
 154 3. Print card info:
 155
 156 Command (m for help): p
 157 Disk /dev/mmcblk0: 1981 MB, 1981284352 bytes
 158
 159 In my case, I have a 2 GB card. I need the size to set later the correct value
 160 for the cylinders.
 161
 162 4. Go to expert mode:
 163
 164 Command (m for help): x
 165
 166 5. Set card geometry
 167
 168 Expert command (m for help): h
 169 Number of heads (1-256, default 4): 255
 170
 171 Expert command (m for help): s
 172 Number of sectors (1-63, default 16): 63
 173 Warning: setting sector offset for DOS compatiblity
 174
 175 We have set 255 heads, 63 sector. We have to set the cylinder.
 176 The value to be set can be calculated with:
 177
 178         cilynder = <total size> / <heads> / <sectors> / <blocksize>
 179
 180 in this example,
 181         1981284352 / 255 / 63 / 512 = 239.x = 239
 182
 183
 184 Expert command (m for help): c
 185 Number of cylinders (1-1048576, default 60032): 239
 186
 187 6. Leave the expert mode
 188 Expert command (m for help): r
 189
 190 7. Set up a partition
 191
 192 Now set a partition table to store the kernel or whatever you want. Of course,
 193 you can set additional partitions to store rootfs, data, etc.
 194 In my example I want to set a single partition. I must take care
 195 to not overwrite the space where I will put u-boot.
 196
 197 Command (m for help): n
 198 Command action
 199    e   extended
 200    p   primary partition (1-4)
 201 p
 202 Partition number (1-4): 1
 203 First cylinder (1-239, default 1): 3
 204 Last cylinder, +cylinders or +size{K,M,G} (3-239, default 239): +100M
 205
 206 Command (m for help): p
 207
 208 Disk /dev/mmcblk0: 1967 MB, 1967128576 bytes
 209 255 heads, 63 sectors/track, 239 cylinders
 210 Units = cylinders of 16065 * 512 = 8225280 bytes
 211 Disk identifier: 0xb712a870
 212
 213         Device Boot      Start         End      Blocks   Id  System
 214 /dev/mmcblk0p1               3          16      112455   83  Linux
 215
 216 I have set 100MB, leaving the first 2 sectors free. I will copy u-boot
 217 there.
 218
 219 8. Write the partition table and exit.
 220
 221 Command (m for help): w
 222 The partition table has been altered!
 223
 224 Calling ioctl() to re-read partition table.
 225
 226 9. Copy u-boot.imx on the SD card
 227
 228 I use dd:
 229
 230 dd if=u-boot.imx of=/dev/mmcblk0 bs=512 seek=2
 231
 232 This command copies the u-boot image at the address 0x400, as required
 233 by the processor.
 234
 235 Now remove your card from the PC and go to the target. If evrything went right,
 236 the u-boot prompt should come after power on.
 237
 238 ------------------------------------------------
 239 Author: Stefano babic <sbabic@denx.de>