1 U-Boot for the Gateworks Ventana Product Family boards
3 This file contains information for the port of U-Boot to the Gateworks
4 Ventana Product family boards.
6 The entire Ventana product family (http://www.gateworks.com/product#ventana)
7 is supported by a single bootloader build by using a common SPL and U-Boot
8 that dynamically determines the characterstics of the board at runtime via
9 information from an EEPROM on the board programmed at the factory and supports
10 all of the various boot mediums available.
12 1. Secondary Program Loader (SPL)
13 ---------------------------------
15 The i.MX6 has a BOOT ROM PPL (Primary Program Loader) which supports loading
16 an executable image from various boot devices.
18 The Gateworks Ventana board config uses an SPL build configuration. This
19 will build the following artifacts from U-Boot source:
20 - SPL - Secondary Program Loader that the i.MX6 BOOT ROM (Primary Program
21 Loader) boots. This detects CPU/DRAM configuration, configures
22 The DRAM controller, loads u-boot.img from the detected boot device,
23 and jumps to it. As this is booted from the PPL, it has an IVT/DCD
25 - u-boot.img - The main U-Boot core which is u-boot.bin with a image header.
31 To build U-Boot for the Gateworks Ventana product family:
33 For NAND FLASH based boards:
34 make gwventana_nand_config
37 For EMMC FLASH based boards:
38 make gwventana_emmc_config
45 The Gateworks Ventana boards support booting from NAND or micro-SD depending
46 on the board model. The IMX6 BOOT ROM will choose a boot media based on eFUSE
47 settings programmed at the factory.
49 Boards with NAND flash will always boot from NAND, and NAND-less boards will
50 always boot from micro-SD. However, it is possible to use the U-Boot bmode
51 command (or the technique it uses) to essentially bootstrap to another boot
57 The i.MX6 BOOT ROM expects some structures that provide details of NAND layout
58 and bad block information (referred to as 'bootstreams') which are replicated
59 multiple times in NAND. The number of replications and their spacing (referred
60 to as search stride) is configurable through board strapping options and/or
61 eFUSE settings (BOOT_SEARCH_COUNT / Pages in block from BOOT_CFG2). In
62 addition, the i.MX6 BOOT ROM Flash Configuration Block (FCB) supports two
63 copies of a bootloader in flash in the case that a bad block has corrupted one.
64 The Freescale 'kobs-ng' application from the Freescale LTIB BSP, which runs
65 under Linux and operates on an MTD partition, must be used to program the
66 bootstream in order to setup this flash structure correctly.
68 The Gateworks Ventana boards with NAND flash have been factory programmed
69 such that their eFUSE settings expect 2 copies of the boostream (this is
70 specified by providing kobs-ng with the --search_exponent=1 argument). Once in
71 Linux with MTD support for the NAND on /dev/mtd0 you can program the SPL
74 kobs-ng init -v -x --search_exponent=1 SPL
76 The kobs-ng application uses an imximage which contains the Image Vector Table
77 (IVT) and Device Configuration Data (DCD) structures that the i.MX6 BOOT ROM
78 requires to boot. The kobs-ng adds the Firmware Configuration Block (FCB) and
79 Discovered Bad Block Table (DBBT). The SPL build artifact from U-Boot is
82 The u-boot.img, which is the non SPL U-Boot binary appended to a U-Boot image
83 header must be programmed in the NAND flash boot device at an offset hard
84 coded in the SPL. For the Ventana boards, this has been chosen to be 14MB.
85 The image can be programmed from either U-Boot or Linux:
88 Ventana > setenv mtdparts mtdparts=nand:14m(spl),2m(uboot),1m(env),-(rootfs)
89 Ventana > tftp ${loadaddr} u-boot.img && nand erase.part uboot && \
90 nand write ${loadaddr} uboot ${filesize}
93 nandwrite /dev/mtd1 u-boot.img
95 The above assumes the default Ventana partitioning scheme which is configured
96 via the mtdparts env var:
102 This information is taken from:
103 http://trac.gateworks.com/wiki/ventana/bootloader#nand
105 More details about the i.MX6 BOOT ROM can be found in the IMX6 reference manual.
107 3.1. boot from MMC (eMMC/microSD)
108 ---------------------------------
110 When the IMX6 eFUSE settings have been factory programmed to boot from
111 MMC the SPL will be loaded from offset 0x400 (1KB). Once the SPL is
112 booted, it will load and execute U-Boot (u-boot.img) from offset 69KB
113 on the micro-SD (defined by CONFIG_SYS_MMCSD_RAW_MODE_U_BOOT_SECTOR).
115 While it is technically possible to enable the SPL to be able to load
116 U-Boot from a file on a FAT/EXT filesystem on the micro-SD, we chose to
117 use raw micro-SD access to keep the code-size and boot time of the SPL down.
119 For these reasons an MMC device that will be used as an IMX6 primary boot
120 device must be carefully partitioned and prepared.
122 The following shell commands are executed on a Linux host (adjust DEV to the
123 block storage device of your MMC, ie /dev/mmcblk0):
126 # zero out 1MB of device
127 sudo dd if=/dev/zero of=$DEV count=1 bs=1M oflag=sync status=none && sync
128 # copy SPL to 1KB offset
129 sudo dd if=SPL of=$DEV bs=1K seek=1 oflag=sync status=none && sync
130 # copy U-Boot to 69KB offset
131 sudo dd if=u-boot.img of=$DEV bs=1K seek=69 oflag=sync status=none && sync
132 # create a partition table with a single rootfs partition starting at 1MB
133 printf "1,,L\n" | sudo sfdisk --in-order --no-reread -L -uM $DEV && sync
135 sudo mkfs.ext4 -L root ${DEV}1
136 # mount the partition
137 sudo udisks --mount ${DEV}1
139 sudo tar xvf rootfs.tar.gz -C /media/root
141 sync && sudo umount /media/root
143 The above assumes the default Ventana micro-SD partitioning scheme
144 - spl : 1KB-69KB (68KB) required by IMX6 BOOT ROM
145 - uboot : 69KB-709KB (640KB) defined by
146 CONFIG_SYS_MMCSD_RAW_MODE_U_BOOT_SECTOR
147 - env : 709KB-965KB (256KB) defined by
149 CONFIG_ENV_MMC_OFFSET_REDUND
152 This information is taken from:
153 http://trac.gateworks.com/wiki/ventana/bootloader#microsd
155 More details about the i.MX6 BOOT ROM can be found in the IMX6 reference manual.
158 ------------------------------
160 The Gateworks Ventana board config enables Falcon mode (CONFIG_SPL_OS_BOOT)
161 which allows the SPL to boot directly to an OS instead of to U-Boot
162 (u-boot.img) thus acheiving a faster overall boot time. The time savings
163 depends on your boot medium (ie NAND Flash vs micro-SD) and size/storage
164 of the OS. The time savings can be anywhere from 2 seconds (256MB NAND Flash
165 with ~1MB kernel) to 6 seconds or more (2GB NAND Flash with ~6 kernel)
167 The Gateworks Ventana board supports Falcon mode for the following boot
172 For all boot mediums, raw mode is used. While support of more complex storage
173 such as files on top of FAT/EXT filesystem is possible but not practical
174 as the size of the SPL is fairly limitted (to 64KB based on the smallest
175 size of available IMX6 iRAM) as well as the fact that this would increase
176 OS load time which defeats the purpose of Falcon mode in the first place.
178 The SPL decides to boot either U-Boot (u-boot.img) or the OS (args + kernel)
179 based on the return value of the spl_start_uboot() function. While often
180 this can simply be the state of a GPIO based pushbutton or DIP switch, for
181 Gateworks Ventana, we use an EEPROM register on i2c-0 at 0x50:0x00:
182 set to '0' will choose to boot to U-Boot and otherwise it will boot to OS.
184 To use Falcon mode it is required that you first 'prepare' the 'args' data
185 that is stored on your boot medium along with the kernel (which can be any
186 OS or bare-metal application). In the case of the Linux kernel the 'args'
187 is the flatenned device-tree which normally gets altered prior to booting linux
188 by U-Boot's 'bootm' command. To achieve this for SPL we use the
189 'spl export fdt' command in U-Boot after loading the kernel and dtb which
190 will go through the same process of modifying the device-tree for the board
191 being executed on but not jump to the kernel. This allows you to save the
192 args data to the location the SPL expects it and then enable Falcon mode.
194 It is important to realize that there are certain values in the dtb that
195 are board model specific (IMX6Q vs IMX6DL for example) and board specific
196 (board serial number, MAC addrs) so you do not want to use the 'args'
197 data prepared from one board on another board.
199 4.1. Falcon Mode on NAND flash
200 ------------------------------
201 To prepare a Gateworks Ventana board that boots from NAND flash for Falcon
202 mode you must program your flash such that the 'args' and 'kernel' are
203 located where defined at compile time by the following:
204 CONFIG_CMD_SPL_NAND_OFS 17MB - offset of 'args'
205 CONFIG_SYS_NAND_SPL_KERNEL_OFFS 18MB - offset of 'kernel'
207 The location offsets defined above are defaults chosen by Gateworks and are
208 flexible if you want to re-define them.
210 The following steps executed in U-Boot will configure Falcon mode for NAND
211 using rootfs (ubi), kernel (uImage), and dtb from the network:
213 # change mtd partitions to the above mapping
214 Ventana > setenv mtdparts 'mtdparts=nand:14m(spl),2m(uboot),1m(env),1m(args),10m(kernel),-(rootfs)'
216 # flash rootfs (at 28MB)
217 Ventana > tftp ${loadaddr} rootfs_${flash_layout}.ubi && \
218 nand erase.part rootfs && nand write ${loadaddr} rootfs ${filesize}
220 # load the device-tree
221 Ventana > tftp ${fdt_addr} ventana/${fdt_file2}
224 Ventana > tftp ${loadaddr} ventana/uImage
226 # flash kernel (at 18MB)
227 Ventana > nand erase.part kernel && nand write ${loadaddr} kernel ${filesize}
229 # set kernel args for the console and rootfs (used by spl export)
230 Ventana > setenv bootargs 'console=ttymxc1,115200 root=ubi0:rootfs ubi.mtd=5 rootfstype=ubifs quiet'
232 # create args based on env, board, EEPROM, and dtb
233 Ventana > spl export fdt ${loadaddr} - ${fdt_addr}
235 # flash args (at 17MB)
236 Ventana > nand erase.part args && nand write 18000000 args 100000
238 # set i2c register 0x50:0x00=0 to boot to Linux
239 Ventana > i2c dev 0 && i2c mw 0x50 0x00.0 0 1
241 Be sure to adjust 'bootargs' above to your OS needs (this will be different
242 for various distros such as OpenWrt, Yocto, Android, etc). You can use the
243 value obtained from 'cat /proc/cmdline' when booted to Linux.
245 This information is taken from:
246 http://trac.gateworks.com/wiki/ventana/bootloader/falcon-mode#nand
249 4.2. Falcon Mode on micro-SD card
250 ---------------------------------
252 To prepare a Gateworks Ventana board with a primary boot device of micro-SD
253 you first need to make sure you build U-Boot with CONFIG_ENV_IS_IN_MMC
254 instead of CONFIG_ENV_IS_IN_NAND.
256 For micro-SD based Falcon mode you must program your micro-SD such that
257 the 'args' and 'kernel' are located where defined at compile time
259 CONFIG_SYS_MMCSD_RAW_MODE_ARGS_SECTOR 0x800 (1MB) - offset of 'args'
260 CONFIG_SYS_MMCSD_RAW_MODE_KERNEL_SECTOR 0x1000 (2MB) - offset of 'kernel'
262 The location offsets defined above are defaults chosen by Gateworks and are
263 flexible if you want to re-define them.
265 First you must prepare a micro-SD such that the SPL can be loaded by the
266 IMX6 BOOT ROM (fixed offset of 1KB), and U-Boot can be loaded by the SPL
267 (fixed offset of 69KB defined by CONFIG_SYS_MMCSD_RAW_MODE_U_BOOT_SECTOR).
269 The following shell commands are executed on a Linux host (adjust DEV to the
270 block storage device of your micro-SD):
273 # zero out 1MB of device
274 sudo dd if=/dev/zero of=$DEV count=1 bs=1M oflag=sync status=none && sync
275 # copy SPL to 1KB offset
276 sudo dd if=SPL of=$DEV bs=1K seek=1 oflag=sync status=none && sync
277 # copy U-Boot to 69KB offset
278 sudo dd if=u-boot.img of=$DEV bs=1K seek=69 oflag=sync status=none && sync
279 # create a partition table with a single rootfs partition starting at 10MB
280 printf "10,,L\n" | sudo sfdisk --in-order --no-reread -L -uM $DEV && sync
282 sudo mkfs.ext4 -L root ${DEV}1
283 # mount the partition
284 sudo udisks --mount ${DEV}1
286 sudo tar xvf rootfs.tar.gz -C /media/root
288 sync && sudo umount /media/root
290 Now that your micro-SD partitioning has been adjusted to leave room for the
291 raw 'args' and 'kernel' data boot the board with the prepared micro-SD, break
292 out in U-Boot and use the following to enable Falcon mode:
294 # load device-tree from rootfs
295 Ventana > ext2load mmc 0:1 ${fdt_addr} boot/${fdt_file2}
297 # load kernel from rootfs
298 Ventana > ext2load mmc 0:1 ${loadaddr} boot/uImage
300 # write kernel at 2MB offset
301 Ventana > mmc write ${loadaddr} 0x1000 0x4000
303 # setup kernel bootargs
304 Ventana > setenv bootargs 'console=ttymxc1,115200 root=/dev/mmcblk0p1 rootfstype=ext4 rootwait rw'
307 Ventana > spl export fdt ${loadaddr} - ${fdt_addr}
309 # write args 1MB data (0x800 sectors) to 1MB offset (0x800 sectors)
310 Ventana > mmc write 18000000 0x800 0x800
312 # set i2c register 0x50:0x00=0 to boot to Linux
313 Ventana > i2c dev 0 && i2c mw 0x50 0x00.0 0 1
315 Be sure to adjust 'bootargs' above to your OS needs (this will be different
316 for various distros such as OpenWrt, Yocto, Android, etc). You can use the
317 value obtained from 'cat /proc/cmdline' when booted to Linux.
319 This information is taken from:
320 http://trac.gateworks.com/wiki/ventana/bootloader/falcon-mode#microsd