Chapter 224. Getting Started with RedBoot

RedBoot™ is an acronym for "Red Hat Embedded Debug and Bootstrap", and is the standard embedded system debug/bootstrap environment from eCosCentric, replacing the previous generation of debug firmware: CygMon and GDB stubs. It provides a complete bootstrap environment for a range of embedded operating systems, such as embedded Linux® and eCos®, and includes facilities such as network downloading and debugging. It also provides a simple flash file system for boot images.

[Note]Note

Red Hat no longer maintain nor support RedBoot and have contributed both RedBoot and eCos to the stewardship of the Free Software Foundation (FSF). eCosCentric are now the sole commercial maintainers of both eCos and RedBoot.

RedBoot provides a wide set of tools for downloading and executing programs on embedded target systems, as well as tools for manipulating the target system's environment. It can be used for both product development (debug support) and for end product deployment (flash and network booting).

Here are some highlights of RedBoot‚s capabilities:

  • Boot scripting support
  • Simple command line interface for RedBoot configuration and management, accessible via serial (terminal) or Ethernet (telnet)
  • Integrated GDB stubs for connection to a host-based debugger via serial or ethernet. (Ethernet connectivity is limited to local network only)
  • Attribute Configuration - user control of aspects such as system time and date (if applicable), default Flash image to boot from, default failsafe image, static IP address, etc.
  • Configurable and extensible, specifically adapted to the target environment
  • Network bootstrap support including setup and download, via BOOTP, DHCP and TFTP
  • X/Y/Z Modem support for image download via serial
  • Power On Self Test

Although RedBoot is derived from eCos, it may be used as a generalized system debug and bootstrap control software for any embedded system and any operating system. For example, with appropriate additions, RedBoot could replace the commonly used BIOS of PC (and certain other) architectures. Red Hat is currently installing RedBoot on all embedded platforms as a standard practice, and RedBoot is now generally included as part of all eCosCentric eCos ports. Users who specifically wish to use RedBoot with the eCos operating system should refer to the Getting Started with eCos document, which provides information about the portability and extendability of RedBoot in an eCos environment.

224.1. More information about RedBoot on the web

The eCosCentric RedBoot Documentation contains updated documentation for all public and commercial versions of RedBoot, including new features and capabilities.

The RedBoot Net Distribution web site contains downloadable sources and documentation for all publically released targets.

224.2. Installing RedBoot

To install the RedBoot package on target hardware, follow the procedures detailed in the documentation accompanying the release. This is normally found in the [eCos and eCosPro Reference Manual] or may also be found in the respective target hardware documentation in eCosCentric's eCos and eCosPro Reference Manual for publically available target hardware.

Although there are other possible configurations, RedBoot is usually run from the target platform‚s flash boot sector or boot ROM, and is designed to run when your system is initially powered on. The method used to install the RedBoot image into non-volatile storage varies from platform to platform. In general, it requires that the image be programmed into flash in situ or programmed into the flash or ROM using a device programmer. In some cases this will be done at manufacturing time; the platform being delivered with RedBoot already in place. In other cases, you will have to program RedBoot into the appropriate device(s) yourself. Installing to flash in situ may require special cabling or interface devices and software provided by the board manufacturer. The details of this installation process for a given platform will be found in Installation and Testing. Once installed, user- specific configuration options may be applied, using the fconfig command, providing that persistent data storage in flash is present in the relevant RedBoot version. See Section 224.8, “Configuring the RedBoot Environment” for details.

224.3. User Interface

RedBoot provides a command line user interface (CLI). At the minimum, this interface is normally available on a serial port on the platform. If more than one serial interface is available, RedBoot is normally configured to try to use any one of the ports for the CLI. Once command input has been received on one port, that port is used exclusively until the board is reset or the channel is manually changed by the user. If the platform has networking capabilities, the RedBoot CLI is also accessible using the telnet access protocol. By default, RedBoot runs telnet on port TCP/9000, but this is configurable and/or settable by the user.

RedBoot also contains a set of GDB “stubs”, consisting of code which supports the GDB remote protocol. GDB stub mode is automatically invoked when the '$' character appears anywhere on a command line unless escaped using the '\' character. The platform will remain in GDB stub mode until explicitly disconnected (via the GDB protocol). The GDB stub mode is available regardless of the connection method; either serial or network. Note that if a GDB connection is made via the network, then special care must be taken to preserve that connection when running user code. eCos contains special network sharing code to allow for this situation, and can be used as a model if this methodology is required in other OS environments.

224.4. RedBoot Editing Commands

RedBoot uses the following line editing commands.

  • Delete (0x7F) or Backspace (0x08) erases the character to the left of the cursor.
  • ^A or HOME moves the cursor (insertion point) to the beginning of the line.
  • ^K erases all characters on the line from the cursor to the end.
  • ^E or END positions the cursor to the end of the line.
  • ^D or DELETE erases the character under the cursor.
  • ^F or RIGHT-ARROW moves the cursor one character to the right.
  • ^B or LEFT-ARROW moves the cursor one character to the left.
  • ^P or UP-ARROW replaces the current line by a previous line from the history buffer. A small number of lines can be kept as history. Using ^P (and ^N), the current line can be replaced by any one of the previously typed lines.
  • ^N or DOWN-ARROW replaces the current line by the next line from the history buffer.
[Note]Note

In this description, ^A means the character formed by typing the letter “A” while holding down the control key.

In the case of the fconfig command, additional editing commands are possible. As data are entered for this command, the current/previous value will be displayed and the cursor placed at the end of that data. The user may use the editing keys (above) to move around in the data to modify it as appropriate. Additionally, when certain characters are entered at the end of the current value, i.e. entered separately, certain behavior is elicited.

  • ^ (caret) switch to editing the previous item in the fconfig list. If fconfig edits item A, followed by item B, pressing ^ when changing item B, allows you to change item A. This is similar to the up arrow. Note: ^P and ^N do not have the same meaning while editing fconfig data and should not be used.
  • . (period) stop editing any further items. This does not change the current item.
  • Return leaves the value for this item unchanged. Currently it is not possible to step through the value for the start-up script; it must always be retyped.

224.5. RedBoot Command History

RedBoot provides support for listing and repeating previously entered commands. A list of previously entered commands may be obtained by typing history at the command line:

RedBoot> history
  0 fis list
  1 fconfig -l
  2 load -m ymodem
  3 history

The following history expansions may be used to execute commands in the history list:

  • !! repeats last command.
  • !n repeats command n.
  • !string repeats most recent command starting with string.

224.6. RedBoot Startup Mode

RedBoot can normally be configured to run in a number of startup modes (or just "modes" for short), determining its location of residence and execution:

ROM mode, ROMINT mode, EEPROM mode
In this mode, RedBoot both resides and executes from ROM memory (ROMINT:internal flash, ROM:external flash, EPROM: EEPROM memory). This mode is used when there are limited RAM resources. The flash commands cannot update the region of flash where the RedBoot image resides. In order to update the RedBoot image in flash, it is necessary to run a RAM mode instance of RedBoot. The exact location is defined by the port and provided in the target hardware documentation section of the eCos and eCosPro Reference Manual.
ROMRAM mode
In this mode, RedBoot resides in ROM memory (flash or EPROM), but is copied to RAM memory before it starts executing. The RAM footprint is larger than for ROM mode, but there are two advantages to make up for this: it normally runs faster (relevant only on slower boards) and it is able to update the flash region where the image resides.The exact location is defined by the port and provided in the target hardware documentation section of the eCos and eCosPro Reference Manual.
RAM mode, SRAM mode, JTAG mode

In this mode, RedBoot both resides and executes from RAM or SRAM memory. The memory may be on-chip RAM or SRAM or external RAM or SRAM. The exact location is defined by the port and provided in the target hardware documentation section of the eCos and eCosPro Reference Manual. This is used for updating a primary ROM mode image in situ and sometimes as part of the RedBoot installation on the board when there's already an existing (non-RedBoot) boot monitor available.

You can only use ROM, ROMRAM and EEPROM mode images for booting a board - a RAM mode image cannot run unless loaded by another ROM monitor. There is no need for this startup mode if a RedBoot ROMRAM mode image is the primary boot monitor. When this startup mode is programmed into flash (as a convenience as it's fast to load from flash) it will generally be named as "RedBoot[RAM]" in the FIS directory.

The chosen mode has influence on flash and RAM resource usage (see Section 224.7, “RedBoot Resource Usage”) and the procedure of an in situ update of RedBoot in flash (see Chapter 227, Updating RedBoot).

The startup mode is controlled by the option CYG_HAL_STARTUP which resides in the platform HAL. Some platforms provide only some of the RAM, ROM, ROMRAM, etc. modes, others provide additional modes.

To see mode of a currently executing RedBoot, issue the version command, which prints the RedBoot banner, including the startup mode (here ROM):

RedBoot>version

RedBoot(tm) bootstrap and debug environment [ROM]
Non-certified release, version UNKNOWN - built 13:31:57, May 17 2002

224.7. RedBoot Resource Usage

RedBoot takes up both flash and RAM resources depending on its startup mode and number of enabled features. There are also other resources used by RedBoot, such as timers. Platform-specific resources used by RedBoot are listed in the platform specific parts of this manual.

Both flash and RAM resources used by RedBoot depend to some degree on the features enabled in the RedBoot configuration. It is possible to reduce in particular the RAM resources used by RedBoot by removing features that are not needed. Flash resources can also be reduced, but due to the granularity of the flash (the block sizes), reductions in feature size do not always result in flash resource savings.

224.7.1. Flash Resources

On many platforms, a ROM mode RedBoot image resides in the first flash sectors, working as the board's primary boot monitor. On these platforms, it is also normal to reserve a similar amount of flash for a secondary RAM mode image, which is used when updating the primary ROM mode image.

On other platforms, a ROMRAM mode RedBoot image is used as the primary boot monitor. On these platforms there is not normally reserved space for a RAM mode RedBoot image, since the ROMRAM mode RedBoot is capable of updating the primary boot monitor image.

Most platforms also contain a FIS directory (keeping track of available flash space) and a RedBoot config block (containing RedBoot board configuration data).

To see the amount of reserved flash memory, run the fis list command:

RedBoot> fis list
Name              FLASH addr  Mem addr    Length      Entry point
RedBoot           0x00000000  0x00000000  0x00020000  0x00000000
RedBoot[RAM]      0x00020000  0x06020000  0x00020000  0x060213C0
RedBoot config    0x0007F000  0x0007F000  0x00001000  0x00000000
FIS directory     0x00070000  0x00070000  0x0000F000  0x00000000

To save flash resources, use a ROMRAM mode RedBoot, or if using a ROM mode RedBoot, avoid reserving space for the RedBoot[RAM] image (this is done by changing the RedBoot configuration) and download the RAM mode RedBoot whenever it is needed. If the RedBoot image takes up a fraction of an extra flash block, it may be possible to reduce the image size enough to free this block by removing some features.

224.7.2. RAM Resources

RedBoot reserves RAM space for its run-time data, and such things as CPU exception/interrupt tables. It normally does so at the bottom of the memory map. It may also reserve space at the top of the memory map for configurable RedBoot features such as the net stack and zlib decompression support.

To see the actual amount of reserved space, issue the version command, which prints the RedBoot banner, including the RAM usage:

RedBoot> version

RedBoot(tm) bootstrap and debug environment [ROM]
Non-certified release, version UNKNOWN - built 13:31:57, May 17 2002

Platform: FooBar (SH 7615)
Copyright (C) 2000, 2001, 2002, Free Software Foundation, Inc.

RAM: 0x06000000-0x06080000, 0x06012498-0x06061000 available
FLASH: 0x00000000 - 0x00080000, 8 blocks of 0x00010000 bytes each.

To simplify operations that temporarily need data in free memory, the limits of free RAM are also available as aliases (aligned to the nearest kilo-byte limit). These are named FREEMEMLO and FREEMEMHI, and can be used in commands like any user defined alias:

RedBoot> load -r -b %{FREEMEMLO} file
Raw file loaded 0x06012800-0x06013e53, assumed entry at 0x06012800
RedBoot> x -b %{FREEMEMHI}
06061000: 86 F5 EB D8 3D 11 51 F2  96 F4 B2 DC 76 76 8F 77  |….=.Q…..vv.w|
06061010: E6 55 DD DB F3 75 5D 15  E0 F3 FC D9 C8 73 1D DA  |.U…u]…...s..|

To reduce RedBoot's RAM resource usage, use a ROM mode RedBoot. The RedBoot features that use most RAM are the net stack, the flash support and the gunzip support. These, and other features, can be disabled to reduce the RAM footprint, but obviously at the cost of lost functionality.

224.8. Configuring the RedBoot Environment

Once installed, RedBoot will operate fairly generically. However, there are some features that can be configured for a particular installation. These depend primarily on whether flash and/or networking support are available. The remainder of this discussion assumes that support for both of these options is included in RedBoot.

224.8.1. Target Network Configuration

Each node in a networked system needs to have a unique address. Since the network support in RedBoot is based on TCP/IP, this address is an IP (Internet Protocol) address. There are two ways for a system to “know” its IP address. First, it can be stored locally on the platform. This is known as having a static IP address. Second, the system can use the network itself to discover its IP address. This is known as a dynamic IP address. RedBoot supports this dynamic IP address mode by use of either the BOOTP protocol, or a subset of the DHCP protocol. In this case, RedBoot will ask the network (actually some generic server on the network) for the IP address to use.

[Note]Note

Currently, RedBoot only supports BOOTP and a very simple form of DHCP which is limited to additional data items, not lease-based address allocation. If you wish to use this subset of DHCP, then ensure you the configuration option CYGSEM_REDBOOT_NETWORKING_DHCP is enabled in RedBoot's configuration.

If you are intending to use RedBoot for network debugging, and are also intending to use BOOTP or DHCP in the loaded application, then you should not also use BOOTP/DHCP with RedBoot. Otherwise the DHCP server is likely to give both RedBoot's and the application's network stacks the same IP address which will result in problems.

The choice of IP address type is made via the fconfig command. Once a selection is made, it will be stored in flash memory. RedBoot only queries the flash configuration information at reset, so any changes will require restarting the platform.

Here is an example of the RedBoot fconfig command, showing network addressing:

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

In this case, the board has been configured with a static IP address listed as the Local IP address. The default server IP address specifies which network node to communicate with for TFTP service. This address can be overridden directly in the TFTP commands.

The DNS server IP address option controls where RedBoot should make DNS lookups. A setting of 0.0.0.0 will disable DNS lookups. The DNS server IP address can also be set at runtime.

If the selection for Use BOOTP for network configuration had been true, these IP addresses would be determined at boot time, via the BOOTP protocol. The final number which needs to be configured, regardless of IP address selection mode, is the GDB connection port. RedBoot allows for incoming commands on either the available serial ports or via the network. This port number is the TCP port that RedBoot will use to accept incoming connections.

These connections can be used for GDB sessions, but they can also be used for generic RedBoot commands. In particular, it is possible to communicate with RedBoot via the telnet protocol. For example, on Linux®:

% telnet redboot_board 9000
Connected to redboot_board
Escape character is ’^]‚.
RedBoot>  

224.8.2. Host Network Configuration

RedBoot may require three different classes of service from a network host:

  • dynamic IP address allocation, using BOOTP
  • TFTP service for file downloading
  • DNS server for hostname lookups

Depending on the host system, these services may or may not be available or enabled by default.

In particular, on most Linux distributions, none of these services will be configured out of the box. As the method for configuring and enabling these services varies widely between Linux distributions and even between versions of the same distribution, the reader is advised to refer to the system documentation of your chosen Linux distribution and version for more details.

The Windows Desktop operating system does not provide these services. Instead these services are included with Windows Server. Please refer to your system administrator, or Microsoft TechNet, for details on how to configure these services on your Windows Server. Alternatively, if you do not have access to a Windows Server or Linux or do not wish to use either, you can use freely available MaraDNS, currently available from http://www.maradns.org/, to provide a DNS server and the Open TFTP Server, currently available from https://sourceforge.net/projects/tftp-server/, to provide a TFTP service on your Windows Desktop.

224.8.2.1. BOOTP/DHCP server settings for most Linux distributions

First, ensure that you have the proper package, dhcp (not dhcpd) installed. The DHCP server provides Dynamic Host Configuration, that is, IP address and other data to hosts on a network. It does this in different ways. Next, there can be a fixed relationship between a certain node and the data, based on that node‚s unique Ethernet Station Address (ESA, sometimes called a MAC address). The other possibility is simply to assign addresses that are free. The sample DHCP configuration file shown does both. Refer to the DHCP documentation for more details.

Example 224.1. Sample DHCP configuration file

--------------- /etc/dhcpd.conf -----------------------------
default-lease-time 600;
max-lease-time 7200;
option subnet-mask 255.255.255.0;
option broadcast-address 192.168.1.255;
option domain-name-servers 198.41.0.4, 128.9.0.107;
option domain-name “bogus.com”;
allow bootp;
shared-network BOGUS {
  subnet 192.168.1.0 netmask 255.255.255.0
    {
       option routers 192.168.1.101;
       range 192.168.1.1 192.168.1.254;
    }
}
host mbx {
   hardware ethernet 08:00:3E:28:79:B8;
   fixed-address 192.168.1.20;
   filename “/tftpboot/192.168.1.21/zImage”;
   default-lease-time -1;
   server-name “srvr.bugus.com”;
   server-identifier 192.168.1.101;
   option host-name “mbx”;
} 

Once the DHCP package has been installed and the configuration file set up, type:

# service dhcpd start

224.8.2.2. DNS server for most Linux distributions

First, ensure that you have the proper package installed. Then change the configuration (in /etc/named.conf) so that the forwarders point to the primary nameservers for your machine, normally using the nameservers listed in /etc/resolv.conf.

Example 224.2. Sample /etc/named.conf for most Linux distributions

--------------- /etc/named.conf -----------------------------
// generated by named-bootconf.pl

options {
  directory "/var/named";
  /*
   * If there is a firewall between you and nameservers you want
   * to talk to, you might need to uncomment the query-source
   * directive below.  Previous versions of BIND always asked
   * questions using port 53, but BIND 8.1 uses an unprivileged
   * port by default.
   */
  // query-source address * port 53;


  forward first;
  forwarders {
    212.242.40.3;
    212.242.40.51;
  };
};

//
// a caching only nameserver config
//
// Uncomment the following for Red Hat Linux 7.2 or above:
// controls {
//         inet 127.0.0.1 allow { localhost; } keys { rndckey; };
// };
// include "/etc/rndc.key";
zone "." IN {
  type hint;
  file "named.ca";
};

zone "localhost" IN {
  type master;
  file "localhost.zone";
  allow-update { none; };
};

zone "0.0.127.in-addr.arpa" IN {
  type master;
  file "named.local";
  allow-update { none; };
};

Make sure the server is started. Older distributions may use the command:

# service named start

and is started on the next reboot with the command

# chkconfig named on

Newer Linux distributions may use the command:

# systemctl start named

and is started on the next reboot with the command

# systemctl enable named

Finally, if you are developing on Linux and using your host to provide the DNS server, you may wish to change /etc/resolv.conf to use 127.0.0.1 as the nameserver for your local machine. Depending on the Linux distribution and its age, you may have to manually set the nameserver in your Network Configuration.

224.8.2.3. RedBoot network gateway

RedBoot only provides simple routing. If a remote host is not on the same directly connected IP subnet as that associated with the network interface (even if on the same ’wire‚), then you will need to configure a gateway which can be used to route packets to the remote host. First you should ensure RedBoot has been built with support for using a gateway using the configuration option CYGSEM_REDBOOT_NETWORKING_USE_GATEWAY. Then you can either:-

  • Hard-code a gateway into the configuration with the option CYGDAT_REDBOOT_DEFAULT_GATEWAY_IP_ADDR;
  • Use RedBoot's persistent flash configuration to set the “Gateway IP address” gateway persistently in flash using the fconfig command; or
  • Configure RedBoot to use obtain an address from a DHCP server (not just BOOTP), and then configure the DHCP server to provide the gateway IP address.

224.8.3. Verification

Once your network setup has been configured, perform simple verification tests as follows:

  • Reboot your system, to enable the setup, and then try to ’ping‚ the target board from a host.
  • Once communication has been established, try to ping a host using the RedBoot ping command - both by IP address and hostname.
  • Try using the RedBoot load command to download a file from a host.