Chapter 227. Updating RedBoot

227.1. Introduction

RedBoot normally resides in internal flash on the CPU or external flash on the board. It is often possible to update RedBoot in situ using a hardware debugger or even Redboot's flash management commands. Occasionally vendor specific software tools such as ATMEL's SAM-BA In- system Programmer may also be required.

The process of updating RedBoot in situ is documented in this section. For this process, it is assumed that the target is connected to a host system and that there is a serial or TCPIP connection giving access to the RedBoot CLI. For platforms with a ROMRAM mode RedBoot, skip to Section 227.3, “Update the primary RedBoot flash image”.

Older boards may use EEPROM although this is a lot less common nowadays. In this case of EPROM, updating RedBoot normally necessitates physically removing the part and reprogramming a new RedBoot image into it using prommer hardware.

[Note]Note

The addresses and sizes included in the below are examples only, and will differ from those you will see. This is normal and should not cause concern.

227.2. Load and start a RedBoot RAM instance

There are a number of choices here. The basic case is where a RAM mode image has been stored in the FIS (flash Image System). To load and execute this image, use the commands:

RedBoot> fis load RedBoot[RAM]
RedBoot> go

If this image is not available, or does not work, then an alternate RAM mode image can be loaded via one of several other methods:

  • TFTP via a network connection:

    RedBoot> load redboot_RAM.img
    Entry point: 0x060213c0, address range: 0x06020000-0x060369c8
    RedBoot> go
  • X, Y or Z modem: (y modem in this example)

    RedBoot> load -m y -r -b %{FREEMEMLO}
    ...
    Raw file loaded 0x06046800-0x06062fe8, assumed entry at 0x06046800
    RedBoot> go
  • A filesystem, if available:

    RedBoot> load hda2:redboot_RAM.img
    Entry point: 0x060213c0, address range: 0x06020000-0x060369c8
    RedBoot> go
[Note]Notes
  • Refer to the load command for a complete list of options available.
  • If you expect to be doing this more than once, it is a good idea to program the RAM mode image into the flash. You do this using the fis create command after having downloaded the RAM mode image, but before you start it.

    Some platforms support locking (write protecting) certain regions of the flash, while others do not. If your platform does not support locking, simply ignore the fis unlock and fis lock steps (the commands will not be recognized by RedBoot).

    RedBoot> fis unlock RedBoot[RAM]
      ... Unlock from 0x00000000-0x00020000: ..
    RedBoot> fis create RedBoot[RAM]
    An image named 'RedBoot[RAM]' exists - continue (y/n)? y
    * CAUTION * about to program 'RedBoot[RAM]'
                at 0x00020000..0x000369c7 from 0x06020000 - continue (y/n)?y
    ... Erase from 0x00020000-0x00040000: ..
    ... Program from 0x06020000-0x060369c8 at 0x00020000: ..
    ... Erase from 0x00070000-0x00080000: .
    ... Program from 0x0606f000-0x0607f000 at 0x00070000: .
    RedBoot> fis lock RedBoot[RAM]
      ... Lock from 0x00000000-0x00020000: ..

227.3. Update the primary RedBoot flash image

An instance of RedBoot should now be running on the target from RAM. This can be verified by looking for the mode identifier in the banner. It should be either [RAM] or [ROMRAM].

If this is the first time RedBoot is running on the board or if the flash contents has been damaged, initialize the FIS directory:

RedBoot> fis init -f
About to initialize [format] FLASH image system - continue (y/n)? y
*** Initialize FLASH Image System
... Erase from 0x00020000-0x00070000: .....
... Erase from 0x00080000-0x00080000:
... Erase from 0x00070000-0x00080000: .
... Program from 0x0606f000-0x0607f000 at 0x00070000: .

It is important to understand that the presence of a correctly initialized FIS directory allows RedBoot to automatically determine the flash parameters. Additionally, executing the steps below as stated without loading other data or using other flash commands (than possibly fis list) allows RedBoot to automatically determine the image location and size parameters. This greatly reduces the risk of potential critical mistakes due to typographical errors. It is still always possible to explicitly specify parameters, and indeed override these, but it is not advised.

[Note]Note

If the new RedBoot image has grown beyond the slot in flash reserved for it, it is necessary to change the RedBoot configuration option CYGBLD_REDBOOT_MIN_IMAGE_SIZE so the FIS is created with adequate space reserved for RedBoot images. In this case, it is necessary to re-initialize the FIS directory as described above, using a RAM mode RedBoot compiled with the updated configuration.

Using the load command, download the new flash based image from the host, relocating the image to RAM:

RedBoot> load -r -b %{FREEMEMLO} redboot_ROM.bin
Raw file loaded 0x06046800-0x06062fe8, assumed entry at 0x06046800
[Note]Notes
  • This command loads the RedBoot image using the TFTP protocol via a network connection. Other methods of loading are available, refer to the load command for more details.
  • The binary version of the image is being downloaded. This is to ensure that the memory after the image is loaded should match the contents of the file on the host. Loading SREC or ELF versions of the image does not guarantee this since these formats may contain holes, leaving bytes in these holes in an unknown state after the load, and thus causing a likely cksum difference. It is possible to use these, but then the step verifying the cksum below may fail.

Once the image is loaded into RAM, it should be checksummed, thus verifying that the image on the target is indeed the image intended to be loaded, and that no corruption of the image has happened. This is done using the cksum command:

RedBoot> cksum
Computing cksum for area 0x06046800-0x06062fe8
POSIX cksum = 2535322412 116712 (0x971df32c 0x0001c7e8)

Compare the numbers with those for the binary version of the image on the host. If they do not match, try downloading the image again.

Assuming the cksum matches, the next step is programming the image into flash using the FIS commands.

Some platforms support locking (write protecting) certain regions of the flash, while others do not. If your platform does not support locking, simply ignore the fis unlock and fis lock steps (the commands will not be recognized by RedBoot).

RedBoot> fis unlock RedBoot
... Unlock from 0x00000000-0x00020000: ..
RedBoot> fis create RedBoot
An image named 'RedBoot' exists - continue (y/n)? y
* CAUTION * about to program 'RedBoot'
            at 0x00000000..0x0001c7e7 from 0x06046800 - continue (y/n)? y
... Erase from 0x00000000-0x00020000: ..
... Program from 0x06046800-0x06062fe8 at 0x00000000: ..
... Erase from 0x00070000-0x00080000: .
... Program from 0x0606f000-0x0607f000 at 0x00070000: .
RedBoot> fis lock RedBoot
  ... Lock from 0x00000000-0x00020000: ..

227.4. Reboot; run the new RedBoot image

Once the image has been successfully written into the flash, simply reset the target OR RUN THE reset command and the new version of RedBoot should be running.

When installing RedBoot for the first time, or after updating to a newer RedBoot with different configuration keys, it is necessary to update the configuration directory in the flash using the fconfig command. See Section 225.5, “Persistent State Flash-based Configuration and Control ”.