L4Re - L4 Runtime Environment
Ned, the Init Process

Ned's job is to bootstrap the system running on L4Re.

The main thing to do here is to coordinate the startup of services and applications as well as to provide the communication channels for them. The central facility in Ned is the Lua (http://www.lua.org) script interpreter with the L4Re and ELF-loader bindings.

The boot process is based on the execution of one or more Lua scripts that create communication channels (IPC gates), instantiate other L4Re objects, organize capabilities to these objects in sets, and start application processes with access to those objects (or based on those objects).

For starting applications, Ned depends on the services of Moe, the Root-Task or another loader, which must provide data spaces and region maps. Ned also uses the 'rom' capability as source for Lua scripts and at least the 'l4re' binary (the runtime environment core) running in each application.

Each application Ned starts is equipped with an L4Re::Env environment that provides information about all the initial objects made accessible to this application.

Lua Bindings for L4Re

Ned provides various bindings for L4Re abstractions. These bindings are located in the 'L4' package (require "L4").

Capabilities in Lua

Capabilities are handled as normal values in Lua. They can be stored in normal variables or Lua compound structures (tables). A capability in Lua possesses additional information about the access rights that shall be transfered to other tasks when the capability is transfered. To support implementation of the Principle of Least Privilege, minimal rights are assigned by default. Extended rights can be added using the method mode("...") (short m("...")) that returns a new reference to the capability with the given rights.

Note
It is generally impossible to elevate the real access rights to an object. This means that if Ned has only restricted rights to an object it is not possible to upgrade the access rights with the mode method.

The capabilities in Lua also carry dynamic type information about the referenced objects. They thereby provide type-specific operations on the objects, such as the create operation on a generic factory or the query and register operations on a name space.

Access to L4Re::Env Capabilities

The initial objects provided to Ned itself are accessible via the table L4.Env. The default (usually unnamed) capabilities are accessible as factory, log, mem_alloc, parent, rm, and scheduler in the L4.Env table.

Constants

Protocols

The protocol constants are defined by default in the L4 package's table L4.Proto. The definition is not complete and only covers what is usually needed to configure and start applications. The protocols are for example used as first argument to the Factory:create method.

Proto = {
Dataspace = 0x4000,
Namespace = 0x4001,
Goos = 0x4003,
Mem_alloc = 0x4004,
Rm = 0x4005,
Event = 0x4006,
Inhibitor = 0x4007,
Sigma0 = -6,
Log = -13,
Scheduler = -14,
Factory = -15,
Vm = -16,
Dma_space = -17,
Irq_sender = -18,
Irq_muxer = -19,
Semaphore = -20,
Iommu = -22,
Ipc_gate = 0,
}

Debugging Flags

Debugging flags used for the applications L4Re core:

Dbg = {
Info = 1,
Warn = 2,
Boot = 4,
Server = 0x10,
Exceptions = 0x20,
Cmd_line = 0x40,
Loader = 0x80,
Name_space = 0x400,
All = 0xffffffff,
}

Loader Flags

Flags for configuring the loading process of an application.

Ldr_flags = {
eager_map = 0x1, -- L4RE_AUX_LDR_FLAG_EAGER_MAP
all_segs_cow = 0x2, -- L4RE_AUX_LDR_FLAG_ALL_SEGS_COW
pinned_segs = 0x4, -- L4RE_AUX_LDR_FLAG_PINNED_SEGS
}

Application Startup Details

The central facility for starting a new task with Ned is the class L4.Loader. This class provides interfaces for conveniently configuring and starting programs. It provides three operations:

  • new_channel() Returns a new IPC gate that can be used to connect two applications
  • start() and startv() Start a new application process and return a process object

The new_channel() call is used to provide a service application with a communication channel to bind its initial service to. The concrete behavior of the object and the number of IPC gates required by a server depends on the server implementation. The channel can the be passed to client applications as well or can be used for operations within the script itself.

start() and startv() always require at least two arguments. The first one is a table that contains information about the initial objects an application shall get. The second argument is a string, which for start() is the program name plus a white-space-separated list of program arguments (argv). For startv() the second argument is just the program binary name – which may contain spaces –, and the program arguments are provided as separate string arguments following the binary name (allowing spaces in arguments, too). The last optional argument is a table containing the POSIX environment variables for the program.

The Loader class uses reasonable defaults for most of the initial objects. However, you can override any initial object with some user-defined values. The main elements of the initial object table are:

  • factory The factory used by the new process to create new kernel objects, such as threads etc. This must be a capability to an object implementing the L4::Factory protocol and defaults to the factory object provided to Ned.
  • mem The memory allocator provided to the application and used by Ned allocates data spaces for the process. This defaults to Ned's memory allocator object (see L4Re::Mem_alloc).
  • rm_fab The generic factory object used to allocate the region-map object for the process. (defaults to Ned's memory allocator).
  • log_fab The generic factory to create the L4Re::Log object for the application's output (defaults to Ned's memory allocator). The create method of the log_fab object is called with log_tag and log_color, from this table, as arguments.
  • log_tag The string used for tagging log output of this process (defaults to the program name) (see log_fab).
  • log_color The color used for the log tag (defaults to "white").
  • scheduler The scheduler object used for the process' threads (defaults to Ned's own scheduler).
  • caps The table with application-specific named capabilities (default is an empty table). If the table does not contain a capability with the name 'rom', the 'rom' capability from Ned's initial caps is inserted into the table.

Command Line Options

Ned's command line syntax is:

[--interactive|-i] [--cmdcap|-c CAP] [--noexit] [--execute|-e STATEMENT] <lua script> [options passed to lua script]

Ned interprets the first non-option argument <lua script> as the Lua script which it should load and run. All arguments following the first non-option argument are passed as arguments to the Lua script via Lua's global arg table.

  • Interactive Option: interactive, i

    Start ned in interactive mode. After running the initial lua script, ned will present a prompt, where Lua statements can be typed in interactively.

    Must not be used together with server mode (-c).

  • Command Capability Option: cmdcap, c

    Start ned in server mode. After running the initial Lua script, ned will accept Lua statements via IPC on the given capability (see L4Re::Ned::Cmd_control).

    Must not be used together with interactive mode (-i).

  • No exit Option: noexit

    Ned does not terminate if only Return is entered at ned's prompt.

  • Execute Statement Option: execute, e

    Execute the Lua statement STATEMENT.