DESCRIPTION

A .runinfo file describes the possible targets for executing an application based on Xenomai. Each target is defined on one line, with the following format:

name:modulenames:actions:message

The meanings of the fields are:

name

The name of the target.

modulenames

The list of names of modules to be loaded by xeno-load(1) before executing the application, and unloaded after execution. If several module names are specified, they must be separated by pluses (+). Order is important: modules are loaded in the same order as in the list, and unloaded in the reverse order. Every module is loaded and unloaded only once, so duplicate module names are allowed in the list.

A module name can be that of any Linux kernel module, or of one of Xenomai's modules. In the latter case, the name of a Xenomai module must be specified without the xeno_ name prefix, e.g. native must be specified in order to load/unload Xenomai's xeno_native module. Modules xeno_hal and xeno_nucleus are always loaded/unloaded by xeno-load(1): there is no need to explicitly specify them.

Xenomai modules are loaded directly using insmod(8), and other modules are loaded using modprobe(8). All modules are unloaded after execution using rmmod(8).

actions

Sequence of actions to execute the application. In the simplest case, this is only the command line to execute. More generally, this field is a sequence of actions separated by semi-colons (;). Any number of the following actions are allowed, in any order:

push modulename

Loads the module with the specified name, using insmod(8). If a module with that name exists in the application-specific module directory (as specified in user_moddir, see below), that module is loaded. Otherwise, modulename must be a sufficiently qualified relative file name, or an absolute file name.

[exec|spawn] [!] commandline [&]

Executes the specified commandline. The args arguments passed to the xeno-load(1) command are appended to the commandline, so that invariable arguments can be "hard-coded" in the target commandline, and variable arguments can be passed as args to xeno-load(1).

The exec and spawn keywords are equivalent to having no keyword, hence have no effect.

If the ! option is specified, the application is executed as root using sudo(8), hence the user may have to enter a password. Otherwise, the application is directly executed as the user that executes xeno-load(1).

If the & option is specified, the application is executed as a background shell job; otherwise it is executed as a foreground job.

klog [args] ...

A shortcut equivalent to the following action, which displays logging messages from the kernel:

! tail -f /var/log/messages

Arguments following the klog keyword are ignored.

pop [modulename] ...

Unloads the modules with the specified names (separated by spaces). If no module name is specified, the lastly loaded module (e.g. loaded by the last push action) is unloaded.

popall | flush

Terminates any currently executing actions, especially background jobs (started with the & option, see above), unloads all modules loaded by push actions, and unloads all modules listed in the modulenames field of the target. popall and flush are synomous.

It is recommended to terminate every target action list by a popall or flush action, in order to unload all loaded modules after the application execution is terminated. A popall action is executed when xeno-load(1) receives a SIGINT signal (e.g. the user typed CONTROL-C); then it terminates.

message

A message that is printed at target startup. As a shortcut, if the message is control_c, it is replaced by:

Type ^C to stop this application.

One or more such targets can be defined in a .runinfo file, one per line. The first defined target is the default target.

In addition to lines defining targets, a .runinfo file can contain lines that define paths to directory containg module files. The following optional line defines the path to Xenomai's kernel module files, referred to in targets' modulenames fields. By default, if no such line is specified, the path is Xenomai's modules installation path.

xeno_moddir=directory

The following optional line defines the path to the application's kernel module files to be loaded. This path is used by push actions.

user_moddir=directory

Module names specified in the modulenames target fields or as parameters to push and pop actions must be specified without the kernel module file extension (e.g.: .ko).

EXAMPLES

This is the .runinfo file for the latency test program distributed with Xenomai:

latency:native:!./latency;popall:control_c

This file defines a single target, called latency. This target uses Xenomai's xeno_native module (the native name is specified, without the xeno_ name prefix). The application is executed by two actions. Fist, the latency command is executed, as root using sudo(8) (since the ! option is specified). Then, the popall action is executed, to unload all modules (xeno_native, etc.). The message to be displayed before the application is executed is:

Type ^C to stop this application.

since control_c is a shortcut for that common message.

This is a more complex .runinfo file, with multiple targets and module paths definitions:

### Target definitions ###
userspace:posix+native:exec ./app1;popall:control_c
kernelspace:native:push mymodule;exec !./app2;pop mymodule;popall:control_c
debug:native:push mymodule;klog:Type ^C to stop printing logging messages.
### Modules directories ###
xeno_moddir=/usr/realtime/modules
user_moddir=/usr/local/lib/mymodules

In this example, target userspace is the default target, since it is the first defined.