FUA Software Design Description

From RidgeRun Developer Connection
Jump to: navigation, search

RR Eval SDK download button.png RR Pre built demo image download.png RR Contact Us.png



This document describes the proposed design for the Firmware Upgrade Application (FUA).

The Firmware Update Application (which from now on will be referred as FUA) is an application intended to act as a generic firmware update engine for boards running on RidgeRun’s SDK, it can be easily invoked as a stand-alone application, from a command line interface or by other applications.

It is intended to solve the major issues found while trying to upgrade the software/firmware in your device, it provides a platform-independent application that automates and standardizes the firmware update process for platforms running RidgeRun's software. Not only by providing tools to easily create and supply updates, but also it also minimizes the necessary human interaction after these have been applied


The ultimate goal is to create a software package that will provide the functionality to safely install software updates for devices ready to go to the market and devices already in the market that need to receive a newer version of your software (BSP, Filesystem, etc) where normally the manufacturer only has remote access to them. The application provides an standardized and platform agnostic method to automate the software upgrading process.

System Overview

The Firmware Update Application is an application intended to act as a generic firmware update engine for boards running RidgeRun’s SDK, it can be easily invoked as a stand-alone application from the command line of the board or from other applications. It provides tools to easily create and install updates and simultaneously it reduces the necessary human interaction after these new images have been deployed.

System Architecture

Basic structure of the system

Figure 1. FUA System Architecture

  • Main: Main entry point for FUA, it calls and executes methods depending of the update mode selected by the user.
  • Core: It handles the installation, verification and parsing methods implemented by FUA.
  • FUBParser: It handles FUB package parsing.
  • DescriptorParser: Descriptor Files parser for software components.
  • NandProvider: It implements the ServiceProvider interface in order to install components on NAND devices.
  • NoInstallProvider: It implements the ServiceProvider interface in order to perform updates not requiring any installation on persistent storage devices (such as scripts).
  • FSProvider: It implements the ServiceProvider interface to install board's filesystem.
  • ServiceProvider: Interface for all ServiceProviders modules.
  • BlockProvider: Methods used by ServiceProvider module.

Upgrade Design

This section describes the algorithms used by FUA.

Kernel Upgrade

The kernel upgrade method uses the NandProvider services to install different files like binaries, scripts and tarballs directly into the NAND memory. Specifically, kernel upgrade uses the binary installation method described below:

Figure 2. Flow diagram for Kernel upgrade


  • FUA verifies the call of pre and post update scripts, to be called before and after a specific component’s installation, it also performs a decryption of the flags within the FUB package such as mtd partition number.
  • Create fub-tmp directory in /tmp directory and extract the temporal files such as descriptor files, Kernel Image into it.
  • Erase the mtd partition of the Kernel using the flash_erase command.
  • Flash the kernel image into the empty mtd paritition using nandwrite

Partial Filesystem Upgrade

Tarball installation service provided by FSProvider. Basically it deploys and modifies partially the tarball contained on the filesystem.

Figure 3. Flow diagram for the Filesystem upgrade


  • Create to fub-tmp directory in /tmp directory and extract the temporal files such as descriptor files, partial filesystem tarball into it.
  • Extract the partial filesystem tarball into filesystem root.

The partial filesystem upgrade process is sensitive to changes of the filesystem format, for this reason, it is necessary to keep the filesystem structure (bin/ dev/ etc/ lib/ proc/ sbin/ srv/ sys/ tmp/ usr/ var/).

Entire file system update

The entire file system upgrade is performed by moving the mounting 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 mounting point can belong to an existent fallback NAND partition or an external file system (such as a bootable SD card). Additionally, if an alternate mounting point is not specified by the user FUA is capable of creating a temporal mount point for the upgrade process.

This process consists of 3 main parts shown in Figure 5. In the first instance, it is necessary to build the upgrading environment within a recovery directory that contains the necessary elements for a successful pivot, then you must move the update_device from the original_path to the recovery directory, after this it must generate the init_script inside of the recovery directory which will update the NAND memory from new_root and finally it will perform the pivot from the current filesystem to the updated environment. Each part will be explained with more details later.

Figure 5. Flow diagram for entire filesystem upgrade

Building Upgrade Environment

The building upgrade environment consists on the creation of a default_filesystem containing at least the elements necessary to create a minimal_filesystem, this is necessary because the pivot_process applies only to filesystems.

There are different methods to build the upgrade environment, this consist of mounting a filesystem from some devices such as SD card or MTD as shown in Figure 2 and use them to perform the pivot. Please keep in mind that that filesystems are provided by the FUA user and need to meet the minimum requirements (See Appendix) to be a pivot_root.

There is also a method of self-generation filesystem, This is to copy the elements needed to create the environment upgrade from the current filesystem. This method is recommended because it does not require the user to provide any additional filesystem

Figure 6. Flow diagram to Build the upgrade environment

Generate flashing script

This process generates a initial_script that will be invoked from the environment upgrade process. Figure 3 shows the steps performed on this stage.

First, It must create a directory where you are going to store the initial_script, then this creates the flashing script which contains some commands to remove and release the current filesystem form NAND memory, after creating the flashing script, it gives execution permissions to it and finally sets it up as iniitab_script with priority.

Figure 7. Flow diagram to generate initial script

Pivot process

In this process, it creates a directory that is going to contain the current filesystem (the one you want to install), after this the pivot is performed on environment and filesystem and finally all the processes running within the current filesystem are deleted.

Figure 8. Flow diagram of the Pivot process

Definitions and Acronyms

FUA: Firmware Upgrade Application.

Related Links