[[PageOutline]]

= 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 [wiki:linux/ubi 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: [wiki:jtag_instructions 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:
{{{#!bash
# 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
{{{#!bash
dd if=/dev/mtd1 of=env bs=1M
}}}
  - from U-Boot:
{{{#!bash
# 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)
{{{#!bash
dd if=/dev/mtd2 of=/tmp/ubi bs=4M
}}}
 * From U-Boot
{{{#!bash
# 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)'
{{{#!bash
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:
{{{#!bash
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:
{{{#!bash
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


[=#microsd]
== micro-SD provisioning ==

=== Directly Cloning SD Cards ===
See [wiki:linux/blockdev#Creatingadiskimage 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:
{{{#!bash
# 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:
{{{#!bash
# 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:
{{{#!bash
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:
{{{#!bash
# 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