Description

A RedBoot configured with RBL support will provide a new command rbl with various sub-commands. These allow users to access the RBL functionality at the RedBoot prompt.

rbl info can be used to get information about the RBL subsystem, for example how many flash blocks are allocated to each code block. Typical output might look like:

RedBoot> rbl info
Code block A : backup
  First flash block 1 (address 0xffe40000)
  Size 52012, sequence number 3
Code block B : primary
  First flash block 3 (address 0xffec0000)
  Size 52028, sequence number 4
Data block A : primary
  First flash block 2 (address 0xffe80000)
  Size 272, sequence number 11
Data block B : backup
  First flash block 5 (address 0xfff40000)
  Size 272, sequence number 10

This shows that the code is currently on its fourth revision and is held in flash block 2 at the given address. Here all code and data blocks fit into a single flash block, which will not always be the case. The data is currently on revision 11.

The rbl newcode command can be used to install a new revision of the code, although usually this will be done by the application itself via a call to rbl_update_code. However the RedBoot command can be used for the initial installation or if the currently installed version is broken somehow. Typically the code will first be loaded into RAM using a RedBoot load command, then programmed into flash.

RedBoot> load -r -m ymodem -b %{freememlo}
Raw file loaded 0x0000d400-0x00019f3b, assumed entry at 0x0000d400
xyzModem - CRC mode, 409(SOH)/0(STX)/0(CAN) packets, 3 retries
RedBoot> rbl newcode -b %{freememlo} -l 52028
... Erase from 0xffe40000-0xffe80000: .
... Program from 0x0000d400-0x00019f3c at 0xffe40000: .
... Program from 0x00005728-0x0000573c at 0xffe7ffec: .

The loaded program should be a stripped ELF executable appropriate for the target platform. The -b option specifies the memory location. Usually the RedBoot %{freememlo} variable will be used for this. The -l option corresponds to the file length. First the appropriate flash block or blocks are erased. Next the code is written to the flash. Finally the RBL code writes a little trailer at the end of the flash block containing a checksum, a sequence number, and similar information.

The rbl newdata command provides the same functionality for persistent data. Again the data is first loaded into RAM, then programmed into flash.

RedBoot> load -r -m ymodem -b %{freememlo}
Raw file loaded 0x0000d400-0x0000d5ba, assumed entry at 0x0000d400
xyzModem - CRC mode, 6(SOH)/0(STX)/0(CAN) packets, 3 retries
RedBoot> rbl newdata -b %{freememlo} -l 443
... Erase from 0xfff40000-0xfff80000: .
... Program from 0x0000d400-0x0000d5bb at 0xfff40000: .
... Program from 0x00005728-0x0000573c at 0xfff7ffec: .

The rbl boot command is used to load and run the current primary code block. The block should contain a stripped ELF executable which still contains the required relocation tables and the entry point, so there is no need for additional options. During development this command can be run manually to try out the current version of the application. In a production system RedBoot can be configured to run this command automatically by setting the configuration option CYGDAT_REDBOOT_DEFAULT_BOOT_SCRIPT. The command does not return. If it is necessary to get back to a RedBoot prompt then either the target board should be reset or the loaded application should call rbl_reset.

rbl condboot is a variant of rbl boot, available only on certain platforms. The command checks a platform-specific condition, for example the state of a jumper or a button. Depending on the condition condboot will either proceed to load and run the current primary code block in exactly the same way as rbl boot, or it will do nothing. Again in a production system RedBoot can be configured to run this command automatically by setting the configuration option CYGDAT_REDBOOT_DEFAULT_BOOT_SCRIPT. Following power up or reset RedBoot will normally run the current application, but if the button is held down then it will provide an interactive session instead (unless of course the boot script runs additional commands after rbl condboot). The interactive session allows the usual RedBoot and rbl commands to be executed, so for example the user can perform a ymodem transfer and then replace the primary code block via rbl newcode.

Jumpers and buttons are inherently platform-specific so rbl condboot will only be built if the platform HAL provides a suitable macro HAL_RBL_CONDBOOT. Typically this macro would be defined in the header file cyg/hal/plf_io.h which is automatically #include'd by the RBL code. The macro should take the following form:

#define HAL_RBL_CONDBOOT(_do_boot_)     \
    CYG_MACRO_START                     \
    …                                   \
    CYG_MACRO_END

_do_boot_ should be set to 1 if the system should proceed with the bootstrap, i.e. load and run the primary code block. It should be set to 0 if rbl condboot should do nothing. Depending on the complexity of the hardware the macro body may involve just a couple of lines of inline code or it may involve a function call into the main platform HAL code, for example:

#define HAL_RBL_CONDBOOT(_do_boot_)                                 \
    CYG_MACRO_START                                                 \
    extern int hal_alaia_rbl_condboot(void);                        \
    _do_boot_ = hal_alaia_rbl_condboot();                           \
    CYG_MACRO_END