12.4. Tester Configuration

The RTEMS Tester and RTEMS Run are controlled by configuration data and scripts. The user specifies a BSP on the command line using the --rtems-bsp option as well as optionally specifying a user configuration file using --user-config.

The Figure RTEMS Tester and Run Configuration Files shows the various sources of configuration data and their format. The ini files are the standard INI format, the mc are the internal RTEMS Toolkit’s Macro format, and cfg is the RTEMS Toolkit’s Configuration script format, the same format used by the RTEMS Source Builder.

RTEMS Tester and Run Configuration Files

Fig. 12.1 RTEMS Tester and Run Configuration Files

Configuration data is held in a macro database keyed on the macro name. Macros can be expanded in configuration scripts using the syntax %{name}. The macro database is layered using maps. The defaults and values created when a configure script runs live the in the global map. Values read from the BSP and User INI configuration files are loaded into maps based on the BSP name. This lets a single User configuration file contain specialized configuration values for a number of BSPs and the tester and run commands select the values based on the selected BSP. Macros are expanded using the BSP map first giving those values the highest priority. User defined values are loaded after the BSP configuration values overwriting them letting a user speckles a BSP’s default configuration for their local needs.

Figure RTEMS Tester and Run Configuration Load and Execute Sequence shows the configuration loading and script execution order.

RTEMS Tester and Run Configuration Load and Execute Sequence

Fig. 12.2 RTEMS Tester and Run Configuration Load and Execute Sequence

12.4.1. Defaults

The RTEMS Tester and RTEMS Run are primed using defaults from the file rtems/testing/testing.mc. All default settings can be overridden in a BSP or User configuration file.

12.4.2. BSP and User Configuration

The BSP and User configuration files are INI format files. The BSP configuration file has to have an INI section that is the name of the BSP passed on the command line. The section has the following mandatory values:

bsp

The name of the BSP. The BSP name is used to create a macro map to hold the BSP’s configuration data. Typically this is the same as the BSP name used on the command line.

arch

The name of the BSP architecture. This is need for the GDB configuration scripts where the architecture specific GDB needs to run. It is mandatory so the arch/bsp standard RTEMS BSP string can be used.

tester

The tester or run configuration script. This is the name of the configuration script the RTEMS Tester or RTEMS Run executes as a back end. The tester value is typically of the form %{_rtscripts}/<script> where <script> is name of the back end script to be run.

Target commands support expansion of specific tags to provide a convenient way for users to customize a local test environment. The parameters expanded are:

@ARCH@

The BSP architecture.

@BSP@

The BSP’s name set by the bsp value.

@EXE@

The executable name as an absolute path

@FEXE@

The filtered executable if a target_exe_filter is provided else the executable’s file name.

The following are optional and depend on the back end being used and the local target hardware set up:

jobs

The jobs value sets the number of jobs that can be run at once. This setting only effects the RTEMS Tester. The tester can run up to the jobs value of tests concurrently. If the tester back end is a simulator running a job on each available core lowers the total test time. Overloading a machine with too many simulators running in parallel can slow down each simulation and test timeouts may be recorded.

bsp_tty_dev

The BSP’s tty device. This can be a real device on the host machine the executable is being run from or it can be a telnet server and port defined using the stand host format. See Consoles for details.

target_pretest_command

The pre-test command is a host shell command that is called before each test runs. It can be used to construct a suitable environment or image needed by a simulator or target. The RTEMS executate being run is provided as an argument and the bootloader specific format is the output.

target_posttest_command

The post-test command is a host shell command that is called after each test has finished. It can be used to destroy any environment or image created by the pre-test command.

target_exe_filter

The target executable filter transforms the executable name into a filtered executable name. This filter lets the tester or run command track the name of any generated file a pre-test command may generate. The syntax is a simplified sed regular expression. The first character is a delimiter and there must be 2 sections therefore 3 delimiter. The first section is a Python regular expression and the second section is plain text that replaces anywhere the regular expression matches. For example /\.exe/.exe.img/ will search for .exe in the executable name and replace it with .exe.img. Note, there is no need to escape the text in the second part, it is just plain test.

test_restarts

The number of restarts before the test is considered invalid. Currently not used.

target_reset_regex

The target reset regular expression. This is a Python regular expression used to filter the console input. If a match is made something has happened during the boot process that requires a reset. The target_reset_command is issued to perform the reset. Typically this field looks for boot loader error messages that indicate the boot process as failed.

target_start_regex

The target start regular expression. This is a Python regular expression to filter the console input to asynchronously detect if a target has reset. If a board crashes running a test or at any point reset this filter detects the restart and ends the test with a suitable result.

target_on_command

The target on command is a host shell command that is called before the first test. This command powers on a target. Targets should be left powered off when not running tests or the target may request TFTP downloads that are for another target interfering with those test results. We recommend you implement this command as a target off command, a pause, then a target on command.

target_off_command

The target off command is a host shell command that is called after the last test powering off the target.

target_reset_command

The target reset command is a host shell command that is called when the target needs to be reset. This command can power cycle the target or toggle a reset signal connected to the target. If you are power cycling a target make sure you have a suitable pause to let the target completely power down.

12.4.3. Configuration Scripts

Configuration scripts are provided for each supported RTEMS Tester and RTEMS Run back end and console management. The scripts are in the standard RTEMS Toolkit Configuration Script format. Please refer to the RTEMS Source Builder documentation for the basic scripting syntax and usage.

The RTEMS Tester and RTEMS Run specializes the standard configuration syntax providing a directive for the console and each supported back end. The supported directives are:

  • %console

  • %execute

  • %gdb

  • %tftp

  • %wait

12.4.3.1. Console

The %console configures the console used to access the target’s console. The console can be a process’s stdout, a termios tty on Unix and MacOS and Telnet on all hosts. The directive accepts:

stdio

The standard output stream from the executing processing.

tty <dev> <settings>

The name of the tty to open and use. The tty device or <dev> can be a termio device and the <settings> are standard termios values.

The Python termios document provides details of the settings that can be controlled. The settings are a single string where prefix the value with ~ negates the setting. Setting are:

  • B115200 (an example buadrate)

  • BRKINT

  • IGNBRK

  • IGNCR

  • ICANON

  • ISIG

  • IEXTEN

  • ECHO

  • CLOCAL

  • CRTSCTS

  • VMIN=<value>

  • VTIME=<value

A example in a configuration script is:

%define bsp_tty_dev      /dev/ttyUSB2
%define bsp_tty_settings B115200,~BRKINT,IGNBRK,IGNCR,~ICANON,~ISIG,~IEXTEN,~ECHO,CLOCAL,~CRTSCTS,VMIN=1,VTIME=2

A example BSP or User configuration file is:

[bsp-special]
bsp              = example-bsp
bsp_tty_dev      = /dev/ttyUSB2
bsp_tty_settings = B115200,~BRKINT,IGNBRK,IGNCR,~ICANON,~ISIG,~IEXTEN,~ECHO,CLOCAL,~CRTSCTS,VMIN=1,VTIME=2

The console directive is managed in the %{_rtscripts}/console.cfg configuration script. If the %{console_stdio} is defined the console will be stdio else the console will be the BSP console or %{bsp_tty_dev}.

Telnet can be combined with the ser2net daemon to remotely access a target’s physical serial UART interface. The syntax is host:port:

%define bsp_tty_dev      1.2.3.4:8989

12.4.3.2. Execute

The %execute directive executes a command for each rest. The execute forks the command and arguments supplied to the execute directive and captures the stdout stream as the console. If the console directive is set to stdout the sub-processes stdout stream is used as the console.

The RTEMS Tester will run parallel tests as jobs.

An example is:

%execute %{run_cmd} %{run_opts} %{test_executable} %{test_executable_opts}

12.4.3.3. GDB

The %gdb directive executes GDB in the machine interface mode give the RTEMS Tester and RTEMS Run commands control. The console is taken from GDB if it is stdout.

The RTEMS Tester will run parallel tests as jobs.

An example is:

%gdb %{gdb_cmd} %{test_executable} %{gdb_script}

12.4.3.4. TFTP

The %tftp directive starts a TFTP session on a specified port sending the test executable to the target over a networking using the TFTP protocol.

The RTEMS Tester will run only one test at a time. There is just one physical board running the test.

An example is:

%tftp %{test_executable} %{tftp_port}

The RTEMS Tester contains a TFTP server so an external TFTP is not needed. It is recommended a TFTP Proxy is set up to handle the TFTP sessions for your network. The internal TFTP server ignores the requrest file and serves the next executable. If the target requires the executable ne in a specific format provide a script via the target_pretest_command option in your user configuration file.

The RTEMS Tools provides a TFTP protocol proxy server. It takes a list of MAC addresses and proxies TFTP sessions for that MAC address to another IP address and port. A proxy provides the following benefits:

  1. The TFTP proxy server is the only software required to run as root

  2. All hardware targets can be configured to serve from a single machine and the proxy can distribute the sessions out to developer machines

  3. There is no need to provide a globally writable file system a central TFTP server acceses

If you have a central TFTP server refer to the %wait directive.

12.4.3.5. Wait

The %wait directive waits the timeout period for a test to complete. The directive monitors the console output and resets the timeout timer if console output is seen. If the test runs for too long while outputing data an error is reported.

The wait directive can be used in systems where there is an external mechanism being used to send the executable to the target hardware.

An example is:

%wait

Wait has no options. The timeouts are controlled in other ways.

If you have an external system wide TFTP server with global access wait can used by providing a `` script that places the file in the location the TFTP server can see. This is done as the test start so if networking loading there is normally enough time to get the executable image in place before the transfer starts. The MVME2700 (powerpc/mvme2307) is a BSP that supports the %wait directive.

The following is an example user configuration file (see --user-config):

#
# MVME2700 (mvme2307)
#
[mvme2307]
bsp_tty_dev            = 1.2.3.4:5678
target_pretest_command = mk-mvme2307-img @EXE@ /tftp/cjohns/rtems.img
target_exe_filter      = /\.exe/.exe.img/
target_on_command      = pw-ctl 1.2.3.4 toggle-on 3 1
target_off_command     = pw-ctl 1.2.3.4 off 3
target_reset_command   = pw-ctl 1.2.3.4 toggle-on 3 1

The script mk-mvme2307-img converts the RTEMS ELF executable into the PowerPC prep bootloader format and copies the file to the TFTP server’s network wide location. The MVME2700 is configured to request rtems.img from this location. The command pw-ctl is a command to control the power to the board.