Files
moslab-code/doc/source/html/l4re_servers_ned.html
2025-09-12 15:55:45 +02:00

289 lines
23 KiB
HTML

<!-- HTML header for doxygen 1.9.1-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.15.0"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>L4Re Operating System Framework: Ned, the Init Process</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript" src="cookie.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="doxygen-awesome.css" rel="stylesheet" type="text/css"/>
<link href="l4re-awesome.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectlogo"><img alt="Logo" src="L4Re_rgb_logo_quer_hg_h55.png"/></td>
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">L4Re Operating System Framework
</div>
<div id="projectbrief">Interface and Usage Documentation</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.15.0 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search/",'.html');
</script>
<script type="text/javascript">
$(function() { codefold.init(); });
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
initMenu('',true,false,'search.php','Search',true);
$(function() { init_search(); });
});
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
$(function(){initNavTree('l4re_servers_ned.html','',''); });
</script>
<div id="container">
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<div id="MSearchResults">
<div class="SRPage">
<div id="SRIndex">
<div id="SRResults"></div>
<div class="SRStatus" id="Loading">Loading...</div>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
</div>
</div>
</div>
</div>
<div><div class="header">
<div class="headertitle"><div class="title">Ned, the Init Process </div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>Ned's job is to bootstrap the system running on <a class="el" href="namespaceL4Re.html" title="L4Re C++ Interfaces.">L4Re</a>. 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 (<a href="http://www.lua.org">http://www.lua.org</a>) script interpreter with the <a class="el" href="namespaceL4Re.html" title="L4Re C++ Interfaces.">L4Re</a> and ELF-loader bindings.</p>
<p>The boot process is based on the execution of one or more Lua scripts that create communication channels (IPC gates), instantiate other <a class="el" href="namespaceL4Re.html" title="L4Re C++ Interfaces.">L4Re</a> objects, organize capabilities to these objects in sets, and start application processes with access to those objects (or based on those objects).</p>
<p>For starting applications, Ned depends on the services of <a class="el" href="l4re_servers_moe.html">Moe, the Root-Task</a> or another <em>loader</em>, 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.</p>
<p>Each application Ned starts is equipped with an <a class="el" href="classL4Re_1_1Env.html" title="C++ interface of the initial environment that is provided to an L4 task.">L4Re::Env</a> environment that provides information about all the initial objects made accessible to this application.</p>
<h1 class="doxsection"><a class="anchor" id="l4re_ned_lua_l4re"></a>
Lua Bindings for L4Re</h1>
<p>Ned provides various bindings for <a class="el" href="namespaceL4Re.html" title="L4Re C++ Interfaces.">L4Re</a> abstractions. These bindings are located in the '<a class="el" href="namespaceL4.html" title="L4 low-level kernel interface.">L4</a>' package (<code>require</code> <code>"L4"</code>).</p>
<h2 class="doxsection"><a class="anchor" id="l4re_ned_lua_tutorial"></a>
Tutorial</h2>
<p>For a verbose example using the Ned Lua bindings, see <a class="el" href="tutorial_8lua_source.html">tutorial.lua</a>.</p>
<h2 class="doxsection"><a class="anchor" id="l4re_ned_lua_caps"></a>
Capabilities in Lua</h2>
<p>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 <code>mode</code>("...") (short <code>m</code>("...")) that returns a new reference to the capability with the given rights. </p><dl class="section note"><dt>Note</dt><dd>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 <code>mode</code> method.</dd></dl>
<p>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 <code>create</code> operation on a generic factory or the <code>query</code> and <code>register</code> operations on a name space.</p>
<h2 class="doxsection"><a class="anchor" id="l4re_ned_lua_l4re_env"></a>
Access to L4Re::Env Capabilities</h2>
<p>The initial objects provided to Ned itself are accessible via the table <code>L4.Env</code>. The default (usually unnamed) capabilities are accessible as <code>factory</code>, <code>log</code>, <code>mem_alloc</code>, <code>parent</code>, <code>rm</code>, and <code>scheduler</code> in the <code>L4.Env</code> table.</p>
<h2 class="doxsection"><a class="anchor" id="l4re_ned_lua_consts"></a>
Constants</h2>
<p><b>Protocols</b> </p>
<p>The protocol constants are defined by default in the <a class="el" href="namespaceL4.html" title="L4 low-level kernel interface.">L4</a> package's table <code>L4.Proto</code>. 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 <code>Factory:create</code> method.</p>
<div class="fragment"><div class="line">Proto = {</div>
<div class="line"> Dataspace = 0x4000,</div>
<div class="line"> Namespace = 0x4001,</div>
<div class="line"> Goos = 0x4003,</div>
<div class="line"> Mem_alloc = 0x4004,</div>
<div class="line"> Rm = 0x4005,</div>
<div class="line"> Event = 0x4006,</div>
<div class="line"> Inhibitor = 0x4007,</div>
<div class="line"> Sigma0 = -6,</div>
<div class="line"> Log = -13,</div>
<div class="line"> Scheduler = -14,</div>
<div class="line"> Factory = -15,</div>
<div class="line"> Vm = -16,</div>
<div class="line"> Dma_space = -17,</div>
<div class="line"> Irq_sender = -18,</div>
<div class="line"> Semaphore = -20,</div>
<div class="line"> Iommu = -22,</div>
<div class="line"> Ipc_gate = 0,</div>
<div class="line">}</div>
</div><!-- fragment --><p> <b>Rights</b> </p>
<p>The rights of a Lua capability can be defined in two ways via the <span class="tt">:mode()</span> interface. Either via a string representation of the rights or via an integer value. An example for the former is <span class="tt">:mode("rsnc")</span> while the latter equivalent is <span class="tt">:mode(L4.Rights.r | L4.Rights.s | L4.Rights.n | L4.Rights.c)</span>. The following listing shows the integer constants. The constant names can be used in the string parameter to <span class="tt">:mode()</span>.</p>
<div class="fragment"><div class="line">Rights = {</div>
<div class="line"> s = 2,</div>
<div class="line"> w = 1,</div>
<div class="line"> r = 4,</div>
<div class="line"> d = 8,</div>
<div class="line"> n = 16,</div>
<div class="line"> c = 32,</div>
<div class="line"> ro = 4,</div>
<div class="line"> rw = 5,</div>
<div class="line"> rws = 7,</div>
<div class="line">}</div>
</div><!-- fragment --><p> <b>Debugging</b> <b>Flags</b> </p>
<p>Debugging flags used for the applications <a class="el" href="namespaceL4Re.html" title="L4Re C++ Interfaces.">L4Re</a> core:</p>
<div class="fragment"><div class="line">Dbg = {</div>
<div class="line"> Info = 1,</div>
<div class="line"> Warn = 2,</div>
<div class="line"> Boot = 4,</div>
<div class="line"> Server = 0x10,</div>
<div class="line"> Exceptions = 0x20,</div>
<div class="line"> Cmd_line = 0x40,</div>
<div class="line"> Loader = 0x80,</div>
<div class="line"> Name_space = 0x400,</div>
<div class="line"> All = 0xffffffff,</div>
<div class="line">}</div>
</div><!-- fragment --><p><b>Loader</b> <b>Flags</b> </p>
<p>Flags for configuring the loading process of an application.</p>
<div class="fragment"><div class="line">Ldr_flags = {</div>
<div class="line"> eager_map = 0x1, -- L4RE_AUX_LDR_FLAG_EAGER_MAP</div>
<div class="line"> all_segs_cow = 0x2, -- L4RE_AUX_LDR_FLAG_ALL_SEGS_COW</div>
<div class="line"> pinned_segs = 0x4, -- L4RE_AUX_LDR_FLAG_PINNED_SEGS</div>
<div class="line">}</div>
</div><!-- fragment --> <h2 class="doxsection"><a class="anchor" id="l4re_ned_startup"></a>
Application Startup Details</h2>
<p>The central facility for starting a new task with Ned is the class <code>L4.Loader</code>. This class provides interfaces for conveniently configuring and starting programs. It provides three operations: </p><ul>
<li><code>new_channel()</code> Returns a new IPC gate that can be used to connect two applications </li>
<li><code>start()</code> and <code>startv()</code> Start a new application process and return a process object</li>
</ul>
<p>The <code>new_channel()</code> 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.</p>
<p><code>start()</code> and <code>startv()</code> 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 <code>start()</code> is the program name plus a white-space-separated list of program arguments (argv). For <code>startv()</code> the second argument is just the program binary name &ndash; which may contain spaces &ndash;, 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.</p>
<p>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: </p><ul>
<li><code>factory</code> 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 <a class="el" href="classL4_1_1Factory.html" title="C++ Factory interface, see Factory for the C interface.">L4::Factory</a> protocol and defaults to the factory object provided to Ned. </li>
<li><code>mem</code> 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 <a class="el" href="classL4Re_1_1Mem__alloc.html" title="Memory allocation interface.">L4Re::Mem_alloc</a>). </li>
<li><code>rm_fab</code> The generic factory object used to allocate the region-map object for the process. (defaults to Ned's memory allocator). </li>
<li><code>log_fab</code> The generic factory to create the <a class="el" href="classL4Re_1_1Log.html" title="Log interface class.">L4Re::Log</a> object for the application's output (defaults to Ned's memory allocator). The <code>create</code> method of the <code>log_fab</code> object is called with <code>log_tag</code> and <code>log_color</code>, from this table, as arguments. </li>
<li><code>log</code> A table with parameters passed to the <code>log_fab:</code> <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 <a class="el" href="classL4Re_1_1Log.html" title="Log interface class.">L4Re::Log</a> interface. </li>
</ul>
</li>
<li><code>scheduler</code> The scheduler object used for the process' threads (defaults to Ned's own scheduler). </li>
<li><code>caps</code> 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.</li>
</ul>
<p>Less frequently used parameters: </p><ul>
<li><code>l4re_dbg</code> An integer value overriding the debug level of the ITAS used for this application. Default is 2 (Warn). See <em>Debugging Flags</em> above. </li>
<li><code>ldr_flags</code> An integer value for setting additional flags for attaching regions, see <em>Loader Flags</em> above.</li>
</ul>
<p>The <code>start()</code> and <code>startv()</code> calls return a task object that supports a number of operations. </p><ul>
<li><code>state()</code> returns a string with the current task state: "running" or "zombie" if the task has terminated. If the task was alreay reaped ( <code>wait()</code> returned) or if <code>kill()</code> was called, then the function will return <code>nil</code>. </li>
<li><code>exit_code()</code> returns the exit code if the task has terminated or <code>nil</code> if it was either killed or has been reaped. </li>
<li><code>kill()</code> forcefully terminates the task. Returns "killed" if the task was terminated or the exit code if the task was already gone. Returns <code>nil</code> if the task was already reaped. </li>
<li><code>exit_handler(function)</code> registers a Lua function that is invoked when the task terminates. If the task has already terminated, the function is called immediately. Returns <code>true</code> if the callback is pending, otherwise <code>false</code>. The callback function gets the exit code (<code>nil</code> if killed) of the task as its only parameter. The return value of the function is ignored. Only one callback can be registered. </li>
<li><code>wait()</code> suspends execution until the task has terminated. It's better to use <code>exit_handler()</code> instead. While the Lua code executes <code>wait()</code>, no <code>exit_handler()</code> will be dispatched.</li>
</ul>
<h2 class="doxsection"><a class="anchor" id="l4re_ned_exit_handler"></a>
Reacting on task termination</h2>
<p>Ned can react on the termination of child tasks. The preferred mechanism is to register an <code>exit_handler()</code> for a task:</p>
<div class="fragment"><div class="line">task = L4.default_loader:start(...)</div>
<div class="line">task:exit_handler(function(exit_code)</div>
<div class="line"> if exit_code == nil then</div>
<div class="line"> print(&quot;Task was killed&quot;)</div>
<div class="line"> else</div>
<div class="line"> print(&quot;Task has terminated w/ code [&quot; .. exit_code .. &quot;]&quot;)</div>
<div class="line"> end</div>
<div class="line">end)</div>
</div><!-- fragment --><p>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:</p>
<div class="fragment"><div class="line">task = L4.default_loader:start(...)</div>
<div class="line">task:wait()</div>
</div><!-- fragment --><p>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 <code>exit_handler()</code> will be called during this time, nor will the <a class="el" href="#l4re_ned_interactive">remote command interface</a> be able to execute commands either.</p>
<h2 class="doxsection"><a class="anchor" id="l4re_ned_sched"></a>
Control scheduling</h2>
<p>Scheduling of <a class="el" href="namespaceL4Re.html" title="L4Re C++ Interfaces.">L4Re</a> 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:</p>
<div class="fragment"><div class="line">sched_proxy = L4.default_loader:create_sched_proxy{ cpus=L4.Cpu_set:new(&quot;0-3&quot;) }</div>
<div class="line">L4.default_loader:start({ scheduler = sched_proxy }, ...)</div>
</div><!-- fragment --><p>The <span class="tt">create_sched_proxy</span> function takes the following table arguments. All arguments are optional:</p>
<p><span class="tt">cpus</span>: Set of allowed CPUs. Default: all CPUs. <span class="tt">prio_offset</span>: Base priority of all threads. Default: <span class="tt">0</span>. <span class="tt">prio_limit</span>: Maximum priority of all threads. Default <span class="tt">priority + 10</span>. <span class="tt">fab</span>: Scheduler proxy factory capability. Default: loader <span class="tt">sched_fab</span>.</p>
<p>The <span class="tt">Cpu_set</span> constructor takes any number of CPU numbers or ranges:</p>
<div class="fragment"><div class="line">Cpu_set:new() -- all CPUs (because no argument was passed)</div>
<div class="line">Cpu_set:new{} -- empty CPU set (because an empty table was passed)</div>
<div class="line">Cpu_set:new(42) -- single CPU: 42</div>
<div class="line">Cpu_set:new(&quot;0-3&quot;) -- 4 CPUs: 0..3</div>
<div class="line">Cpu_set:new{&quot;0-3&quot;, 42} -- 5 CPUs: 0..3, 42</div>
</div><!-- fragment --><p>A limited number of operations are defined on CPU sets. To compute the union of two sets (all CPUs of both sets), use the <span class="tt">|</span> operator. To compute the intersection of two sets (all CPUs common to both sets), use the <span class="tt">&amp;</span> operator.</p>
<h2 class="doxsection"><a class="anchor" id="l4re_ned_jdb"></a>
Access to the kernel debugger</h2>
<p>Applications can enrich the kernel debugger with information using the API defined in <a class="el" href="debugger.html">l4/sys/debugger</a>. 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:</p>
<div class="fragment"><div class="line">L4.default_loader:start({ caps = { jdb = L4.Env.jdb; }}, &quot;rom/example&quot;)</div>
</div><!-- fragment --><h2 class="doxsection"><a class="anchor" id="l4re_ned_interactive"></a>
Using the interactive ned prompt</h2>
<p>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:</p>
<div class="fragment"><div class="line">local L4 = require(&quot;L4&quot;);</div>
<div class="line">local l = L4.default_loader;</div>
<div class="line"> </div>
<div class="line">cmd = l:new_channel()</div>
<div class="line"> </div>
<div class="line">l:start({ log = L4.Env.log, caps = { svr = cmd} }, &quot;rom/ned-prompt&quot;)</div>
<div class="line"> </div>
<div class="line">L4.server_loop(cmd)</div>
</div><!-- fragment --><p>The script hands in ned's own log capability to <span class="tt">ned-prompt</span>. This ensures that input and output of ned and the prompt appear on the same console.</p>
<p><span class="tt">ned-prompt</span> needs to be added to your modules list.</p>
<h1 class="doxsection"><a class="anchor" id="l4re_ned_options"></a>
Command Line Options</h1>
<p>Ned's command line syntax is: </p><pre class="fragment">[--exit|--wait-and-exit] [--disable-backtracer-autoload] [--execute|-e STATEMENT] &lt;lua script&gt; [options passed to lua script]
</pre><p>Ned interprets the first non-option argument <span class="tt">&lt;lua script&gt;</span> 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 <span class="tt">arg</span> table.</p>
<ul>
<li>Exit Options: <b>exit</b>, <b>wait-and-exit</b> (must be first if used)<ul>
<li><b>exit</b>: terminates the application after the script has run through even if there are still tasks running. <span class="tt">wait</span> for tasks at the end of the script to ensure they do not die forcefully.</li>
<li><b>exit-and-wait</b>: terminates the application after the script has run through and all tasks started by ned have signaled their exit.</li>
</ul>
</li>
<li><p class="startli">Execute Statement Option: <b>execute</b>, <b>e</b></p>
<p class="startli">Execute the Lua statement <span class="tt">STATEMENT</span>.</p>
</li>
<li><b>disable-backtracer-autoload</b>: Do not load the backtracer automatically. </li>
</ul>
</div></div><!-- contents -->
</div><!-- PageDoc -->
</div><!-- doc-content -->
<div id="page-nav" class="page-nav-panel">
<div id="page-nav-resize-handle"></div>
<div id="page-nav-tree">
<div id="page-nav-contents">
</div><!-- page-nav-contents -->
</div><!-- page-nav-tree -->
</div><!-- page-nav -->
</div><!-- container -->
<!-- HTML footer for doxygen 1.9.1-->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="navelem"><a href="l4re_servers.html">L4Re Servers</a></li>
<li class="footer">Generated on <span class="timestamp"></span> for L4Re Operating System Framework by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.15.0 </li>
</ul>
</div>
</body>
</html>