blob: ca165b2bfcba90ccce47704ec49237f068a0b140 [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://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"/>
<title>Memory Management</title>
<title>CMSIS-RTOS2: Memory Management</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="cmsis.css" rel="stylesheet" type="text/css" />
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<script type="text/javascript" src="printComponentTabs.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
$(document).ready(initResizable);
$(window).load(resizeHeight);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
$(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
</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: 46px;">
<td id="projectlogo"><img alt="Logo" src="CMSIS_Logo_Final.png"/></td>
<td style="padding-left: 0.5em;">
<div id="projectname">CMSIS-RTOS2
&#160;<span id="projectnumber">Version 2.1.3</span>
</div>
<div id="projectbrief">Real-Time Operating System: API and RTX Reference Implementation</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<div id="CMSISnav" class="tabs1">
<ul class="tablist">
<script type="text/javascript">
<!--
writeComponentTabs.call(this);
//-->
</script>
</ul>
</div>
<!-- Generated by Doxygen 1.8.6 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main&#160;Page</span></a></li>
<li><a href="pages.html"><span>Usage&#160;and&#160;Description</span></a></li>
<li><a href="modules.html"><span>Reference</span></a></li>
<li>
<div id="MSearchBox" class="MSearchBoxInactive">
<span class="left">
<img id="MSearchSelect" src="search/mag_sel.png"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
alt=""/>
<input type="text" id="MSearchField" value="Search" accesskey="S"
onfocus="searchBox.OnSearchFieldFocus(true)"
onblur="searchBox.OnSearchFieldFocus(false)"
onkeyup="searchBox.OnSearchFieldChange(event)"/>
</span><span class="right">
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
</span>
</div>
</li>
</ul>
</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">
$(document).ready(function(){initNavTree('group__CMSIS__RTOS__MemoryMgmt.html','');});
</script>
<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)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark">&#160;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&#160;</span>Data Structures</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark">&#160;</span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark">&#160;</span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark">&#160;</span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&#160;</span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark">&#160;</span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark">&#160;</span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark">&#160;</span>Macros</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(9)"><span class="SelectionMark">&#160;</span>Groups</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(10)"><span class="SelectionMark">&#160;</span>Pages</a></div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<div class="header">
<div class="headertitle">
<div class="title">Memory Management<div class="ingroups"><a class="el" href="group__CMSIS__RTOS.html">CMSIS-RTOS API v2</a></div></div> </div>
</div><!--header-->
<div class="contents">
<p>Information about memory management possibilities.
<a href="#details">More...</a></p>
<p>The <a class="el" href="group__CMSIS__RTOS.html">CMSIS-RTOS API v2</a> offers two options for memory management the user can choose. For object storage one can either use</p>
<ul>
<li><a class="el" href="group__CMSIS__RTOS__MemoryMgmt.html#CMSIS_RTOS_MemoryMgmt_Automatic">Automatic Dynamic Allocation</a> (fully portable), or</li>
<li><a class="el" href="group__CMSIS__RTOS__MemoryMgmt.html#CMSIS_RTOS_MemoryMgmt_Manual">Manual User-defined Allocation</a> (implementation specific).</li>
</ul>
<p>In order to affect the memory allocation scheme all RTOS objects that can be created on request, i.e. those having a <code>osXxxNew</code> function, accept an optional <code>osXxxAttr_t attr</code> argument on creation. As a rule of thumb the object attributes at least have members to assign custom control block memory, i.e. <code>cb_mem</code> and <code>cb_size</code> members. By default, i.e. <code>attr</code> is <code>NULL</code> or <code>cb_mem</code> is <code>NULL</code>, <a class="el" href="group__CMSIS__RTOS__MemoryMgmt.html#CMSIS_RTOS_MemoryMgmt_Automatic">Automatic Dynamic Allocation</a> is used. Providing a pointer to user memory in <code>cb_mem</code> switches to <a class="el" href="group__CMSIS__RTOS__MemoryMgmt.html#CMSIS_RTOS_MemoryMgmt_Manual">Manual User-defined Allocation</a>.</p>
<dl class="section note"><dt>Note</dt><dd>For detailed information about memory allocation strategies provided in RTX5 refer to <a class="el" href="theory_of_operation.html#MemoryAllocation">Memory Allocation</a>.</dd></dl>
<h1><a class="anchor" id="CMSIS_RTOS_MemoryMgmt_Automatic"></a>
Automatic Dynamic Allocation</h1>
<p>The automatic allocation is the default and viable for many use-cases. Moreover it is fully portable across different implementations of the <a class="el" href="group__CMSIS__RTOS.html">CMSIS-RTOS API v2</a>. The common drawback of dynamic memory allocation is the possibility of memory fragmentation and exhaustion. Given that all needed objects are created once upon system initialization and never deleted at runtime this class of runtime failures can be prevented, though.</p>
<p>The actual allocation strategy used is implementation specific, i.e. whether global heap or preallocated memory pools are used.</p>
<p><b> Code Example:</b> </p>
<div class="fragment"><div class="line"><span class="preprocessor">#include &quot;<a class="code" href="cmsis__os2_8h.html">cmsis_os2.h</a>&quot;</span> <span class="comment">// implementation agnostic</span></div>
<div class="line"> </div>
<div class="line"><a class="code" href="group__CMSIS__RTOS__MutexMgmt.html#ga313801836c62deb23055efb55a420e42">osMutexId_t</a> mutex_id;</div>
<div class="line"><a class="code" href="group__CMSIS__RTOS__MutexMgmt.html#ga313801836c62deb23055efb55a420e42">osMutexId_t</a> mutex2_id;</div>
<div class="line"> </div>
<div class="line"><span class="keyword">const</span> <a class="code" href="group__CMSIS__RTOS__MutexMgmt.html#structosMutexAttr__t">osMutexAttr_t</a> Thread_Mutex_attr = {</div>
<div class="line"> <span class="stringliteral">&quot;myThreadMutex&quot;</span>, <span class="comment">// human readable mutex name</span></div>
<div class="line"> <a class="code" href="group__CMSIS__RTOS__MutexMgmt.html#ga65c2482cc64a35d03871f3180f305926">osMutexRecursive</a> | <a class="code" href="group__CMSIS__RTOS__MutexMgmt.html#ga40fba270cb31a977b3bd551d41eb9599">osMutexPrioInherit</a>, <span class="comment">// attr_bits</span></div>
<div class="line"> NULL, <span class="comment">// memory for control block (default)</span></div>
<div class="line"> 0U <span class="comment">// size for control block (default)</span></div>
<div class="line">};</div>
<div class="line"> </div>
<div class="line"><span class="keywordtype">void</span> CreateMutex (<span class="keywordtype">void</span>) {</div>
<div class="line"> mutex_id = <a class="code" href="group__CMSIS__RTOS__MutexMgmt.html#gab90920022ab944296821368ef6bb52f8">osMutexNew</a>(NULL); <span class="comment">// use default values for all attributes</span></div>
<div class="line"> mutex2_id = <a class="code" href="group__CMSIS__RTOS__MutexMgmt.html#gab90920022ab944296821368ef6bb52f8">osMutexNew</a>(&amp;Thread_Mutex_attr); <span class="comment">// use attributes from defined structure</span></div>
<div class="line"> :</div>
<div class="line">}</div>
</div><!-- fragment --><p>The Mutexes in this example are created using automatic memory allocation.</p>
<h1><a class="anchor" id="CMSIS_RTOS_MemoryMgmt_Manual"></a>
Manual User-defined Allocation</h1>
<p>One can get fine grained control over memory allocation by providing user-defined memory. The actual requirements such user-defined memory are implementation specific. Thus one needs to carefully refer to the size and alignment rules of the implementation used, e.g. for RTX see <a class="el" href="theory_of_operation.html#StaticObjectMemory">Static Object Memory</a>.</p>
<p><b> Code Example:</b> </p>
<div class="fragment"><div class="line"><span class="preprocessor">#include &quot;<a class="code" href="rtx__os_8h.html">rtx_os.h</a>&quot;</span> <span class="comment">// implementation specific</span></div>
<div class="line"> </div>
<div class="line"><a class="code" href="group__CMSIS__RTOS__MutexMgmt.html#ga313801836c62deb23055efb55a420e42">osMutexId_t</a> mutex_id;</div>
<div class="line"> </div>
<div class="line"><span class="keyword">static</span> <a class="code" href="rtx__os_8h.html#structosRtxMutex__t">osRtxMutex_t</a> mutex_cb __attribute__((section(<span class="stringliteral">&quot;.bss.os.mutex.cb&quot;</span>))); <span class="comment">// Placed on .bss.os.mutex.cb section for RTX5 aware debugging</span></div>
<div class="line"> </div>
<div class="line"><span class="keyword">const</span> <a class="code" href="group__CMSIS__RTOS__MutexMgmt.html#structosMutexAttr__t">osMutexAttr_t</a> Thread_Mutex_attr = {</div>
<div class="line"> <span class="stringliteral">&quot;myThreadMutex&quot;</span>, <span class="comment">// human readable mutex name</span></div>
<div class="line"> <a class="code" href="group__CMSIS__RTOS__MutexMgmt.html#ga65c2482cc64a35d03871f3180f305926">osMutexRecursive</a> | <a class="code" href="group__CMSIS__RTOS__MutexMgmt.html#ga40fba270cb31a977b3bd551d41eb9599">osMutexPrioInherit</a>, <span class="comment">// attr_bits</span></div>
<div class="line"> &amp;mutex_cb, <span class="comment">// memory for control block (user-defined)</span></div>
<div class="line"> <span class="keyword">sizeof</span>(mutex_cb) <span class="comment">// size for control block (user-defined)</span></div>
<div class="line">};</div>
<div class="line"> </div>
<div class="line"><span class="keywordtype">void</span> CreateMutex (<span class="keywordtype">void</span>) {</div>
<div class="line"> mutex_id = <a class="code" href="group__CMSIS__RTOS__MutexMgmt.html#gab90920022ab944296821368ef6bb52f8">osMutexNew</a>(&amp;Thread_Mutex_attr); <span class="comment">// use attributes from defined structure</span></div>
<div class="line"> :</div>
<div class="line">}</div>
</div><!-- fragment --><p>The above example uses user-defined memory for the mutex control block. Depending on the actual implementation used one needs to include the specific header file, <code><a class="el" href="rtx__os_8h.html">rtx_os.h</a></code> in this case. </p>
</div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="footer">Generated on Wed Jul 10 2019 15:21:04 for CMSIS-RTOS2 Version 2.1.3 by Arm Ltd. All rights reserved.
<!--
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.6
-->
</li>
</ul>
</div>
</body>
</html>