Raw partition update

The update command simplifies the task of updating a partition of the eMMC by performing the following operations:

  • Download the required firmware image files from the specified media to RAM memory.

  • Retrieve and check information (offset, size) of the partition to update.

  • Write the firmware image to the partition.

  • Read back and verify the written firmware image.

Syntax

'update' syntax
=> help update
update - Digi modules update command

Usage:
update <partition>  [source] [extra-args...]
 Description: updates (raw writes) <partition> in $mmcdev via <source>
 Arguments:
   - partition:    a partition index, a GUID partition name, or one
                   of the reserved names: uboot
   - [source]:     tftp|nfs|mmc|ram
   - [extra-args]: extra arguments depending on 'source'

      source=tftp|nfs -> [filename]
       - filename: file to transfer (if not provided, filename
                   will be taken from variable $<partition>_file)

      source=mmc|usb -> [device:part] [filesystem] [filename]
       - device:part: number of device and partition
       - filesystem: fat (default)|ext4
       - filename: file to transfer (if not provided, filename
                   will be taken from variable $<partition>_file)

      source=ram -> [image_address] [image_size]
       - image_address: address of image in RAM
                        ($loadaddr if not provided)
       - image_size: size of image in RAM
                    ($filesize if not provided)

Examples

Example 1: Update partition named myname with file test.img downloaded from TFTP:

=> update myname tftp test.img

Example 2: Update partition named linux in the eMMC of the module using default filename (determined by variable $linux_file) reading the file from a FAT partition on the uSD card:

=> update linux mmc 1:1 fat

Check the default partition names at Storage layout.

Customization using environment variables

You can customize the behavior of the update command through its parameters and also by using the following environment variables:

Addresses

Variable Description

$update_addr

RAM address where the firmware image file to use for the update is downloaded.

$verifyaddr

RAM address where the firmware image is read back to, for verification. U-Boot automatically sets this variable to a RAM address halfway through the available RAM, starting at $loadaddr, to maximize the size of firmware that can be transferred to RAM and verified during the update process.

Image file names

Variable Description

$uboot_file

Default image filename to use for updating the bootloader (if no filename is passed as parameter).

$<partition-name>_file

A variable of this form will contain the default filename to use for updating the partition named <partition-name>. For example, the variable containing the default filename for a partition named recovery would be called $recovery_file.

Target media

Variable Description

$mmcdev

Target MMC device index to write the firmware to.

$mmcbootpart

For "u-boot" partition updates, target MMC partition index to write the firmware to.

Updating the bootloader

You can use the update command to manually update the bootloader in the eMMC. For example, to update from TFTP using the default filename (in variable $uboot_file):

=> update uboot tftp
Writing an invalid bootloader file may lead to the target not booting.

Digi releases U-Boot updates from time to time to fix problems or add new functionality. Much of the custom functionality added to U-Boot depends on environment variables and scripts that may have new values in newly released versions. Digi recommends that you reset the environment to its defaults after upgrading U-Boot:

Reset U-Boot environment to default values
=> env default -a

This resets the whole environment, with the exception of protected variables (like the MAC addresses). After resetting the environment, you may need to adjust your manufacturing or boot scripts to accommodate changes in the default environment, like new or modified scripts, variables, and default filenames.

See U-Boot files by variant to verify which U-Boot binary you need.

On-the-fly update mechanism

The normal update command first transfers the file completely from a media into the RAM memory. Then it writes the file from RAM into the eMMC. Occasionally, the firmware files used to update a certain partition are very large, maybe larger than the available RAM of the platform. In that scenario, the update strategy must:

  • Transfer a chunk of the file from the specified media to the RAM memory.

  • Write the chunk to the partition and verify the written data.

  • Repeat the process until the file has been completely written.

We call this mechanism on-the-fly update.

The on-the-fly update mechanism can only work when updating from TFTP source and is only recommended for updating very large images. Note that if there is any problem during the transmission of the file, the partition is left partially written (compared to the standard update where, if the transmission fails, the partition remains untouched).

For security reasons, the on-the-fly update mechanism is automatically disabled when updating the bootloader.

You can activate the on-the-fly update mechanism by setting the variable $otf-update to yes, and then using the update command normally. If the variable $otf-update is not defined, the update command may automatically activate the on-the-fly update mechanism if the size of the partition to update is larger than the available RAM to hold the firmware. (The TFTP protocol does not indicate the size of the file being transferred.)

The on-the-fly update mechanism pauses the TFTP transfer while it writes each chunk to the eMMC, and resumes after reading back and verifying the written data. For this reason it may not work with all TFTP servers. Be sure to check that your TFTP server has a large enough timeout so that it doesn’t cancel the transfer due to not receiving the client’s ACKs in time while the device is writing and verifying. Also, disable any mechanism that sends packets without waiting for the client’s ACKs (like anticipation window) which may not always work with the on-the-fly update mechanism.

Update files within partition

The updatefile command simplifies the update of files in a partition’s file system. While the standard update command writes raw data to the eMMC, the updatefile command uses U-Boot file system support to write files to a formatted partition by performing the following operations:

  • Download the required file from the specified media to RAM memory.

  • Write the file to the partition’s file system.

Syntax

'updatefile' syntax
=> help updatefile
updatefile - Digi modules updatefile command

Usage:
updatefile <partition>  [source] [extra-args...]
 Description: updates/writes a file in <partition> in $mmcdev via
              <source>
 Arguments:
   - partition:    a partition index or a GUID partition name where
                   to upload the file
   - [source]:     tftp|nfs|mmc|ram
   - [extra-args]: extra arguments depending on 'source'

      source=tftp|nfs -> [source_file] [targetfile] [target_fs]
       - source_file: file to transfer
       - target_file: target filename
       - target_fs: fat (default)

      source=mmc -> [device:part] [filesystem] [source_file] [target_file] [target_fs]
       - device:part: number of device and partition
       - filesystem: fat (default)|ext4
       - source_file: file to transfer
       - target_file: target filename
       - target_fs: fat (default)

      source=ram -> [image_address] [image_size] [targetfile] [target_fs]
       - image_address: address of image in RAM
                        ($loadaddr if not provided)
       - image_size: size of image in RAM
                    ($filesize if not provided)
       - target_file: target filename
       - target_fs: fat (default)

Examples

Example 1: Update the newkernel.bin file from TFTP to linux FAT partition:

=> updatefile linux tftp newkernel.bin

Example 2: Update the newkernel.bin file from uSD card FAT partition 3 to linux FAT partition and save it with filename myImage-test:

=> updatefile linux mmc 1:3 fat newkernel.bin myImage-test fat

Limitations and cautions

  • Only FAT and EXT4 file systems are supported.

  • Files can be overwritten but cannot be deleted.

  • File system support does not check for available space.

Writing a file on a file system that does not have space for it may corrupt the entire file system.