245 lines
32 KiB
HTML
245 lines
32 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: Interface Definition Language</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('l4_cxx_ipc_iface.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">Interface Definition Language </div></div>
|
|
</div><!--header-->
|
|
<div class="contents">
|
|
<div class="textblock"><p>An interface definition in <a class="el" href="namespaceL4Re.html" title="L4Re C++ Interfaces.">L4Re</a> is normally declared as a class derived from <a class="el" href="classL4_1_1Kobject__t.html" title="Helper class to create an L4Re interface class that is derived from a single base class.">L4::Kobject_t</a>. For example, the <a class="el" href="examples_2clntsrv_2src_2shared_8h-example.html">simple calculator example </a> declares its interface like that:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">struct </span>Calc : <a class="code hl_class" href="classL4_1_1Kobject__t.html">L4::Kobject_t</a><Calc, L4::Kobject></div>
|
|
<div class="line">{</div>
|
|
<div class="line"> <a class="code hl_define" href="ipc__iface.html#a5772eb61b611f8f17bbc89e02e534ca1">L4_INLINE_RPC</a>(<span class="keywordtype">long</span>, sub, (<a class="code hl_typedef" href="group__l4__basic__types.html#gac1d09f3e382e711b776931f10e6e1e5a">l4_uint32_t</a> a, <a class="code hl_typedef" href="group__l4__basic__types.html#gac1d09f3e382e711b776931f10e6e1e5a">l4_uint32_t</a> b, <a class="code hl_typedef" href="group__l4__basic__types.html#gac1d09f3e382e711b776931f10e6e1e5a">l4_uint32_t</a> *res));</div>
|
|
<div class="line"> <a class="code hl_define" href="ipc__iface.html#a5772eb61b611f8f17bbc89e02e534ca1">L4_INLINE_RPC</a>(<span class="keywordtype">long</span>, neg, (<a class="code hl_typedef" href="group__l4__basic__types.html#gac1d09f3e382e711b776931f10e6e1e5a">l4_uint32_t</a> a, <a class="code hl_typedef" href="group__l4__basic__types.html#gac1d09f3e382e711b776931f10e6e1e5a">l4_uint32_t</a> *res));</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> <span class="keyword">typedef</span> <a class="code hl_struct" href="structL4_1_1Typeid_1_1Rpcs.html">L4::Typeid::Rpcs<sub_t, neg_t></a> Rpcs;</div>
|
|
<div class="line">};</div>
|
|
<div class="ttc" id="aclassL4_1_1Kobject__t_html"><div class="ttname"><a href="classL4_1_1Kobject__t.html">L4::Kobject_t</a></div><div class="ttdoc">Helper class to create an L4Re interface class that is derived from a single base class.</div><div class="ttdef"><b>Definition</b> <a href="____typeinfo_8h_source.html#l00749">__typeinfo.h:750</a></div></div>
|
|
<div class="ttc" id="agroup__l4__basic__types_html_gac1d09f3e382e711b776931f10e6e1e5a"><div class="ttname"><a href="group__l4__basic__types.html#gac1d09f3e382e711b776931f10e6e1e5a">l4_uint32_t</a></div><div class="ttdeci">unsigned int l4_uint32_t</div><div class="ttdoc">Unsigned 32bit value.</div><div class="ttdef"><b>Definition</b> <a href="l4_2sys_2l4int_8h_source.html#l00029">l4int.h:29</a></div></div>
|
|
<div class="ttc" id="aipc__iface_html_a5772eb61b611f8f17bbc89e02e534ca1"><div class="ttname"><a href="ipc__iface.html#a5772eb61b611f8f17bbc89e02e534ca1">L4_INLINE_RPC</a></div><div class="ttdeci">#define L4_INLINE_RPC(res, name, args, attr...)</div><div class="ttdoc">Define an inline RPC call (type and callable).</div><div class="ttdef"><b>Definition</b> <a href="ipc__iface_source.html#l00482">ipc_iface:482</a></div></div>
|
|
<div class="ttc" id="astructL4_1_1Typeid_1_1Rpcs_html"><div class="ttname"><a href="structL4_1_1Typeid_1_1Rpcs.html">L4::Typeid::Rpcs</a></div><div class="ttdoc">Standard list of RPCs of an interface.</div><div class="ttdef"><b>Definition</b> <a href="____typeinfo_8h_source.html#l00428">__typeinfo.h:428</a></div></div>
|
|
</div><!-- fragment --><p>The signature of each function is first declared using one of the RPC macros (see below) and then all the functions need to be listed in the Rpcs type.</p>
|
|
<p>Clients invoke these functions with the name given to the RPC macros, <span class="tt">sub</span> and <span class="tt">neg</span> above. Servers implement them by defining functions with an <span class="tt">op_</span> prepended, <span class="tt">op_sub</span> and <span class="tt">op_neg</span>. The types of the parameters in the macro definition, on the server side, and on the client side are not the same. The following section describes how they are related to each other.</p>
|
|
<h1 class="doxsection"><a class="anchor" id="l4_cxx_ipc_iface_types"></a>
|
|
Parameter types for RPC</h1>
|
|
<p>Generally all value parameters, const reference parameters, and const pointer parameters to an RPC interface are considered as input parameters for the RPC and are transmitted from the client to the server. </p><dl class="section note"><dt>Note</dt><dd>This means that <span class="tt">char const *</span> is treated as an input <span class="tt">char</span> and not as a zero terminated string value, for strings see L4::Ipc::String<>.</dd></dl>
|
|
<p>Parameters that are non-const references or non-const pointers are treated as output parameters going from the server to the client.</p>
|
|
<p>There are special data types that appear on only one side (client or server) when used, see the following table for details.</p>
|
|
<div class="fragment"><div class="line"><a class="code hl_define" href="ipc__iface.html#a5e5588cacb2659f18f48ae49c2beb800">L4_RPC</a>(<span class="keywordtype">long</span>, test, (<span class="keywordtype">int</span> arg1, <span class="keywordtype">char</span> <span class="keyword">const</span> *arg2, <span class="keywordtype">unsigned</span> *ret1));</div>
|
|
<div class="ttc" id="aipc__iface_html_a5e5588cacb2659f18f48ae49c2beb800"><div class="ttname"><a href="ipc__iface.html#a5e5588cacb2659f18f48ae49c2beb800">L4_RPC</a></div><div class="ttdeci">#define L4_RPC(res, name, args, attr...)</div><div class="ttdoc">Define an RPC call (type and callable).</div><div class="ttdef"><b>Definition</b> <a href="ipc__iface_source.html#l00541">ipc_iface:541</a></div></div>
|
|
</div><!-- fragment --><p>The example shows the declaration of a method called <span class="tt">test</span> with <span class="tt">long</span> as return type, <span class="tt">arg1</span> is an <span class="tt">int</span> input, <span class="tt">arg2</span> a <span class="tt">char</span> input, and <span class="tt">ret1</span> an <span class="tt">unsigned</span> output parameter.</p>
|
|
<table class="markdownTable">
|
|
<tr class="markdownTableHead">
|
|
<th class="markdownTableHeadLeft">Type </th><th class="markdownTableHeadLeft">Direction </th><th class="markdownTableHeadLeft">Client-Type </th><th class="markdownTableHeadLeft">Server-Type </th></tr>
|
|
<tr class="markdownTableRowOdd">
|
|
<td class="markdownTableBodyLeft"><span class="tt">T</span> </td><td class="markdownTableBodyLeft">Input </td><td class="markdownTableBodyLeft"><span class="tt">T</span> </td><td class="markdownTableBodyLeft"><span class="tt">T</span> </td></tr>
|
|
<tr class="markdownTableRowEven">
|
|
<td class="markdownTableBodyLeft"><span class="tt">T const &</span> </td><td class="markdownTableBodyLeft">Input </td><td class="markdownTableBodyLeft"><span class="tt">T const &</span> </td><td class="markdownTableBodyLeft"><span class="tt">T const &</span> </td></tr>
|
|
<tr class="markdownTableRowOdd">
|
|
<td class="markdownTableBodyLeft"><span class="tt">T const *</span> </td><td class="markdownTableBodyLeft">Input </td><td class="markdownTableBodyLeft"><span class="tt">T const *</span> </td><td class="markdownTableBodyLeft"><span class="tt">T const &</span> </td></tr>
|
|
<tr class="markdownTableRowEven">
|
|
<td class="markdownTableBodyLeft"><span class="tt">T &</span> </td><td class="markdownTableBodyLeft">Output </td><td class="markdownTableBodyLeft"><span class="tt">T &</span> </td><td class="markdownTableBodyLeft"><span class="tt">T &</span> </td></tr>
|
|
<tr class="markdownTableRowOdd">
|
|
<td class="markdownTableBodyLeft"><span class="tt">T *</span> </td><td class="markdownTableBodyLeft">Output </td><td class="markdownTableBodyLeft"><span class="tt">T *</span> </td><td class="markdownTableBodyLeft"><span class="tt">T &</span> </td></tr>
|
|
<tr class="markdownTableRowEven">
|
|
<td class="markdownTableBodyLeft"><span class="tt"><a class="el" href="structL4_1_1Ipc_1_1In__out.html" title="Mark an argument as in-out argument.">L4::Ipc::In_out</a><T &></span> </td><td class="markdownTableBodyLeft">In/Out </td><td class="markdownTableBodyLeft"><span class="tt">T &</span> </td><td class="markdownTableBodyLeft"><span class="tt">T &</span> </td></tr>
|
|
<tr class="markdownTableRowOdd">
|
|
<td class="markdownTableBodyLeft"><span class="tt"><a class="el" href="structL4_1_1Ipc_1_1In__out.html" title="Mark an argument as in-out argument.">L4::Ipc::In_out</a><T *></span> </td><td class="markdownTableBodyLeft">In/Out </td><td class="markdownTableBodyLeft"><span class="tt">T *</span> </td><td class="markdownTableBodyLeft"><span class="tt">T &</span> </td></tr>
|
|
<tr class="markdownTableRowEven">
|
|
<td class="markdownTableBodyLeft"><span class="tt"><a class="el" href="classL4_1_1Ipc_1_1Cap.html" title="Capability type for RPC interfaces (see L4::Cap<T>).">L4::Ipc::Cap</a><T></span> </td><td class="markdownTableBodyLeft">Input </td><td class="markdownTableBodyLeft"><span class="tt"><a class="el" href="classL4_1_1Ipc_1_1Cap.html" title="Capability type for RPC interfaces (see L4::Cap<T>).">L4::Ipc::Cap</a><T></span> </td><td class="markdownTableBodyLeft"><span class="tt"><a class="el" href="classL4_1_1Ipc_1_1Snd__fpage.html" title="Send item or return item.">L4::Ipc::Snd_fpage</a></span> </td></tr>
|
|
<tr class="markdownTableRowOdd">
|
|
<td class="markdownTableBodyLeft"><span class="tt"><a class="el" href="structL4_1_1Ipc_1_1Out.html" title="Mark an argument as a output value in an RPC signature.">L4::Ipc::Out</a><<a class="el" href="classL4_1_1Cap.html" title="C++ interface for capabilities.">L4::Cap</a><T> ></span> </td><td class="markdownTableBodyLeft">Output </td><td class="markdownTableBodyLeft"><span class="tt"><a class="el" href="classL4_1_1Cap.html" title="C++ interface for capabilities.">L4::Cap</a><T></span> </td><td class="markdownTableBodyLeft"><span class="tt"><a class="el" href="classL4_1_1Ipc_1_1Cap.html" title="Capability type for RPC interfaces (see L4::Cap<T>).">L4::Ipc::Cap</a><T> &</span> </td></tr>
|
|
<tr class="markdownTableRowEven">
|
|
<td class="markdownTableBodyLeft"><span class="tt"><a class="el" href="classL4_1_1Ipc_1_1Rcv__fpage.html" title="Non-small receive item.">L4::Ipc::Rcv_fpage</a></span> </td><td class="markdownTableBodyLeft">Input </td><td class="markdownTableBodyLeft"><span class="tt"><a class="el" href="classL4_1_1Ipc_1_1Rcv__fpage.html" title="Non-small receive item.">L4::Ipc::Rcv_fpage</a></span> </td><td class="markdownTableBodyLeft"><span class="tt">void</span> </td></tr>
|
|
<tr class="markdownTableRowOdd">
|
|
<td class="markdownTableBodyLeft"><span class="tt"><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></span> </td><td class="markdownTableBodyLeft">Input </td><td class="markdownTableBodyLeft"><span class="tt"><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></span> </td><td class="markdownTableBodyLeft"><span class="tt">void</span> </td></tr>
|
|
</table>
|
|
<p>Array types can be used to transmit arrays of variable length. They can either be stored in a client-provided buffer (<a class="el" href="structL4_1_1Ipc_1_1Array.html" title="Array data type for dynamically sized arrays in RPCs.">L4::Ipc::Array</a>), copied into a server-provided buffer (<a class="el" href="structL4_1_1Ipc_1_1Array__in__buf.html" title="Server-side copy in buffer for Array.">L4::Ipc::Array_in_buf</a>) or directly read and written into the UTCB (<a class="el" href="structL4_1_1Ipc_1_1Array__ref.html" title="Array reference data type for arrays located in the message.">L4::Ipc::Array_ref</a>).</p>
|
|
<p>Constraints on <a class="el" href="structL4_1_1Ipc_1_1Array__ref.html" title="Array reference data type for arrays located in the message.">L4::Ipc::Array_ref</a>:</p><ul>
|
|
<li>the start position of this array type needs to be known in advance.</li>
|
|
<li>it must be the last parameter of a message.</li>
|
|
<li>the size of the array type is not transmitted to the server, only the client side knows the intended size of the input array. The server assumes the rest of the UTCB as the actual array. Different sever-side behavior must be steered otherwise, e.g. through another parameter.</li>
|
|
</ul>
|
|
<table class="markdownTable">
|
|
<tr class="markdownTableHead">
|
|
<th class="markdownTableHeadLeft">Type </th><th class="markdownTableHeadLeft">Direction </th><th class="markdownTableHeadLeft">Client-Type </th><th class="markdownTableHeadLeft">Server-Type </th></tr>
|
|
<tr class="markdownTableRowOdd">
|
|
<td class="markdownTableBodyLeft"><span class="tt"><a class="el" href="structL4_1_1Ipc_1_1Array.html" title="Array data type for dynamically sized arrays in RPCs.">L4::Ipc::Array</a><const T></span> </td><td class="markdownTableBodyLeft">Input </td><td class="markdownTableBodyLeft"><span class="tt"><a class="el" href="structL4_1_1Ipc_1_1Array.html" title="Array data type for dynamically sized arrays in RPCs.">L4::Ipc::Array</a><const T></span> </td><td class="markdownTableBodyLeft"><span class="tt"><a class="el" href="structL4_1_1Ipc_1_1Array__ref.html" title="Array reference data type for arrays located in the message.">L4::Ipc::Array_ref</a><const T></span> </td></tr>
|
|
<tr class="markdownTableRowEven">
|
|
<td class="markdownTableBodyLeft"><span class="tt"><a class="el" href="structL4_1_1Ipc_1_1Array.html" title="Array data type for dynamically sized arrays in RPCs.">L4::Ipc::Array</a><const T></span> </td><td class="markdownTableBodyLeft">Input </td><td class="markdownTableBodyLeft"><span class="tt"><a class="el" href="structL4_1_1Ipc_1_1Array.html" title="Array data type for dynamically sized arrays in RPCs.">L4::Ipc::Array</a><const T></span> </td><td class="markdownTableBodyLeft"><span class="tt"><a class="el" href="structL4_1_1Ipc_1_1Array__in__buf.html" title="Server-side copy in buffer for Array.">L4::Ipc::Array_in_buf</a><T> const &</span> </td></tr>
|
|
<tr class="markdownTableRowOdd">
|
|
<td class="markdownTableBodyLeft"><span class="tt"><a class="el" href="structL4_1_1Ipc_1_1Array.html" title="Array data type for dynamically sized arrays in RPCs.">L4::Ipc::Array</a><T> &</span> </td><td class="markdownTableBodyLeft">Output </td><td class="markdownTableBodyLeft"><span class="tt"><a class="el" href="structL4_1_1Ipc_1_1Array.html" title="Array data type for dynamically sized arrays in RPCs.">L4::Ipc::Array</a><T> &</span> </td><td class="markdownTableBodyLeft"><span class="tt"><a class="el" href="structL4_1_1Ipc_1_1Array__ref.html" title="Array reference data type for arrays located in the message.">L4::Ipc::Array_ref</a><T> &</span> </td></tr>
|
|
<tr class="markdownTableRowEven">
|
|
<td class="markdownTableBodyLeft"><span class="tt"><a class="el" href="structL4_1_1Ipc_1_1Array__ref.html" title="Array reference data type for arrays located in the message.">L4::Ipc::Array_ref</a><T> &</span> </td><td class="markdownTableBodyLeft">Output </td><td class="markdownTableBodyLeft"><span class="tt"><a class="el" href="structL4_1_1Ipc_1_1Array__ref.html" title="Array reference data type for arrays located in the message.">L4::Ipc::Array_ref</a><T> &</span> </td><td class="markdownTableBodyLeft"><span class="tt"><a class="el" href="structL4_1_1Ipc_1_1Array__ref.html" title="Array reference data type for arrays located in the message.">L4::Ipc::Array_ref</a><T> &</span> </td></tr>
|
|
</table>
|
|
<p>Finally, there are some optional types where the sender can choose if the parameter should be included in the message. These types are for the implementation of some legacy message formats and should generally not be needed for the definition of ordinary interfaces.</p>
|
|
<table class="markdownTable">
|
|
<tr class="markdownTableHead">
|
|
<th class="markdownTableHeadLeft">Type </th><th class="markdownTableHeadLeft">Direction </th><th class="markdownTableHeadLeft">Client-Type </th><th class="markdownTableHeadLeft">Server-Type </th></tr>
|
|
<tr class="markdownTableRowOdd">
|
|
<td class="markdownTableBodyLeft"><span class="tt"><a class="el" href="structL4_1_1Ipc_1_1Opt.html" title="Attribute for defining an optional RPC argument.">L4::Ipc::Opt</a><T></span> </td><td class="markdownTableBodyLeft">Input </td><td class="markdownTableBodyLeft"><span class="tt"><a class="el" href="structL4_1_1Ipc_1_1Opt.html" title="Attribute for defining an optional RPC argument.">L4::Ipc::Opt</a><T></span> </td><td class="markdownTableBodyLeft"><span class="tt">T</span> </td></tr>
|
|
<tr class="markdownTableRowEven">
|
|
<td class="markdownTableBodyLeft"><span class="tt"><a class="el" href="structL4_1_1Ipc_1_1Opt.html" title="Attribute for defining an optional RPC argument.">L4::Ipc::Opt</a><const T*></span> </td><td class="markdownTableBodyLeft">Input </td><td class="markdownTableBodyLeft"><span class="tt"><a class="el" href="structL4_1_1Ipc_1_1Opt.html" title="Attribute for defining an optional RPC argument.">L4::Ipc::Opt</a><const T*></span> </td><td class="markdownTableBodyLeft"><span class="tt">T</span> </td></tr>
|
|
<tr class="markdownTableRowOdd">
|
|
<td class="markdownTableBodyLeft"><span class="tt"><a class="el" href="structL4_1_1Ipc_1_1Opt.html" title="Attribute for defining an optional RPC argument.">L4::Ipc::Opt</a><T &></span> </td><td class="markdownTableBodyLeft">Output </td><td class="markdownTableBodyLeft"><span class="tt">T &</span> </td><td class="markdownTableBodyLeft"><span class="tt"><a class="el" href="structL4_1_1Ipc_1_1Opt.html" title="Attribute for defining an optional RPC argument.">L4::Ipc::Opt</a><T> &</span> </td></tr>
|
|
<tr class="markdownTableRowEven">
|
|
<td class="markdownTableBodyLeft"><span class="tt"><a class="el" href="structL4_1_1Ipc_1_1Opt.html" title="Attribute for defining an optional RPC argument.">L4::Ipc::Opt</a><T *></span> </td><td class="markdownTableBodyLeft">Output </td><td class="markdownTableBodyLeft"><span class="tt">T *</span> </td><td class="markdownTableBodyLeft"><span class="tt"><a class="el" href="structL4_1_1Ipc_1_1Opt.html" title="Attribute for defining an optional RPC argument.">L4::Ipc::Opt</a><T> &</span> </td></tr>
|
|
<tr class="markdownTableRowOdd">
|
|
<td class="markdownTableBodyLeft"><span class="tt"><a class="el" href="structL4_1_1Ipc_1_1Opt.html" title="Attribute for defining an optional RPC argument.">L4::Ipc::Opt</a><Array_ref<T> &></span> </td><td class="markdownTableBodyLeft">Output </td><td class="markdownTableBodyLeft"><span class="tt">Array_ref<T> &</span> </td><td class="markdownTableBodyLeft"><span class="tt"><a class="el" href="structL4_1_1Ipc_1_1Opt.html" title="Attribute for defining an optional RPC argument.">L4::Ipc::Opt</a><Array_ref<T>> &</span> </td></tr>
|
|
</table>
|
|
<h1 class="doxsection"><a class="anchor" id="l4_cxx_ipc_iface_server_interface"></a>
|
|
Server Side Interface</h1>
|
|
<p>The server side function signature for the Calc example above is </p><div class="fragment"><div class="line"><span class="keywordtype">long</span> op_sub(Calc::Rights, <a class="code hl_typedef" href="group__l4__basic__types.html#gac1d09f3e382e711b776931f10e6e1e5a">l4_uint32_t</a> a, <a class="code hl_typedef" href="group__l4__basic__types.html#gac1d09f3e382e711b776931f10e6e1e5a">l4_uint32_t</a> b, <a class="code hl_typedef" href="group__l4__basic__types.html#gac1d09f3e382e711b776931f10e6e1e5a">l4_uint32_t</a> &res);</div>
|
|
</div><!-- fragment --><p>The first rights parameter is a bitfield encoding the rights the client has on the used capability in the lower two bits. Currently, the W-right and S-right are supported. The rest of the Rights-bitfield is reserved.</p>
|
|
<p>The second and third arguments are input parameters as can be deduced from the tables above. The fourth parameter is an output parameter, delivered to the client with the return value of type long.</p>
|
|
<h1 class="doxsection"><a class="anchor" id="l4_cxx_ipc_iface_return_types"></a>
|
|
RPC Return Types</h1>
|
|
<p>On the server side, the return type of an RPC handling function is always <span class="tt">long</span>. The return value is transmitted via the label field in <a class="el" href="structl4__msgtag__t.html" title="Message tag data structure.">l4_msgtag_t</a> and is therefore restricted to its length. Per convention, a negative return value is interpreted as an error condition. If the return value is negative, output parameters are not transmitted back to the client.</p>
|
|
<dl class="section attention"><dt>Attention</dt><dd>The client must never rely on the content of output parameters when the return value is negative.</dd></dl>
|
|
<p>On the client-side, the return value of the RPC is set as defined in the RPC macro. If <span class="tt"><a class="el" href="structl4__msgtag__t.html" title="Message tag data structure.">l4_msgtag_t</a></span> is given, then the client has access to the full message tag, otherwise the return type should be <span class="tt">long</span>. Note that the client might not only receive the server return value in response but also an IPC error code.</p>
|
|
<h1 class="doxsection"><a class="anchor" id="l4_cxx_ipc_iface_members"></a>
|
|
RPC Method Declaration</h1>
|
|
<p>RPC member functions can be declared using one of the following C++ macros.</p>
|
|
<p>For inline RPC stubs, where the RPC stub code itself is <span class="tt">inline</span>:</p><ul>
|
|
<li><div class="fragment"><div class="line"><a class="code hl_define" href="ipc__iface.html#a5772eb61b611f8f17bbc89e02e534ca1">L4_INLINE_RPC</a>(res, name, (args...), flags)</div>
|
|
</div><!-- fragment --> Define an inline RPC call (type and callable). </li>
|
|
<li><div class="fragment"><div class="line"><a class="code hl_define" href="ipc__iface.html#afd77fe126e97c4d046e3842d948ec91d">L4_INLINE_RPC_OP</a>(op, res, name, (args...), flags)</div>
|
|
<div class="ttc" id="aipc__iface_html_afd77fe126e97c4d046e3842d948ec91d"><div class="ttname"><a href="ipc__iface.html#afd77fe126e97c4d046e3842d948ec91d">L4_INLINE_RPC_OP</a></div><div class="ttdeci">#define L4_INLINE_RPC_OP(op, res, name, args, attr...)</div><div class="ttdoc">Define an inline RPC call with specific opcode (type and callable).</div><div class="ttdef"><b>Definition</b> <a href="ipc__iface_source.html#l00497">ipc_iface:497</a></div></div>
|
|
</div><!-- fragment --> Define an inline RPC call with specific opcode (type and callable). </li>
|
|
<li><div class="fragment"><div class="line"><a class="code hl_define" href="ipc__iface.html#a7bc5bdbe269ef0598c166ed1dd923549">L4_INLINE_RPC_NF</a>(res, name, (args...), flags)</div>
|
|
<div class="ttc" id="aipc__iface_html_a7bc5bdbe269ef0598c166ed1dd923549"><div class="ttname"><a href="ipc__iface.html#a7bc5bdbe269ef0598c166ed1dd923549">L4_INLINE_RPC_NF</a></div><div class="ttdeci">#define L4_INLINE_RPC_NF(res, name, args...)</div><div class="ttdoc">Define an inline RPC call type (the type only, no callable).</div><div class="ttdef"><b>Definition</b> <a href="ipc__iface_source.html#l00453">ipc_iface:453</a></div></div>
|
|
</div><!-- fragment --> Define an inline RPC call type (the type only, no callable). </li>
|
|
<li><div class="fragment"><div class="line"><a class="code hl_define" href="ipc__iface.html#a9c231340e92b2868f1b85b302fb2b159">L4_INLINE_RPC_NF_OP</a>(opcode, Ret_type, func_name, (args...), flags)</div>
|
|
<div class="ttc" id="aipc__iface_html_a9c231340e92b2868f1b85b302fb2b159"><div class="ttname"><a href="ipc__iface.html#a9c231340e92b2868f1b85b302fb2b159">L4_INLINE_RPC_NF_OP</a></div><div class="ttdeci">#define L4_INLINE_RPC_NF_OP(op, res, name, args...)</div><div class="ttdoc">Define an inline RPC call type with specific opcode (the type only, no callable).</div><div class="ttdef"><b>Definition</b> <a href="ipc__iface_source.html#l00466">ipc_iface:466</a></div></div>
|
|
</div><!-- fragment --> Define an inline RPC call type with specific opcode (the type only, no callable). </li>
|
|
</ul>
|
|
<p>For external RPC stubs, where the RPC stub code must be defined in a separate compile unit (usually a <span class="tt">.cc</span> file):</p><ul>
|
|
<li><div class="fragment"><div class="line"><a class="code hl_define" href="ipc__iface.html#a5e5588cacb2659f18f48ae49c2beb800">L4_RPC</a>(Ret_type, func_name, (args...), flags)</div>
|
|
</div><!-- fragment --> Define an RPC call (type and callable). </li>
|
|
<li><div class="fragment"><div class="line"><a class="code hl_define" href="ipc__iface.html#a0264d26151de8ed0903379a035c223bb">L4_RPC_OP</a>(opcode, Ret_type, func_name, (args...), flags)</div>
|
|
<div class="ttc" id="aipc__iface_html_a0264d26151de8ed0903379a035c223bb"><div class="ttname"><a href="ipc__iface.html#a0264d26151de8ed0903379a035c223bb">L4_RPC_OP</a></div><div class="ttdeci">#define L4_RPC_OP(op, res, name, args, attr...)</div><div class="ttdoc">Define an RPC call with specific opcode (type and callable).</div><div class="ttdef"><b>Definition</b> <a href="ipc__iface_source.html#l00556">ipc_iface:556</a></div></div>
|
|
</div><!-- fragment --> Define an RPC call with specific opcode (type and callable). </li>
|
|
<li><div class="fragment"><div class="line"><a class="code hl_define" href="ipc__iface.html#ada755c1db9f58471fc483ccfbed1f518">L4_RPC_NF</a>(Ret_type, func_name, (args...), flags)</div>
|
|
<div class="ttc" id="aipc__iface_html_ada755c1db9f58471fc483ccfbed1f518"><div class="ttname"><a href="ipc__iface.html#ada755c1db9f58471fc483ccfbed1f518">L4_RPC_NF</a></div><div class="ttdeci">#define L4_RPC_NF(res, name, args...)</div><div class="ttdoc">Define an RPC call type (the type only, no callable).</div><div class="ttdef"><b>Definition</b> <a href="ipc__iface_source.html#l00510">ipc_iface:510</a></div></div>
|
|
</div><!-- fragment --> Define an RPC call type (the type only, no callable). </li>
|
|
<li><div class="fragment"><div class="line"><a class="code hl_define" href="ipc__iface.html#aaf74b7e287f17aa9629ac694bbe6bc39">L4_RPC_NF_OP</a>(opcode, Ret_type, func_name, (args...), flags)</div>
|
|
<div class="ttc" id="aipc__iface_html_aaf74b7e287f17aa9629ac694bbe6bc39"><div class="ttname"><a href="ipc__iface.html#aaf74b7e287f17aa9629ac694bbe6bc39">L4_RPC_NF_OP</a></div><div class="ttdeci">#define L4_RPC_NF_OP(op, res, name, args...)</div><div class="ttdoc">Define an RPC call type with specific opcode (the type only, no callable).</div><div class="ttdef"><b>Definition</b> <a href="ipc__iface_source.html#l00525">ipc_iface:525</a></div></div>
|
|
</div><!-- fragment --> Define an RPC call type with specific opcode (the type only, no callable). </li>
|
|
</ul>
|
|
<p>To generate the implementation of an external RPC stub:</p><ul>
|
|
<li><div class="fragment"><div class="line"><a class="code hl_define" href="ipc__client.html#aebfe730f4231dc11a7a1998acc6e4ab6">L4_RPC_DEF</a>(class_name::func_name)</div>
|
|
<div class="ttc" id="aipc__client_html_aebfe730f4231dc11a7a1998acc6e4ab6"><div class="ttname"><a href="ipc__client.html#aebfe730f4231dc11a7a1998acc6e4ab6">L4_RPC_DEF</a></div><div class="ttdeci">#define L4_RPC_DEF(name)</div><div class="ttdoc">Generate the definition of an RPC stub.</div><div class="ttdef"><b>Definition</b> <a href="ipc__client_source.html#l00032">ipc_client:32</a></div></div>
|
|
</div><!-- fragment --> Generate the definition of an RPC stub. </li>
|
|
</ul>
|
|
<p>The <span class="tt">NF</span> versions of the macro generally do not generate a callable member function named <span class="tt"><name></span> but do only generate the type <span class="tt"><name>_t</span>. This data type can be used to call the RPC stub explicitly using <span class="tt"><name>_t::call(<a class="el" href="classL4_1_1Cap.html" title="C++ interface for capabilities.">L4::Cap</a><Iface_class> cap, args...)</span>. </p>
|
|
</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>
|