How to Install and Configure the RedBoot ROM Monitor

Posted May 04, 2016

RedBoot is a portable, open-source ROM monitor that offers a download and debug environment. What more could you want?

Many embedded developers today use a ROM- or flash-resident software program that provides functionality such as loading and running application software, scripting, read/write access to processor registers, and memory dumps. A ROM monitor, as it is often called, can be a useful and far less expensive debugging tool than an in-circuit emulator.

This article describes the RedBoot ROM monitor. We'll take a look at the features offered by the RedBoot ROM monitor and see how it can be configured. We'll also walk through the steps of rebuilding and installing a new RedBoot image on a target platform. Finally, we'll look at future enhancements that are coming in new releases and how to get support and additional information when using RedBoot.

Red Hat Embedded Debug and Bootstrap (RedBoot)

RedBoot, which is also called Red Hat Embedded Debug and Bootstrap Program, is a standalone open source bootstrap/loader designed for use in embedded systems. Although RedBoot uses software modules from the eCos real-time operating system (RTOS) and is often used in systems running embedded Linux, it is completely independent of both operating systems. RedBoot can be used with any operating system or RTOS—or even without one. The RedBoot source code is available for download and is currently covered by the eCos license, a modified version of the GNU General Public License (GPL).¹

RedBoot includes a GDB "stub," which provides the target side communication software to allow remote debugging via standard GDB protocol commands. This allows you to use RedBoot and a host running the GNU debugger to debug your embedded applications over a serial port or network connection. For more information about using GDB in this way, read Bill Gatliff's "Embedding with GNU: GNU Debugger." ²

RedBoot supports a wide range of processor architectures and hardware platforms. The list of supported architectures includes ARM, Hitachi SHx, MIPS, PowerPC, SPARC, x86, and many others.³

Network and Serial Communications

RedBoot can be run in many different configurations. However, it is typically run from the target platform's flash boot sector or boot ROM. RedBoot is designed to start when the system is powered on, providing enough processor initialization and device configuration to allow you to communicate with the system from that point forward.

RedBoot can be configured to use either a serial port or Ethernet port (via telnet) for communication. Once the first command is received from one of the enabled ports, all RedBoot communications are conducted over that port until the system is reset.

When using the Ethernet port to communicate with RedBoot, it is important to understand how the target will obtain its IP address. There are two methods for configuring the target IP address: static and dynamic. In the static scenario, the IP address for the target is set before the RedBoot image is compiled, as described in a later section of this article, or via command over the serial port.

To assign an IP address dynamically, RedBoot uses the BOOTP protocol, which is a subset of the Dynamic Host Configuration Protocol (DHCP) widely supported on many networks these days. Enabling the target to use dynamic network configuration can also be done at compile time or over the serial port. Of course, in order to get an IP address, the device must be on a network that has an accessible BOOTP or DHCP server.

It is important not to use a dynamic IP address for the RedBoot image if the application software it will load needs an IP address of its own. Otherwise, conflicts may occur in the configuration of the Ethernet port's IP address, causing communication problems with RedBoot, the application software, or both. In this case, it is best to set a static IP address for RedBoot that is outside the range for the dynamic network configuration protocol.

RedBoot is also capable of using the Trivial File Transfer Protocol (TFTP) to download application code automatically, based on the configuration information received with the BOOTP response. In this case, a TFTP server is also needed on the host to provide access to the software images.

Command Line Interface (CLI)

RedBoot provides a command line interface (CLI) for entering commands. At a minimum, the RedBoot CLI is available on the target hardware serial port. If multiple serial ports exist, RedBoot may use any of them for communication. Alternatively, the RedBoot CLI may use the Ethernet port, via the telnet protocol. (By default, RedBoot uses port 9000 for telnet; however, this can be changed using the fconfig command described later.)

FLASH: 0xfe000000-0xfe080000, 8 blocks of 0x00010000 bytes each.
IP: 192.168.0.100, Default server: 192.168.0.3

RedBoot (tm) bootstrap and debug environment - built 17:55:12, Apr 21 2001

Platform: Motorola MBX (PowerPC 860)
Copyright (C) 2000, 2001, Red Hat, Inc.

RAM:0x00000000-0x00400000, 0x00022420-0x003e0000 available
RedBoot>

Listing 1. RedBoot initialization message

The RedBoot initialization message, which is output by the CLI, is shown in Listing 1. This message gives information about the RedBoot image such as the image build date, the target hardware platform, and the resources available for RedBoot to use. When the RedBoot> prompt is shown, the CLI is ready for command input from the user.

The basic form of a RedBoot command is:

COMMAND [-OPTION1] [-OPTION2 VALUE] OPERAND

where OPTION1 and OPTION2 are optional switches for specific actions or additional information that can be added to certain commands. In the case of OPTION2, a value is also included with the switch. OPERAND specifies additional information needed for particular commands.

Commands may be abbreviated to their shortest unique string. For example, dump, dum, du, and d are all valid command inputs for the dump command.

RedBoot downloads application software images using the load command. Images can be downloaded using the TFTP protocol, the X/Y modem protocol, or directly from target hardware resources. After an image is downloaded to the target hardware, the software can be executed using the go command.

A full list of the available commands can be displayed by typing help at the RedBoot prompt. Not all commands are available for all RedBoot images. The available commands depend on the resources provided by the target. For example, some commands may be excluded for hardware platforms that do not have flash memory.

The GDB stub is invoked in the RedBoot image when the "$" character appears as the first character of a command. Once entered, RedBoot remains in GDB mode until the system is restarted.

RedBoot offers several commands worth noting. The first are the Flash Image System (fis) commands. If flash memory is provided on the hardware platform, RedBoot provides the fis commands as a basic file system. These commands are used to manipulate the images in the file system.

RedBoot> fconfig -l
Run script at boot: false
Use BOOTP for network configuration: false
Local IP address: 192.168.1.6
Default server IP address: 192.168.1.12
GDB connection port: 9000
Network debug at boot time: false

Listing 2. Querying RedBoot configuration using the fconfig command

Another useful command is the flash-based configuration and control command, fconfig. Example output from a query of the fconfig command can be found in Listing 2. As you can see from this listing, the configuration can be set for the RedBoot startup sequence. The startup configuration includes whether a boot script should be run at initialization time, whether the BOOTP protocol should be used to obtain an IP address, and the GDB telnet port to use for debugging.

RedBoot also supports boot scripting. This allows you to run commands that you want executed after the power up cycle. Boot scripting can be very helpful when using RedBoot to load a software application image during the product test phase. A timeout can be set to allow you to abort the boot script, by pressing Ctrl+C, before it executes. Boot scripts are setup using the fconfig command.

Configuring RedBoot

It is important to be able to rebuild the RedBoot image yourself, since there may be code updates and bug fixes that you want to use. You'll also need to rebuild RedBoot if you want to customize it, such as by adding your own commands or porting it.

The first step in rebuilding the RedBoot image is to set up the host development environment. The tools needed to build the RedBoot image can be run on a Windows or Linux host platform. The host development tools include the GNU binary utilities (commonly called binutils), the C/C++ compiler, and the debugger.

Detailed steps for building the GNU development tools and setting up the host development environment, based on the target processor architecture and host operating system platform, can be found online at eCos Downloading and Installation.

After the GNU tools are installed, the next step is to get the configuration tools. You can configure and build the RedBoot image using either the graphical Configuration Tool or a command line tool. In this article, we will focus on using the graphical Configuration Tool.

The Configuration Tool allows source-level configuration, which ensures a RedBoot image that is specific for each user's application. The entire source code repository and the Configuration Tool rely on the Component Definition Language (CDL) to describe the components in the repository and rules for building the software images.⁴

The Configuration Tool uses the previously set up GNU tools to build the RedBoot image for a specific processor architecture. Additional information about the Configuration Tool can be found online, as well as under the help menu of the Configuration Tool.⁵

For the examples below, I used configtool-2.08-setup.exe, which was the latest release of the Configuration Tool as of the writing of this article. It is a good idea to read the readme.txt file before proceeding with the installation of the Configuration Tool. The file changes.txt, also within the download, lists the modifications to the Configuration Tool executable for different releases.

Next, we need to download the RedBoot source code. The RedBoot source code is contained in the anonymous CVS repository, which can be accessed using free client software. Detailed information is available online.⁶

It is a good idea to get all of the source code, including the eCos files, when connected to the repository. RedBoot uses some of the eCos source files, such as device drivers. After you are certain which files are needed to build your RedBoot image, you can remove the others.

An overview block diagram detailing some of the main software modules in the RedBoot software architecture is shown in Figure 1.

Figure 1. RedBoot software architecture

RedBoot uses a layered approach in its software architecture. The RedBoot architecture was designed to accommodate new functionality and software components. The foundation of RedBoot relies on eCos' Hardware Abstraction Layer (HAL) and device drivers.

Let's take a look at the RedBoot source code directory structure. After downloading the source files from the anonymous CVS repository, the source code files are contained under the packages subdirectory. Under this main directory is the reboot subdirectory where all of the RedBoot files reside. Since the files were downloaded from the anonymous CVS repository, they are all located under the current revision subdirectory.

There is a file called ChangeLog, located under the reboot subdirectory that keeps a list of all changes to the RedBoot source files. Table 1 lists and describes the RedBoot source code directories.

Directory	Description
cdl	Contains the CDL script file that details the RedBoot package configuration and build information. The Configuration Tool uses the CDL files to understand the RedBoot source code.
include	Directory for the header files necessary to build the RedBoot image.
include\fs	Header files for the RedBoot file system.
include\net	Header files for the RedBoot networking support.
misc	Contains the eCos Minimal Configuration (.ecm) file used to import a baseline configuration into the Configuration Tool.
src	Includes the main source files for RedBoot such as the RedBoot startup, flash memory support, the I/O communication, and command line parser files.
src\fs	Source files for RedBoot file system support.
src\net	Source files for RedBoot networking support, including the BOOTP and TFTP source code files.

Table 1. RedBoot source code directory structure

Figure 2 is a snapshot of the RedBoot configuration options that are shown in the Configuration Tool. The Configuration Tool offers an easy method for graphically configuring the necessary components that are built into the RedBoot image.

Figure 2. Configuration Tool showing RedBoot configuration options

Configuration options are enabled or disabled by checking or unchecking the selection boxes for a particular component. The values for a configuration can be set on the right side pane in the configuration window.

There are two methods to create a new RedBoot configuration. The first method is to select Templates under the Build menu item in the Configuration Tool. This brings up the Templates dialog box, which allows the selection of the hardware platform and template packages. In this case, the template package to select is redboot. This method gives a basic set-up for building the RedBoot image with all default configuration options. Additional packages can be added or removed using the Packages dialog box, which is launched by selecting Build—>Packages from the menu.

The second method to create a new RedBoot configuration is to import an eCos minimal configuration (.ecm) file. Minimal configuration files are included for each hardware platform supported by RedBoot. These configuration files are typically located under the misc subdirectory for each architecture under the Hardware Abstraction Layer directory, hal.

Minimal configuration files contain the basic configuration information for a particular hardware platform. By using the .ecm file as a starting point, we have a working configuration for the hardware platform that we are using as a baseline. The configuration options can then be modified to support any changes needed in the RedBoot image.

cdl_savefile_version 1;
cdl_savefile_command cdl_savefile_version {};
cdl_savefile_command cdl_savefile_command {};

cdl_configuration eCos {
    description "" ;
    hardware mbx ;
    template redboot ;
    package -hardware CYGPKG_HAL_POWERPC current ;
    package -hardware CYGPKG_HAL_POWERPC_MPC8xx current ;
    package -hardware CYGPKG_HAL_POWERPC_MBX current ;
} ;

cdl_option CYGDBG_HAL_DEBUG_GDB_INCLUDE_STUBS {
    inferred_value 1
} ;

cdl_option CYGSEM_HAL_ROM_MONITOR {
    inferred_value 1
} ;

Listing 3. Example eCos minimal configuration (.ecm) file

Minimal configuration files also use the CDL. Listing 3 is from the redboot_ROM.ecm file for the PowerPC-based Motorola MBX development board. As you can see, the .ecm file shows a list of the packages, under the cdl_configuration command, that need to be included for the RedBoot configuration. The cdl_option commands set the configuration option values for specific options.

Most supported platforms contain a ROM and RAM RedBoot .ecm file that can be imported as the configuration starting point. ROM and RAM indicate where the RedBoot image resides on the target hardware. Typically, the RAM configuration is initially used when debugging hardware and the ROM configuration is used when the image has been debugged and is ready to be placed in flash memory. The RAM image is also used to update the flash-resident RedBoot image. The i386 PC target platform also includes a RedBoot FLOPPY configuration file that can be used if booting RedBoot from a floppy drive.

In order to import a minimal configuration file, we select File—>Import from the menu in the Configuration Tool. Then we browse to the appropriate .ecm file and select it. The Configuration Tool uses the .ecm file to load the appropriate packages and set the options accordingly. If conflicts arise due to the configuration option settings, the Configuration Tool displays a conflict resolution dialog box. The conflicts can be resolved by selecting the continue button.

Since RedBoot relies on other software modules, such as the HAL, not all of the configuration options are located under the RedBoot ROM Monitor package. The low-level hardware configuration options are found under the eCos HAL package. Other packages that may need configuration are device drivers. For example, on platforms that include networking support, the Ethernet device driver options are located under the Common Ethernet Support package.

If network communication is desired, the RedBoot Networking configuration options need to be set up. This sets the default IP address for the target hardware or configures that BOOTP is used during initialization.

After completing the RedBoot configuration, it is a good idea to save a minimal configuration file. This is accomplished by selecting File—>Export and saving the configuration under the desired filename.

Building the RedBoot Image

Next, we need to save the current configuration. To save the current configuration into an eCos current configuration file (.ecc), we go to Save As under the File menu bar item. We can save the file as redboot_rom.ecc. This creates a working directory structure for the RedBoot image we are creating. All directories begin with the name of the .ecc file we created. In our case, the directories begin with reboot. The working directory structure is shown in Table 2.

Directory	Description
redboot_build	Contains all files created during the RedBoot build process.
redboot_install	Output files generated from the build process are located under this directory.
redboot_install\bin	This directory contains the different RedBoot image files. The types of files generated can vary depending on the processor architecture. The file format types may include binary, ELF, and S-record.
redboot_install\include	Contains the header files for the RedBoot image build
redboot_install\lib	Includes the library files generated for the RedBoot image build and the linker script files.
redboot_mlt	Contains the memory layout files used by the Configuration Tool.

Table 2. RedBoot working directory structure

Now that we have the configuration set up correctly, we can build the RedBoot image. To launch the build process, we select Build—>Library. The build information is displayed in the output window of the Configuration Tool.

When the build is complete, the RedBoot images are stored in the redboot_install\bin subdirectory, as described in Table 2. For our example, the new RedBoot image is called redboot_rom.bin.

Updating the Target

The method used to install the RedBoot image into non-volatile storage varies by target. In general, the image must be programmed into flash using software or ROM using a device programmer.

Once a RedBoot image is resident in the flash memory, the task of updating that image, for bug fixes or additional features, is straightforward. The existing flash RedBoot image and a RedBoot image built to run from RAM are needed.

First we boot the target and run the outdated RedBoot image from flash memory. Since we use the Flash Image System commands to program the new RedBoot image into flash memory, we need to initialize the fis system by running the command:

RedBoot> fis init

This will initialize the flash memory and enable new images to be downloaded using the vis commands. After initializing the image system, we can see the images in flash memory by running the command:

RedBoot> fis list
Name              FLASH addr  Mem addr    Length      Entry point
RedBoot           0xA0000000  0xA0000000  0x020000    0x80000000
RedBoot[backup]   0xA0020000  0x8C010000  0x010000    0x8C010000
RedBoot config    0xA0FC0000  0xA0FC0000  0x020000    0x00000000
FIS directory     0xA0FE0000  0xA0FE0000  0x020000    0x00000000

Listing 4. Example output from fis list command

Output similar to that shown in Listing 4 is displayed. The addresses, lengths, and entry points may differ depending on the hardware platform you are using. We can see the RedBoot image name, which indicates the RedBoot image currently executing in flash memory.

Next, a RedBoot RAM image, redboot_ram.bin, is created using the steps detailed above. To build an image that runs from RAM, we want to ensure the Startup Type (CYG_HAL_STARTUP) configuration option is set to RAM. Since hardware platforms include a ROM and RAM minimal configuration file, it's not difficult to import and build the RAM configuration. It is important to remember to save the RAM and ROM images to separate working directories.

We load the redboot_ram.bin image into RAM using the outdated RedBoot image residing in flash memory. This is accomplished using the following command:

RedBoot> load redboot_ram.bin

The load command offers various methods, such as TFTP, for transmitting the image from the host computer to the target hardware. The method depends on the resources you have available. The fis load command can also be used to load and store the redboot_ram.bin image using the Flash Image Storage system.

We execute the RedBoot image we just loaded into RAM using:

RedBoot> go

This produces a new initialization message, similar to the one shown in Listing 1, after the RedBoot image executes from RAM. At this point we are executing the RedBoot image from RAM.

Next, we want to load the RedBoot image we created for ROM from the steps above. To load the redboot_rom.bin image we use the command:

RedBoot> load redboot_rom.bin -b <ram_addr>

where ram_addr is the location in RAM, which varies from platform to platform, where we temporarily store the redboot_rom.bin image before programming it into flash.

Now we can program the new image into flash memory using the fis commands. Certain platforms may support locking and unlocking of flash memory. If we can unlock the flash, the first fis command that we need to enter is:

RedBoot> fis unlock <flash_addr> -l <flash_len>

where flash_addr is the address of flash memory we want to unlock. In our case, this corresponds to the flash address of the RedBoot image name from the fis list command. We also get the length for flash_len from the fis list command. If the platform does not support flash locking, we can skip this step.

Next, we program the new RedBoot image from RAM into flash memory using the command:

RedBoot> fis create RedBoot -f <flash_addr> -b <ram_addr>
-l <flash_len> -s <data_len>

where flash_addris the location in flash memory where the new RedBoot image will be programmed, as shown in the fis list command. ram_addr is the location where we loaded the redboot_rom.bin file into RAM memory. The flash_len, also shown in the fis list command, is the length of the RedBoot flash image. data_len is the length of the redboot_rom.bin file to be programmed into flash memory.

Before proceeding, the fis create command asks if you would like to replace the existing image named RedBoot. Replying y causes the new image to be programmed into flash memory. Next, the flash can be locked, if the hardware platform permits it, using the following command:

RedBoot> fis lock -f <flash_addr> -l <flash_len>

The actual memory locations described above for the platforms supported are detailed in the RedBoot documentation.

Finally, reboot the target hardware to begin using the new RedBoot image we just programmed into flash memory.

Porting RedBoot

Since RedBoot uses the eCos HAL for its low level interface to the hardware, the procedure for porting RedBoot to a new hardware platform is the same as that for porting eCos. The procedure for porting eCos was covered in my Embedded Systems Design article called "eCos Porting Guide."⁷ The procedures detailed in that article apply directly to the porting of RedBoot to new hardware platforms.

Futurespeak

As of the writing of this article, a new release of RedBoot is planned to coincide with the upcoming v. 2 release of eCos. Planned RedBoot enhancements include a DHCP client, an embedded web server, USB debugging, and IDE drive support.

Even without these improvements, the RedBoot ROM monitor provides a low-cost, easy to use method for debugging and testing hardware. And because RedBoot is open source, it can be customized to meet any specific need during the project development and test phases. The support for GDB might even eliminate your need for expensive hardware debugging tools.