Subversion Repositories openrisc

Red Bootgetting started

RedBoot™ is an acronym for "Red Hat Embedded Debug and Bootstrap",

and is the standard embedded system debug/bootstrap environment from Red Hat,

replacing the previous generation of debug firmware: CygMon

CygMon and GDB stubsGDB

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.

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

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/YModem 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 Red Hat Embedded Linux

and 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.

The RedBoot Net

Distribution web site contains downloadable sources and documentation

for all publically released targets, including the latest features and updates.

installing RedBootgeneral procedures

RedBoot installation

general proceduresTo install the RedBoot

package, follow the procedures detailed in the accompanying README. 

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 

for details.

user interface

uicliRedBoot

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 

telnettelnet on port TCP/9000,

but this is configurable and/or settable by the user. 

RedBoot also contains a set of GDB stubs

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.

RedBootediting commands

editing commands

commandseditingRedBoot

uses the following line editing commands.

In this description, ^A means the character formed

by typing the letter “A” while holding down the control key.

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.

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.

RedBootcommand history

command history

commandshistory

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

  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.

  RedBootmode

  RedBootstartup 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

 In this mode, RedBoot both resides and executes from

 ROM memory (flash or EPROM). 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.

 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.

 RAM mode

 In this mode, RedBoot both resides and executes from

 RAM memory. 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 and ROMRAM 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

) and the procedure of an in situ update

of RedBoot in flash (see ).

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, and ROMRAM 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

  RedBootresource 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.

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.

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

FREEMEMLOFREEMEMLO and

FREEMEMHIFREEMEMHI, 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.

configuring the RedBoot environment

RedBoot environment configuration

environment configuration

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

supportnetworking and/or flash support

flash and/or networking support are available. The remainder

of this discussion assumes that support for both of these options is included

in RedBoot.

target network configuration

network configurationconfiguration

secondaryEach node in a networked

system needs to have a unique address. Since the network support in RedBoot

is based on TCP/IPTCP/IP, this address

is an IP (Internet Protocol) address. IP address type

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 the BOOTP

BOOTP (a subset of DHCP

DHCP) protocol. In this case, RedBoot will ask the network (actually

some generic server on the network) for the IP address to use.

Currently, RedBoot only supports BOOTP. In future releases, DHCP may

also be supported, but such support will be limited to additional data items,

not lease-based address allocation.

The choice of IP address typeIP

address type is made via the fconfig command

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 commandsTFTP

commands.

The DNS server IP address option

controls where RedBoot should make DNS lookupsDNS

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

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 telnettelnet

protocol. For example, on Linux®: 

% telnet redboot_board 9000

Connected to redboot_board

Escape character is ‘^]’.

RedBoot>  

host network configuration

network configurationhost

configurationnetworkRedBoot

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. See your system documentation for more details.

In particular, on Red Hat Linux, neither of these services will be configured

out of the box. The following will provide a limited explanation of how to

set them up. These configuration setups must be done as root

 on the host or server machine.

TFTPenabling on Red Hat

Linux 6.2Red Hat Linux

enabling TFTP on version 6.2Ensure that

you have the tftp-server RPM package installed. By default, this installs

the TFTP server in a disabled state. These steps will enable it:

Make sure that the following line is uncommented in the control

file /etc/inetd.conf tftp dgram   udp     wait    root    /usr/sbin/tcpd      /usr/sbin/in.tftpd

If it was necessary to change the line in Step 2, then the inetd

server must be restarted, which can be done via the command:    

# service inet reload

TFTPenabling on Red Hat

Linux 7Red Hat Linux

enabling TFTP on version 7Ensure that the

xinetd RPM is installed.

Ensure that the tftp-server RPM is installed.

Enable TFTP by means of the following: /sbin/chkconfig tftp on

Reload the xinetd configuration using the command:

 /sbin/service xinetd reload Create the directory /tftpboot

using the command mkdir /tftpboot

If you are using Red Hat 8 or newer, you may need to configure

the built-in firewall to allow through TFTP. Either edit

/etc/sysconfig/iptables or run

redhat-config-securitylevel on the command line or from

the menu as System Settings->Security Settings to lower the security level.

You should only do this with the permission of your systems administrator and

if you are already behind a separate firewall.

Under Red Hat 7 you must address files by absolute pathnames, for example: 

/tftpboot/boot.img not /boot.img, as you may have done with

other implementations.

On systems newer than Red Hat 7 (7.1 and beyond), filenames are once again relative to the

/tftpboot directory.

DHCPenabling on Red Hat Linux

BOOTP

enabling on Red Hat LinuxFirst, 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.

--------------- /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

DNSenabling on Red Hat

LinuxFirst, ensure that you have the proper

RPM package, caching-nameserver

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.

--------------- /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 with the command:

# service named start and is

started on next reboot with the command

# chkconfig named on

Finally, you may wish to change

/etc/resolv.conf to use

127.0.0.1 as the nameserver for your

local machine.

RedBoot network gateway

network gatewayRedBoot cannot communicate with

machines on different subnets because it does not support routing. It always

assumes that it can get to an address directly, therefore it always tries

to ARP and then send packets directly to that unit. This means that whatever

it talks to must be on the same subnet. If you need to talk to a host on a

different subnet (even if it's on the same ‘wire’), you need to

go through an ARP proxy, providing that there is a Linux box connected to

the network which is able to route to the TFTP server. For example: 

/proc/sys/net/ipv4/conf/<interface>/proxy_arp where 

<interface>should be replaced with whichever network interface

is directly connected to the board.

verification (network)

network verificationOnce 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.