Developer Handbook - Shell Command Reference

12.1 Introduction

This chapter defines the arguments and exit status codes of the RCE-specific RTEMS shell commands:

• #burnContainer
• #burnSystem
• #burnTask
• #freeBlocks
• #lsSystem
• #lsTask
• #mount
• #reboot
• #rmContainer
• #rmTask
• runTask (local)
• runTask (remote)
• #stopTask
• #syslog

For descriptions of the built-in RTEMS shell commands, consult The RTEMS Shell manual (http, pdf).

burnContainer

To be implemented.

Load data from a file on a mounted file system, then write the data to a configuration memory container, along with user-specified metadata. The rce supports 4 container types: TASK (for runnable modules), DATA (for library modules), CONFIGURATION (for generic data, like port settings and Ethernet configuration), and SYSTEM (for system images).

burnContainer is a general command. It can be used to burn arbitrary data to configuration memory, including runnable elf modules and their associated metadata; however, for runnables, the convenience command burnTask (Section 12.4) is more appropriate.

burnContainer
    -T <type>
    -I <containerName>
    [-F1 <field1>]
    [-F2 <field2>]
    [-F3 <field3>]
    [-F4 <field4>]
    [-F5 <field5>]
    [-F6 <field6>]
    [-F7 <field7>]
    <filePath>

Arguments

• -T <type>
  Type of container to be burned. Valid values are "DATA", "TASK", "CONFIGURATION", and "SYSTEM".
• -I <containerName>
  Numeric "name" of the container to be burned. Valid range depends on container type: 0 - 63 for DATA containers, 0 - 7 for TASK containers, 0 - 63 for CONFIGURATION containers, 0 - 1 for SYSTEM containers.
• -FN <fieldN>
  User-defined 32-bit value to be stored as a field in the container's metadata record. Default = 0.
• <filePath>
  Local path to file.

Exit Status

• 0 on success.
• -1 if the data cannot be written to configuration memory.
• -2 if the file cannot be read from the remote file system.
• 2 on unparseable or missing argument(s).

Remarks

• The command fails and returns -1 if the user specifies the name of a container that is already in use. burnContainer will not overwrite an existing container; use rmContainer to remove the container first.
• The command fails if no source file system is mounted. See mount (Section 12.9).

burnSystem

Load a bootstrap from a file on a mounted file system, then write it to a configuration memory container. burnSystem is used to burn runnable ELF executables.

burnSystem
    -I <containerName>
    -A <loadAddr>
    <filePath>

Arguments

• -I <containerName>
  Numeric "name" of the container to be burned. Valid range is 0 - 1. The value is chosen according to a policy. The currently agreed upon policy is to load prod bootstraps into container 0 and rescue bootstraps into container 1.
• -A <loadAddr>
  Decimal load address of the image being burned. This argument is vestigial since our migration to storing/loading ELF images to/from flash, and thus should henceforth be supplied with the value zero. Note that the implementation treats this argument as optional, but an incorrect value will be used when it is omitted. Always specify -A 0. Some day we'll fix this .
• <filePath>
  Local path to file.

Exit Status

• 0 on success.
• -1 if the data cannot be written to configuration memory.
• -2 if the file cannot be read from the remote file system.
• 2 on unparseable or missing argument(s).

Remarks

• The command fails and returns -1 if the user specifies the name of a container that is already in use. burnSystem will not overwrite an existing container; use rmContainer to remove the container first.
• The command fails if no source file system is mounted. See mount (Section 12.9).

burnTask

Load a runnable module image from a mounted file system, then write the image to a configuration memory TASK container and store the corresponding metadata.

burnTask
    -I <containerName>
    -N <taskName>
    [-P <priority>]
    [-S <stacksize>]
    [-M <mode>]
    [-A <attribute>]
    <filePath>

Arguments

• -I <containerName>
  Numeric "name" of the container in which the task image should be stored. Valid range: 0 - 7.
• -N <taskName>
  User-defined, 4-character rtems task name. For instance, "UAPP".
• -P <priority>
  rtems task priority. Default = 1.
• -S <stacksize>
  rtems stack size. Default = 8 Kbytes (1024 * 8) for rtems built in the slac rce repository.
• -M <mode>
  rtems task mode configuration bitmask. Default = 0 (preemption enabled, timeslicing disabled, asynchronous signal processing enabled). See below.
• -A <attribute>
  rtems task attributes bitmask. Default = 0 (task is local, ignore floating point hardware). See below.
• <filePath>
  Local path to task image.

Exit Status

• 0 on success.
• -1 if the task image cannot be written to configuration memory.
• -2 if the task image cannot be read from the remote file system.
• 2 on unparseable or missing argument(s).

Remarks

• The task mode of an rtems task defines the task's interrupt level, and its preemption, timeslicing, and signal response behavior. The attributes of an rtems task define whether it is considered a local or global task and whether the task makes use of floating point hardware. Modes and attributes are set with separate bitmasks, the bit positions of which are defined in <rtems_target_build>/lib/include/rtems/rtems/modes.h and <rtems_target_build>/lib/include/rtems/rtems/attr.h.
• The command fails and returns -1 if the user specifies the name of a task container that is already exists. burnTask will not overwrite an existing task container; use rmtask to remove the task container first.
• The command fails if no source file system is mounted. See mount (Section 12.8).

freeBlocks

Display a block usage report for rce configuration memory.

freeBlocks

Arguments

None.

Exit Status

• 0 on success.

lsSystem

Display the metadata for each system image stored in rce configuration memory: load address, transfer address, and image size.

lsSystem

Arguments

None.

Exit Status

• 0 on success.
• -1 if metadata could not be retrieved from configuration memory.

Remarks

Image size is reported in units of blocks (16K).

lsTask

Display the metadata for each task image stored in rce configuration memory: rtems taskname , stack size, load address, rtems task mode bitmask and rtems task attribute bitmask.

lsTask

Arguments

None.

Exit Status

• 0 on success.
• -1 if metadata could not be retrieved from configuration memory.

mount

Mount a remote file system, allowing task images and other data to be transferred to the rce.
This is a built-in rtems shell command.

mount
    -t <type>
    <host>:<export>
    <local>

Arguments

• -t <type>
  File system type. For the rce, must be either "nfs" or "tftp".
• <host>:<export>
  Remote device. When -t is "nfs", specify the NFS host and the exported directory tree. When -t is "tftp", specify the ip address of the tftp server.
• <local>
  Local mount point.

Exit Status

• 0 on success.
• Not 0 if an error occurs.

reboot

Initiate a warm reboot of the rce using the configuration currently stored in the rce Restart Options register. Optionally, modify the value in the Restart options field of this register to point to a new system image/task image pair, then reboot.

reboot
    [ -S <containerName> ]
    [ -I <containerName> ]

Arguments

• -S <containerName>
  Numeric "name" of the container that stores the system image to load after reboot. Valid range: 0 - 1. Container 0 holds the "production" system image; container 1 holds the development system image (with rce shell).
• -I <containerName>
  Numeric "name" of the container that stores the task image to load after reboot. Valid range: 0 - 7.

Exit Status

• 0 on success.
• 2 on unparsable or missing argument(s).
• 3 if a system image or task image container name is out of range.

Remarks

The rce Restart Options register defines a mapping between the front-panel rotary switch and a system image/task image pair. This command effectively assigns the specified image pair to the currently-selected switch position.

The contents of the rce Restart Options register are cleared on a hard reset.

rmContainer

Remove a container of any type from rce configuration memory.

rmContainer
    -T <type>
    -I <containerName>

Arguments

• -T <type>
  Type of container to be removed. Valid values are "DATA", "TASK", "CONFIGURATION", and "SYSTEM".
• -I <containerName>
  Numeric "name" of the container to be removed. Valid range depends on container type.

Exit Status

• 0 on success.
• -1 if container is not extant.
• -2 if an error occurs during container deletion.
• 2 on (a) unparsable or missing argument(s), or (b) invalid container type.

Remarks

Note to Editor: Looks from the code like we built to tool to remove SYSTEM images as well. We have to strip this out before releasing into the wild.

Note to Editor: TBS what to recommend if the command fails with -2 and the container cannot be removed.

rmTask

Remove a task image stored in rce configuration memory, along with its corresponding metadata.

rmTask
    -I <containerName>

Arguments

• -I <containerName>
  Numeric "name" of the task container to remove. Valid range is 0 - 7.

Exit Status

• 0 on success.
• -1 if the container for the task image is not extant.
• -2 if an error occurs on task container deletion.
• 2 on unparsable or missing argument(s).

runTask (local)

The runTask command provides two usage options: remote and local.

For local usage, the command loads a task image from rce configuration memory and executes it using its stored task metadata.

runTask
    -I <containerName>

Arguments

• -I <containerName>
  Numeric "name" of the container that stores the task image to run. Valid range: 0 - 7.

Exit Status

• 0 on success.
• -1 on a dynamic linking error.
• -2 if the task image cannot be read from configuration memory.
• 2 on unparsable or missing argument(s).

runTask (remote)

The runTask command provides two usage options: remote and local.

For remote usage, the command loads a task image from a mounted file system, and executes the module in an rtems task with the user-specified rtems task name. Since the image is stored remotely, task metadata are not available in rce configuration memory and must be specified as arguments.

runTask 
    -N <taskName>
    [-P <priority>]
    [-S <stacksize>]
    [-M <mode>]
    [-A <attribute>]
    <filePath>

Arguments

• -N <taskName>
  User-defined, 4-character rtems task name. For instance, "UTSK".
• -P <priority>
  rtems task priority. Defaults to 100.
• -S <stacksize>
  rtems stack size. Default = 8 Kbytes (1024 * 8) for rtems built in the slac rce repository.
• -M <mode>
  rtems task mode configuration bitmask. Default = 0 (preemption enabled, timeslicing disabled, asynchronous signal processing enabled). See below.
• -A <attribute>
  rtems task attributes bitmask. Default = 0 (task is local, ignore floating point hardware). See below.
• <filePath>
  Local path to task image.

Exit Status

• 0 on success.
• -1 on a dynamic linking error.
• -2 if the task image cannot be read from the remote file system.
• 2 on unparsable or missing argument(s).

Remarks

• The task mode of an rtems task defines the task's interrupt level, and its preemption, timeslicing, and signal response behavior. The attributes of an rtems task define whether it is considered a local or global task and whether the task makes use of floating point hardware. Modes and attributes are set with separate bitmasks, the bit positions of which are defined in <rtems_target_build>/lib/include/rtems/rtems/modes.h and <rtems_target_build>/lib/include/rtems/rtems/attr.h.
• The command fails if no source file system is mounted. See mount (Section 12.8).

stopTask

Stop a task.

stopTask
    [-I <taskID>]
    [-N <taskName>]

Arguments

• -I <taskID>
  An rtems task id.
• -N <taskName>
  User-defined, 4-character rtems task name. For example, "UTSK."

Exit Status

• 0 on success.
• -1 if (a) an rtems task id was specified, but the id did not resolve to any running task, or (b) the specified task is running on another node.
• 1 if an rtems task name was specified, but the name did not resolve to any running task.
• 2 on unparsable or missing argument(s).

Remarks

Either a task id or task name must be specified.

This command calls the rtems_task_delete directive to stop the specified task. The task's name and id become invalid, and its control block, resource claims, and stack are deleted.

Though the rtems_task_delete directive stops the specified task, it does not call any shutdown routines defined by the task; thus, not all of the task's dynamically allocated resources are necessarily freed. This command should be used for stopping unresponsive tasks, not as a tool for general task management.

See XXX for additional information on the rtems_task_delete directive.

syslog

Show or clear the rce system log.

syslog
    [ -l <n> ]
    [ -f <n> ]
    [ -c ]

Arguments

• -l <n>
  Show only the last n messages.
• -f <n>
  Show only the first n messages.
• -c
  Clear the system log

Arguments -l, -n and -c are mutually exclusive

Exit Status

• 0 on success.
• 2 on unparsable or missing argument(s).