board/gateworks/gw_ventana/README

   1 U-Boot for the Gateworks Ventana Product Family boards
   2
   3 This file contains information for the port of U-Boot to the Gateworks
   4 Ventana Product family boards.
   5
   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.
  11
  12 1. Secondary Program Loader (SPL)
  13 ---------------------------------
  14
  15 The i.MX6 has a BOOT ROM PPL (Primary Program Loader) which supports loading
  16 an executable image from various boot devices.
  17
  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
  24          table.
  25  - u-boot.img - The main u-boot core which is u-boot.bin with a image header.
  26
  27
  28 2. Build
  29 --------
  30
  31 To build U-Boot for the Gateworks Ventana product family:
  32
  33  make gwventana_config
  34  make
  35
  36
  37 3. Boot source:
  38 ---------------
  39
  40 The Gateworks Ventana boards support booting from NAND or micro-SD depending
  41 on the board model. The IMX6 BOOT ROM will choose a boot media based on eFUSE
  42 settings programmed at the factory.
  43
  44 Boards with NAND flash will always boot from NAND, and NAND-less boards will
  45 always boot from micro-SD. However, it is possible to use the U-Boot bmode
  46 command (or the technique it uses) to essentially bootstrap to another boot
  47 media at runtime.
  48
  49 3.1. boot from NAND
  50 -------------------
  51
  52 The i.MX6 BOOT ROM expects some structures that provide details of NAND layout
  53 and bad block information (referred to as 'bootstreams') which are replicated
  54 multiple times in NAND. The number of replications and their spacing (referred
  55 to as search stride) is configurable through board strapping options and/or
  56 eFUSE settings (BOOT_SEARCH_COUNT / Pages in block from BOOT_CFG2). In
  57 addition, the i.MX6 BOOT ROM Flash Configuration Block (FCB) supports two
  58 copies of a bootloader in flash in the case that a bad block has corrupted one.
  59 The Freescale 'kobs-ng' application from the Freescale LTIB BSP, which runs
  60 under Linux and operates on an MTD partition, must be used to program the
  61 bootstream in order to setup this flash structure correctly.
  62
  63 The Gateworks Ventana boards with NAND flash have been factory programmed
  64 such that their eFUSE settings expect 2 copies of the boostream (this is
  65 specified by providing kobs-ng with the --search_exponent=1 argument). Once in
  66 Linux with MTD support for the NAND on /dev/mtd0 you can program the SPL
  67 with:
  68
  69 kobs-ng init -v -x --search_exponent=1 SPL
  70
  71 The kobs-ng application uses an imximage which contains the Image Vector Table
  72 (IVT) and Device Configuration Data (DCD) structures that the i.MX6 BOOT ROM
  73 requires to boot.  The kobs-ng adds the Firmware Configuration Block (FCB) and
  74 Discovered Bad Block Table (DBBT).  The SPL build artifact from u-boot is
  75 an imximage.
  76
  77 The u-boot.img, which is the non SPL u-boot binary appended to a u-boot image
  78 header must be programmed in the NAND flash boot device at an offset hard
  79 coded in the SPL. For the Ventana boards, this has been chosen to be 14MB.
  80 The image can be programmed from either u-boot or Linux:
  81
  82 u-boot:
  83 Ventana > setenv mtdparts mtdparts=nand:14m(spl),2m(uboot),1m(env),-(rootfs)
  84 Ventana > tftp ${loadaddr} u-boot.img && nand erase.part uboot && \
  85           nand write ${loadaddr} uboot ${filesize}
  86
  87 Linux:
  88 nandwrite /dev/mtd1 u-boot.img
  89
  90 The above assumes the default Ventana partitioning scheme which is configured
  91 via the mtdparts env var:
  92  - spl: 14MB
  93  - uboot: 2M
  94  - env: 1M
  95  - rootfs: the rest
  96
  97 This information is taken from:
  98   http://trac.gateworks.com/wiki/ventana/bootloader#nand
  99
 100 More details about the i.MX6 BOOT ROM can be found in the IMX6 reference manual.
 101
 102 3.1. boot from micro-SD
 103 -----------------------
 104
 105 When the IMX6 eFUSE settings have been factory programmed to boot from
 106 micro-SD the SPL will be loaded from offset 0x400 (1KB). Once the SPL is
 107 booted, it will load and execute U-boot (u-boot.img) from offset 69KB
 108 on the micro-SD (defined by CONFIG_SYS_MMCSD_RAW_MODE_U_BOOT_SECTOR).
 109
 110 While it is technically possible to enable the SPL to be able to load
 111 U-Boot from a file on a FAT/EXT filesystem on the micro-SD, we chose to
 112 use raw micro-SD access to keep the code-size and boot time of the SPL down.
 113
 114 For these reasons a micro-SD that will be used as an IMX6 primary boot
 115 device must be carefully partitioned and prepared.
 116
 117 The following shell commands are executed on a Linux host (adjust DEV to the
 118 block storage device of your micro-SD):
 119
 120  DEV=/dev/sdc
 121  # zero out 1MB of device
 122  sudo dd if=/dev/zero of=$DEV count=1 bs=1M oflag=sync status=none && sync
 123  # copy SPL to 1KB offset
 124  sudo dd if=SPL of=$DEV bs=1K seek=1 oflag=sync status=none && sync
 125  # copy U-Boot to 69KB offset
 126  sudo dd if=u-boot.img of=$DEV bs=1K seek=69 oflag=sync status=none && sync
 127  # create a partition table with a single rootfs partition starting at 1MB
 128  printf "1,,L\n" | sudo sfdisk --in-order --no-reread -L -uM $DEV && sync
 129  # format partition
 130  sudo mkfs.ext4 -L root ${DEV}1
 131  # mount the partition
 132  sudo udisks --mount ${DEV}1
 133  # extract filesystem
 134  sudo tar xvf rootfs.tar.gz -C /media/root
 135  # flush and unmount
 136  sync && sudo umount /media/root
 137
 138 The above assumes the default Ventana micro-SD partitioning scheme
 139  - spl    :   1KB-69KB  (68KB)  required by IMX6 BOOT ROM
 140  - uboot  :  69KB-709KB (640KB) defined by
 141                                 CONFIG_SYS_MMCSD_RAW_MODE_U_BOOT_SECTOR
 142  - env    : 709KB-965KB (256KB) defined by
 143                                 CONFIG_ENV_MMC_SIZE
 144                                 CONFIG_ENV_MMC_OFFSET_REDUND
 145  - rootfs :   1MB-
 146
 147 This information is taken from:
 148   http://trac.gateworks.com/wiki/ventana/bootloader#microsd
 149
 150 More details about the i.MX6 BOOT ROM can be found in the IMX6 reference manual.
 151