Chapter 202. BootUp overview
Table of Contents
eCosPro-BootUp is eCosCentric's commercial name for
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.
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.
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).
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.
Architectures, variants or platforms that support the BootUp loader
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.
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
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
CYG_HAL_BOOTUP_COPYAPP are provided by the
target then there is no real need for the BootUp to be used, and a
ROM application configuration would
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
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
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
202.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.
The function referenced by this macro returns boolean
trueif the main application image is valid (this is the application image that BootUp starts). It will return boolean
falseif no valid main application is found.
The function referenced by this macro returns boolean
trueif 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
falseif no valid alternative application is available, or the alternative image is the same as the current main application.
The function referenced by this macro is only called if
falseto indicate that the main application image is missing or invalid. This macro returns boolean
trueif the alternative (pending update) application image is valid and the main application has been updated successfully. This macro will return boolean
falseif no valid alternative image is available or the update process has failed.
CYG_HAL_BOOTUP_VALID_UPDATEmacros 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.
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_ALTcall. It will return boolean
trueif it successfully updates the main application, otherwise boolean
falseis returned to indicate failure.
The function referenced by this macro returns boolean
trueif the main application image has been successfully copied to its execution location. It will return boolean
falseif no valid main application is available.
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.
option is enabled then the following C function is called:
22.214.171.124. 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
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
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
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.
202.2.2. Building BootUp
Platforms that support a BootUp configuration will normally provide a
.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
file. When porting BootUp support to a new platform this example file
can be used as the basis for the target
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/[ … ecosconfig output elided … ] $
At the end of the build
will contain the file
bootup.bin. This may be
programmed into the target platform as specified for the system being
202.3. Applications using
The following section is only relevant for target platforms that
CYG_HAL_BOOTUP_VALID_ALT where the BootUp world
is designed to allow for robust in-field updates of the firmware on a
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.
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.
|2021-09-02||eCosPro Non-Commercial Public License|