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

249 lines
21 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: L4::Kobject Class Reference</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('classL4_1_1Kobject.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 class="header">
<div class="headertitle"><div class="title">L4::Kobject Class Reference<div class="ingroups"><a class="el" href="group__l4__api.html">Base API</a> &raquo; <a class="el" href="group__l4__kernel__object__api.html">Kernel Objects</a></div></div></div>
</div><!--header-->
<div class="contents">
<p>Base class for all kinds of kernel objects and remote objects, referenced by capabilities.
<a href="#details">More...</a></p>
<p><code>#include &lt;<a class="el" href="kobject_source.html">kobject</a>&gt;</code></p>
<div id="dynsection-0" onclick="return dynsection.toggleVisibility(this)" class="dynheader closed" style="cursor:pointer;"><span class="dynarrow"><span class="arrowhead closed"></span></span>Inheritance diagram for L4::Kobject:</div>
<div id="dynsection-0-summary" class="dynsummary" style="display:block;">
</div>
<div id="dynsection-0-content" class="dyncontent" style="display:none;">
<div class="center"><iframe scrolling="no" loading="lazy" frameborder="0" src="classL4_1_1Kobject__inherit__graph.svg" width="5270" height="918"><p><b>This browser is not able to show SVG: try Firefox, Chrome, Safari, or Opera instead.</b></p></iframe></div>
</div>
<div id="dynsection-1" onclick="return dynsection.toggleVisibility(this)" class="dynheader closed" style="cursor:pointer;"><span class="dynarrow"><span class="arrowhead closed"></span></span>Collaboration diagram for L4::Kobject:</div>
<div id="dynsection-1-summary" class="dynsummary" style="display:block;">
</div>
<div id="dynsection-1-content" class="dyncontent" style="display:none;">
<div class="center"><iframe scrolling="no" loading="lazy" frameborder="0" src="classL4_1_1Kobject__coll__graph.svg" width="118" height="96"><p><b>This browser is not able to show SVG: try Firefox, Chrome, Safari, or Opera instead.</b></p></iframe></div>
</div>
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 id="header-pub-methods" class="groupheader"><a id="pub-methods" name="pub-methods"></a>
Public Member Functions</h2></td></tr>
<tr class="memitem:a9fe009599de49f1af438ff49998faec0" id="r_a9fe009599de49f1af438ff49998faec0"><td class="memItemLeft" align="right" valign="top"><a class="el" href="structl4__msgtag__t.html">l4_msgtag_t</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#a9fe009599de49f1af438ff49998faec0">dec_refcnt</a> (<a class="el" href="group__l4__basic__types.html#ga51d9492e7700d70ed35838154ca9b279">l4_mword_t</a> diff, <a class="el" href="group__l4__utcb__api.html#ga89be8a86d11c1d532b636cc2df1330fb">l4_utcb_t</a> *utcb=<a class="el" href="group__l4__utcb__api.html#gadc099b4a59e1d99638c72c11a8c8b644">l4_utcb</a>())</td></tr>
<tr class="memdesc:a9fe009599de49f1af438ff49998faec0"><td class="mdescLeft">&#160;</td><td class="mdescRight">Decrement the in kernel reference counter for the object. <br /></td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 id="header-pro-methods" class="groupheader"><a id="pro-methods" name="pro-methods"></a>
Protected Member Functions</h2></td></tr>
<tr class="memitem:a4f2117ae76762f4084e6a1adb915863c" id="r_a4f2117ae76762f4084e6a1adb915863c"><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__l4__cap__api.html#ga1445e923ce73029130d569d6e69a4dd8">l4_cap_idx_t</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#a4f2117ae76762f4084e6a1adb915863c">cap</a> () const noexcept</td></tr>
<tr class="memdesc:a4f2117ae76762f4084e6a1adb915863c"><td class="mdescLeft">&#160;</td><td class="mdescRight">Return capability selector. <br /></td></tr>
</table>
<a name="details" id="details"></a><h2 id="header-details" class="groupheader">Detailed Description</h2>
<div class="textblock"><p>Base class for all kinds of kernel objects and remote objects, referenced by capabilities. </p>
<dl class="section user"><dt>Include File</dt><dd><div class="fragment"><div class="line"><span class="preprocessor">#include &lt;<a class="code" href="capability.html">l4/sys/capability</a>&gt;</span> </div>
<div class="ttc" id="acapability_html"><div class="ttname"><a href="capability.html">capability</a></div><div class="ttdoc">L4::Cap related definitions.</div></div>
</div><!-- fragment --></dd></dl>
<p>This is the base class for all remote objects accessible using RPC. However, subclasses do not directly inherit from <a class="el" href="classL4_1_1Kobject.html" title="Base class for all kinds of kernel objects and remote objects, referenced by capabilities.">L4::Kobject</a> but <em>must</em> use <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> (L4::Kobject_0t, <a class="el" href="classL4_1_1Kobject__2t.html" title="Helper class to create an L4Re interface class that is derived from two base classes (see L4::Kobject...">L4::Kobject_2t</a>, <a class="el" href="structL4_1_1Kobject__3t.html" title="Helper class to create an L4Re interface class that is derived from three base classes (see L4::Kobje...">L4::Kobject_3t</a>, or <a class="el" href="structL4_1_1Kobject__x.html" title="Generic Kobject inheritance template.">L4::Kobject_x</a>) for inheritance, otherwise these classes cannot be used as RPC interfaces.</p>
<dl class="section attention"><dt>Attention</dt><dd>Objects derived from <a class="el" href="classL4_1_1Kobject.html" title="Base class for all kinds of kernel objects and remote objects, referenced by capabilities.">Kobject</a> <em>must</em> never add any data to those objects. Kobjects can act only as proxy object for encapsulating object invocations. </dd></dl>
<p class="definition">Definition at line <a class="el" href="kobject_source.html#l00036">36</a> of file <a class="el" href="kobject_source.html">kobject</a>.</p>
</div><a name="doc-func-members" id="doc-func-members"></a><h2 id="header-doc-func-members" class="groupheader">Member Function Documentation</h2>
<a id="a4f2117ae76762f4084e6a1adb915863c" name="a4f2117ae76762f4084e6a1adb915863c"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a4f2117ae76762f4084e6a1adb915863c">&#9670;&#160;</a></span>cap()</h2>
<div class="memitem">
<div class="memproto">
<table class="mlabels">
<tr>
<td class="mlabels-left">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="group__l4__cap__api.html#ga1445e923ce73029130d569d6e69a4dd8">l4_cap_idx_t</a> L4::Kobject::cap </td>
<td>(</td>
<td class="paramname"><span class="paramname"><em></em></span></td><td>)</td>
<td> const</td>
</tr>
</table>
</td>
<td class="mlabels-right">
<span class="mlabels"><span class="mlabel inline">inline</span><span class="mlabel protected">protected</span><span class="mlabel noexcept">noexcept</span></span> </td>
</tr>
</table>
</div><div class="memdoc">
<p>Return capability selector. </p>
<dl class="section return"><dt>Returns</dt><dd>Capability selector.</dd></dl>
<p>This method is for derived classes to gain access to the actual capability selector. </p>
<p class="definition">Definition at line <a class="el" href="kobject_source.html#l00069">69</a> of file <a class="el" href="kobject_source.html">kobject</a>.</p>
<p class="reference">Referenced by <a class="el" href="thread__group_source.html#l00053">L4::Thread_group::add()</a>, <a class="el" href="debugger_source.html#l00161">L4::Debugger::add_image_info()</a>, <a class="el" href="task_source.html#l00281">L4::Task::add_ku_mem()</a>, <a class="el" href="mem__alloc__impl_8h_source.html#l00024">L4Re::Mem_alloc::alloc()</a>, <a class="el" href="vbus_source.html#l00382">L4vbus::Vbus::assign_dma_domain()</a>, <a class="el" href="vbus_source.html#l00357">L4vbus::Vbus::assign_dma_domain()</a>, <a class="el" href="irq_source.html#l00310">L4::Icu::bind()</a>, <a class="el" href="rcv__endpoint_source.html#l00101">L4::Rcv_endpoint::bind_snd_destination()</a>, <a class="el" href="irq_source.html#l00158">L4::Irq::bind_vcpu()</a>, <a class="el" href="task_source.html#l00251">L4::Task::cap_equal()</a>, <a class="el" href="task_source.html#l00222">L4::Task::cap_valid()</a>, <a class="el" href="sys_2thread_source.html#l00243">L4::Thread::control()</a>, <a class="el" href="factory_source.html#l00329">L4::Factory::create()</a>, <a class="el" href="factory_source.html#l00292">L4::Factory::create()</a>, <a class="el" href="factory_source.html#l00404">L4::Factory::create_factory()</a>, <a class="el" href="factory_source.html#l00440">L4::Factory::create_gate()</a>, <a class="el" href="factory_source.html#l00370">L4::Factory::create_task()</a>, <a class="el" href="factory_source.html#l00475">L4::Factory::create_thread_group()</a>, <a class="el" href="goos_source.html#l00312">L4Re::Video::Goos::create_view()</a>, <a class="el" href="kobject_source.html#l00100">dec_refcnt()</a>, <a class="el" href="task_source.html#l00180">L4::Task::delete_obj()</a>, <a class="el" href="irq_source.html#l00176">L4::Irq::detach()</a>, <a class="el" href="semaphore_source.html#l00089">L4::Semaphore::down()</a>, <a class="el" href="sys_2thread_source.html#l00119">L4::Thread::ex_regs()</a>, <a class="el" href="sys_2thread_source.html#l00084">L4::Thread::ex_regs()</a>, <a class="el" href="vcon_source.html#l00151">L4::Vcon::get_attr()</a>, <a class="el" href="debugger_source.html#l00148">L4::Debugger::get_object_name()</a>, <a class="el" href="debugger_source.html#l00071">L4::Debugger::global_id()</a>, <a class="el" href="irq_source.html#l00345">L4::Icu::info()</a>, <a class="el" href="scheduler_source.html#l00154">L4::Scheduler::is_online()</a>, <a class="el" href="debugger_source.html#l00083">L4::Debugger::kobj_to_id()</a>, <a class="el" href="task_source.html#l00085">L4::Task::map()</a>, <a class="el" href="irq_source.html#l00393">L4::Icu::mask()</a>, <a class="el" href="sys_2thread_source.html#l00525">L4::Thread::modify_senders()</a>, <a class="el" href="debugger_source.html#l00116">L4::Debugger::query_log_name()</a>, <a class="el" href="debugger_source.html#l00097">L4::Debugger::query_log_typeid()</a>, <a class="el" href="vcon_source.html#l00098">L4::Vcon::read()</a>, <a class="el" href="vcon_source.html#l00125">L4::Vcon::read_with_flags()</a>, <a class="el" href="irq_source.html#l00191">L4::Irq::receive()</a>, <a class="el" href="sys_2thread_source.html#l00427">L4::Thread::register_del_irq()</a>, <a class="el" href="sys_2thread_source.html#l00553">L4::Thread::register_doorbell_irq()</a>, <a class="el" href="task_source.html#l00201">L4::Task::release_cap()</a>, <a class="el" href="vbus_source.html#l00323">L4vbus::Vbus::release_ioport()</a>, <a class="el" href="thread__group_source.html#l00067">L4::Thread_group::remove()</a>, <a class="el" href="vbus_source.html#l00311">L4vbus::Vbus::request_ioport()</a>, <a class="el" href="vbus_source.html#l00336">L4vbus::Vbus::root()</a>, <a class="el" href="vcon_source.html#l00065">L4::Vcon::send()</a>, <a class="el" href="vcon_source.html#l00138">L4::Vcon::set_attr()</a>, <a class="el" href="irq_source.html#l00421">L4::Icu::set_mode()</a>, <a class="el" href="debugger_source.html#l00059">L4::Debugger::set_object_name()</a>, <a class="el" href="sys_2thread_source.html#l00264">L4::Thread::stats_time()</a>, <a class="el" href="debugger_source.html#l00133">L4::Debugger::switch_log()</a>, <a class="el" href="sys_2thread_source.html#l00253">L4::Thread::switch_to()</a>, <a class="el" href="irq_source.html#l00091">L4::Triggerable::trigger()</a>, <a class="el" href="irq_source.html#l00328">L4::Icu::unbind()</a>, <a class="el" href="task_source.html#l00135">L4::Task::unmap()</a>, <a class="el" href="task_source.html#l00154">L4::Task::unmap_batch()</a>, <a class="el" href="irq_source.html#l00064">L4::Irq_eoi::unmask()</a>, <a class="el" href="sys_2thread_source.html#l00358">L4::Thread::vcpu_control()</a>, <a class="el" href="sys_2thread_source.html#l00398">L4::Thread::vcpu_control_ext()</a>, <a class="el" href="sys_2thread_source.html#l00334">L4::Thread::vcpu_resume_commit()</a>, <a class="el" href="____vm-arm_8h_source.html#l00030">L4::Vm::vgicc_map()</a>, <a class="el" href="goos_source.html#l00363">L4Re::Video::Goos::view()</a>, and <a class="el" href="vcon_source.html#l00079">L4::Vcon::write()</a>.</p>
<div id="dynsection-2" onclick="return dynsection.toggleVisibility(this)" class="dynheader closed" style="cursor:pointer;"><span class="dynarrow"><span class="arrowhead closed"></span></span>Here is the caller graph for this function:</div>
<div id="dynsection-2-summary" class="dynsummary" style="display:block;">
</div>
<div id="dynsection-2-content" class="dyncontent" style="display:none;">
<div class="center"><iframe scrolling="no" loading="lazy" frameborder="0" src="classL4_1_1Kobject_a4f2117ae76762f4084e6a1adb915863c_icgraph.svg" width="902" height="3406"><p><b>This browser is not able to show SVG: try Firefox, Chrome, Safari, or Opera instead.</b></p></iframe></div>
</div>
</div>
</div>
<a id="a9fe009599de49f1af438ff49998faec0" name="a9fe009599de49f1af438ff49998faec0"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a9fe009599de49f1af438ff49998faec0">&#9670;&#160;</a></span>dec_refcnt()</h2>
<div class="memitem">
<div class="memproto">
<table class="mlabels">
<tr>
<td class="mlabels-left">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="structl4__msgtag__t.html">l4_msgtag_t</a> L4::Kobject::dec_refcnt </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__l4__basic__types.html#ga51d9492e7700d70ed35838154ca9b279">l4_mword_t</a></td> <td class="paramname"><span class="paramname"><em>diff</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="group__l4__utcb__api.html#ga89be8a86d11c1d532b636cc2df1330fb">l4_utcb_t</a> *</td> <td class="paramname"><span class="paramname"><em>utcb</em></span><span class="paramdefsep"> = </span><span class="paramdefval"><a class="el" href="group__l4__utcb__api.html#gadc099b4a59e1d99638c72c11a8c8b644">l4_utcb</a>()</span>&#160;)</td>
</tr>
</table>
</td>
<td class="mlabels-right">
<span class="mlabels"><span class="mlabel inline">inline</span></span> </td>
</tr>
</table>
</div><div class="memdoc">
<p>Decrement the in kernel reference counter for the object. </p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">diff</td><td>The delta that shall be subtracted from the reference count. </td></tr>
<tr><td class="paramname">utcb</td><td>UTCB to be used for this operation, shall be the UTCB of the calling thread. See <a class="el" href="group__l4__utcb__api.html#gadc099b4a59e1d99638c72c11a8c8b644" title="Get the UTCB address.">l4_utcb</a>.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Syscall return tag</dd></dl>
<p>This function is intended for servers to be able to remove the servers own capability from the counted references. This leads to the semantics that the kernel will delete the object even if the capability of the server is valid. The server can detect the deletion by polling its capabilities or by using the IPC-gate deletion IRQs. And to cleanup if the clients dropped the last reference (capability) to the object.</p>
<p>This function only succeeds on a kernel object of type <a class="el" href="classL4_1_1Ipc__gate.html" title="The C++ IPC gate interface, see IPC-Gate API for the C interface.">L4::Ipc_gate</a> which has the server right (<a class="el" href="group__l4__msgitem__api.html#ggad142e99a533af52d358f9940fa00966aa8436980325edd409d8aa71e1ef567bc4" title="The receiver may invoke IPC-gate-specific functions on the capability, e.g.">L4_FPAGE_C_IPCGATE_SVR</a>). For other kernel objects, -L4_ENOSYS is returned. </p>
<p class="definition">Definition at line <a class="el" href="kobject_source.html#l00100">100</a> of file <a class="el" href="kobject_source.html">kobject</a>.</p>
<p class="reference">References <a class="el" href="kobject_source.html#l00069">cap()</a>.</p>
<div id="dynsection-3" onclick="return dynsection.toggleVisibility(this)" class="dynheader closed" style="cursor:pointer;"><span class="dynarrow"><span class="arrowhead closed"></span></span>Here is the call graph for this function:</div>
<div id="dynsection-3-summary" class="dynsummary" style="display:block;">
</div>
<div id="dynsection-3-content" class="dyncontent" style="display:none;">
<div class="center"><iframe scrolling="no" loading="lazy" frameborder="0" src="classL4_1_1Kobject_a9fe009599de49f1af438ff49998faec0_cgraph.svg" width="352" height="36"><p><b>This browser is not able to show SVG: try Firefox, Chrome, Safari, or Opera instead.</b></p></iframe></div>
</div>
</div>
</div>
<hr/>The documentation for this class was generated from the following file:<ul>
<li>l4/sys/<a class="el" href="kobject_source.html">kobject</a></li>
</ul>
</div><!-- contents -->
</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="namespaceL4.html">L4</a></li><li class="navelem"><a href="classL4_1_1Kobject.html">Kobject</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>