l4/pkg/ned/doc/ned.dox

   1 // vi:ft=c
   2 /**
   3
   4 \page l4re_servers_ned Ned, the Init Process
   5
   6 Ned's job is to bootstrap the system running on L4Re.  The main thing to do
   7 here is to coordinate the startup of services and applications as well as to
   8 provide the communication channels for them.  The central facility in Ned is
   9 the Lua (http://www.lua.org) script interpreter with the L4Re and ELF-loader
  10 bindings.
  11
  12 The boot process is based on the execution of one or more Lua scripts that
  13 create communication channels (IPC gates), instantiate other L4Re objects,
  14 organize capabilities to these objects in sets, and start application processes
  15 with access to those objects (or based on those objects).
  16
  17 For starting applications, Ned depends on the services of \ref l4re_servers_moe or
  18 another \em loader, which must provide data spaces and region maps.
  19 Ned also uses the 'rom' capability as source for Lua scripts and at least
  20 the 'l4re' binary (the runtime environment core) running in each application.
  21
  22 Each application Ned starts is equipped with an L4Re::Env environment that
  23 provides information about all the initial objects made accessible to this
  24 application.
  25
  26
  27 \section l4re_ned_lua_l4re Lua Bindings for L4Re
  28
  29 Ned provides various bindings for L4Re abstractions.  These bindings are
  30 located in the 'L4' package (\c require \c "L4").
  31
  32
  33 \subsection l4re_ned_lua_caps Capabilities in Lua
  34
  35 Capabilities are handled as normal values in Lua. They can be stored in normal
  36 variables or Lua compound structures (tables).  A capability in Lua possesses
  37 additional information about the access rights that shall be transfered to
  38 other tasks when the capability is transfered. To support implementation of the
  39 Principle of Least Privilege, minimal rights are assigned by default.  Extended
  40 rights can be added using the method \c mode("...") (short \c m("...")) that
  41 returns a new reference to the capability with the given rights.
  42 \note It is generally impossible to elevate the real access rights to an
  43 object.  This means that if Ned has only restricted rights to an object it is
  44 not possible to upgrade the access rights with the \c mode method.
  45
  46 The capabilities in Lua also carry dynamic type information about the
  47 referenced objects. They thereby provide type-specific operations on the
  48 objects, such as the \c create operation on a generic factory
  49 or the \c query and \c register operations on a name space.
  50
  51
  52 \subsection l4re_ned_lua_l4re_env Access to L4Re::Env Capabilities
  53
  54 The initial objects provided to Ned itself are accessible via the table
  55 \c L4.Env.  The default (usually unnamed) capabilities are accessible
  56 as \c factory, \c log, \c mem_alloc, \c parent, \c rm, and \c scheduler in
  57 the \c L4.Env table.
  58
  59
  60 \subsection l4re_ned_lua_consts Constants
  61
  62 \b Protocols
  63
  64 The protocol constants are defined by default in the L4 package's
  65 table \c L4.Proto.  The definition is not complete and only covers
  66 what is usually needed to configure and start applications.  The protocols
  67 are for example used as first argument to the \c Factory:create method.
  68
  69 \dontinclude "ned.lua"
  70 \skipline Proto = {
  71 \until }
  72
  73 \b Debugging \b Flags
  74
  75 Debugging flags used for the applications L4Re core:
  76
  77 \dontinclude "ned.lua"
  78 \skipline Dbg = {
  79 \until }
  80
  81
  82 \b Loader \b Flags
  83
  84 Flags for configuring the loading process of an application.
  85
  86 \dontinclude "ned.lua"
  87 \skipline Ldr_flags = {
  88 \until }
  89
  90 \subsection l4re_ned_startup Application Startup Details
  91
  92 The central facility for starting a new task with Ned is
  93 the class \c L4.Loader.  This class provides interfaces for conveniently
  94 configuring and starting programs.  It provides three operations:
  95 \li \c new_channel() Returns a new IPC gate that can be used to connect
  96     two applications
  97 \li \c start() and \c startv() Start a new application process and return a
  98     process object
  99
 100 The \c new_channel() call is used to provide a service application with a
 101 communication channel to bind its initial service to.  The concrete behavior of
 102 the object and the number of IPC gates required by a server depends on the
 103 server implementation.  The channel can the be passed to client applications as
 104 well or can be used for operations within the script itself.
 105
 106 \c start() and \c startv() always require at least two arguments. The first one
 107 is a table that contains information about the initial objects an application
 108 shall get.  The second argument is a string, which for \c start() is the
 109 program name plus a white-space-separated list of program arguments (argv). For
 110 \c startv() the second argument is just the program binary name -- which may
 111 contain spaces --, and the program arguments are provided as separate string
 112 arguments following the binary name (allowing spaces in arguments, too).  The
 113 last optional argument is a table containing the POSIX environment variables
 114 for the program.
 115
 116 The Loader class uses reasonable defaults for most of the initial objects.
 117 However, you can override any initial object with some user-defined values.
 118 The main elements of the initial object table are:
 119 \li \c factory The factory used by the new process to create new kernel objects,
 120        such as threads etc.  This must be a capability to an object implementing
 121        the L4::Factory protocol and defaults to the factory object provided to
 122        Ned.
 123 \li \c mem The memory allocator provided to the application and used by Ned
 124        allocates data spaces for the process.  This defaults to Ned's
 125        memory allocator object (see L4Re::Mem_alloc).
 126 \li \c rm_fab The generic factory object used to allocate the region-map
 127        obejct for the process. (defaults to Ned's memory allocator).
 128 \li \c log_fab The generic factory to create the L4Re::Log object for the
 129        application's output (defaults to Ned's memory allocator).
 130        The \c create method of the \c log_fab object is called with
 131        \c log_tag and \c log_color, from this table, as arguments.
 132 \li \c log_tag The string used for tagging log output of this process (defaults
 133        to the program name) (see \c log_fab).
 134 \li \c log_color The color used for the log tag (defaults to "white").
 135 \li \c scheduler The scheduler object used for the process' threads (defaults
 136        to Ned's own scheduler).
 137 \li \c caps The table with application-specific named capabilities (default is
 138        an empty table).  If the table does not contain a capability with the
 139        name 'rom', the 'rom' capability from Ned's initial caps is inserted
 140        into the table.
 141
 142
 143 \todo Write more documentation for application startup via Ned
 144
 145 */