Chapter 225. RedBoot Commands and Examples

225.1. Introduction

RedBoot provides three basic classes of commands:

  • Program loading and execution
  • Flash image and configuration management
  • Miscellaneous commands

Given the extensible and configurable nature of eCos and RedBoot, there may be extended or enhanced sets of commands available.

The basic format for commands is:

RedBoot> COMMAND [-S]... [-s val]... operand

Commands may require additional information beyond the basic command name. In most cases this additional information is optional, with suitable default values provided if they are not present.

FormatDescriptionExample
-S A boolean switch; the behavior of the command will differ, depending on the presence of the switch. In this example, the -f switch indicates that a complete initialization of the FIS data should be performed. There may be many such switches available for any given command and any or all of them may be present, in any order. RedBoot> fis init -f
-s val A qualified value; the letter "s" introduces the value, qualifying it's meaning. In the example, -b 0x100000 specifies where the memory dump should begin. There may be many such switches available for any given command and any or all of them may be present, in any order. RedBoot> dump -b 0x100000 -l 0x20
operand A simple value; some commands require a single parameter for which an additional -X switch would be redundant. In the example, JFFS2 is the name of a flash image. The image name is always required, thus is no need to qualify it with a switch. Note that any un-qualified operand must always appear at the end of the command. RedBoot> fis delete JFFS2

The list of available commands, and their syntax, can be obtained by typing help at the command line:

RedBoot> help
Manage aliases kept in FLASH memory
      alias name [value]
Set/Query the system console baud rate
      baudrate [-b <rate>]
Manage machine caches
      cache [ON | OFF]
Display/switch console channel
      channel [-1|<channel number>]
Display disk partitions
      disks
Display (hex dump) a range of memory
      dump -b <location> [-l <length>] [-s]
Manage flash images
      fis {cmds}
Manage configuration kept in FLASH memory
      fconfig [-i] [-l] [-n] [-f] [-d] | [-d] nickname [value]
Execute code at a location
      go [-w <timeout>] [-c] [-n] [entry]
Help about help?
      help [<topic>]
Set/change IP addresses
      ip_address [-l <local_ip_address>[/<mask_length>]] [-h <server_address>]
Load a file
      load [-r] [-v] [-d] [-c <channel>] [-h <host>] [-m {TFTP | HTTP | {x|y|z}MODEM | disk}]
      [-b <base_address>] <file_name>
Network connectivity test
      ping [-v] [-n <count>] [-t <timeout>] [-i <IP_addr]
      -h <host>
Reset the system
      reset
Display RedBoot version information
      version
Display (hex dump) a range of memory
      x -b <location> [-l <length>] [-s]

Commands can be abbreviated to their shortest unique string. Thus in the list above, d,du,dum and dump are all valid for the dump command. The fconfig command can be abbreviated fc, but f would be ambiguous with fis.

There is one additional, special command. When RedBoot detects '$' or '+' (unless escaped via '\') in a command, it switches to GDB protocol mode. At this point, the eCos GDB stubs take over, allowing connections from a GDB host. The only way to get back to RedBoot from GDB mode is to restart the platform.

[Note]Note

Multiple commands may be entered on a single line, separated by the semi-colon “;” character.

The standard RedBoot command set is structured around the bootstrap environment. These commands are designed to be simple to use and remember, while still providing sufficient power and flexibility to be useful. No attempt has been made to render RedBoot as the end-all product. As such, things such as the debug environment are left to other modules, such as GDB stubs, which are typically included in RedBoot.

The command set may be also be extended on a platform basis.

225.2. Common Commands

alias — Manipulate command line aliases
baudrate — Set the baud rate for the system serial console
cache — Control hardware caches
channel — Select the system console channel
cksum — Compute POSIX checksums
disks — List available disk partitions.
dump — Display memory.
help — Display help on available commands
iopeek — Read I/O location
iopoke — Write I/O location
gunzip — Uncompress GZIP compressed data
ip_address — Set IP addresses
load — Download programs or data to the RedBoot platform
mcmp — Compare two segments of memory
mcopy — Copy memory
mfill — Fill RAM with a specified pattern
ping — Verify network connectivity
reset — Reset the device
version — Display RedBoot version information

225.3. Flash Image System (FIS)

fis init — Initialize Flash Image System (FIS)
fis list — List Flash Image System directory
fis free — Free flash image
fis create — Create flash image
fis load — Load flash image
fis delete — Delete flash image
fis lock — Lock flash area
fis unlock — Unlock flash area
fis erase — Erase flash area
fis read — Read flash area
fis write — Write flash area

If the platform has flash memory, RedBoot can use this for image storage. Executable images, as well as data, can be stored in flash in a simple file store. The fis command (fis is short for Flash Image System) is used to manipulate and maintain flash images.

225.4. Filesystem Interface

fs info — Print filesystem information
fs mount — Mount a filesystem
fs umount — Unmount filesystem
fs cd — Change filesystem directory
fs mkdir — Create filesystem directory
fs rmdir — Delete filesystem directory
fs rm — Delete file
fs mv — Move file
fs cp — Copy file
fs cat — Display file
fs ls — List filesystem directory
fs write — Write to filesystem

If the platform has access to secondary storage, then RedBoot may be able to access a filesystem stored on this device. RedBoot can access FAT filesystems stored on IDE disks, CompactFlash devices, MMC and SD cards or USB mass storage devices and can use JFFS2 filesystems stored in FLASH memory. The fs command is used to manipulate files on filesystems. Applications may be loaded into memory using the file mode of the load command.

225.5. Persistent State Flash-based Configuration and Control

RedBoot provides flash management support for storage in the flash memory of multiple executable images and of non-volatile information such as IP addresses and other network information.

RedBoot on platforms that support flash based configuration information will report the following message the first time that RedBoot is booted on the target:

flash configuration checksum error or invalid key

This error can be ignored if no flash based configuration is desired, or can be silenced by running the fconfig command as described below. At this point you may also wish to run the fis init command. See other fis commands in Section 225.3, “Flash Image System (FIS)”.

Certain control and configuration information used by RedBoot can be stored in flash.

The details of what information is maintained in flash differ, based on the platform and the configuration. However, the basic operation used to maintain this information is the same. Using the fconfig -l command, the information may be displayed and/or changed.

If the optional flag -i is specified, then the configuration database will be reset to its default state. This is also needed the first time RedBoot is installed on the target, or when updating to a newer RedBoot with different configuration keys.

If the optional flag -l is specified, the configuration data is simply listed. Otherwise, each configuration parameter will be displayed and you are given a chance to change it. The entire value must be typed - typing just carriage return will leave a value unchanged. Boolean values may be entered using the first letter (t for true, f for false). At any time the editing process may be stopped simply by entering a period (.) on the line. Entering the caret (^) moves the editing back to the previous item. See “RedBoot Editing Commands”, Section 224.4, “RedBoot Editing Commands”.

If any changes are made in the configuration, then the updated data will be written back to flash after getting acknowledgment from the user.

If the optional flag -n is specified (with or without -l) then “nicknames” of the entries are used. These are shorter and less descriptive than “full” names. The full name may also be displayed by adding the -f flag.

The reason for telling you nicknames is that a quick way to set a single entry is provided, using the format

  RedBoot> fconfig nickname value

If no value is supplied, the command will list and prompt for only that entry. If a value is supplied, then the entry will be set to that value. You will be prompted whether to write the new information into flash if any change was made. For example

  RedBoot> fconfig -l -n
  boot_script: false
  bootp: false
  bootp_my_ip: 10.16.19.176
  bootp_server_ip: 10.16.19.66
  dns_ip: 10.16.19.1
  gdb_port: 9000
  net_debug: false
  RedBoot> fconfig bootp_my_ip 10.16.19.177
  bootp_my_ip: 10.16.19.176 Setting to 10.16.19.177
  Update RedBoot non-volatile configuration - continue (y/n)? y
  ... Unlock from 0x507c0000-0x507e0000: .
  ... Erase from 0x507c0000-0x507e0000: .
  ... Program from 0x0000a8d0-0x0000acd0 at 0x507c0000: .
  ... Lock from 0x507c0000-0x507e0000: .
  RedBoot>

Additionally, nicknames can be used like aliases via the format %{nickname}. This allows the values stored by fconfig to be used directly by scripts and commands.

Depending on how your terminal program is connected and its capabilities, you might find that you are unable to use line-editing to delete the ’old‚ value when using the default behaviour of fconfig nickname or just plain fconfig, as shown in this example:

RedBoot> fco bootp
bootp: false_

The user deletes the word “false;” and enters “true” so the display looks like this:

RedBoot> fco bootp
bootp: true
Update RedBoot non-volatile configuration - continue (y/n)? y
... Unlock from ...
RedBoot> _

To edit when you cannot backspace, use the optional flag -d (for “dumb terminal”) to provide a simpler interface thus:

RedBoot> fco -d bootp
bootp: false ? _

and you enter the value in the obvious manner thus:

RedBoot> fco -d bootp
bootp: false ? true
Update RedBoot non-volatile configuration - continue (y/n)? y
... Unlock from ...
RedBoot> _

One item which is always present in the configuration data is the ability to execute a script at boot time. A sequence of RedBoot commands can be entered which will be executed when the system starts up. Optionally, a time-out period can be provided which allows the user to abort the startup script and proceed with normal command processing from the console.

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 domain name: example.com
DNS server IP address: 192.168.1.1
GDB connection port: 9000
Network debug at boot time: false

The following example sets a boot script and then shows it running.

RedBoot> fconfig
Run script at boot: false t
      Boot script:
Enter script, terminate with empty line
>> fi li
    Boot script timeout: 0 10
Use BOOTP for network configuration: false .
Update RedBoot non-volatile configuration - continue (y/n)? y
... Erase from 0xa0fc0000-0xa0fe0000: .
... Program from 0x8c021f60-0x8c022360 at 0xa0fc0000: .
RedBoot>
RedBoot(tm) debug environment - built 08:22:24, Aug 23 2000
Copyright (C) 2000, Free Software Foundation, Inc.


RAM: 0x8c000000-0x8c800000
flash: 0xa0000000 - 0xa1000000, 128 blocks of 0x00020000 bytes ea.
Socket Communications, Inc: Low Power Ethernet CF Revision C \
5V/3.3V 08/27/98 IP: 192.168.1.29, Default server: 192.168.1.101 \
== Executing boot script in 10 seconds - enter ^C to abort
RedBoot> fi li
Name              flash addr   Mem addr    Length    Entry point
RedBoot          0xA0000000   0xA0000000  0x020000  0x80000000
RedBoot config   0xA0FC0000   0xA0FC0000  0x020000  0x00000000
FIS directory    0xA0FE0000   0xA0FE0000  0x020000  0x00000000
RedBoot>
[Note]Notes
  • The bold characters above indicate where something was entered on the console. As you can see, the fi li command at the end came from the script, not the console. Once the script is executed, command processing reverts to the console.
  • RedBoot supports the notion of a boot script timeout, i.e. a period of time that RedBoot waits before executing the boot time script. This period is primarily to allow the possibility of canceling the script. Since a timeout value of zero (0) seconds would never allow the script to be aborted or canceled, this value is not allowed. If the timeout value is zero, then RedBoot will abort the script execution immediately.

On many targets, RedBoot may be configured to run from ROM or it may be configured to run from RAM. Other configurations are also possible. All RedBoot configurations will execute the boot script, but in certain cases it may be desirable to limit the execution of certain script commands to one RedBoot configuration or the other. This can be accomplished by prepending {<startup type>} to the commands which should be executed only by the RedBoot configured for the specified startup type. The following boot script illustrates this concept by having the ROM based RedBoot load and run the RAM based RedBoot. The RAM based RedBoot will then list flash images.

RedBoot> fco
Run script at boot: false t
Boot script:
Enter script, terminate with empty line
>> {ROM}fis load RedBoot[RAM]
>> {ROM}go
>> {RAM}fis li
>>
Boot script timeout (1000ms resolution): 2
Use BOOTP for network configuration: false
 ...
Update RedBoot non-volatile configuration - continue (y/n)? y
... Unlock from 0x007c0000-0x007e0000: .
... Erase from 0x007c0000-0x007e0000: .
... Program from 0xa0015030-0xa0016030 at 0x007df000: .
... Lock from 0x007c0000-0x007e0000: .
RedBoot> reset
... Resetting.
+Ethernet eth0: MAC address 00:80:4d:46:01:05
IP: 192.168.1.153, Default server: 192.168.1.10

RedBoot(tm) bootstrap and debug environment [ROM]
eCosCentric certified release, version R1.xx - built 12:27:26, Sep 11 2003

Platform: IQ80310 (XScale)
Copyright (C) 2000, 2001, Free Software Foundation, Inc.

RAM: 0xa0000000-0xa2000000, 0xa001b088-0xa1fdf000 available
FLASH: 0x00000000 - 0x00800000, 64 blocks of 0x00020000 bytes each.
== Executing boot script in 2.000 seconds - enter ^C to abort
RedBoot> fis load RedBoot[RAM]
RedBoot> go
+Ethernet eth0: MAC address 00:80:4d:46:01:05
IP: 192.168.1.153, Default server: 192.168.1.10

RedBoot(tm) bootstrap and debug environment [RAM]
eCosCentric certified release, version R1.xx - built 18:03:27, Sep 11 2003

Platform: IQ80310 (XScale)
Copyright (C) 2000, 2001, Free Software Foundation, Inc.

RAM: 0xa0000000-0xa2000000, 0xa0057fe8-0xa1fdf000 available
FLASH: 0x00000000 - 0x00800000, 64 blocks of 0x00020000 bytes each.
== Executing boot script in 2.000 seconds - enter ^C to abort
RedBoot> fis li
Name              FLASH addr  Mem addr    Length      Entry point
RedBoot           0x00000000  0x00000000  0x00040000  0x00002000
RedBoot config    0x007DF000  0x007DF000  0x00001000  0x00000000
FIS directory     0x007E0000  0x007E0000  0x00020000  0x00000000
RedBoot>

225.6. Persistent State in a NAND-based environment

On some boards it is necessary to use NAND flash to store persistent state and configuration. This is normally provided by the config store.

For simplicity, a bridge driver has been developed which allows the config store to be used by RedBoot as if it were NOR flash. (The reason for this is that the RedBoot fconfig system has a much lower overhead than the NAND storage system, in order to operate in environments with very limited resources. NAND-based boards have much more flash and RAM available, so the overhead of the extra layers is not an issue.)

To RedBoot, the config store behaves identically to regular (NOR) flash storage. However its use has a number of implications:

  • If the NAND is repartitioned or erased, all persistent configuration is likely to be lost.
  • The configuration is susceptible to the same wearout and read disturb effects that affect all NAND parts over time. (This is mitigated by allowing multiple NAND blocks for the config store partition, which are used in rotation.)

Even though the bridge driver may be in use, it is still possible to use the config store directly for other options.

[Note]Note

Some platform HALs use this mechanism to set the size of the config store partition in such a way that does not depend on RedBoot. Refer to the documentation for those HAL ports for details.

225.6.1. Manipulating persistent state stored on NAND

To modify configuration items managed by RedBoot, use the fconfig command in the usual way. See Section 225.5, “Persistent State Flash-based Configuration and Control ”.

To modify items in the config store which are not managed by RedBoot, use the nconfig command. See Section 225.8, “NAND configuration commands ”. You may also wish to manipulate the NAND array with the nand command family; see Section 225.9, “NAND manipulation commands ”.

225.7. Executing Programs from RedBoot

go — Execute a program
exec — Execute a Linux kernel

Once an image has been loaded into memory, either via the load command or the fis load command, execution may be transfered to that image.

[Note]Note

The image is assumed to be a stand-alone entity, as RedBoot gives the entire platform over to it. Typical examples would be an eCos application or a Linux kernel.

225.8. NAND configuration commands

nconfig list — List configuration keys
nconfig info — Query metadata for one or more config keys
nconfig types — List all known config data types
nconfig get — Outputs the current value of one or more config keys
nconfig put — Writes a config key
nconfig del — Deletes a config key
nconfig dump — Diagnostic dump output
[Note]Note

This section does not cover configuration items managed by RedBoot; for those, use the fconfig command instead (Section 225.5, “Persistent State Flash-based Configuration and Control ”).

The config store is the backing store for this persistent information. Data is stored as (key, value) pairs; values are typed. This section refers only to the RedBoot commands for manipulating the config store.

[Note]Note

The config key ecos.fakeflash.config contains the RedBoot configuration information as managed by the fconfig command. Do not edit this key directly; it is automatically managed by RedBoot and the driver stack.

225.9. NAND manipulation commands

nand list — List NAND devices
nand info — Output information about a NAND device
nand badblocks states — List all current valid BBT states
nand badblocks summary — Summary of the Bad Block Table
nand badblocks list — List not-OK blocks in a Bad Block Table
nand badblocks mark — Manipulate the Bad Block Table
nand erase — Erase an entire NAND partition
nand eraseblock — Erase a specific NAND block
[Note]Notes
  • These commands are only available when there is at least one NAND driver configured.
  • All the nand badblocks commands may be configured out simultaneously by turning off the CYGSEM_REDBOOT_NAND_BADBLOCKS_CMD option.