// vi:ft=c
/**

\page l4re_servers_ned 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 \ref l4re_servers_moe or
another \em 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.


\section l4re_ned_lua_l4re Lua Bindings for L4Re

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


\subsection l4re_ned_lua_tutorial Tutorial

For a verbose example using the Ned Lua bindings, see tutorial.lua.


\subsection l4re_ned_lua_caps 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 \c mode("...") (short \c 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 \c 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 \c create operation on a generic factory
or the \c query and \c register operations on a name space.


\subsection l4re_ned_lua_l4re_env Access to L4Re::Env Capabilities

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


\subsection l4re_ned_lua_consts Constants

\b Protocols

The protocol constants are defined by default in the L4 package's
table \c 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 \c Factory:create method.

\dontinclude "ned.lua"
\skipline Proto = {
\until }

\b Rights

The rights of a Lua capability can be defined in two ways via the `:mode()`
interface. Either via a string representation of the rights or via an integer
value.
An example for the former is `:mode("rsnc")` while the latter equivalent is
`:mode(L4.Rights.r | L4.Rights.s | L4.Rights.n | L4.Rights.c)`.
The following listing shows the integer constants. The constant names can be
used in the string parameter to `:mode()`.

\dontinclude "ned.lua"
\skipline Rights = {
\until }

\b Debugging \b Flags

Debugging flags used for the applications L4Re core:

\dontinclude "ned.lua"
\skipline Dbg = {
\until }


\b Loader \b Flags

Flags for configuring the loading process of an application.

\dontinclude "ned.lua"
\skipline Ldr_flags = {
\until }

\subsection l4re_ned_startup Application Startup Details

The central facility for starting a new task with Ned is
the class \c L4.Loader.  This class provides interfaces for conveniently
configuring and starting programs.  It provides three operations:
\li \c new_channel() Returns a new IPC gate that can be used to connect
    two applications
\li \c start() and \c startv() Start a new application process and return a
    process object

The \c 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.

\c start() and \c 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 \c start() is the
program name plus a white-space-separated list of program arguments (argv). For
\c 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:
\li \c 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.
\li \c 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).
\li \c rm_fab The generic factory object used to allocate the region-map
       object for the process. (defaults to Ned's memory allocator).
\li \c log_fab The generic factory to create the L4Re::Log object for the
       application's output (defaults to Ned's memory allocator).
       The \c create method of the \c log_fab object is called with
       \c log_tag and \c log_color, from this table, as arguments.
\li \c log A table with parameters passed to the \c log_fab:
       <ul>
       <li>The first item is a short string defining the tag used for tagging
           log output of this process (defaults to the program name).</li>
       <li>The second item is a string defining the color used for the log tag
           and the log string (defaults to "white").</li>
       <li>Further parameters might be evaluated by certain implementations of
           the L4Re::Log interface.</li>
       </ul>
\li \c scheduler The scheduler object used for the process' threads (defaults
       to Ned's own scheduler).
\li \c 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.

Less frequently used parameters:
\li \c l4re_dbg An integer value overriding the debug level of the ITAS used for
       this application. Default is 2 (Warn). See _Debugging Flags_ above.
\li \c ldr_flags An integer value for setting additional flags for attaching
       regions, see _Loader Flags_ above.

The \c start() and \c startv() calls return a task object that supports a
number of operations.
\li \c state() returns a string with the current task state: "running" or
    "zombie" if the task has terminated. If the task was alreay reaped (
    \c wait() returned) or if \c kill() was called, then the function will
    return \c nil.
\li \c exit_code() returns the exit code if the task has terminated or \c nil
    if it was either killed or has been reaped.
\li \c kill() forcefully terminates the task. Returns "killed" if the task was
    terminated or the exit code if the task was already gone. Returns \c nil
    if the task was already reaped.
\li \c exit_handler(function) registers a Lua function that is invoked when the
    task terminates. If the task has already terminated, the function is called
    immediately. Returns \c true if the callback is pending, otherwise \c
    false. The callback function gets the exit code (\c nil if killed) of the
    task as its only parameter. The return value of the function is ignored.
    Only one callback can be registered.
\li \c wait() suspends execution until the task has terminated. It's better
    to use \c exit_handler() instead. While the Lua code executes \c wait(),
    no \c exit_handler() will be dispatched.

\subsection l4re_ned_exit_handler Reacting on task termination

Ned can react on the termination of child tasks. The preferred mechanism is
to register an \c exit_handler() for a task:

\code{.lua}
task = L4.default_loader:start(...)
task:exit_handler(function(exit_code)
  if exit_code == nil then
    print("Task was killed")
  else
    print("Task has terminated w/ code [" .. exit_code .. "]")
  end
end)
\endcode

If the task did already terminate then the callback is invoked immediately. It
is also possible to suspend execution of the Ned script until a task has
terminated:

\code{.lua}
task = L4.default_loader:start(...)
task:wait()
\endcode

This method should be used with caution, though. The Ned script will wait until
the child task has terminated. Neither will any of the registered \c
exit_handler() will be called during this time, nor will the \ref
l4re_ned_interactive "remote command interface" be able to execute commands
either.

\subsection l4re_ned_sched Control scheduling

Scheduling of L4Re applications is controlled by creating scheduler proxies.
The proxy restricts the threads of an application to run on a subset of the
available CPUs and to set their minimum and maximum priority. Use the loader
factory function to create the proxy and pass it to the application:

\code{.lua}
sched_proxy = L4.default_loader:create_sched_proxy{ cpus=L4.Cpu_set:new("0-3") }
L4.default_loader:start({ scheduler = sched_proxy }, ...)
\endcode

The `create_sched_proxy` function takes the following table arguments. All
arguments are optional:

* `cpus`: Set of allowed CPUs. Default: all CPUs.
* `prio_offset`: Base priority of all threads. Default: `0`.
* `prio_limit`: Maximum priority of all threads. Default `priority + 10`.
* `fab`: Scheduler proxy factory capability. Default: loader `sched_fab`.

The `Cpu_set` constructor takes any number of CPU numbers or ranges:

\code{.lua}
Cpu_set:new()          -- all CPUs (because no argument was passed)
Cpu_set:new{}          -- empty CPU set (because an empty table was passed)
Cpu_set:new(42)        -- single CPU: 42
Cpu_set:new("0-3")     -- 4 CPUs: 0..3
Cpu_set:new{"0-3", 42} -- 5 CPUs: 0..3, 42
\endcode

A limited number of operations are defined on CPU sets. To compute the union
of two sets (all CPUs of both sets), use the `|` operator. To compute the
intersection of two sets (all CPUs common to both sets), use the `&` operator.

\subsection l4re_ned_jdb Access to the kernel debugger

Applications can enrich the kernel debugger with information using the API
defined in \ref l4/sys/debugger. In order to do so, the developer has to
assign access to the kernel debugger kernel object to the application. This
can be done like this:

\code{.lua}
 L4.default_loader:start({ caps = { jdb = L4.Env.jdb; }}, "rom/example")
\endcode

\todo Write more documentation for application startup via Ned

\subsection l4re_ned_interactive Using the interactive ned prompt

Ned can be used in interactive mode by connecting the small ned-prompt helper
tool to the command capability. Add the following code snippet at the end of
your ned script:

\code{.lua}
local L4 = require("L4");
local l = L4.default_loader;

cmd = l:new_channel()

l:start({ log = L4.Env.log, caps = { svr = cmd} }, "rom/ned-prompt")

L4.server_loop(cmd)
\endcode

The script hands in ned's own log capability to `ned-prompt`. This ensures that
input and output of ned and the prompt appear on the same console.

`ned-prompt` needs to be added to your modules list.

\section l4re_ned_options Command Line Options

Ned's command line syntax is:

    [--exit|--wait-and-exit] [--disable-backtracer-autoload] [--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.

- Exit Options: **exit**, **wait-and-exit** (must be first if used)

  - **exit**: terminates the application after the script has run through even
              if there are still tasks running. `wait` for tasks at the end of
              the script to ensure they do not die forcefully.

  - **exit-and-wait**: terminates the application after the script has run
              through and all tasks started by ned have signaled their exit.

- Execute Statement Option: **execute**, **e**

  Execute the Lua statement `STATEMENT`.

- **disable-backtracer-autoload**: Do not load the backtracer automatically.
*/
