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.