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.

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: 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.

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.

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.

2017-02-09
Documentation license for this page: eCosPro License