Using the flash memory

All of the ARRIS VIP set-top boxes contain flash memory, which is used to store or cache the downloaded boot image and so improve the set-top box startup time. The flash memory is also used for storing the current DBL, configuration parameters, and configuration objects. This page discusses the storage of boot images and how it relates to booting the STB.

Storing the boot image in the flash memory is entirely optional. If the system is not configured to do this, then the STB will download its boot image from the network every time it boots. Three-stage boot will always be used in this scenario. Since not saving the boot image in the flash memory adds to the network load and increases the boot times, it is not desirable in a live deployment. However, it can sometimes be very useful in a lab situation when you are making rapid changes to the boot image.

Configuring

To use the flash memory for storage of the boot image, the kernel protocol, (discussed here), needs to contain the number "3". This tells the STB to boot from the flash memory when a valid boot image is available there, and also, the next time a download is required, to also save that boot image into the flash memory.

To empty the flash memory, turn on the STB and press MENU on the remote control shortly after the STB displays something on the TV. This will bring up the boot loader menus. Under the System tab you can find an option to Remove Software. This will remove any boot image cached in the flash memory. If you are already in two-stage boot mode the boot loader menu is not available, so you will need to perform a disaster recovery operation, which discards the boot image and exits two-stage boot mode.

In addition, the boot server needs to be correctly configured to broadcast the correct Kernel Version of the boot image being offered. Every boot image contains a string to identify the software version. This string is set when building the boot image, by supplying it to the build_boot_image script, or the various build_device.sh scripts.You can determine the version of a built boot image with the boot_image_version tool in the SDK. This version string needs to be supplied in the boot servers XML manifest file.

Disabling

If you want to force three-stage boot for some reason, add the following to the boot image configuration file:

# disable two-stage boot
kreatv-option-boot:two_stage_boot=false

In this scenario, the RBL will always start the DBL. If you have the number "3" in the Kernel Protocol, the boot image will still be saved to the flash memory, but on cycling the power the RBL will launch the DBL unconditionally. The DBL will check the versions and proceed to either download a new image or start the one in the flash memory.

To not use the flash memory at all, use a Kernel Protocol string which does not contain the number "3" at all. This means that not only will the RBL always launch the DBL, but that the DBL will always have to download a boot image from the server each time the STB boots up.

Boot process using flash memory

When the STB first boots up, with an empty flash memory, the RBL will notice that no valid boot image is available locally, and so it starts the DBL. The DBL checks the network for a boot image and downloads it, also saving it to the flash memory. The DBL then launches the KreaTV platform contained in the boot image.

Once the KreaTV platform successfully starts, it indicates this by writing a flag to the flash memory, saying that the image is ok. If you are watching the KreaTV log you will see a "Software considered OK" message appear shortly after the platform start. This is the point where the STB enters two-stage boot.

On the next boot, the RBL will find a valid image in the flash memory, and skip the DBL, launching the software directly.

Updating

The KernelVersion is an arbitrary string, embedded into each boot image when it is made, to indicate the software version. Each of the supported boot server types makes both the boot image, and the version of that boot image available on the network.

Splash images are handled in a similar way, using a SplashVersion string.

While the KreaTV platform is up and running, it will periodically poll the boot server to check what KernelVersion is currently available. If the version available on the network changes, and so no longer matches the version stored in the STB flash memory, KreaTV marks the boot image in the flash memory as invalid. KreaTV does not download the actual boot image, the DBL is the only part of the system which performs the download. The next time the STB boots, the RBL will not find a valid boot image locally and exit two-stage boot by starting the DBL. The DBL in turn will check the network for new software, and download, save and start it, entering into two-stage boot mode again if all went well. The new KernelVersion and SplashVersion get saved to the flash too, and KreaTV will again being a periodic poll for differences with the network versions.

Forcing a change

To force an immediate software upgrade, you need to perform a disaster recovery, or reboot the STB using the TOI API. Both of these operations mark the boot image in the flash memory as invalid, so the following reboot will download new software. Simply pulling the power cable from the STB to restart it does NOT exit the two-stage boot mode, even if new software has been deployed on the boot server.