LINUX RTAI中.runinfo文件详解（英文）

Description of the "runinfo" format
-----------------------------------

Purpose of the "runinfo" files
------------------------------

"runinfo" files found in the source tree allow the "rtai-load" script
(see rtai-core/scripts/rtai-load) to retrieve the information it needs
to execute a RTAI application in an automated manner. This file
basically describes the module dependencies (i.e from standard RTAI
system modules) and the load/startup actions (i.e. insmoding module(s)
and/or launching executable(s)) that need to be taken to start a given
application.

This mecanism replaces the various hand-crafted "run" shell scripts
that existed up to RTAI's 24.1.12 (stromboli) version.

Format of a runinfo file
------------------------

All examples and tests contain/should contain an ASCII file called
runinfo that provides the needed information for having the
corresponding RTAI applications run through the "rtai-load"
script. This file is actually a template read by Autoconf's
"configure" script, where installation-dependent information is
automatically patched in, to produce the corresponding ".runinfo"
file. The "rtai-load" script will exclusively use .runinfo files to
find out the actions needed to bootstrap an application.

runinfo should list all possible execution targets for the given
example/test directory.

Each execution target appears on a single text line, contains four
specification fields separated by double-colons, and is parsed as:

target_name:module_dependencies:run_actions:init_comment

Therefore, having multiple targets in a single file is possible, like
this:

target_name1:module_dependencies_1:run_actions_1:init_comment_1
target_name2:module_dependencies_2:run_actions_2:init_comment_2
...
and so on.

o target_name is a symbolic name. The first line seen in a given file
stands for the default target.

o module_dependencies is a list defining the standard RTAI modules the
test/example depends on, and which must be loaded before the run
actions are executed. Dependencies are listed in sequential order,
from the less dependent to the most, with the "rtai_" prefix stripped
from the module name, separated by "+" signs. The HAL module needs not
be specified, since "rtai-load" automatically probes and loads it as
needed. Moreover, one should use "ksched" to specify the active RTAI
scheduler for kernel-based applications, which will cause "rtai_up.o"
or "rtai_smp.o" to be loaded, depending on the current configuration.
e.g. "myapp:ksched+fifos+math:..." will cause rtai_hal.o,
rtai_up.o/rtai_smp.o, rtai_fifos.o and rtai_math.o to be loaded.

o run_actions is a shell like list of actions to run separated by
semi-colons, executed one at a time in sequential order. Five special
verbs have a special meaning when found at the beginning of an action:

      > "push <kernel-module>", causes the given kernel module to be
        installed. <kernel-module> should be passed without ".o" or
        ".ko" extension. e.g. "push rt_process" will perform as
	"insmod rt_process.o"

      > "pop [<kernel-module-list>]", causes the given kernel modules
        to be removed. If no module list is specified, the last pushed
        module is popped. e.g. "pop rt_process" or "pop" will unload
	rt_process.o right after it has been loaded using "push".

      > "popall" or "flush", causes all modules to be recursively
	unloaded using "rmmod -r" starting from the last module
	pushed.

      > "klog", causes "tail -f /var/log/messages" to be substituted,
        so that the kernel message log is displayed in follow mode.

      > "exec" is syntactic sugar silently stripped when found from
      the beginning of the action.

All other actions are passed "as is" to a sub-shell for
interpretation. "rtai-load" will wait for each action to complete,
unless it is terminated by an ampersand symbol '&'.
e.g. "./latency &; ./display" will spawn the "latency" executable
in the background, then immediately run "display" in the foreground.

If the action is preceded by a '!' sign, "rtai-load" will attempt to
"sudo" the command.

o init_comment is a message which should be echoed to the terminal
before the actions are run by "rtai-load". The special verb
"control_c" causes a standard message inviting the user to type ^C for
exiting the application to be echoed.

The file may also contain some specific variable assignments defining
some parameters internally used by "rtai-load". As of now there is
only one of them:

o rtai_moddir=<path_to_RTAI_system_modules>

  > Causes each kernel module listed in the dependency section to be
searched into the given directory. Otherwise, it is searched in the
installation directory for modules (e.g. /usr/realtime/modules).

Example
-------

For instance, rtai-testsuite/kern/latency/runinfo specifies how to
run the kernel-based latency calibration test. It contains the
following directives:

latency:ksched+fifos:push rt_process;display;popall:control_c

This line defines the "latency" target. To run the "latency"
application, tell "rtai-load" to load the active RTAI scheduler for
kernel-based tasks and the FIFOS support module. Then, "insmod
./rt_process.o", then spawn the user-space viewer called ./display (if
none exists in the current directory, $PATH is used). The user will
have been invited to hit ^C to exit the view, and after it did, the
next action "popall" is executed, which cause "rmmod -r rt_process" to
be fired.

Calling rtai-load
-----------------

"rtai-load" is the shell script that parses the .runinfo files. It can
be used with the following syntaxes:

$ rtai-load
  => attemps to run the default target (1st one found) from the
.runinfo file found into the current directory.

OR,

$ rtai-load foo

  => attemps to run the target named "foo" from the .runinfo file
  found into the current directory.

OR,

$ rtai-load /home/bar:foo

  => attemps to run the target named "foo" from the /home/bar/.runinfo
  file; the script will change directory to the target one to make
  sure that relative paths given in .runinfo correctly refer to the
  proper files from the specified directory.

So, in its simplest and usual form, when the user is already in the
target directory and there is only one example or test, "rtai-load"
should be the only thing to run.

"rtai-load" automatically attempts to "sudo" all commands needing the
super-user privileges (e.g. insmod/rmmod or actions prefixed by a '!' 
sign) if it is found on the system.