Chapter 203. Rebuilding RedBoot

203.1. Introduction

Prebuilt images of RedBoot are provided for all target platforms supported by an eCosCentric release, so it is not normally required to rebuild RedBoot in order to be able to begin your software development on eCos/eCosPro and the target platform. However, for later development you may wish to build your own cut down version of RedBoot or custom enhanced version that includes features such as manufacturing tests, initial programming, recovery, security and so on. This chapter describes the process of building, or rebuilding, RedBoot.

RedBoot is built as an application on top of eCos. The makefile rules for building RedBoot are part of the eCos CDL package so building RedBoot may be easily achieved. Typically building involves a command shell and the command line tool ecosconfig, with additional configuration or final build done through the eCos Configuration Tool.

Building RedBoot requires only a few steps: selecting the platform and the RedBoot template, importing a platform specific configuration file, and finally starting the build.

The platform specific configuration file makes sure the settings are correct for building RedBoot for the given target platform. Each target platform supporting RedBoot normally provides at least one configuration file whose name typically indicates the startup mode of RedBoot (see Section 201.6, “RedBoot Startup Mode”). For example, redboot_RAM.ecm indicates the filename of a RAM mode RedBoot configuration and redboot_ROM.ecm or redboot_ROMRAM.ecm for a ROM or ROMRAM mode RedBoot configuration filename respectively. There may be additional configuration files according to the requirements of the particular platform. These files are placed into the install/etc/redboot/<target> directory of the install tree, or may be found in the misc sub-directory of the platform HAL directory for older releases of eCos.

The RedBoot build process results in a number of files in the install/bin directory. The ELF file redboot.elf is the principal result. Depending on the platform CDL, there will also be generated versions of RedBoot in other file formats, such as redboot.bin (binary format, good when doing an update of a primary RedBoot image, see Section 204.3, “Update the primary RedBoot flash image”), redboot.srec (Motorola S-record format, good when downloading a RAM mode image for execution), and redboot.img (stripped ELF format, good when downloading a RAM mode image for execution, smaller than the .srec file). Some platforms may provide additional file formats and also relocate some of these files to a particular address making them more suitable for downloading using a different boot monitor or flash programming tools.

The platform specific information in the relevant platform's HAL documentation must be consulted as there may be other special instructions required to build RedBoot.

203.2. Variables

These instructions assume that the ECOS_REPOSITORY environment variable contains the full pathname of the packages subdirectory or directories containing the eCosPro repository or repositories from which RedBoot is to be built.

These instructions also make use of the ECOS_TARGET and REDBOOT_CFG environment variables to simplify and provide generic instructions for building RedBoot. Their used is not required and users are free to replace these with their own actual values in the instructions provided.

The instructions provided in this section are for a bash shell environment but are also applicable to a Windows CMD environment. The only differences between the instructions for either is the appearance of environment variables in the instructions and the different format of directory paths. For example, where you see the use of the ${REDBOOT_CFG} environment variable in the bash shell, %REDBOOT_CFG% must be used in the Windows CMD environment.

The setting of an envirnment variable also differs. For example in the bash shell a variables may be set as follows:

$ export REDBOOT_CFG=redboot_RAM

In the windows CMD environment a variable is set as follows:

C:\users\demo> set REDBOOT_CFG=redboot_RAM

The same applies for the ${ECOS_TARGET} environment variable. In the example below it is set for at91sam9g45ek target platform, the AT91SAM9G45-EKES board. For the bash shell:

$ export ECOS_TARGET=at91sam9g45ek

For the Windows CMD:

C:\users\demo> set ECOS_TARGET=at91sam9g45ek
[Note]Note

Windows users using eCosPro Developer's Kits may also use the bash shell by changing the shell opened from the eCos Configuration Tool using the ToolsShell menu option by selecting ViewSettings (Ctrl+T) , selecting the Viewers/Shell tab within the resulting dialog and changing the Command Shell to bash.

203.3. Building RedBoot using ecosconfig

To build RedBoot using the ecosconfig tool in a command line environment:

  1. Create a temporary directory for building RedBoot, and change into it. For example:

    $ mkdir /tmp/${REDBOOT_CFG}
    $ cd /tmp/${REDBOOT_CFG}
  2. Create a partial build tree to instantiate the platform specific configuration files for the chosen platform:

    $ ecosconfig --noresolve new ${ECOS_TARGET} redboot
    $ ecosconfig --ignore-errors --no-resolve tree
    $ make etc

    At this point all the relevant RedBoot configuration files should be found in the install/etc/redboot/${ECOS_TARGET} subdirectory. install/etc will become further populated with other configuration files, such as example PEEDI and OpenOCD configuration files, after a complete build of RedBoot.

  3. Import the appropriate platform RedBoot configuration file:

    $ ecosconfig --no-resolve import install/etc/${ECOS_TARGET}/${REDBOOT_CFG}.ecm

    At this point the eCos configuration in ecos.ecc will contain all the unresolved settings required to build a ${REDBOOT_CFG} for the ${ECOS_TARGET} platform

  4. Resolve any conflicts and create build tree for RedBoot:

    $ ecosconfig resolve
    $ ecosconfig tree
  5. RedBoot can now be built:

    $ make

    The resulting RedBoot files will be in the associated install directory, in this example, ./install/bin.

[Note]Note

Older revisions of eCos or some platforms may not support the etc make target. In these instances the RedBoot configuration file will not be found in the install/etc/${ECOS_TARGET}/ subdirectory but may be found in the misc subdirectory of the platform HAL within ${ECOS_REPOSITORY}. In these instances please refer to the specific platform HAL documentation for instructions on how to build RedBoot using an appropriate configuration file.

To build for another configuration, simply change the REDBOOT_CFG definition accordingly. For example:

export REDBOOT_CFG=redboot_ROM
mkdir /tmp/${REDBOOT_CFG}
cd /tmp/${REDBOOT_CFG}
ecosconfig --no-resolve new ${ECOS_TARGET} redboot
ecosconfig --no-resolve --ignore-errors tree
make etc
ecosconfig --no-resolve import install/etc/${REDBOOT_CFG}.ecm
ecosconfig resolve
ecosconfig tree
make
[Note]Notes
  • The options --no-resolve and --ignore-errors are essential to certain targets. Their purpose is to delay the libcdl inferrence engine from being applied to a configuration until the required settings for the RedBoot configuration have been imported. This prevents any inferrences from being made during each creation step of the RedBoot configuration which may steer the final outcome to an unresolveable conflict. This is because inferrences cannot currently be implicitly undone within a configuration, and some inferences may need to be reversed by settings imported within ${REDBOOT_CFG}.ecm. The final ecosconfig resolve command above therefore applies the libcdl inferrence engine to the configuration settings once all the required settings have been made. The options are otherwise harmless for targets which are not sensitive to premature inferrences.
  • If the bash shell or Windows CMD was started from within the eCos Configuration Tool, the environment variable ECOS_TARGET will be set within the shell to the target of the configuration tool's eCos configuration at the time bash or CMD was started.

203.4. Rebuilding RedBoot from the eCos Configuration Tool

While it is possible to rebuild RedBoot from the eCos Configuration Tool, creating a RedBoot configuration is not always simple due to certain behavioural limitations of the eCos Configuration Tool. Instead, developers are recommended to use the ToolsShell menu option to create a command shell and follow the instructions in Section 203.3, “Building RedBoot using ecosconfig up to and including the make etc step with the inclusion of the --compat and --config=<savefile>.ecc options to every ecosconfig command. For example, assuming a working directory of /tmp:

cd /tmp
ecosconfig --compat --config=<savefile>.ecc --no-resolve new ${ECOS_TARGET} redboot
ecosconfig --compat --config=<savefile>.ecc --no-resolve --ignore-errors tree
make etc
[Note]Note

The environment variable ${ECOS_TARGET} will be set by the eCos Configuration Tool to the current configuration's hardware, or profile's default hardware if no configuration has been created. It may therefore not be necessary to set this variable.

At this point the 1st stage RedBoot configuration can be loaded into the eCos Configuration Tool using FileOpen to open the file /tmp/<savefile>.ecc and the RedBoot settings imported from /tmp/<savefile>_install/etc/redboot/${ECOS_TARGET}/${REDBOOT_CFG}.ecm. using FileImport .

Depending on the platform, a number of conflicts may need to be resolved before the build can be started. To resolve conflicts, if any, use the menu item ToolsResolve Conflicts .

If you wish to switch to a different location or filename, you may now do so using the menu option FileSave As .

Generate a build tree to instantiate the platform specific configuration files for the chosen platform BuildGenerate Build Tree .

Then start the build ( BuildLibrary (F7) ) and wait for it to complete. The resulting RedBoot files will be in the associated install directory, for the example this would be <savefile>_install/bin

As noted above, please also refer to the platform's HAL documentation to determine if there are any additional platform specific instructions that must be followed when rebuilding RedBoot.