360 lines
45 KiB
HTML
360 lines
45 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: Kernel ABI</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_concepts_abi.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">Kernel ABI </div></div>
|
||
</div><!--header-->
|
||
<div class="contents">
|
||
<div class="textblock"><p>This section details the binary representation of the IPC interface of the kernel. It accompanies the <a class="el" href="l4re_concepts_ipc.html">L4 Inter-Process Communication (IPC)</a> section. The details presented here are usually not relevant when developing L4Re applications and can therefore be skipped by many readers.</p>
|
||
<dl class="section note"><dt>Note</dt><dd>The kernel ABI is subject to change. Please use the API instead of relying on particular binary representations.</dd></dl>
|
||
<p>The following notation is used to indicate how particular data fields are used:</p>
|
||
<ul>
|
||
<li>[in]: The kernel reads and interprets this field.</li>
|
||
<li>[out]: The kernel writes this field with information provided by the kernel.</li>
|
||
<li>[cpy]: The kernel copies this field from sender to receiver (without interpretation if [in] is not listed as well).</li>
|
||
</ul>
|
||
<p>The above indications may be combined.</p>
|
||
<h1 class="doxsection"><a class="anchor" id="l4re_concepts_abi_capsel"></a>
|
||
Capability selector and flags</h1>
|
||
<p>See <a class="el" href="l4re_concepts_ipc.html#l4re_concepts_descr_capidx">partner capability selector</a> and <a class="el" href="l4re_concepts_ipc.html#l4re_concepts_descr_flags">IPC flags</a>.</p>
|
||
<p>The kernel reads and interprets all the fields ([in]). </p><pre class="fragment"> MSB 12 11 10 [7] 4 3 2 1 0 bits
|
||
┌───────────┬─────────┬─────────┬─────────┬─────────┬─────────┬─────────┐
|
||
│ [in] │ [in] │ │ [in] │ [in] │ [in] │ [in] │
|
||
│(see below)│ special │ SBZ │ reply │open wait│ recv │ send │
|
||
└───────────┴─────────┴─────────┴─────────┴─────────┴─────────┴─────────┘
|
||
┌───────────┬─────────┬─
|
||
│ cap idx │ 0 │ if special is 0
|
||
└───────────┴─────────┴─
|
||
┌───────────┬─────────┬─
|
||
│ 1...1 │ 1 │ if special is 1
|
||
└───────────┴─────────┴─
|
||
</pre><ul>
|
||
<li>Bits 0…3 [in]: These bits correspond to the flags defined in <a class="el" href="group__l4__ipc__api.html#gaecfdf101783a02772b67b94793f3a915" title="Capability selector flags.">l4_syscall_flags_t</a>. The individual bits correspond to <a class="el" href="group__l4__ipc__api.html#ggaecfdf101783a02772b67b94793f3a915a21d07c1e159b0e4b2bd824ac052e4508" title="Reply flag.">L4_SYSF_REPLY</a>, <a class="el" href="group__l4__ipc__api.html#ggaecfdf101783a02772b67b94793f3a915ad5a30ca5d080abeafb2752878672b14f" title="Open-wait flag.">L4_SYSF_OPEN_WAIT</a>, <a class="el" href="group__l4__ipc__api.html#ggaecfdf101783a02772b67b94793f3a915ad2c6caeec90ece83786de0596f06af70" title="Receive-phase flag.">L4_SYSF_RECV</a>, <a class="el" href="group__l4__ipc__api.html#ggaecfdf101783a02772b67b94793f3a915a5b352c0582c47836abceacaa0ecb8f2e" title="Send-phase flag.">L4_SYSF_SEND</a>. Note that not all combinations of those bits are defined; see <a class="el" href="group__l4__ipc__api.html#gaecfdf101783a02772b67b94793f3a915" title="Capability selector flags.">l4_syscall_flags_t</a>.</li>
|
||
<li>Bits 4…10 [in] <span class="tt">SBZ</span>: should be zero</li>
|
||
<li>Bit 11 [in] <span class="tt">special</span>: Set when using <a class="el" href="group__l4__cap__api.html#ggafee0421c2fe0e5cfc59f17f16ea10879aff9320ed307e76cebfca6c2871136102" title="Invalid capability selector.">L4_INVALID_CAP</a>, otherwise unset.</li>
|
||
<li>Bits 12…MSB [in]: Capability index if <span class="tt">special</span> is unset, otherwise all those bits should be one (see <a class="el" href="group__l4__cap__api.html#ggafee0421c2fe0e5cfc59f17f16ea10879aff9320ed307e76cebfca6c2871136102" title="Invalid capability selector.">L4_INVALID_CAP</a>, <a class="el" href="l4re_concepts_ipc.html#l4re_concepts_descr_capidx">partner capability selector</a> and <a class="el" href="group__l4__cap__api.html#ga1445e923ce73029130d569d6e69a4dd8" title="Capability selector type.">l4_cap_idx_t</a>).</li>
|
||
</ul>
|
||
<h1 class="doxsection"><a class="anchor" id="l4re_concepts_abi_label"></a>
|
||
Label</h1>
|
||
<p>See <a class="el" href="l4re_concepts_ipc.html#l4re_concepts_descr_label">IPC label</a>.</p>
|
||
<p>When IPC is sent via a thread capability, the label is copied to the receiver unchanged ([cpy]).</p>
|
||
<p>When IPC is sent via an IPC gate, the sent label is ignored and the kernel provides the bitwise OR (<span class="tt">|</span>) of the IPC gate label and the sender’s write and special permissions (see <a class="el" href="group__l4__fpage__api.html#ggaee60789a48cab2782f5a368237591b39a561054fb4021ff4a22ab1881c7a7de5a" title="Interface specific 'W' right for capability flexpages.">L4_CAP_FPAGE_W</a> and <a class="el" href="group__l4__fpage__api.html#ggaee60789a48cab2782f5a368237591b39acb2b2e95f6be245f64937ac48a068066" title="Interface specific 'S' right for capability flexpages.">L4_CAP_FPAGE_S</a>) of the used capability ([out]): </p><pre class="fragment"> MSB 2 1 0 bits
|
||
┌───────────────────┬─────────────────┬─────────────────┐
|
||
│ [out] │ [out] │ [out] │
|
||
│ label │ label | special │ label | write │
|
||
│ │ right │ right │
|
||
└───────────────────┴─────────────────┴─────────────────┘
|
||
</pre><h1 class="doxsection"><a class="anchor" id="l4re_concepts_abi_msgtag"></a>
|
||
Message tag</h1>
|
||
<p>See <a class="el" href="l4re_concepts_ipc.html#l4re_concepts_descr_msgtag">IPC message tag</a>. Note that, for a message tag returned by the kernel, if the error flag is set, all other contents of the message tag is undefined. </p><pre class="fragment"> MSB 16 15 14 13 12 11 [6] 6 5 [6] 0 bits
|
||
┌─────────────────┬──────────┬──────────┬──────────┬──────────┬─────────────┬─────────────┐
|
||
│ [cpy] │ [out] │ │ [in,cpy] │ [in,cpy] │ [in,cpy] │ [in,cpy] │
|
||
│ payload │ error │ SBZ │ schedule │ transfer │ items │ words │
|
||
│ │ flag │ │ flag │ FPU flag │ │ │
|
||
└─────────────────┴──────────┴──────────┴──────────┴──────────┴─────────────┴─────────────┘
|
||
</pre><ul>
|
||
<li>Bits 0…5 [in,cpy] <span class="tt">words</span>: Number of (untyped) message words in the UTCB’s message registers. See <a class="el" href="group__l4__msgtag__api.html#ga6d29d688c50ece7ec55f3c6ed749d375" title="Get the number of untyped words.">l4_msgtag_words()</a> and <a class="el" href="structl4__msgtag__t.html#a98577ea730d9abcd938b89d5c7adb18c" title="Get the number of untyped words.">l4_msgtag_t::words()</a>.</li>
|
||
<li>Bits 6…11 [in,cpy] <span class="tt">items</span>: Number of typed message items in the UTCB’s message registers. See <a class="el" href="group__l4__msgtag__api.html#ga2f57b9cb540e4cbb6a77363828b9a671" title="Get the number of typed items.">l4_msgtag_items()</a> and <a class="el" href="structl4__msgtag__t.html#ad014e4a9f4509b068ddda678f6f8d568" title="Get the number of typed items.">l4_msgtag_t::items()</a>.</li>
|
||
<li>Bit 12 [in,cpy] <span class="tt">transfer FPU flag</span>: See <a class="el" href="group__l4__msgtag__api.html#gga16589e963a73c13aefd2760ce418e053aea4fd67d2f81b00e6949ddcdc7beb5f9" title="Enable FPU transfer flag for IPC.">L4_MSGTAG_TRANSFER_FPU</a>.</li>
|
||
<li>Bit 13 [in,cpy] <span class="tt">schedule flag</span>: See <a class="el" href="group__l4__msgtag__api.html#gga16589e963a73c13aefd2760ce418e053ad220e1ca078f0ea69c8368cb3401d941" title="Enable schedule in IPC flag.">L4_MSGTAG_SCHEDULE</a>.</li>
|
||
<li>Bit 14 <span class="tt">SBZ</span>: should be zero</li>
|
||
<li>Bit 15 [out] <span class="tt">error</span>: See <a class="el" href="group__l4__msgtag__api.html#gga16589e963a73c13aefd2760ce418e053aad1669664171cc979970b1e2300bd463" title="Error indicator flag.">L4_MSGTAG_ERROR</a>, <a class="el" href="group__l4__msgtag__api.html#ga52e71bb66855f4d78fa5c82b5f0c5a87" title="Test for error indicator flag.">l4_msgtag_has_error()</a> and <a class="el" href="structl4__msgtag__t.html#a433eb16b19202d09cc98b40a139b3c29" title="Test if flags indicate an error.">l4_msgtag_t::has_error()</a>.</li>
|
||
<li>Bits 16…MSB [cpy] <span class="tt">payload</span>: Transferred to receiver unchanged; not interpreted by kernel (unless it is the communication partner). For IPC calls or send-only IPC, this is usually the protocol. For replies, this is usually used for return values and server error signaling. See <a class="el" href="group__l4__msgtag__api.html#gab0c4422a230cf5ef5793dbab1faeb3af" title="Get the protocol of tag.">l4_msgtag_label()</a> and <a class="el" href="structl4__msgtag__t.html#a002076380a3f6e4f29a1f6b50ce2bde2" title="Get the protocol value.">l4_msgtag_t::label()</a>.</li>
|
||
</ul>
|
||
<h1 class="doxsection"><a class="anchor" id="l4re_concepts_abi_timeouts"></a>
|
||
Timeouts</h1>
|
||
<p>See <a class="el" href="l4re_concepts_ipc.html#l4re_concepts_descr_timeouts">IPC timeouts</a> and <a class="el" href="unionl4__timeout__t.html" title="Timeout pair.">l4_timeout_t</a>.</p>
|
||
<p>The kernel reads and interprets all the fields ([in]). </p><pre class="fragment"> 31 [16] 16 15 [16] 0 bits
|
||
┌─────────────────┬─────────────────┐
|
||
│ [in] │ [in] │
|
||
│ send timeout │ receive timeout │
|
||
└─────────────────┴─────────────────┘
|
||
</pre><p>A timeout has the following format. There are two special timeout values:</p>
|
||
<ul>
|
||
<li><em>Zero timeout:</em> Only bit 10 is set. See <a class="el" href="group__l4__timeout__api.html#ga1fd51d98ee92362453e7bc266fa8b455" title="Timeout constants.">L4_IPC_TIMEOUT_0</a>. <pre class="fragment"> 15 [5] 11 10 9 [10] 0 bits
|
||
┌───────────┬─────┬──────────────────────┐
|
||
│ 0 │ 1 │ 0 │
|
||
└───────────┴─────┴──────────────────────┘
|
||
</pre></li>
|
||
</ul>
|
||
<ul>
|
||
<li><em>Infinite timeout:</em> All bits are unset. See <a class="el" href="group__l4__timeout__api.html#ga10233285bd94a308b93087f765c83218" title="never timeout">L4_IPC_TIMEOUT_NEVER</a>. <pre class="fragment"> 15 [16] 0 bits
|
||
┌────────────────────────────────────────┐
|
||
│ 0 │
|
||
└────────────────────────────────────────┘
|
||
</pre></li>
|
||
</ul>
|
||
<p>Otherwise, the timeout is either relative or absolute, which is specified by bit 15.</p>
|
||
<ul>
|
||
<li><em>Relative timeout:</em> If bit 15 is unset, the timeout is <span class="tt">mantissa * 2 ^
|
||
exponent</span> micro seconds relative to the current time. The <span class="tt">mantissa</span> must not be zero: <pre class="fragment"> 15 14 [5] 10 9 [10] 0 bits
|
||
┌─────┬───────────┬──────────────────────┐
|
||
│ 0 │ exponent │ mantissa ≠ 0 │
|
||
└─────┴───────────┴──────────────────────┘
|
||
</pre></li>
|
||
</ul>
|
||
<ul>
|
||
<li><em>Absolute timeout:</em> If bit 15 is set, an absolute timeout is specified in the UTCB’s buffer registers starting at <span class="tt">buf reg idx</span> (the particular number of registers depends on the architecture; see <a class="el" href="structl4__timeout__s.html" title="Basic timeout specification.">l4_timeout_s</a>): <pre class="fragment"> 15 14 [9] 6 5 [6] 0 bits
|
||
┌─────┬────────────────────┬─────────────┐
|
||
│ 1 │ SBZ │ buf reg idx │
|
||
└─────┴────────────────────┴─────────────┘
|
||
</pre></li>
|
||
</ul>
|
||
<h1 class="doxsection"><a class="anchor" id="l4re_concepts_abi_utcb"></a>
|
||
User-level thread control block (UTCB)</h1>
|
||
<p>See <a class="el" href="l4re_concepts_ipc.html#l4re_concepts_descr_utcb">User-level thread control block (UTCB)</a>. </p><pre class="fragment"> l4_utcb_mr() l4_utcb_br() l4_utcb_tcr()
|
||
l4_msg_regs_t l4_buf_regs_t l4_thread_regs_t
|
||
┌─────────────────┐ ┌────────┐ ┌───────────────────────────┐ ┌───────────────────────────────────┐
|
||
0 [63] 62 63 64 65 [58] 122 123 124 125 [3] 128 words
|
||
┌───────────────────┬──────────┬──────────┬──────────────────┬──────────┬──────────┬───────────────┐
|
||
│ │ [(out)] │ [in] │ [in] │ [out] │ [(out)] │ │
|
||
│ message registers │ arch │ BDR │ buffer registers │ error │ free │ thread‐local │
|
||
│ (MRs) │ specific │ │ (BRs) │ code │ marker │ storage (TLS) │
|
||
└───────────────────┴──────────┴──────────┴──────────────────┴──────────┴──────────┴───────────────┘
|
||
│ └────────────────────┐
|
||
│0 [words] [2 * items] 62│ words
|
||
┌───────────────┬───────────────┬────────┐
|
||
│ [cpy] │ [in,out] │ │
|
||
│ (untyped) │ typed │ unused │
|
||
│ message words │ message items │ │
|
||
└───────────────┴───────────────┴────────┘
|
||
</pre><ul>
|
||
<li>Words 0…62 <span class="tt">MRs</span>: See <a class="el" href="l4re_concepts_ipc.html#l4re_concepts_descr_mrs">IPC Message registers</a> and <a class="el" href="group__l4__utcb__api.html#ga090bdcc433d5ce568b22ec9ab4f3357b" title="Get the message-register block of a UTCB.">l4_utcb_mr()</a>. The number of message registers is defined by <a class="el" href="group__l4__utcb__api__x86.html#ggac03d87ea12ff53e0a7037eb3f9408af8abc15992493ad991b1854c23002fbbe16" title="Total number of message register (MRs) available.">L4_UTCB_GENERIC_DATA_SIZE</a>. The actually used message registers are defined by <span class="tt">words</span> and <span class="tt">items</span> in the <a class="el" href="#l4re_concepts_abi_msgtag">message tag</a>. The layout of a typed message item varies depending on being an input or output value, see <a class="el" href="#l4re_concepts_abi_items">typed message items</a>.</li>
|
||
<li>Word 63 [(out)]: Depending on the architecture, this word may be used by the kernel to signify the position of a thread’s UTCB in memory. See architecture-specific implementation of <a class="el" href="group__l4__utcb__api.html#gadc099b4a59e1d99638c72c11a8c8b644" title="Get the UTCB address.">l4_utcb()</a>. If at all, the kernel writes this word when kernel-user memory is set up as UTCB while binding a thread to a task; see <a class="el" href="group__l4__thread__control__api.html#ga370fd9233ecb6be3c0c697e6f66539ab" title="Bind the thread to a task.">l4_thread_control_bind()</a>, <a class="el" href="classL4_1_1Thread_1_1Attr.html#a858c0a51f7b147c4b2ba21d4a97afdbb" title="Bind the thread to a task.">L4::Thread::Attr::bind()</a>.</li>
|
||
<li>Word 64 [in] <span class="tt">BDR</span>: See <a class="el" href="#l4re_concepts_abi_utcb_bdr">buffer descriptor register</a>.</li>
|
||
<li>Words 65…122 [in] <span class="tt">BRs</span>: See <a class="el" href="l4re_concepts_ipc.html#l4re_concepts_descr_brs">IPC Buffer Registers</a>, <a class="el" href="#l4re_concepts_abi_items_receive">receive items</a> and <a class="el" href="group__l4__utcb__api.html#gae35044c9bae188ccffb2fd90781c60a5" title="Get the buffer-register block of a UTCB.">l4_utcb_br()</a>-><a class="el" href="structl4__buf__regs__t.html#a716f3f2090e6d861415e3386bfa3037d">br</a>. The number of buffer registers is defined by <a class="el" href="group__l4__utcb__api__x86.html#ggac03d87ea12ff53e0a7037eb3f9408af8ad311749a2178cbc16f654fd48fb4930d" title="Total number of buffer registers (BRs) available.">L4_UTCB_GENERIC_BUFFERS_SIZE</a>.</li>
|
||
<li>Word 123 [out] <span class="tt">error code</span>: See <a class="el" href="l4re_concepts_ipc.html#l4re_concepts_descr_tcrs">IPC Thread Control Registers</a> and <a class="el" href="group__l4__utcb__api.html#ga78ce6eec1d9b19af0f87119c6ac72716" title="Get the thread-control-register block of a UTCB.">l4_utcb_tcr()</a>-><a class="el" href="structl4__thread__regs__t.html#a5938a98c49f9b75e46046b36e6f65e89">error</a>.</li>
|
||
<li>Word 124 [(out)] <span class="tt">free marker</span>: Written by the kernel, but not necessarily during IPC. See <a class="el" href="l4re_concepts_ipc.html#l4re_concepts_descr_tcrs">IPC Thread Control Registers</a> and <a class="el" href="group__l4__utcb__api.html#ga78ce6eec1d9b19af0f87119c6ac72716" title="Get the thread-control-register block of a UTCB.">l4_utcb_tcr()</a>-><a class="el" href="structl4__thread__regs__t.html#a50e81e415f7d4ca398b320f9e9d507be">free_marker</a>.</li>
|
||
<li>Word 125…128 <span class="tt">TLS</span>: Ignored and left untouched by the kernel. See <a class="el" href="l4re_concepts_ipc.html#l4re_concepts_descr_tcrs">IPC Thread Control Registers</a> and <a class="el" href="group__l4__utcb__api.html#ga78ce6eec1d9b19af0f87119c6ac72716" title="Get the thread-control-register block of a UTCB.">l4_utcb_tcr()</a>-><a class="el" href="structl4__thread__regs__t.html#aed661adcf9bc544584d9104741cd9908">user</a>.</li>
|
||
</ul>
|
||
<h2 class="doxsection"><a class="anchor" id="l4re_concepts_abi_utcb_bdr"></a>
|
||
Buffer descriptor register</h2>
|
||
<p>See <a class="el" href="l4re_concepts_ipc.html#l4re_concepts_descr_bdr">IPC Buffer Descriptor Register</a> and <a class="el" href="group__l4__utcb__api.html#gae35044c9bae188ccffb2fd90781c60a5" title="Get the buffer-register block of a UTCB.">l4_utcb_br()</a>-><a class="el" href="structl4__buf__regs__t.html#a852ae37fbb64d4a2f71cbd4c0ba905d1">bdr</a>. </p><pre class="fragment"> MSB 25 24 23 [9] 15 14 [5] 10 9 [5] 5 4 [5] 0 bits
|
||
┌───────────┬──────────┬───────────┬────────────────┬────────────────┬────────────────┐
|
||
│ SBZ │ inherit │ SBZ │ index of first │ index of first │ index of first │
|
||
│ │ FPU flag │ │ obj cap buffer │ io buffer │ memory buffer │
|
||
└───────────┴──────────┴───────────┴────────────────┴────────────────┴────────────────┘
|
||
</pre><h1 class="doxsection"><a class="anchor" id="l4re_concepts_abi_items"></a>
|
||
Typed message items</h1>
|
||
<p>The number of words in a typed message item varies depending on the particular kind of item. However, for the first word, the following properties are shared:</p>
|
||
<ul>
|
||
<li><em>Void item:</em> If all bits of the first word of a typed message item are zero, then it is a void item.</li>
|
||
<li><p class="startli"><em>Non-void item:</em> The first word of a non-void typed message item has the following binary layout: </p><pre class="fragment"> MSB 4 3 2 0 bits
|
||
┌────────────────────────────┬───┬────────┐
|
||
│ │ t │ │
|
||
└────────────────────────────┴───┴────────┘
|
||
</pre><p class="startli">Bit 3 (<span class="tt">t</span>) is the type bit. If <span class="tt">t</span> is set, the item is a map item. Currently, map item is the only supported type. Hence, this bit must be set for all items except for void items.</p>
|
||
</li>
|
||
</ul>
|
||
<p>There are three sub-types of typed message items: <em>send items</em>, <em>receive items</em>, and <em>return items</em>; see <a class="el" href="group__l4__msgitem__api.html">Message Items</a>.</p>
|
||
<p>Many typed items make use of flexpages, therefore, these are described before the various kinds of typed items. Note that flexpages are also used outside of typed message items, e.g., for <a class="el" href="classL4_1_1Task.html#a4b9294cc5d6338a36958df578f092a25" title="Revoke rights from the task.">L4::Task::unmap()</a>.</p>
|
||
<h2 class="doxsection"><a class="anchor" id="l4re_concepts_abi_items_flexpages"></a>
|
||
Flexpages</h2>
|
||
<p>A flexpage consists of a single word and, except for some special values, describes a range in an address space, see <a class="el" href="group__l4__fpage__api.html">flex pages</a>.</p>
|
||
<p>The general layout is defined as follows: </p><pre class="fragment"> MSB 6 5 [2] 4 3 [4] 0 bits
|
||
┌───────────────────────────────────┬─────────┬─────────────┐
|
||
│ │ type │ │
|
||
└───────────────────────────────────┴─────────┴─────────────┘
|
||
</pre><ul>
|
||
<li>Bits 4…5 <span class="tt">type</span>: See <a class="el" href="group__l4__fpage__api.html#ga7616290ff22f4145650aa664d012f833" title="Return type from a flexpage.">l4_fpage_type()</a> and <a class="el" href="group__l4__fpage__api.html#gacbb9260e4a3b77be0fc14df24b838d52" title="Flexpage type.">L4_fpage_type</a>.</li>
|
||
</ul>
|
||
<p>The type <a class="el" href="group__l4__fpage__api.html#ggacbb9260e4a3b77be0fc14df24b838d52ae0c8f334d7955ee515bb7dd22251ac60" title="Special flexpage, either l4_fpage_invalid() or l4_fpage_all(); only supported by selected interfaces.">L4_FPAGE_SPECIAL</a> only supports some selected values, which are only supported for selected interfaces; see <a class="el" href="group__l4__fpage__api.html#ggacbb9260e4a3b77be0fc14df24b838d52ae0c8f334d7955ee515bb7dd22251ac60" title="Special flexpage, either l4_fpage_invalid() or l4_fpage_all(); only supported by selected interfaces.">L4_FPAGE_SPECIAL</a>.</p>
|
||
<p>The other types share the same layout: </p><pre class="fragment"> MSB 12 11 [6] 6 5 [2] 4 3 [4] 0 bits
|
||
┌─────────────────┬─────────────────┬─────────┬─────────────┐
|
||
│ start │ order │ type │ permissions │
|
||
└─────────────────┴─────────────────┴─────────┴─────────────┘
|
||
</pre><ul>
|
||
<li>Bits 0…3 <span class="tt">permissions</span>: See <a class="el" href="group__l4__fpage__api.html#gaad7579a5ab36d5cbda48bbb4fc365cd7" title="Return rights from a flexpage.">l4_fpage_rights()</a>, <a class="el" href="group__l4__fpage__api.html#ga5d4f4972d58f72b2a33b6c139b5950a8" title="Memory and IO port flexpage rights.">L4_fpage_rights</a> (memory space) and <a class="el" href="group__l4__fpage__api.html#gaee60789a48cab2782f5a368237591b39" title="Object flexpage rights.">L4_cap_fpage_rights</a> (object space). Should be zero for I/O port space.</li>
|
||
<li>Bits 6…11 <span class="tt">order</span>: The log₂ size of the flexpage. See <a class="el" href="group__l4__fpage__api.html#ga905f25ce8cd4e02fb988702dc85e18e0" title="Return size (log2) from a flexpage.">l4_fpage_size</a>.</li>
|
||
<li>Bits 12…MSB <span class="tt">start</span>: The starting page number / I/O port number / capability index of the flexpage. Must be aligned to the flexpage size. See <a class="el" href="group__l4__fpage__api.html#ga0a2b8a60053c0a34eb1cbdcc5db9a430" title="Return the page part from a flexpage.">l4_fpage_page()</a>, <a class="el" href="group__l4__fpage__api.html#ga87c7b03e1b72e9cfed3ad4b31a0c58ba" title="Return the memory address from the memory flexpage.">l4_fpage_memaddr()</a>, <a class="el" href="group__l4__fpage__api.html#ga870f97aa1727c673716618514a124bf8" title="Return the IO port number from the IO flexpage.">l4_fpage_ioport()</a> and <a class="el" href="group__l4__fpage__api.html#gaeb484f02b9ea93d811fea4e5d0c4fb45" title="Return the capability index from the object flexpage.">l4_fpage_obj()</a>.</li>
|
||
</ul>
|
||
<p>Also see <a class="el" href="group__l4__fpage__api.html#ga8d185d1e2ec513f1b3e8a5634469b756" title="Create a memory flexpage.">l4_fpage()</a> (memory space), <a class="el" href="group__l4__fpage__api.html#gab918a25f8a923b7a68158e737d4801a8" title="Create an IO-port flexpage.">l4_iofpage()</a> (I/O port space) and <a class="el" href="group__l4__fpage__api.html#gaeb484f02b9ea93d811fea4e5d0c4fb45" title="Return the capability index from the object flexpage.">l4_fpage_obj()</a> (object space).</p>
|
||
<h2 class="doxsection"><a class="anchor" id="l4re_concepts_abi_items_send"></a>
|
||
Send items</h2>
|
||
<p>A send item consists of two words. The second word of a non-void send item is a <a class="el" href="#l4re_concepts_abi_items_flexpages">flexpage</a>. The type of the flexpage determines the interpretation of the <span class="tt">attr</span> bits in the first word (see below).</p>
|
||
<p>If not void, the layout of the first word is defined as follows: </p><pre class="fragment"> first word second word
|
||
MSB 12 11 8 7 4 3 2 1 0 bits
|
||
┌──────────┬─────┬──────┬───┬─────┬───────┬──────────┐┌───────────────┐
|
||
│ hot_spot │ SBZ │ attr │ 1 │ SBZ │ grant │ compound ││ send flexpage │
|
||
└──────────┴─────┴──────┴───┴─────┴───────┴──────────┘└───────────────┘
|
||
</pre><p><span class="tt">SBZ</span> means “should be zero”.</p>
|
||
<ul>
|
||
<li>Bit 0 (<span class="tt">compound</span>): Compound bit. See <a class="el" href="group__l4__msgitem__api.html#gga94ecfe2908867c4ed0c13a7a97337f6aac4ea7fecbdc440401bde677de3df051d" title="Denote that the following item shall be put into the same receive item as this one.">L4_ITEM_CONT</a> and <a class="el" href="classL4_1_1Ipc_1_1Snd__fpage.html#a4b9daf1621d847ba1b1e360a9665358f" title="Check if the item has the compound bit set, see Continue.">L4::Ipc::Snd_fpage::is_compound()</a>.</li>
|
||
<li>Bit 1 (<span class="tt">grant</span>): Grant flag. See <a class="el" href="group__l4__msgitem__api.html#gga94ecfe2908867c4ed0c13a7a97337f6aa818a51ad60a66f82775c39c2eb550f4d" title="Identify a message item as map item.">L4_ITEM_MAP</a>, <a class="el" href="group__l4__msgitem__api.html#gga94ecfe2908867c4ed0c13a7a97337f6aa390d5fd9efeb212bfbed501498387c9e" title="Flag as grant instead of map operation.">L4_MAP_ITEM_GRANT</a> and <a class="el" href="classL4_1_1Ipc_1_1Snd__fpage.html#a478ea520c3c74d5e8ffcca7de6674492" title="(Defined for send items only.) Kind of mapping.">L4::Ipc::Snd_fpage::Map_type</a>.</li>
|
||
<li>Bits 7..4 (<span class="tt">attr</span>): Attributes. See <a class="el" href="group__l4__msgitem__api.html#gad142e99a533af52d358f9940fa00966a" title="Attributes and additional permissions for object send items.">L4_obj_fpage_ctl</a> and <a class="el" href="group__l4__msgitem__api.html#ga547729eef68ea9c0e085c34a66e133fa" title="Cacheability options for memory send items.">l4_fpage_cacheability_opt_t</a>, <a class="el" href="classL4_1_1Ipc_1_1Snd__fpage.html#a6c3ef306df19fd2a6f2e03ca4b79b1ae" title="(Defined for memory send items only.) Caching options, see l4_fpage_cacheability_opt_t.">L4::Ipc::Snd_fpage::Cacheopt</a>.</li>
|
||
<li>Bits MSB..12 (<span class="tt">hot_spot</span>): Send base (also called hot spot). See <a class="el" href="classL4_1_1Ipc_1_1Snd__fpage.html#a79f4f5fb4cf226f3a276c76c204883c3" title="Get the position in receive window for the case that this item has a different size than the correspo...">L4::Ipc::Snd_fpage::snd_base()</a>.</li>
|
||
</ul>
|
||
<p>For details, see <a class="el" href="l4re_concepts_ipc.html#l4re_concepts_descr_mrs">IPC Message registers</a>.</p>
|
||
<h2 class="doxsection"><a class="anchor" id="l4re_concepts_abi_items_receive"></a>
|
||
Receive items</h2>
|
||
<p>A non-void receive item consists of up to three words.</p>
|
||
<p>If not void, the general layout of the first word is defined as follows: </p><pre class="fragment"> MSB 4 3 2 1 0 bits
|
||
┌──────────────────────────┬───┬────────┬───────┬─────┐
|
||
│ │ 1 │ rcv_id │ small │ fwd │
|
||
└──────────────────────────┴───┴────────┴───────┴─────┘
|
||
</pre><p>The <span class="tt">small</span> and <span class="tt">fwd</span> bits determine the details of the layout of the whole message item.</p>
|
||
<p>If <span class="tt">small</span> is unset, then also <span class="tt">rcv_id</span> must be unset, and the most significant bits should be zero: </p><pre class="fragment">┌──────────────────────────┬───┬────────┬───────┬─────┐
|
||
│ SBZ (should be zero) │ 1 │ 0 │ 0 │ fwd │
|
||
└──────────────────────────┴───┴────────┴───────┴─────┘
|
||
</pre><p>If <span class="tt">small</span> is set, the most significant bits are layouted as follows: </p><pre class="fragment"> MSB 12 11 4 3 2 1 0 bits
|
||
┌─────────────┬────────────┬───┬────────┬───────┬─────┐
|
||
│ rcv cap idx │ SBZ │ 1 │ rcv_id │ 1 │ fwd │
|
||
└─────────────┴────────────┴───┴────────┴───────┴─────┘
|
||
</pre><p>At most one of <span class="tt">rcv_id</span> and <span class="tt">fwd</span> may be set.</p>
|
||
<p>The number and meaning of the words in the whole item are determined by the <span class="tt">small</span> and <span class="tt">fwd</span> bits: </p><pre class="fragment"> first word second word third word
|
||
rcv_id small fwd
|
||
─┬─────┬─────┬─────┐┌───────────────────┐
|
||
│ 0 │ 0 │ 0 ││ rcv flexpage │
|
||
─┴─────┴─────┴─────┘└───────────────────┘ 12 11 0
|
||
─┬─────┬─────┬─────┐┌───────────────────┐┌─────────────┬─────┐
|
||
│ 0 │ 0 │ 1 ││ rcv flexpage ││ fwd cap idx │ SBZ │
|
||
─┴─────┴─────┴─────┘└───────────────────┘└─────────────┴─────┘
|
||
─┬─────┬─────┬─────┐
|
||
│ 0/1 │ 1 │ 0 │
|
||
─┴─────┴─────┴─────┘ 12 11 0
|
||
─┬─────┬─────┬─────┐┌─────────────┬─────┐
|
||
│ 0 │ 1 │ 1 ││ fwd cap idx │ SBZ │
|
||
─┴─────┴─────┴─────┘└─────────────┴─────┘
|
||
</pre><p>The meaning of the bits in detail:</p>
|
||
<ul>
|
||
<li>Bit 0 (<span class="tt">fwd</span>): See <a class="el" href="group__l4__msgitem__api.html#gga94ecfe2908867c4ed0c13a7a97337f6aa624249a87f6c2461451cc559cb8ae99f" title="This flag specifies if received capabilities shall be mapped to a particular task instead of the invo...">L4_RCV_ITEM_FORWARD_MAPPINGS</a> and <a class="el" href="classL4_1_1Ipc_1_1Rcv__fpage.html#a81c3a50ddd10a3aad0bc2ca73c2781af" title="Check if rcv_task() shall be used as destination for received capabilities.">L4::Ipc::Rcv_fpage::forward_mappings()</a>. For <span class="tt">fwd cap idx</span> see <a class="el" href="classL4_1_1Ipc_1_1Rcv__fpage.html#a99e3351649bd10992f3564768dfd06e0" title="Get the capability index of the destination task for received capabilities.">L4::Ipc::Rcv_fpage::rcv_task()</a>.</li>
|
||
<li>Bit 1 (<span class="tt">small</span>): See <a class="el" href="group__l4__msgitem__api.html#gga94ecfe2908867c4ed0c13a7a97337f6aaf41c9a3e815dffeb73eef8660392572f" title="Mark the receive buffer to be a small receive item that describes a buffer for a single object capabi...">L4_RCV_ITEM_SINGLE_CAP</a> and <a class="el" href="classL4_1_1Ipc_1_1Small__buf.html" title="A receive item for receiving a single object capability.">L4::Ipc::Small_buf</a> vs. <a class="el" href="classL4_1_1Ipc_1_1Rcv__fpage.html" title="Non-small receive item.">L4::Ipc::Rcv_fpage</a>.</li>
|
||
<li>Bit 2 (<span class="tt">rcv_id</span>): See <a class="el" href="group__l4__msgitem__api.html#gga94ecfe2908867c4ed0c13a7a97337f6aa9ec3db5390483f9f0cd4a4571b04b5be" title="The receiver requests to receive a local ID instead of a mapping whenever possible.">L4_RCV_ITEM_LOCAL_ID</a>.</li>
|
||
</ul>
|
||
<h2 class="doxsection"><a class="anchor" id="l4re_concepts_abi_items_return"></a>
|
||
Return items</h2>
|
||
<p>A return item always consists of two words. The general layout of a non-void return item is defined as follows: </p><pre class="fragment"> first word second word
|
||
MSB 12 11 6 5 4 3 2 1 0 bits
|
||
┌──────────┬───────┬──────┬───┬──────────┬───┐┌───────────────────┐
|
||
│ hot_spot │ order │ type │ 1 │ rcv_type │ c ││ payload │
|
||
└──────────┴───────┴──────┴───┴──────────┴───┘└───────────────────┘
|
||
└──────────┘ └───┘ └───┘ from send item’s first word
|
||
└──────────────┘ from send item’s flexpage
|
||
└──────────┘ initially zero
|
||
</pre><p>As indicated above, the <span class="tt">hot_spot</span>, <span class="tt">1</span>, and <span class="tt">c</span> (<span class="tt">compound</span>) are copied from the sender’s send item’s first word, and <span class="tt">order</span> and <span class="tt">type</span> are copied from the sender’s send item’s flexpage. The <span class="tt">rcv_type</span> and <span class="tt">payload</span> are determined by what is actually transferred, which is also affected by the <span class="tt">rcv_id</span> bit in the receiver’s receive item. The <span class="tt">rcv_type</span> determines the content and layout of the payload.</p>
|
||
<p>There are four cases for <span class="tt">rcv_type</span>:</p>
|
||
<p><span class="tt">00</span>: Used if at least one mapping was actually transferred for the corresponding send item. The payload is undefined: (also see <a class="el" href="classL4_1_1Ipc_1_1Snd__fpage.html#af9b4655a879646d2e79818e71ef28d81" title="(Defined for return items only.) Check if at least one object capability has been mapped for this ite...">L4::Ipc::Snd_fpage::cap_received()</a>): </p><pre class="fragment">┌──────────┬───────┬──────┬───┬──────────┬───┐┌───────────────────┐
|
||
│ hot_spot │ order │ type │ 1 │ 00 │ c ││ undefined │
|
||
└──────────┴───────┴──────┴───┴──────────┴───┘└───────────────────┘
|
||
</pre><p><span class="tt">01</span>: Used if transfer of mappings was attempted, but actually nothing was transferred, because nothing was mapped on the sender’s side for the corresponding send item. The payload is undefined: </p><pre class="fragment">┌──────────┬───────┬──────┬───┬──────────┬───┐┌───────────────────┐
|
||
│ hot_spot │ order │ type │ 1 │ 01 │ c ││ undefined │
|
||
└──────────┴───────┴──────┴───┴──────────┴───┘└───────────────────┘
|
||
</pre><p><span class="tt">10</span>: Used if the receive item’s <span class="tt">rcv_id</span> bit was set and the conditions for transferring an IPC gate label were fulfilled. In that case, no mapping is done for this item and the payload consists of the bitwise OR (<span class="tt">|</span>) of the IPC gate label and the write and special permissions (see <a class="el" href="group__l4__fpage__api.html#ggaee60789a48cab2782f5a368237591b39a561054fb4021ff4a22ab1881c7a7de5a" title="Interface specific 'W' right for capability flexpages.">L4_CAP_FPAGE_W</a> and <a class="el" href="group__l4__fpage__api.html#ggaee60789a48cab2782f5a368237591b39acb2b2e95f6be245f64937ac48a068066" title="Interface specific 'S' right for capability flexpages.">L4_CAP_FPAGE_S</a>) that would have been mapped (also see <a class="el" href="classL4_1_1Ipc_1_1Snd__fpage.html#a00259520752222efb432314c87d9f0f7" title="(Defined for return items only.) Check if an IPC gate label has been received instead of a mapping.">L4::Ipc::Snd_fpage::id_received()</a>): </p><pre class="fragment"> 2 1 0 bits
|
||
┌──────────┬───────┬──────┬───┬──────────┬───┐┌──────────┬────────┐
|
||
│ hot_spot │ order │ type │ 1 │ 10 │ c ││ label │ rights │
|
||
└──────────┴───────┴──────┴───┴──────────┴───┘└──────────┴────────┘
|
||
</pre><p><span class="tt">11</span>: Used if the receive item’s <span class="tt">rcv_id</span> bit was set and the conditions for transferring the sender’s flexpage word were fulfilled. In that case, no mapping is done for this item and the payload is a copy of the sender’s flexpage word (also see <a class="el" href="classL4_1_1Ipc_1_1Snd__fpage.html#a462e0f1e40c808e9a6d79494b55ea4b4" title="(Defined for return items only.) Check if a raw object flexpage has been received instead of a mappin...">L4::Ipc::Snd_fpage::local_id_received()</a>): </p><pre class="fragment">┌──────────┬───────┬──────┬───┬──────────┬───┐┌───────────────────┐
|
||
│ hot_spot │ order │ type │ 1 │ 11 │ c ││ send flexpage │
|
||
└──────────┴───────┴──────┴───┴──────────┴───┘└───────────────────┘
|
||
</pre> </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_concepts.html">Programming for L4Re</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>
|