Firmware Checksum

WeOS has two firmware images that exist on the device, the primary and the secondary. Both of these images have an associated checksum that is used to verify the integrity of the firmware.

Overview

By default, both of these firmware images have an associated background task started on boot that is responsible for calculation of their individual checksums. The amount of time it takes to finalize the calculation may vary depending on the specific platform.

System Load

These calculations may be somewhat CPU intensive while they are running. It is possible that this extra load can cause slight latency in specific system operations during startup, until both of the individual calculations have been finalized.

The calculated checksum for each of the firmware images, will be compared against the checksum that is present in the header of the firmware image. If the calculated checksum does not match the checksum in the header, the firmware image is considered invalid.

Viewing the Checksum Status

The checksum status for each of the individual firmware images can easily be observed in the system-information status output, which is viewable from the CLI in the following manner:

example:/#> show system-information
[...]

BOOT INFORMATION                                                              
Boot loader ver.   : 2024.03.0-1       Active firmware    : RAM
Primary ver.       : 5.24.0            Primary CRC        : OK ◄──────────────
Secondary ver.     : 5.24.0            Secondary CRC      : OK ◄──────────────
Config media       : internal          Config file        : startup
Certificate media  : internal

[...]
example:/#>

In the above example, we can see how the output will be presented when the checksum for both the primary (Primary CRC) and secondary firmware (Secondary CRC) images have calculated and successfully validated.

The following states are possible for the CRC for each of the individual firmware images:

State	Description
`Unchecked`	The checksum has not yet been calculated.
`Checking ...`	The calculation of the checksum is in progress.
`OK`	The checksum has been calculated and has been correctly validated.
`Invalid`	The checksum has been calculated and is invalid.

Table 1: The possible states for the firmware checksum calculation.

Configuring the Automatic Checksum Calculation

As mentioned above, by default the Automatic Checksum Calculation is enabled. Meaning that as soon as the device is started, the background tasks for the checksum calculations will be started.

However, it is possible to disable this if desired. The only real reason why this would be necessary is if the slight possible latency that may be introduced, directly after startup, is causing some issues in the system during that period of time.

Manual Start Possible

If the automatic checksum calculation is disabled, it can still be manually started when it may be needed. The main function in the system that will require the checksum to be present is is the firmware upgrade. However, it is still possible to initiate a firmware upgrade even if the checksum calculation is not present, but an additional confirmation check must be acknowledged in this case.

Configuration

The setting controlling the automatic checksum calculation is available in the system context from the top level configuration context:

example:/#> configure
example:/config/#> system
example:/config/system/#>

[no] automatic-firmware-checksum

Enable/Disable automatic firmware checksum calculation.

By default the device calculates the firmware checksum automatically. This setting can be used to disable that behavior.

Even if the automatic calculation is disabled, it can still be initiated manually using the ‘firmware-checksum’ command in the exec context.

Note

The firmware checksum calculation can be somewhat heavy during startup, which is why it is possible to disable it, if desired.

Default: Enabled

Example

example:/config/system/#> automatic-firmware-checksum
example:/config/system/#> no automatic-firmware-checksum

no: Disable the automatic checksum calculation.

Manually Starting the Checksum Calculation

If the automatic checksum calculation is disabled, the checksum calculation can still be initiated on demand. When the command is invoked, the system will start a background task that will calculate the checksum.

The command is available from the top level exec context:

example:/#>

firmware-checksum [pri|sec]

Check the CRC of a firmware image on the device.

This command checks the CRC of a firmware image on the device. The image must be in the primary or secondary firmware slot. The command will check the CRC of the image and compare it to the CRC stored in the image header.

The command can be used with the optional parameters pri or sec to specify which image to check. If no parameters are given, the command will check the CRC of both images.

The calculation of the CRC will be started in the background and the command will return immediately. If the CRC calculation is already done, the status for the image will be shown.

Already Calculated

If the CRC has already been calculated for the given firmware image, the status for the image will be shown.

Example

example:/#> firmware-checksum
example:/#> firmware-checksum pri
example:/#> firmware-checksum sec

pri: Check the CRC of the primary firmware image.
sec: Check the CRC of the secondary firmware image.