Provisioning boards

We refer to the act of duplicating a firmware image across multiple boards as Provisioning.

The easiest way to provision boards or removable storage devices is to build the particular BSP you are interested in, and use its tools to create a JTAG image suitable for programming with the Gateworks JTAG dongle (for NAND flash boards) or to create removable storage devices (for NAND-less boards). See linux/ubi.

If however you wish to customize a board's configuration in some way that you have not configured into the build system you will want to boot a board, make your customizations, then pull those customizations off and use them to provision further boards. This is what is presented in detail on this page.

Avila / Cambria / Laguna / Ventana NOR / SPI flash based boards

Products that use NOR and/or SPI flash have the ability to be uploaded to a host PC via the Gateworks GW16042 JTAG dongle and jtag_usb application.

For these products simply configuring a board the way you want it at runtime then uploading the flash to a file provides you with a firmware image that can then be programmed onto other boards.

Please read more about JTAG upload here: JTAG Instructions

Ventana NAND flash based boards

Products that use NAND flash present an issue in that they can contain bad blocks. As a result the raw flash devices can differ in size making it difficult to implement a JTAG flash upload/download scenario.

There are several ways of provisioning NAND bootable boards:

• using JTAG (this is what Gateworks uses on our production line)
• using U-Boot (more complex, much faster than JTAG, but does not allow provisioning the SPL)
• using Linux (even more complex, much faster than JTAG, but allows provisioning the SPL)
• a combination of the above

Regardless of the method used for provisioning there are several artifacts that you need in order to provision NAND:

• SPL (secondary program loader)
• u-boot.img (bootloader)
• env (bootloader env)
• ubi (unsorted block image containing ubifs filesystem)

Pulling Software off of an Existing Board

SPL and Bootloader

The SPL and u-boot.img are built artifacts (which can be downloaded from ​​http://dev.gateworks.com/ventana/images).

Bootloader Environment

The env can be blank, which will use built-in defaults, or can be customized and extracted from the flash.

To create and extract a bootloader env:

1. Create the env on a board:

   # blank per-board vars (which are set from eeprom by default, yet overridable via env)
   setenv fdt_file
   setenv ethaddr
   setenv eth1addr
   # perform any other desired changes
   # save
   saveenv
   

2. Extract the env from the board and save to removable storage:
   • from Linux

     dd if=/dev/mtd1 of=env bs=1M
     

   • from U-Boot:

     # read the env (environment) partition into temporary memory, note the size reported below as 0x100000
     
     Ventana > nand read ${loadaddr} env
     
     NAND read: device 0 offset 0x1000000, size 0x100000
      1048576 bytes read: OK
     Ventana > 
     
     # store it to file on micro-SD with an ext4 fs (size re-used from above)
     mmc dev 0 && ext4write mmc 0:1 ${loadaddr} /env 0x100000
     
     # or store it to file on USB mass storage with an ext4 fs
     usb start && usb dev 0 && ext4write usb 0:1 ${loadaddr} /env 0x100000
     

   • Note that you may find it easier to build yourself a custom bootloader with defaults that match your needs rather than deal with extracting and imaging an env flash partition

Root Filesystem

The ubi root filesystem is originally built by the the build system of the specific BSP your using, however if you end up imaging this onto a board, and customizing it, you may be able to pull it back off as long as your flash size is far less than your memory:

• From Linux assuming /tmp is a tmpfs (ram based) and that you are booted into the filesystem you are copying and you have more ram available than the size of /dev/mtd2 (such as a 256MB flash on a 512MB system)

  dd if=/dev/mtd2 of=/tmp/ubi bs=4M
  

• From U-Boot

  # read the rootfs (filesystem) partition into temporary memory, note the size reported below as 0xef00000
  
  Ventana > nand read ${loadaddr} rootfs
  
  NAND read: device 0 offset 0x1100000, size 0xef00000
   250609664 bytes read: OK
  
  
  # store it to file on micro-SD with an ext4 fs (size re-used from above)
  Ventana > mmc dev 0 && ext4write mmc 0:1 ${loadaddr} /rootfs 0xef00000
  switch to partitions #0, OK
  mmc0 is current device
  File System is consistent
  update journal finished
  250609664 bytes written in 57489 ms (4.2 MiB/s)
  Ventana > 
  
  # or store it to file on USB mass storage with an ext4 fs
  usb start && usb dev 0 && ext4write usb 0:1 ${loadaddr} /rootfs 0xef00000
  

Flashing Boards with Pulled Software

Once you have all the artifacts you can re-assemble them into a JTAG image suitable for the Gateworks JTAG adapter and software. The following usage of mkimage_jtag will create a jtagable image matching the partitioning described by 'mtdparts=nand:16m(uboot),1m(env),-(rootfs)'

mkimage_jtag -e SPL@0 u-boot.img@14M env@16M ubi@17M > image.bin

Or, for a faster two-step method of imaging using U-Boot with serial and ethernet (to a tftp server with the ubi):

1. create a JTAG image of the SPL + bootloader + env:

   mkimage_jtag SPL u-boot.img env > image.bin
   

2. once the above is flashed with the Gateworks JTAG adapter and software you can flash the ubi (much more quickly than via JTAG) within U-Boot
3. break out into the bootloader, transfer the ubi image from a tftp server into SDRAM, and flash it:

   setenv ipaddr 192.168.1.1 # local ip
   setenv serverip 192.168.1.146 # server ip
   tftp ${loadaddr} image.ubi # tftp ubi image
   nand erase.part rootfs # erase the nand partition named rootfs from the mdtparts variable
   nand write ${loadaddr} rootfs ${filesize} # write the downloaded ubi to rootfs
   

Notes:

• you can always elect to build your own bootloader with a custom config rather than pulling the env data off a board

micro-SD provisioning

Directly Cloning SD Cards

See linux/blockdev

U-Boot MicroSD Provisioning

The main difference between provisioning removable storage devices such as micro-SD compared to non-removable storage devices (such as NAND flash) is that the removable devices can be potentially booted on a board with a different model, CPU, or memory configuration. This causes us to treat the U-Boot environment differently when we extract it from a configured board.

If you do not want a blank env (which uses built-in defaults) you must provision one board, boot it to the bootloader, customize your env, then extract that env to use when provisioning additional boards.

The Ventana bootloader stores its microSD env on raw block sectors from offset 709K and is 256K in size.

The env can be blank, which will use built-in defaults, or can be customized and extracted.

To create and extract a bootloader env: (only if this is being used, otherwise skip this step)

1. Create the env on a board:

   # blank per-board vars (which are set from eeprom by default, yet overridable via env)
   setenv fdt_file
   setenv ethaddr
   setenv eth1addr
   # perform any other desired changes
   # save
   saveenv
   

2. extract the env from a board that boots to micro-SD:
   • from Linux:

     # copy 256KB from offset 709KB to 'env' file
     dd if=/dev/sdc of=env bs=1K skip=709 count=256 oflag=sync
     

   • from U-Boot:

     mmc read ${loadaddr} 0x58a 0x200 # read 512x 512byte blocks (256K) from block 0x1418
     # store it to file on micro-SD with an ext4 fs
     ext4write mmc 0:1 ${loadaddr} /mmc.env 0x40000
     # store it to file on USB mass storage with an ext4 fs
     usb start && usb dev 0 && ext4write usb 0:1 ${loadaddr} /mmc.env 0x40000
     

To place an extracted env onto a micro-SD:

• from Linux:

  # copy 256KB from file env to offset 709KB:
  dd if=env of=/dev/sdc bs=1K seek=709 count=256 oflag=sync
  

Other key words

• procure, procurement , copy , jtag upload , production