Chapter 195. BootUp overview

195.1. Introduction

eCosPro-BootUp is eCosCentric's commercial name for the CYGPKG_BOOTUP package. The package is not included as standard in eCosPro Developer's Kit releases. Review the board specific documentation to determine if support has been included for your target platform.

The CYGPKG_BOOTUP package implements a lightweight bootROM that is intended to be easily portable and customizable to support the requirements of a given platform. It is purposely designed to provide an uncomplicated and straightforward boot mechanism, but does however provide a framework that the target platform code can use to easily extend its basic functionality. This can be used to incorporate more advanced features such as secure boot capabilities and application or system updates.

The BootUp code does NOT support any debug ROM monitor features. It is targeted at deployment of SoC-based designs that have limited memory resources and where hardware debugging (JTAG, SWD, BDM, etc.) will be used. It does not incorporate a debug agent such as GDB stubs, a CLI or any other debug monitor features. If you require these kinds of features then the RedBoot bootloader and debug firmware will be a more appropriate vehicle.

The BootUp package provides the generic, logical, framework for optional updating and execution of application images. Most of the heavy-lifting implementation for this is provided by architecture, variant or platform specific code that is incorporated when CYGPKG_BOOTUP is built. This is primarily because the location and format of the relevant application images is platform specific. This provides the greatest flexibility to developers with regards to how applications are stored and what extra information may be embedded to support updating and any other custom bootROM features.

[Note]Note

Normally it is envisaged that the BootUp ROM image will be loaded onto devices once, and then very rarely (if ever) updated. The BootUp world is designed to be very simple to minimise the chances of errors in the implementation that would stop the system from booting, or from allowing a different main application to be loaded into the device. The simpler implementations make no use of specific run-time configuration, and all implementations do not impose any footprint on the target after it has started the main application.

BootUp has been utilised by various example target platform implementations to support different mechanisms for safe application updates. These examples can be used as the basis of an update mechanism for your target platform. For example:

  • A simple implementation with no update support. The on-chip BootUp loader is simply used to validate, load and execute an off-chip NVM based, RAM loaded, application.

    The Atmel SAMA5D3x platform provides an example BootUp implementation for starting RAM based applications. This platform also, optionally, supports secure booting an encrypted applications.

  • A basic update mechanism that is intended to support booting and update of on-chip flash resident applications. In this case, each time the target is reset BootUp checks if a different, valid, application is present in a separate non volatile memory (NVM) area. If an update is found it will be installed into the on-chip flash, prior to the on-chip flash application being executed. The term “different” is used when distinguishing main application images since BootUp does not interpret the binary signature, which need not be a version number. This allows the update system to be used to revert to an earlier version of the application. It will simply update the on-chip application if an application with a different signature is found in the NVM.

    The application itself is responsible for identifying, acquiring, verifying and storing any update into the NVM. BootUp is responsible solely for installation and execution of the application held in on-chip flash.

    The design of this mechanism avoids halving the available on-chip memory space in order to store images of both the existing and updated application. It also avoids possible target complications resulting from executing out of the same memory space that will need to be erased and written to. However, if the on-chip flash is large enough, and the final application small enough, it is possible for the main and alternative application images to be held on the same on-chip flash.

    The robustness (safe update) of an application via this BootUp mechanism relies on the code only attempting to perform an update when a different valid application image is available. If the system loses power, or suffers a reset, during an update the original alternative image will still be available. When the system recovers from the reset state it will just re-start the update (regardless of whether the on-chip application image is still valid, since even if it is, it will still be different from the alternative image that started the original update).

    Specific examples of this style of BootUp implementation can be found in the ST STM324x9I-EVAL and ST STM32F7xx-EVAL platforms' ROMAPP startup type.

  • A more sophisticated update solution that supports a “bundle” of application specific files. In this case BootUp is responsible for identifying, loading and executing the main application from within a bundle held in NVM. The application is loaded into and executed in external RAM memory.

    The application itself is generally responsible for identifying, acquiring, verifying and installing any available bundle updates into NVM. BootUp is responsible solely for loading and executing an updated “main” application from within the bundle. Optionally, as a fall-back, if no valid bundle can be located in NVM, then BootUp can locate, verify and install a complete bundle from external media such as an SD card.

    The design of this update mechanism enables, in addition to pure application updates, the update of other target resident code and data. These files might include FPGA bitfiles, DSP firmware, application data and so forth. The bundle update system includes support for decompression and checksumming of the bundle contents. See the Bundle image support chapter for further details.

    Examples of this BootUp approach are available in the ST STM324x9I-EVAL and ST STM32F7xx-EVAL platforms' bundle support.

Architectures, variants or platforms that support the BootUp loader will implement CYGINT_BOOTUP_APPSTART. This feature allows BootUp to start the main application and is an essential requirement for the BootUp world to be used.

If BootUp starts when there is no valid on-chip application, and no valid alternative application is available, then if the platform provides the macro CYG_HAL_BOOTUP_BADAPP then that is used to call platform specific code. This provides a hook to allow target specific feedback indicating the lack of an application.

195.2. Configuration

If CYGINT_BOOTUP_UPDATE is not defined then the BootUp loader will simply just execute the “main” application if it is present and valid. If the platform defines CYG_HAL_BOOTUP_COPYAPP then platform supplied code to copy an application to its executation location is called (e.g. for RAM loaded applications). In reality if neither CYGINT_BOOT_UPDATE and CYG_HAL_BOOTUP_COPYAPP are provided by the target then there is no real need for the BootUp to be used, and a normal simple ROM application configuration would suffice.

When CYGINT_BOOTUP_UPDATE is defined by a platform it indicates that the platform provides the mechanism for identifying if a different alternative application image is available, and that the alternative image should replace the current main (normally on-chip) application when different. It is the responsibility of the platform supplied routines to implement how such image validation is performed.

The following configuration options control the main features of the BootUp bootROM world:

CYGBLD_BUILD_BOOTUP controls whether the BootUp image is created, and will normally be defined for all BootUp configurations.

CYGIMP_BOOTUP_UPDATE controls whether the BootUp bootROM supports replacing the main application image with a different image from the alternative storage location. If not defined then BootUp will simply start the main application.

CYG_HAL_BOOTUP_COPYAPP controls whether the platform provides code to copy an application from NVM to RAM for execution.

195.2.1. Platform Support

A platform supporting the BootUp application update and start features provides the necessary support via specifically named functions. When defined by the platform the BootUp code will call the named macro to perform the necessary action. In the list below the function prototypes are shown using example names. Normally the platform will just map the macro name to a specific named function provided by the platform HAL.

  • CYG_HAL_BOOTUP_VALID_MAIN

    cyg_bool plf_bootup_valid_main(void);

    The function referenced by this macro returns boolean true if the main application image is valid (this is the application image that BootUp starts). It will return boolean false if no valid main application is found.

  • CYG_HAL_BOOTUP_VALID_ALT

    cyg_bool plf_bootup_valid_alt(void);

    The function referenced by this macro returns boolean true if the alternative (pending update) application image is valid and different from the current main application. This is the application image that BootUp will automatically replace the main application with when it is different from the current main application. It will return boolean false if no valid alternative application is available, or the alternative image is the same as the current main application.

  • CYG_HAL_BOOTUP_VALID_UPDATE

    cyg_bool plf_bootup_validate_update(void);

    The function referenced by this macro is only called if CYG_HAL_BOOTUP_VALID_MAIN has returned false to indicate that the main application image is missing or invalid. This macro returns boolean true if the alternative (pending update) application image is valid and the main application has been updated successfully. This macro will return boolean false if no valid alternative image is available or the update process has failed.

    [Note]Note

    The CYG_HAL_BOOTUP_VALID_ALT and CYG_HAL_BOOTUP_VALID_UPDATE macros are mutually exclusive, since they implement slightly different “update” logic based on the presence of a valid main application. A platform should only define one of these macros depending on the style of automatic application update required.

  • CYG_HAL_BOOTUP_UPDATE

    cyg_bool plf_bootup_update(void);

    The function referenced by this macro will replace the main application image with the alternative image. It is only called after the respective images have been validated and only when the alternative image is different as ascertained by a CYG_HAL_BOOTUP_VALID_ALT call. It will return boolean true if it successfully updates the main application, otherwise boolean false is returned to indicate failure.

  • CYG_HAL_BOOTUP_COPYAPP

    cyg_bool plf_bootup_copyapp(void);

    The function referenced by this macro returns boolean true if the main application image has been successfully copied to its execution location. It will return boolean false if no valid main application is available.

  • CYG_HAL_BOOTUP_BADAPP

    void plf_bootup_badapp(void);

    The function referenced by this macro is called when no valid main application exists. This can be used to provide platform specific feedback to the user that the system cannot boot.

If the CYGSEM_BOOTUP_PLF_STARTUP configuration option is enabled then the following C function is called:

void cyg_plf_bootup_startup(void);

This function can be used to provide platform specific optional initialisation prior to the normal BootUp operation being started. This may be performing specific hardware initialisation, or some level of Power On Self Test support.

195.2.1.1. Application Identity

The identification of valid application images is the responsibility of the platform specific code. Depending on the BootUp model implemented by the target platform, it may be the case that a simple binary value will be enough to distinguish different applications, e.g. a monotonically increasing version number, or the UTC timestamp when the binary was produced.

If an application signature needs to be embedded inside the actual application binary then platforms that support the use of BootUp will normally provide a mechanism to provide space within the produced eCos executable. For example the Cortex-M architecture provides the CYGNUM_HAL_CORTEXM_VSR_TABLE_PAD configuration option that allows space for an application specific header to be provided at a fixed offset from the binary start. Similarly the ARM architecture allows for the PLATFORM_PREAMBLE macro to be define to allow for a header to be installed to hold, for example, the BootUp signature, CRC, or whatever information is needed.

The header/block being used to hold such a “signature” need not just contain information for supporting BootUp. For example, it may also need to hold information for the mechanism used to install the pending update application image into the alternative location.

195.2.2. Building BootUp

Platforms that support a BootUp configuration will normally provide a suitable .ecm configuration file to allow a minimal BootUp application to be constructed. The specific platform documentation will provide information regarding BootUp configuration and use, and any specific build sequences. Such documentation should be read in conjunction with this generic BootUp information.

This package provides an example import file in the $ECOS_REPOSITORY/bootup/<version>/misc/bootup_ROM.ecm.example file. When porting BootUp support to a new platform this example file can be used as the basis for the target specific .ecm fragment.

Should it prove necessary to rebuild a BootUp binary it is done most conveniently at the command line. The steps needed to rebuild a ROM version would be similar to:

$ ecosconfig new <target> minimal
[ … ecosconfig output elided … ]
$ ecosconfig import $ECOS_REPOSITORY/hal/TARGETPATH/VERSION/misc/bootup_ROM.ecm
[ … ecosconfig output elided … ]
$ ecosconfig resolve
$ ecosconfig tree
$ make

At the end of the build the install/bin subdirectory will contain the file bootup.bin. This may be programmed into the target platform as specified for the system being targeted.

195.3. Applications using VALID_ALT

The following section is only relevant for target platforms that define CYG_HAL_BOOTUP_UPDATE and CYG_HAL_BOOTUP_VALID_ALT where the BootUp world is designed to allow for robust in-field updates of the firmware on a device.

For such systems the application started by BootUp must implement some of the support needed with regard to providing the “pending update” application image. When a new firmware update has been downloaded by the main application it will normally force a system restart, which will cause BootUp to perform the necessary update prior to starting the new main application.

The main application, when loading a pending update application into the alternative memory/device (e.g. off-chip SPI), should ensure that it does not set (write) the "valid signature" until it has validated the correct storage of the rest of the image. This requirement ensures that if a system reset occurs before the signature has been written that the image will NOT be interpreted by BootUp as being valid. This allows the BootUp loader to be simpler since it can treat a valid, complete, signature as an indication that the application was written correctly.

At a minimum (and critically) the main application needs to ensure that it invalidates the alternative image signature prior to starting the process of storing a new application image into the alternative area. This ensures a partial image is not incorrectly identified as a valid, pending, update. If CRC checking is also being used by the platform HAL then this likelihood is minimised.

[Note]Note

This requirement that the alternative storage area must have a complete valid image, whenever there is a complete signature present, ensures that in the case where the implementation does not use a CRC (or similar check) for the BootUp code to perform validation of a complete image, that any previous previous valid signature is not incorrectly accessed and treated as “valid”. For example, if the writing of a subsequent pending update is interrupted (CPU reset, etc.) before it “overwrites” the signature of the previously stored image. If a pending update is downloaded to the holding area, validated and marked as such BUT the system is not rebooted (so the pending update is not applied). Subsequently another pending update starts to download a different image to the holding area but the process is interrupted before the previous image “valid” signature is over-written. The BootUp code could then incorrectly interpret the invalid (partially overwritten) image as being valid if no other validity checks are performed. This is why the rule exists that the code performing the pending update storage should first invalidate the signature.

It is the responsibility of the main application storing the pending update to ensure that the complete image is valid PRIOR to finalising the platform specific signature. To reiterate, the BootUp package, in combination with the platform HAL support, only requires a simple “signature validity check” for robustness WHEN the code storing the pending update ensures that if there is a valid signature in the alternative area then the rest of the bytes are also valid (i.e. a complete valid image is in place).

Since the BootUp will only perform an update when the valid alternative image is different, there is no strict need to erase the signature/image until the main application needs to provide a new update. However, doing so during its normal startup will avoid BootUp having to spend CPU cycles validating and checking the alternative image prior to checking the signature and deciding not to update.

[Note]Notes
  1. To reiterate, the main application (not BootUp) is responsible for invalidating (erasing/removing) the alternative image, or at least the signature. This allows BootUp to be simpler since it only needs to be able to read from the alternative image location.
  2. The signature can either be embedded in the application (assuming the caveat of it being the last data written), or it can be a totally separate distinct section maintained in conjunction with the update application image. Such design decisions are left to the specific platform HAL support. The use of other validation mechanisms, e.g. a CRC, will only be required if the medium that is used to store the alternative (pending) image can suffer from data corruption, or transient read errors. Such a situation will be extremely unlikely for the vast majority of implementations.