Name

BootUp Integration — Detail

BootUp

The BootUp support for the STM32L4R9-DISCO target is primarily implemented in the stm32l4r9_disco_support.c file. The majority of the functions provided by that source file are only included when the CYGPKG_BOOTUP package is being used to construct the actual BootUp ROM loader binary.

The BootUp code is designed to be very simple, and it is envisaged that once its implementation has been tested and validated, the binary will only need to be installed onto a device once. Its only purpose is to allow the safe updating and startup of the main application. If the BootUp code ever needs to be replaced then it is a “factory” operation, for example using JTAG to re-program the on-chip flash.

This platform specific documentation should be read in conjunction with the generic BootUp package.

The BootUp package provides a basic but fully functional implementation for the platform. This has been tested to ensure that the underlying mechanism is sound. It is envisaged that the developer will customize and further extend the platform side support to meet their specific application update requirements.

BootUp loaded applications

Applications started via the BootUp loader, since they cannot include the CYGPKG_BOOTUP package themselves, may need access to some related configuration state. The platform is responsible for providing such “common” information. For example, the CDL option CYGIMP_BOOTUP_RESERVED specifies the amount of on-chip flash set aside for BootUp. Applications can then ensure that they do not interfere with the BootUp loader if using the remaining on-chip flash for their own purposes.

[Warning]Warning

Care must be taken to ensure that the target application configuration matches the BootUp configuration, since it is normally expected that the applications to be loaded will be independent of the initial BootUp build environment. This includes the fundamental on-chip flash space set aside for the BootUp ROM loader code (CYGIMP_BOOTUP_RESERVED). It is expected that such values, for a particular platform instance, will be fixed at a suitable point during development, and definitely before products are shipped. It is the responsibility of the developer to ensure a consistent configuration between the BootUp ROM loader and any applications that may be installed/started by that BootUp code.

On-Chip ROMAPP applications

BootUp provides an alternative mechanism that supports the safe update of on-chip flash resident (CYG_HAL_STARTUP_ROMAPP) applications.

Updates using this mechanism are initiated and directed solely by the application itself. The application is responsible for locating, acquiring and verifying a new update, and placing it into Non-Volatile Memory (NVM) storage. If BootUp detects a verified update in NVM, it installs the update into the on-chip flash, overwriting and replacing the existing application. The updated application is then executed.

The example implementation uses a simple scheme that checks a fixed-format contiguous structure near the start of the binary application image file. Other than the fields used to identify the structure, the BootUp code does not interpret the hal_stm32l4r9_disco_bootup_structure_t in any other way.

Depending on how the alternative (pending update) application is downloaded and installed in the NVM, it may be more relevant to have the tail marker at the very end of the binary image. The developer may wish to update the build/release process so that the actual binary length is held in the application description structure, since that could avoid the overhead of unnecessary flash reads and writes when processing updates. Similarly, instead of a simple binary number being used to differentiate application images, the choice may be made to use the 64-bit UTC timestamp the application was created, or a human-readable string as the unique identification for a release. It is the responsibility of the build/release engineer to ensure individual releases are uniquely identifiable.

It is critical that the main application, when storing a pending update, stores the tail marker as the last bytes written. It is the responsibility of the main application to verify the data written, prior to placing the tail marker. This ensures that a partial image is not treated as a valid update. For example the sequence undertaken by the main application would be:

Table 310.1. Pending update sequence

OperationDetails
Invalidate “previous” alternative image At a minimum ensure an invalid signature tail marker is written. Erasing the flash is normally required anyway, and would invalidate any previous image.
Receive update application image and write to alternative image location NOT writing the tail marker. The code that stores the application should leave a “hole” where the tail marker resides to ensure a partial image is not incorrectly treated as valid
Verify downloaded contents e.g. CRC or binary comparison. Normally this would be done as individual application chunks are downloaded and written to the alternative storage
Write tail marker This is the very last operation after validating that the alternative image has been stored correctly. If an error has occured during the download then not-writing the tail ensures that the BootUp loader will not interpret the data written as a pending update
Force system RESET to start updatee.g. using the HAL_PLATFORM_RESET macro

The BootUp loader code will only READ from the alternative image location. This ensures that if an in-progress update is interrupted (e.g. power-loss) then when the system restarts the BootUp code will restart the application update as required.

If the BootUp platform implementation for validating the alternative image is extended to include a CRC, or similar “slow” processing, it may be worth considering whether the main application on startup will always invalidate the tail marker after an update to avoid subsequent system resets having to re-validate the alternative image prior to discovering that it is the same as the current main application.

[Note]Note

We cannot have the SIGNATURE support purely conditional on the BOOTUP support; since non-BOOTUP applications need to be built leaving the space. For the moment this is only enforced for ROMAPP applications, since that is all that the simple BootUp update support implements.

Building BootUp

The ROM startup type is chosen for BootUp so that the loader uses the on-chip SRAM for its workspace.

Example eCos configuration templates for BootUp are provided in the misc directory of the release. The bootup_ROM.ecm configuration file can be used to configure the BootUp loader.

Building a BootUp ROM image is most conveniently done at the command line. The steps needed to rebuild the ROM version of BootUp on linux are:

$ mkdir bootup_rom
$ cd bootup_rom
$ ecosconfig new stm32l4r9_disco minimal
[ … ecosconfig output elided … ]
$ ecosconfig import $ECOS_REPOSITORY/hal/cortexm/stm32/stm32l4r9_disco/current/misc/bootup_ROM.ecm
$ ecosconfig resolve
$ ecosconfig tree
$ make

The steps needed to rebuild the bundle based ROM version of BootUp on Windows within the Shell Environment are:

C:\Users\demo> mkdir bootup_rom
C:\Users\demo> cd bootup_rom
C:\Users\demo\bootup_rom> ecosconfig new stm32l4r9_disco minimal
[ … ecosconfig output elided … ]
C:\Users\demo\bootup_rom> ecosconfig import %ECOS_REPOSITORY%/hal/cortexm/stm32/stm32l4r9_disco/current/misc/bootup_ROM.ecm
C:\Users\demo\bootup_rom> ecosconfig resolve
C:\Users\demo\bootup_rom> ecosconfig tree
C:\Users\demo\bootup_rom> make

The resulting install/bin/bootup.bin binary can then be programmed into the on-chip flash from address 0x08000000.

It is expected that the BootUp binary is installed onto the STM32L4S5VI on-chip flash either via JTAG or by utilising the on-chip BootROM USB based DFU process. This is a factory or in-field process requiring specific equipment/host-software.

Once BootUp is installed it is not normally expected to require updating. Its purpose is to bootstrap the main application, and provide a standard mechanism for installing the main application. The update mechanism does NOT provide a method for updating the BootUp loader itself. If in-field updates of the BootUp binary are necessary, this could be achieved via the STM32 on-chip BootROM USB based DFU process.

Altinit Test

This application is used to test BootUp support for updating a ROMAPP application from the QSPI flash. Since there is no Ethernet available on the board, this test uses the application already programmed in to the on-chip flash.

The test expects a ROMAPP application to be stored in the on-chip flash. It erases the alternate application in the QSPI flash, copies the ROMAPP application from on-chip flash into QSPI, and then invalidates the signature of the application in on-chip flash. When BootUp starts it will discover that the main application is invalid, copy the alternate application from the QSPI and then run it.

An example eCos configuration template for building the altinit application is provided in the misc directory. The steps needed to build this application are as follows:

$ mkdir altinit
$ cd altinit
$ ecosconfig new stm32l4r9_disco kernel
[ … ecosconfig output elided … ]
$ ecosconfig import $ECOS_REPOSITORY/hal/cortexm/stm32/stm32l4r9_disco/current/misc/altinit_SRAM.ecm
$ ecosconfig resolve
$ ecosconfig tree
$ make
$ make -C hal/cortexm/stm32/stm32l4r9_disco/current tests

Following this, the altinit executable can be found in install/tests/hal/cortexm/stm32/stm32l4r9_disco/current/tests/altinit. Running this will produce the following output:

INFO:<STM32L4_BOOTUP_ALTERNATIVE_OFFSET 00008000>
INFO:<STM32L4_BOOTUP_ALTERNATIVE_MAXLEN 000F8000>
INFO:<CYGNUM_BOOTUP_SIGNATURE_OFFSET 8>
INFO:<CYGNUM_BOOTUP_SIGNATURE_LENGTH 16>
INFO:<Erasing MX25L128 area for alternative image>
INFO:<Copy main image to alt>
INFO:<Set signature in alt image>
INFO:<Invalidate main image>
INFO:<Update done>

The erase and copy operations here may take a some time, do not reset the board until the program is finished.