9.3. Installation and Configuration
eCos provides a template called Redboot. Using this template, the default packages used with the RedBoot ROM monitor are loaded and configured with the default option settings. The specific packages loaded depend on the hardware platform you are using. For example, the Motorola PowerPC MBX860 board platform loads the Ethernet device driver since this is supported on the MBX platform. However, the Intel StrongARM SA-1100 Multimedia board platform does not contain Ethernet support; therefore, the Ethernet device driver is not loaded on the SA-1100 Multimedia platform. We cover building a RedBoot image in Chapter 12.
NOTE
Most HAL packages include a .ecm file that can be imported, along with using the RedBoot template, in order to set up the packages needed to build the RedBoot ROM monitor for a specific platform. The files are typically named redboot_RAM.ecm, redboot_ROM.ecm, or redboot_ROMRAM.ecm, where ROM, RAM, and ROMRAM determine the startup type for the RedBoot ROM monitor. The files are located in the misc subdirectory under the HAL packages. We cover the details of using .ecm files with the Configuration Tool in Chapter 11.
Although .ecm files are useful for loading a baseline of the proper packages for a specific platform, you should still verify the configuration option settings prior to building the RedBoot image. This ensures that the proper functionality you need is supported by RedBoot; for example, the configuration of certain options allows RedBoot to include certain required functionality, or alternatively eliminate particular features, thus reducing RedBoot's memory footprint.
RedBoot typically resides in the flash boot sector or boot ROM on the target platform. This gives control to RedBoot when the board is powered up. RedBoot can be configured to run from RAM if you need to debug the RedBoot code itself. This might be the case if you are porting RedBoot to run on your own hardware platform.
The method for programming the RedBoot image onto the target hardware varies from platform to platform and depends on the tools available. Some platforms include their own ROM monitor, such as the Motorola PowerPC MBX860 board, which can be used to program an image into flash memory and then run the programmed image on power up. In other cases, a device programmer might need to be used in order to burn the image into memory. Detailed instructions on programming a RedBoot image for each target platform supported by RedBoot can be found online at:
The steps involved in running an image on the i386 PC platform and the Motorola PowerPC MBX860 platform are covered in Chapter 12. These same steps can be applied to running the RedBoot image as well.
The resources (ROM, RAM, and communication ports) used by RedBoot vary for each platform. A description of the resource utilization for the supported platforms can be found in the RedBoot online documentation. The Configuration Tool's Memory Layout viewer can also be used to check and modify the RAM and ROM resources used by RedBoot. We cover the Configuration Tool, and all of its features, in Chapter 11.
9.3.1. RedBoot Configuration
The configuration of the RedBoot image is dependent on the features you want provided by the ROM monitor and the features provided in the application. As previously mentioned, the RedBoot ROM monitor is a standalone program and should be viewed as completely independent and separate from your application. However, the steps for configuring and building a RedBoot image are the same as the steps for configuring and building your application. The configuration allows you to control the functionality provided by RedBoot in order to meet the resource requirements of your system.
The RedBoot ROM Monitor (CYGPKG_REDBOOT) package is contained in the redboot subdirectory under the eCos repository root directory. Item List 9.1 shows the configuration options available for the RedBoot ROM monitor. Some of the options specified in the table are not supported by all platforms and, therefore, cannot be configured.
| Option Name | Include Support for ELF File Format |
| CDL Name | CYGSEM_REDBOOT_ELF |
| Description | Allows application files in ELF to be loaded by RedBoot. |
| Option Name | Build RedBoot ROM ELF Image |
| CDL Name | CYGBLD_BUILD_REDBOOT |
| Description | Builds an ELF of the RedBoot image. This option is disabled by default. The suboptions under this option allow inclusion of decompression support, thread debugging support, and setting a customized version string. |
| Option Name | RedBoot Networking |
| CDL Name | CYGPKG_REDBOOT_NETWORKING |
| Description | Contains suboptions for configuring network support. The default mode for this option is enabled for platforms with Ethernet support. The suboptions allow you to configure a default IP address when BOOTP is used (disabled by default), specify the TCP port for incoming connections (default is 9000), and specify the number of network buffers (default is 4). |
| Option Name | Allow RedBoot to Use Any I/O Channel for Console |
| CDL Name | CYGPKG_REDBOOT_ANY_CONSOLE |
| Description | RedBoot attempts to use all serial I/O channels that are defined for console communication. When input arrives, RedBoot uses that channel for its console. This option is enabled by default. |
| Option Name | Allow RedBoot to Adjust the Baud Rate Serial Console |
| CDL Name | CYGSEM_REDBOOT_VARIABLE_BAUD_RATE |
| Description | Enables RedBoot to support baud rate set commands. This option is enabled by default. |
| Option Name | Maximum Command Line Length |
| CDL Name | CYGPKG_REDBOOT_MAX_CMD_LINE |
| Description | Sets the maximum length for CLI commands. The default value is 256. |
| Option Name | Command Processing Idle Timeout (ms) |
| CDL Name | CYGNUM_REDBOOT_CLI_IDLE_TIMEOUT |
| Description | Specifies the period before command processing is considered idle. A smaller value for this option causes more frequent idle processing. The default value is 10 ms. |
| Option Name | Size of ZLIB Decompression Buffer |
| CDL Name | CYGNUM_REDBOOT_LOAD_ZLIB_BUFFER |
| Description | Sets the size (in bytes) of the buffer that is filled with incoming data during a load before calling the decompression function. The default value is 64 bytes. |
| Option Name | Validate RAM Addresses During Load |
| CDL Name | CYGSEM_REDBOOT_VALIDATE_USER_RAM_LOADS |
| Description | Allows RedBoot to check the validity of user RAM when loading an image. This option is enabled by default; care should be taken when disabling this option. |
| Option Name | Allow RedBoot to Support Flash Programming |
| CDL Name | CYGPKG_REDBOOT_FLASH |
| Description | Enables RedBoot to provide flash image system management. This option is enabled by default for platforms that contain flash support. Suboptions allow specific configuration of the flash memory, such as the minimum image size and the offset where the flash image system begins. |
| Option Name | Allow RedBoot to Support Disks |
| CDL Name | CYGPKG_REDBOOT_DISK |
| Description | Enables RedBoot commands for loading disk files. This option is enabled by default for platforms with disk support. Suboptions allow specific configuration of the disk details such as number of supported disks. |
| Option Name | Boot Scripting |
| CDL Name | CYGPKG_REDBOOT_BOOT_SCRIPT |
| Description | Component that contains the boot scripting configuration options. The options set the script timeout value and default boot script. The default is enabled. |
| Option Name | Behave Like a ROM Monitor |
| CDL Name | CYGPRI_REDBOOT_ROM_MONITOR |
| Description | Allows RedBoot to provide ROM monitor services to applications that are loaded. This option is always enabled when building a ROM startup type image. |
| Option Name | Allow RedBoot to Handle GNUPro Application 'syscalls' |
| CDL Name | CYGSEM_REDBOOT_BSP_SYSCALLS |
| Description | RedBoot installs a syscall handler to support application debugging based on GNUPro newlib/bsp when this option is enabled. The default for this option is disabled. |
The RedBoot image contains its own implementation of the HAL for the specific hardware platform selected. The HAL package is the same that is used in your application. The difference is how the HAL configuration options are set. The standard RedBoot configuration enables the RedBoot HAL option Behave as a ROM Monitor. Enabling this configuration option includes setting the Startup Type to ROM, which directs the HAL to perform all initialization necessary to bring up the hardware from a powered-off state. Using RedBoot in this standard configuration allows applications to be loaded into RAM for debugging on a hardware platform that is properly initialized.
Included in the HAL configuration is the setup of the virtual vectors. The standard configuration allows RedBoot to initialize the entire VVT and claim all of the virtual vectors in the table. The default configuration options for the VVT, which can be overridden, are that the ROM monitor provides the debugging and diagnostic I/O services and RAM applications rely on these services. Refer to Chapter 4, Virtual Vectors, for detailed information on virtual vectors and the VVT.
Because the VVT resides at a fixed area of memory, known by both the ROM monitor and the RAM application, the application can take over any services in the VVT at run time, leaving other services to be provided by RedBoot. RedBoot is capable of providing debugging and diagnostic services via the serial or Ethernet port. The ports used for debugging and diagnostic messages depend on the resources available on the particular platform and your debug configuration. For example, if your platform contains a serial port and an Ethernet port, you can use one port for RedBoot debugging, and the other can be used by your application. With the proper virtual vector setup and configuration option settings, RedBoot is also able to share the ports it uses for debugging and diagnostics with the eCos application.
NOTE
To avoid terminating a RedBoot communication channel that is using the networking stack, you must ensure proper configuration of two options within the eCos application image.
The first configuration option, Inherit Console Settings From ROM Monitor (CYGSEM_HAL_VIRTUAL_VECTOR_INHERIT_CONSOLE), must be enabled. The second configuration option, Claim Comms Virtual Vectors (CYGSEM_HAL_VIRTUAL_VECTOR_CLAIM_COMMS), must be disabled. These configuration options are located under the ROM Monitor Support component within the common configuration components of the eCos HAL.
One issue to keep in mind when configuring your debug environment settings is that using a serial port for debug communications can often be slow when you are loading large application images.
Typically, it is better if the port resources can be dedicated for either RedBoot usage or application usage. The HAL configuration options allow you to set up the debug and diagnostic I/O communications to meet your specific needs. The following two configuration options are used to configure the method of communication for the application. The first configuration option, Route Diagnostic Output to Debug Channel (CYGDBG_HAL_DIAG_TO_DEBUG_CHAN), under the Platform-Independent HAL Options component within the common configuration components allows the use of RedBoot's debug channel for diagnostic messages from the application. RedBoot provides mangling support, using GDB, which then outputs the message to the host. Mangling in this scenario means that RedBoot converts diagnostic messages from the application into a properly formed GDB remote protocol packet.
The second configuration option is Inherit Console Settings From ROM Monitor (CYGSEM_HAL_VIRTUAL_VECTOR_INHERIT_CONSOLE) under ROM Monitor Support within the common configuration components. This option allows the application to use the currently configured RedBoot console setup for output from the application. RedBoot again handles the mangling needed for proper communication.
Two platform-specific configuration options allow specific designation of the port number used for debug and diagnostic communications. If only one port exists on the platform, these options should be configured to use that port. The first is Debug Serial Port (CYGNUM_HAL_VIRTUAL_VECTOR_DEBUG_CHANNEL), which determines the port used to connect to the GDB host.
The other configuration option is Diagnostic Serial Port (CYGNUM_HAL_VIRTUAL_ VECTOR_CONSOLE_CHANNEL), which determines the port used for output of diagnostic messages; for example, using the diag_printf function. Chapter 4 details these configuration options and the steps involved for a typical debug environment configuration using the RedBoot ROM monitor with a separate application RAM image.
NOTE
If the RedBoot image is built with the configuration option Allow RedBoot To Use Any I/O Channel For Its Console (CYGPKG_REDBOOT_ANY_CONSOLE) enabled, which is the default value, the debug and diagnostic serial port configuration settings are ignored and RedBoot latches on to the first port that it receives input.
9.3.2. Host Configuration
Currently, there are two methods for connecting a host to a target running RedBoot, serial or Ethernet. With either method used, RedBoot uses the connection for both GDB and RedBoot command communications, although RedBoot can be configured to use separate communication channels for debugging and commands. RedBoot provides commands, which are detailed in the User Interface and Command Set section of this chapter, for configuring the different parameters associated with both communication methods. After setting these parameters, they are used on subsequent boots of the target hardware.
One important point to understand about the RedBoot driver implementations, for both serial and Ethernet, is that polling (not interrupts) is used for I/O communication. The configuration option Command Processing Idle Timeout (ms) (CYGNUM_REDBOOT_CLI_IDLE_TIMEOUT) sets the RedBoot command processing interval. After this timeout expires, RedBoot assumes the command console is idle and performs various background tasks. The default value for this option is 10 milliseconds. If traffic increases, there might be a point at which the RedBoot driver cannot keep up and packets are dropped. In that case, it might be necessary to adjust the timeout configuration option or re-check the traffic that RedBoot needs to process on the communication channel.
9.3.2.1. Serial
Using the serial connection requires a host-side terminal program. The default parameters that RedBoot uses for a serial connection are specific to the target hardware platform. On some target hardware platforms, the RedBoot baud rate setting can be changed using the baudrate command, which is detailed in the User Interface and Command Set section of this chapter.
Most hardware target platforms should contain at least one serial port for RedBoot communications. Some platforms contain multiple serial ports. The serial port RedBoot uses for serial communication is described in the RedBoot Configuration section of this chapter. By default, RedBoot attempts to communicate with the host via the serial port, set by the configuration options, on power up. Once a command is received by RedBoot on one of the serial ports, that port is used for communications. There is a channel command available, which is detailed in the User Interface and Command Set section of this chapter, that allows the port RedBoot uses for console communication to be changed.
9.3.2.2. Ethernet
The other method for RedBoot communication is using an Ethernet port. In order to use an Ethernet port, the RedBoot image must include networking support and, obviously, the target hardware must have an Ethernet port.
One issue that must be resolved is the method for RedBoot to obtain the Ethernet MAC address. RedBoot attempts to use the MAC address provided by the board manufacturer. However, the MAC address is not provided on all target hardware platforms. On some hardware platforms, the Ethernet driver allows RedBoot to program a MAC address into the flash configuration, using the fconfig command. A default MAC address can also be built into the RedBoot image.
Another issue when using the Ethernet port for RedBoot communication is obtaining an IP address. RedBoot offers two methods for obtaining an IP address for network communication, static and dynamic. Selection of the method is controlled by the fconfig command, which is described in detail in the User Interface and Command Set section of this chapter.
When using the static method, you must set a unique IP address for the RedBoot image. Several IP address ranges are good to use because they are private addresses. By using private addresses, you can create a private network for your debugging configuration, and packets that leave this private network are not forwarded. According to RFC 1918, the reserved private addresses are:
10.0.0.0 to 10.255.255.255
172.16.0.0 to 172.31.255.255
192.168.0.0 to 192.168.255.255
It is important to realize that RedBoot does not offer any routing support; therefore, the IP address selected for the target hardware running RedBoot and the host must be on the same subnet. RedBoot uses ARP to resolve the host address and then sends packets directly to the host unit.
When using the dynamic method, the BOOTP protocol is enabled in the RedBoot image. Again, selecting the dynamic method is accomplished through the fconfig command. The dynamic method also requires a BOOTP server running on the host in order to provide an IP address to the target hardware. There are several free or shareware BOOTP servers available on the Web, including the BOOTP Turbo Server from Weird Solutions and a DHCP/BOOTP Server from Dr. Herbert Hanewinkel.
Once the IP address has been successfully set on the target hardware, you can use the ping utility to verify communication between the target and the host. Most host operating systems should offer this utility. RedBoot also contains a ping command, which is described in the User Interface and Command Set section of this chapter.
After the IP address is assigned to the target hardware Ethernet port, you can connect to RedBoot from the host using a Telnet client application. Most host operating systems provide a Telnet application utility and if not, again, a search on the Web should bring up a few options. Next, the port number that is used for Telnet protocol communications must be set on the host application and in RedBoot. By default, RedBoot uses port 9000. The default port can be changed using the fconfig command. Once the host connects to RedBoot using Telnet, all RedBoot communications take place over the Ethernet port.
NOTE
When using the Ethernet port for RedBoot communication and in your application, it is important to set up the IP addresses properly. The system distinguishes the destination of a packet using the IP address. If the IP address for RedBoot and the application are the same, RedBoot will receive all incoming Ethernet packets, not passing them on to the application for processing. To avoid this situation, it is best to use a static IP address in one image and a separate static or dynamic image in the other image.
NOTE
If you are using RedBoot for debugging purposes and it will not be shipped in the final product, you can assign a static IP address for RedBoot to use and allow the application to obtain its IP address via BOOTP or DHCP. This allows you to test the BOOTP/DHCP protocol in the application.
NOTE
If your application contains complex networking software, it is better to use a serial port for RedBoot communication and allow the application to use the Ethernet port exclusively. Although RedBoot and the application can share an Ethernet device, there are times when debugging is simplified if a separate communications channel is used. If the application image is large and you have concerns over the download time via a serial port, one solution is to download the application over the Ethernet port and then switch to the serial port for the debugging.