FUA Quick Start Guide
RidgeRun Firmware Upgrade Application
RidgeRun's Firmware Upgrade Application (FUA) is a software utility designed to help in the software upgrade process, its main goal is to help the customers to implement a robust and easy to use upgrade utility for their products.
How does it works?
FUA works with fub packages which consist of specially packed files containing the data to be installed in the target device among other optional files, such as bash scripts, allowing the tool to execute actions in the upgrade process automatically.
The fub packages can be transferred to the target by any mean meeting with numerous customer's requirements. Once in the target there are two way to initiate the upgrade process:
a) Manual upgrade execution: FUA can be executed manually allowing any third party process to initiate the upgrade process specifying the fub package to execute.
b) Automatic upgrade execution: FUA implements a FUA Monitor application which is a daemon that will be monitoring a user specified directory. Each time a fub package is copied to this directory FUA validates it and automatically starts the upgrade process.
Key features
FUA has been designed to cover almost all possible upgrade scenarios such as:
- Kernel upgrade
- Entire file system upgrade
- Partial file system upgrade (files upgrade)
- Bootloader upgrade (Note 1)
Additionally it provides some other features such as:
- Checksum verification of the fub packages
- Execution of customized scripts
- Can work together with fall-back partitions for secure upgrade allowing the system to recover from a failed upgrade.
Setting up the environment
Firmware update application
- Start the RR SDK configuration
make config
- Go to:
--> Proprietary software
- Select Firmware update application:
[*] Firmware update application (python)
- Return to Ridgerun SDK Configuration
Firmware Deployment Mode
You select the firmware deployment mode.
- Start the RR SDK configuration
make config
- Go to:
--> Installer Configuration --> Firmware deployment mode
- Press Enter and you will get the following menu:
(X) Attached board on communication port ( ) Deploy all the firmware to an SD card ( ) Create an SD card installer for flash memory
- Select Attached board on communication port.
- Return to Ridgerun SDK Configuration
Filesystem Mode
You can select File system target image configuration
- Go to:
--> File System Configuration ---> File system image target
- Press Enter and you will get the following menu:
( ) Initramfs filesystem ( ) JFFS2 disk image ( ) NFS root file system ( ) Secure Digital Card (X) UBIFS volume
- Select UBIFS volume (Note 2).
- Exit and save the RR SDK configuration.
- Build the SDK or rebuild if you built the SDK previously.
Build Filesystem Image
This method allows to build filesystem image without to have target in your hands.
- Go to SDK:
cd $DEVDIR
- Start the RR SDK configuration
make config
- Go to:
--> Installer Configuration
- Press Enter and you must search these options:
*** NAND size options *** () Nand Block Size () Nand Page Size
- Select each one and type the values required like these:
*** NAND size options *** (131072) Nand Block Size (2048) Nand Page Size
Note: you can find how to determine NAND Block Size and NAND Page Size, go to How to get NAND size options section.
- Exit and save the RR SDK configuration.
- Build the SDK or rebuild if you built the SDK previously
- Build filesystem image with follows:
make ubifs_image
- After that, go to:
cd $DEVDIR/image
- Type this:
ls -lh fsimage*
You should get something as follow:
-rw-rw-r-- 1 $USER $USER 44M May 12 15:05 fsimage -rw-rw-r-- 1 $USER $USER 44M May 12 15:05 fsimage.uImage
Note:The filesystem image size depends of the applications that you have selected.
Generating fub packages
In order to create fub packages you will need fua.py script, you can find into $(DEVDIR)/fua-tools-1.0.
The fub packages are created with a python script, this script has its own help menu, the help menu can be deployed with the -h option:
./fua.py -h
usage: fua.py [-h] {ni,noinstall,script,fs,filesystem,nand} ... Command line utility to build FUB packages in order to upgrade a firmware piece by means of RidgeRun Firmware Upgrade Application (FUA) optional arguments: -h, --help show this help message and exit Service providers: {ni,noinstall,script,fs,filesystem,nand} Each SP has specific options which can be viewed with -h ni Execute a given script on the target FS fs Install a package on the FS nand Update a nand sector, like the kernel or bootloader Run "fua <service provider> -h" for specific options
In the same way that the python script that runs on the host PC has its own menu, the FUA scripts on the target also has one and it can be deployed with the option -h as it is shown at next:
./fua.py -h
usage: fua.py [-h] [-v] [-r] [-l] [-p] [-e] [-t] [-c] [-m] Ridgerun fub package installer optional arguments: -h, --help show this help message and exit -v, --verbose Display verbose messages. -r, --dry-run If used, don't apply changes to system -l , --location Location to search fub packages, defaults to "/etc/fua/fubs/" -p , --package Specify fub package to install -e, --erase-sources Erase source package source after installing -t , --temp-dir Temporal location for deploying fub packages, defaults to "/tmp/fua-tmp/" -c, --checksum If set, does checksum validate to fub packages,checksum needs to be provided, checksum method used for validate is sha1sum. Checksum file needs to be names as fub package and end with .sha1. eg: test1.fub.sha1 -m, --monitor Enable directory monitor for incoming fub packages, -p option will be ignored -l option will specify to be monitored directory
Kernel update
The following commands are used to create the fub package for updating kernel image, in this case the kernel is stored at /dev/mtd1 and this parameter have to be set in order to write the kernel correctly to the NAND; also, the fub package should contain the word kernel on its name.
On PC
./fua.py nand -t binary -i ../images/kernel.uImage -l /dev/mtd1 -w "\-p" kernel-test
- The -t <type> specifies the type that is going to allocate into Nand memory. Type {binary,script,tarball}.
- The -i <file> specifies the file to install by FUA. The type of this file must coincide with the one specified with -t option.
- The -l </dev/mtdX> specifies the location of the partition to update.
- The -w <"params"> specifies the extra parameters to pass to the the nandwrite command.
The number of the MTD partition can be find at the booting log of the board or by running the dmesg command and look for something similar to the follwing message:
3 cmdlinepart partitions found on MTD device davinci_nand.0 Creating 3 MTD partitions on "davinci_nand.0": 0x000000000000-0x000000400000 : "UBOOT" 0x000000400000-0x0000008a0000 : "KERNEL" 0x0000008a0000-0x00000d0a0000 : "FS"
Now it is needed to copy the fub package to the device (SDCard, MTD partition, etc).
cd $DEVDIR/fua-tools-1.0 cp kernel-test.fub /media/<device>
On target
Currently, there are two methods for obtain the Kernel FUB package on target:
Mount SD card on target:
/ # cd / / # mkdir -p <device> / # mount /dev/mmcblk0p1 <device>/ / # cp <device>/kernel-test.fub /
Mount UBI volumen on target:
/ # ubiattach -p /dev/mtd3 / # ubimkvol /dev/ubi1 -s 5MiB -N config_data / # mount -t ubifs /dev/ubi1_0 <device>/ / # cp <device>/kernel-test.fub /
Note: The kernel upgrade from MTD partition is still being supported.
Run the following FUA update command:
/ # fua.py -v -p kernel-test.fub Installing fub package: kernel-test.fub kernel/ kernel/descriptor.fud kernel/kernel.uImage found directory containing fub at: /tmp/fua-tmp/kernel fub descriptor info: Type:binary File:kernel.uImage SP:nand Location:/dev/mtd1 OOB: no Extra params: -p Pre Script: none Post Script: none At Nand Provider constructor flash_eraseall has been replaced by `flash_erase <mtddev> 0 0`; please use it Erasing 128 Kibyte @ 420000 -- 100 % complete Writing data to block 0 at offset 0x0 Writing data to block 1 at offset 0x20000 Writing data to block 2 at offset 0x40000 Writing data to block 3 at offset 0x60000 Writing data to block 4 at offset 0x80000 Writing data to block 5 at offset 0xa0000 Writing data to block 6 at offset 0xc0000 Writing data to block 7 at offset 0xe0000 Writing data to block 8 at offset 0x100000 Writing data to block 9 at offset 0x120000 Writing data to block 10 at offset 0x140000 Writing data to block 11 at offset 0x160000 Writing data to block 12 at offset 0x180000 Writing data to block 13 at offset 0x1a0000 Writing data to block 14 at offset 0x1c0000 Writing data to block 15 at offset 0x1e0000 Writing data to block 16 at offset 0x200000 Writing data to block 17 at offset 0x220000 Writing data to block 18 at offset 0x240000 Writing data to block 19 at offset 0x260000 At Nand Provider destructor
- The -p <package> specifies fub package to install.
- The -v displays verbose messages.
Bootloader update - See (Note 1)
Normally the bootloader is stored at /dev/mtd0 and as same as the generation of the kernel fub package this parameter has to be set for the bootloader, and also in order to flash the bootloader correctly to the NAND the fub package should contain the word "bootloader"on its name.
./fua.py nand -t binary -i ../images/bootloader -l /dev/mtd0 -w "\-p" bootloader-test
- The -t <type> specifies the type that is going to allocate into Nand memory. Type {binary,script,tarball}
- The -i <file> specifies the file to install by FUA. The type of this file must coincide with the one specified with -t option.
- The -l </dev/mtdX> specifies the location of the partition to update.
- The -w <"params"> specifies the extra parameters to pass to the the nandwrite command.
Script update
The fub packages might run a script after/before deploying its content, but also a fub package could only contain a script, for example:
On PC:
Create an script that does some action:
touch test.sh echo "echo \"TEST SCRIPT\"" >> test.sh chmod +x test.sh ./fua.py ni -t script -i test.sh test_script
- The -t <type> specifies the type that is going to allocate into Nand memory. Type {binary,script,tarball}
- The -i <file> specifies the file to install by FUA. The type of this file must coincide with the one specified with -t option.
Copy the fub package on device (SDCard, MTD partition, etc).
cd $DEVDIR/fua-tools-1.0 cp test_script.fub /media/<device>
On target:
Currently, there are two methods for obtain the Script FUB package on target:
Mount SD card on target:
/ # cd / / # mkdir -p <device> / # mount /dev/mmcblk0p1 <device>/ / # cp <device>/test_script.fub /
Mount UBI volumen on target:
/ # cd / / # ubiattach -p /dev/mtd3 / # ubimkvol /dev/ubi1 -s 5MiB -N config_data / # mount -t ubifs /dev/ubi1_0 <device>/ / # cp <device>/test-script.fub /
Note: The script execution from MTD partition is still being supported.
Run the following FUA update command:
/ # cd / / # fua.py -v -p test_script.fub Processing test_script.fub... Extracting... test/ test/descriptor.fud test/test.sh Parsing description file for component test... Checking validity... Performing installation... TEST SCRIPT Cleaning up...
- The -p <package> specifies fub package to install.
- The -v displays verbose messages.
Run script after/before deploying package content
In some cases it is useful to run a script after or before deploying the content of a fub package. For example when doing a bootloader update it is needed to update the uboot's environment, so in order to include a script that should run after deploying the content of the bootloader image (in this case) it is needed to add the fua.py option "-o" or in case that the script has to run before the deployment then the "-e" option as it is shown in the following command; more information about commands are available with the -h option.
./fua.py nand -t binary -i u-boot.bin -l /dev/mtd0 -w "\-p" bootloader-and-script -o nand_env.sh
In this case the fub package will update bootloader at mtd0 with u-boot.bin and will execute nand_env.sh afterwards.
Partial file system update
Filesystem can be updated with a tar file that will deploy its content on the file system.
The following example creates a tar file containing the libraries needed to add support for the i2c-tools package, in order to do this the compressed file needs to contain the complete directory structure that is shown next.
On PC:
cd $DEVDIR/fs tree fs/usr/local/ fs/usr/local/ ├── bin │ ├── ddcmon │ ├── decode-dimms │ ├── decode-edid │ ├── decode-vaio │ ├── hwclock2 │ └── ntpclient └── sbin ├── i2c ├── i2cdetect ├── i2cdump ├── i2cget ├── i2cset └── i2c-stub-from-dump 2 directories, 12 files
Create Tarball of the binaries
cd $DEVDIR/fs/ tar -cvf my_fs_i2c.tar -C fs/usr/local/ . mv my_fs_i2c.tar ../fua-tools-1.0/
Create partial filesystem fub package
cd $DEVDIR/fua-tools-1.0 ./fua.py fs -t tarball -i my_fs_i2c.tar -l / i2c-update
- The -t <type> specifies the type that is going to allocate into Nand memory. Type {binary,script,tarball}.
- The -i <file> specifies the file to install by FUA. The type of this file must coincide with the one specified with -t option.
- The -l <name> specifies the location where on the partial filesystem to install the package..
Copy the fub package on device (SDCard, MTD partition, etc).
cd $DEVDIR/fua-tools-1.0 cp i2c-update.fub /media/<device>
On Target:
Currently, there are two methods for obtain the Partial Filesystem FUB package on target:
Mount SD card on target:
/ # cd / / # mkdir -p <device> / # mount /dev/mmcblk0p1 <device>/ / # cp <device>/i2c-update.fub /
Mount UBI volumen on target:
/ # cd / / # ubiattach -p /dev/mtd3 / # ubimkvol /dev/ubi1 -s 5MiB -N config_data / # mount -t ubifs /dev/ubi1_0 <device>/ / # cp <device>/i2c-update.fub /
Note: The script execution from MTD partition is still being supported.
Run the following FUA update command:
/ # cd / / # mkdir -p sdcard / # mount /dev/mmcblk0p1 sdcard/ / # cp sdcard/i2c-update.fub / / # fua.py -v -p i2c-update.fub Installing fub package: i2c-update.fub my_fs_i2c/ my_fs_i2c/descriptor.fud my_fs_i2c/my_fs_i2c.tar found directory containing fub at: /tmp/fua-tmp/my_fs_i2c fub descriptor info: Type:tarball File:my_fs_i2c.tar SP:filesystem Location:/ OOB: Extra params: Pre Script: none Post Script: none At File System Provider constructor ./ ./bin/ ./bin/ntpclient ./bin/ddcmon ./bin/decode-dimms ./bin/decode-edid ./bin/decode-vaio ./bin/hwclock2 ./sbin/ ./sbin/i2c-stub-from-dump ./sbin/i2cdetect ./sbin/i2cdump ./sbin/i2c ./sbin/i2cget ./sbin/i2cset At File System Provider destructor / #
Entire file system update
The entire file system upgrade is performed by moving the mount point of the file system to a temporal directory so the fub package can be executed and the original file system could be replaced. This temporal mount point can belong to an existent fallback NAND partition or an external file system (such as a bootable SD card). Additionally if not alternate mount point is specified FUA is capable of create a temporal mount point for the upgrade process.
Create FUB package
This section explains how to create a fub package with the entire file system of a RidgeRun SDK using fua-tools-1.0.
On PC:
Go to:
cd $DEVDIR/fua-tools-1.0
Create the fub package:
./fua.py fs -t binary -i ../images/fsimage.uImage -l /tmp/ entire-filesystem -o pivot-root-script.sh
- The -t <type> specifies the type that is going to allocate into Nand memory. Type {binary,script,tarball}
- The -i <file> specifies the file to install by FUA. The type of this file must coincide with the one specified with -t option.
- The -l <name> specifies the location where on the file system to install the package.
- The -o <script_name> specifies the name of the postinstallation script. This script willbe executed after FUA performs the package update.
Note: The pivot-root-script is available into $(DEVDIR)/fua-tools-1.0
Copy the fub package on device (SDCard, MTD partition, etc).
cd $DEVDIR/fua-tools-1.0 cp entire-filesystem.fub /media/<device>
On target:
Currently, there are two methods for obtain the Script FUB package on target:
Mount SD card on target:
/ # cd / / # mkdir -p <device> / # mount /dev/mmcblk0p1 <device>/ / # cp <device>/entire-filesystem.fub /
Mount UBI volumen on target:
/ # cd / / # ubiattach -p /dev/mtd3 / # ubimkvol /dev/ubi1 -s 5MiB -N config_data / # mount -t ubifs /dev/ubi1_0 <device>/ / # cp <device>/entire-filesystem.fub /
Note: The script execution from MTD partition is still being supported.
Start upgrade process on target
To start the upgrade process it is mandatory to provide access to the fub package within the target.
There are two methods for perform the upgrade process:
File system upgrade from an existent mount point
If there is a recovery partition or you are running the upgrade process from an SD card containing all the required system files you can specify such media as the root point from where the upgrade is going to be run. In this case you specify the media partition using the environment variable MOUNT_DEVICE as follows:
- On SD card (The SD card should contain a valid file system for the target platform):
/ # export MOUNT_DEVICE=/dev/mmcblk0p1
- On MTD partition (This is not the same partition to be upgraded):
/ # export MOUNT_DEVICE=/dev/mtd4
Note: See Appendix if you want to know how to create additional MTD Partition.
Then run
FUB_PATH=/<device> EXTRACT_DIR=/<extract_tmp_files_directory> fua.py -v -p $FUB_PATH/entire-filesystem.fub -t $EXTRACT_DIR
- The -t <path> argument tells the FUA where to copy and extract the contents of the upgrade package in the process, its capacity should be enough to allocate the contents of the fub package and should be out of the file system to be replaced.
- The -p <package> specifies fub package to install.
- The -v displays verbose messages.
- The FUB_PATH variable specifies the location of the FUB package that you want to apply.
- The EXTRACT_DIR variable specifies where might be extracted the temporal files using FUA, our recommendation is that you use a memory space enough (least twice the size of filesystem) to extract successfully the temporal files.
File system upgrade from /tmp
If there is not another mount point and the MOUNT_DEVICE variable is undefined, FUA will auto-generate a minimal file system on the /tmp directory and will run the upgrade process from there. This is specially useful when there is not fallback NAND partition or the fub package is read from a media device without any system files on it. In such case the upgrade process should be ran as follows
FUB_PATH=/<device> EXTRACT_DIR=/sdcard fua.py -v -p $FUB_PATH/entire-filesystem.fub -t $EXTRACT_DIR
- The -t <path> argument tells the FUA where to copy and extract the contents of the upgrade package in the process, its capacity should be enough to allocate the contents of the fub package and should be out of the file system to be replaced.
- The -p <package> specifies fub package to install.
- The -v displays verbose messages.
- The FUB_PATH variable specifies the location of the FUB package that you want to apply.
- The EXTRACT_DIR variable specifies where might be extracted the temporal files using FUA, our recommendation is that you use a memory space enough (least twice the size of filesystem) to extract successfully the temporal files.
Manually execution of fub packages
In order to apply all fub packages at /etc/fua/fubs on target:
fua.py -v
In order to apply an specific fub package on target:
fua.py -p <PATH_TO_FUB_PACKAGE>
Note: the FUB packages are executed alphabetically from /etc/fua/fubs.
Fub package checksum verification
The firmware Upgrade Application can do a checksum of the packages that are going to be applied to the system, if the checksum needs to be done to the packages use the '-c' option, also the user needs to provide the checksum file following this naming convention:
Fub package:
example_package.fub
Checksum package:
example_package.fub.sha1
Checksum at example_package.fub.sha1 needs to be obtained with sha1sum, for example:
sha1sum example_package.fub >> example_package.fub.sha1
FUA Monitor
The Firmware Upgrade Application has a feature named FUA Monitor and when it is enabled it will check the content of /etc/fua/fubs every time that the directory has been modified and it will apply the fub packages present in the directory. If doing checksum of the fub packages is needed, there are two files that are needed: the fub package and its sha1sum file, naming convention should be:
- <PACKAGE_NAME>.fub
- <PACKAGE_NAME>.fub.sha1
In order to start FUA Monitor with checksum support use the -c option:
FUA Monitor with checksum:
/usr/bin/fua.py -m -l /etc/fua/fubs/ -c | logger -t fuaMonitor &
FUA Monitor without checksum:
/usr/bin/fua.py -m -l /etc/fua/fubs/ | logger -t fuaMonitor &
In case of needing extra space for deploying the fub package and its content into the system it is recommended to use the /tmp/ directory as a location to look for new packages. This can be achieved by using the -l option:
/usr/bin/fua.py -m -l /tmp/ -c | logger -t fuaMonitor &
Appendix
How to create extra mtd partition
This section explains how to create an extra MTD partition using RidgeRun SDK configuration.
Go to Rigderun SDK and start the RR SDK configuration:
cd $DEVDIR make config
Go to:
-> Installer Configuration -> MTD extra partitions
In order to write the extra MTD memory size, for example:
50432k(extra_mtd)
It is recommended to write the memory size in kilobytes <size>k, in order to avoid problems of interpretation.
How to get NAND size options
This section shows how to get the NAND size options that you might set up in the SDK Configuration.
- Go to target.
- Turn on or restart the target.
- Stop the autoboot count, hit any key to stop this process, you should get something like this:
U-Boot 2010.06-dirty (Apr 08 2015 - 17:36:43) TI8168-GP rev 2.1 ARM clk: 987MHz DDR clk: 675MHz I2C: ready DRAM: 1 GiB NAND: 256 MiB Net: Detected MACID:84:7e:40:e3:4b:ca Ethernet PHY: GENERIC (x001cc915) @ 0x01 DaVinci EMAC Hit any key to stop autoboot: 0 Z3-DM8168-MOD#
NAND Block Size
- Obtain NAND information, for this run the following command:
Z3-DM8168-MOD# nand info Device 0: NAND 256MiB 3,3V 8-bit, sector size 128 KiB
- After that determine the NAND Block size, you must use sector size value KiB.
nand_block_size = <sector_size> * 1024
Example:
nand_block_size = 128 * 1024 = 131072
NAND Page Size
You can find the NAND page size using dump page command on the u-boot, this command shows page section value and OOB page, then you need to do some tests with those values:
Page Size |
---|
0200 |
0400 |
0800 |
1000 |
Then, run this command with values of Table 1. on th U-boot prompt:
Z3-DM8168-MOD# nand dump.oob <page_size>
You should get something like this:
Page 0000<page_size> dump: <--------- OOB: ff ff 53 b3 8d ec 1c 95 94 f0 85 54 c4 e5 bc ff e0 d1 ac 34 42 89 2e f4 1a 22 a9 26 29 00 fc 46 e5 21 ae b2 ff a2 7e d0 e6 4f e7 00 04 6c 5e b1 fa 20 0c 0e 23 c8 fa f1 6a 00 ff ff ff ff ff ff
If the page_size value typed by you matches with the page output (aim with arrow), then the page_size is validated.
After that, you need to convert page_size to decimal value, you can use a calculator.
Example
- Type on u-boot the follows tests:
Test 1:
Z3-DM8168-MOD# nand dump.oob 0200 Page 00000000 dump: OOB: ff ff 22 c3 16 41 8b 3d 98 03 da 13 dc 29 e7 ff 0d 4a 8d 78 6b 86 4f 89 ac 5e 98 5d 6d 00 c9 cd ec e4 55 26 c9 80 50 8f 2a 32 77 00 9d 45 ad d3 99 b4 f0 d2 f7 8b f7 84 c5 00 ff ff ff ff ff ff
The 0200 does not match with Page 00000000 dump
Test 2:
Z3-DM8168-MOD# nand dump.oob 0400 Page 00000000 dump: OOB: ff ff 22 c3 16 41 8b 3d 98 03 da 13 dc 29 e7 ff 0d 4a 8d 78 6b 86 4f 89 ac 5e 98 5d 6d 00 c9 cd ec e4 55 26 c9 80 50 8f 2a 32 77 00 9d 45 ad d3 99 b4 f0 d2 f7 8b f7 84 c5 00 ff ff ff ff ff ff
The 0400 does not match with Page 00000000 dump
Test 3:
Z3-DM8168-MOD# nand dump.oob 0800 Page 00000800 dump: OOB: ff ff 53 b3 8d ec 1c 95 94 f0 85 54 c4 e5 bc ff e0 d1 ac 34 42 89 2e f4 1a 22 a9 26 29 00 fc 46 e5 21 ae b2 ff a2 7e d0 e6 4f e7 00 04 6c 5e b1 fa 20 0c 0e 23 c8 fa f1 6a 00 ff ff ff ff ff ff
The 0800 matches with Page 00000800 dump
The NAND page size of our NAND is 0800.
- Finish, let's convert the NAND page size value to decimal using a calculator:
nand_page_size = 800H = 2048d
NAND page size is 2048
Notes
- Note 1: Bootloader upgrade is platform dependent and currently limited to iMX6 platforms. Support for additional platforms can be added if required.
- Note 2: Currently, RidgeRun firmware update application is supported for UBIFS and NFS. if you select NFS root file system, you might be able to update only bootloader and kernel, because your filesystem is gotten remotely, but if you select UBIFS volume, you might be able to update your firmware fully.