NAME
runinfo - Format of the .runinfo files used by xeno-load(1) to execute
applications based on Xenomai
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.
SEE ALSO
xeno-load(1), sudo(8), insmod(8), modprobe(8), rmmod(8)