l4/pkg/ned/doc/tutorial.lua

   1 local _doc = [==[
   2
   3 Tutorial lua script for Ned
   4 ===========================
   5
   6 Firstly we have a set of definitions available. Some come from 'ned.lua'
   7 and others from the C++ bindings within Ned. The whole L4 stuff is in the
   8 lua module "L4" (use require("L4")).
   9 The L4 module classes and functions to cope with L4 capabilities and
  10 their invocation.  A set of constants and access to the L4Re environment of
  11 the running program.  And a set of classes to start L4 applications and
  12 composing their name spaces.
  13
  14 L4 Capabilities
  15 ===============
  16
  17 The L4 module defines a user data type for capabilities.  A capability in lua
  18 carries a typed L4 capability and is accompanied with a set of type specific
  19 methods that may be called on the object behind the capability.  There also
  20 exists a way to cast a capability to a capability to a different type of
  21 object using L4.cast(type, cap).
  22
  23 L4.cast(type, cap)
  24
  25 Returns a cap transformed to a capability of the given type, whereas type
  26 is either the fully qualified C++ name of the class encapsulating the object
  27 or the L4 protocol ID assigned to all L4Re and L4 system objects.
  28 If the type is unknown than nil is returned.
  29
  30 Generic capabilities provide the methods:
  31
  32 is_valid()
  33
  34   Returns true if the capability is not the invalid cap (L4_INVALID_CAP), and
  35   false if it is the invalid cap.
  36
  37
  38 L4Re::Namespace object
  39 ======================
  40
  41 There is a lua type for name spaces that has the following methods:
  42
  43 query(name), or q(name)
  44
  45   Returns a closure (function) that initiates a query for the given name
  46   within the name space.  The function takes no arguments and returns
  47   a capability if successful or nil if name is not found.
  48
  49
  50 link(name), or l(name)
  51
  52   Returns a function that can create a link to the given object in the name
  53   space if put into another name space. The function takes two parameters
  54   the target name space and the name in the target name space.
  55   Loader:create_namespace and Loader.fill_namespace calls this function
  56   when things are really put into an L4Re::Namespace.
  57
  58
  59 register(name, cap), or r(name, cap)
  60
  61   Registers the given object capability under the given name. cap can
  62   be either a real capability (note query returns a function), a string, or
  63   nil.  If it is a capability it is just put into the name space.
  64   In the case cap is a string a placeholder will be put into the name space
  65   that will be replaced with a real capability later by some program.
  66   And if nil is use the name will be deleted from the name space.
  67
  68
  69 L4::Factory object
  70 ==================
  71
  72 The factory object provides an interface to the generic create method of a
  73 factory.
  74
  75 create(proto, ...)
  76
  77   This method calls the factory to create an object of the given type,
  78   via the L4 protocol number (see L4.Proto table for more) all further
  79   arguments are passed to the factory.
  80
  81
  82 Access to the L4Re Env capabilities
  83 ===================================
  84
  85 The L4 module defines a table L4.Env that contains the capabilities
  86 of the L4Re::Env::env() environment. Namely:
  87
  88 factory   The kernel factory of Ned
  89 log       The log object of Ned
  90 mem_alloc The memory allocator provided to Ned
  91 parent    The parent of Ned
  92 rm        The region map of Ned
  93 scheduler The scheduler of Ned
  94
  95
  96 Some useful constants
  97 =====================
  98
  99 L4.Proto table contains the most important protocol values for
 100 L4 and L4Re objects.
 101
 102   Namespace
 103   Goos
 104   Mem_alloc
 105   Rm
 106   Irq
 107   Sigma0
 108   Factory
 109   Log
 110   Scheduler
 111
 112
 113 Support for starting L4 programs
 114 ================================
 115
 116 The L4 module defines two classes that are useful for starting l4 applications.
 117 The class L4.Loader that encapsulates a fairly high level policy for
 118 that is useful for starting a whole set of processes. And the class L4.App_env
 119 that encapsulates a more fine-grained policy.
 120
 121 L4.Loader
 122 ---------
 123
 124 The class L4.Loader encapsulates the policy for starting programs with the
 125 basic building blocks for the application comming from a dedicated loader,
 126 such as Moe or a Loader instance.  These building blocks are a region map (Rm),
 127 a name space, a scheduler, a memory allocator, and a logging facility.
 128 A L4.Loader object is typically used to start multiple applications. There
 129 is a L4.default_loader instance of L4.Loader that uses the L4.Env.mem_alloc
 130 factory of the current Ned instance to create the objects for a new program.
 131 However you may also use a more restricted factory for applications and
 132 instanciate a loader for them.  The L4.Loader objects can already be used
 133 to start a program with L4.Loader:start(app_spec, cmd, ...).  Where app_spec
 134 is a table containing some parameters for the new application. cmd is the
 135 command to run and the remaining arguments are the command-line options for
 136 the application.
 137
 138 ]==]
 139
 140 L4.default_loader:start({}, "rom/hello");
 141
 142 local _doc = [==[
 143
 144 This statement does the following:
 145  1. create a new name space for the application
 146  2. put L4.Env.names:query("rom") into the new name space (thus shares Ned's
 147     'rom' directory with the new program.
 148  3. Creates all the building blocks for the new process and starts the
 149     'l4re' support kernel in the new process which in turn start's 'rom/hello'
 150     in the new process.
 151
 152 Using the app_spec parameter you can modify the behavior in two ways. There are
 153 two supported options 'ns' for providing a more usefull non-empty name space
 154 for the application. And 'log' for modifying the logger tag and color.
 155
 156 ]==]
 157
 158 local my_ns = {
 159   fb = L4.Env.names:query("vesa");
 160 };
 161
 162 L4.default_loader:start({ns = my_ns, log = {"APP", "blue"}}, "rom/hello");
 163
 164 local _doc = [==[
 165
 166 This snippet creates a name-space template (my_ns) and uses it for the
 167 new process and also sets user-defined log tags.  The L4.Loader:start method,
 168 however, automatically adds the 'rom' directory to the name space if not
 169 already specified in the template.
 170
 171 To use create a new L4.Loader instance you may use a generic factory for all
 172 building blocks or set individual factories.
 173
 174 ]==]
 175
 176 l = L4.Loader.new({mem = L4.Env.mem_alloc:create(L4.Proto.Factory, 512*1024)})
 177
 178 local _doc = [==[
 179
 180 Creates a loader instance that uses the newly created 512 Kbyte factory for
 181 all building blocks. To set individual factories use the options:
 182   'mem'       as memory allocator for the new processes and as
 183               default factory for all objects not explicitely set to a
 184               different factory
 185   'log_fab'   for creating log objects.
 186   'ns_fab'    for creating name-space objects.
 187   'rm_fab'    for creating region-map objects.
 188   'sched_fab' for creating scheduler objects.
 189
 190
 191
 192 L4.App_env
 193 ----------
 194
 195 L4.App_env provides a more fine-grained control for a single process or for a
 196 limited number of processes. L4.App_env uses an L4.Loader object as basic
 197 facility. However you can override the memory allocator 'mem' for for the new
 198 process as well as the kernel factory 'factory', the log capability etc.
 199
 200 ]==]
 201
 202 local e = L4.App_env.new({
 203   loader = l,
 204   mem = L4.Env.mem_alloc:create(L4.Proto.Factory, 128*1024)
 205 });
 206
 207 e:start("rom/hello");
 208
 209 local _doc = [==[
 210
 211 More to come....
 212
 213 ]==]