Provided by: xenomai-runtime_2.5.5.2-1ubuntu2_i386 bug

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)