README 13 KB

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