begriffs open source - cmsis/blob - main/RTOS2/html/group__CMSIS__RTOS__MemoryMgmt.html

   1 <!-- HTML header for doxygen 1.9.6-->
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
   4 <head>
   5 <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
   6 <meta http-equiv="X-UA-Compatible" content="IE=11"/>
   7 <meta name="viewport" content="width=device-width, initial-scale=1"/>
   8 <title>CMSIS-RTOS2: Memory Management</title>
   9 <link href="doxygen.css" rel="stylesheet" type="text/css"/>
  10 <link href="tabs.css" rel="stylesheet" type="text/css"/>
  11 <link href="extra_navtree.css" rel="stylesheet" type="text/css"/>
  12 <link href="extra_stylesheet.css" rel="stylesheet" type="text/css"/>
  13 <link href="extra_search.css" rel="stylesheet" type="text/css"/>
  14 <script type="text/javascript" src="jquery.js"></script>
  15 <script type="text/javascript" src="dynsections.js"></script>
  16 <script type="text/javascript" src="printComponentTabs.js"></script>
  17 <script type="text/javascript" src="footer.js"></script>
  18 <script type="text/javascript" src="navtree.js"></script>
  19 <link href="navtree.css" rel="stylesheet" type="text/css"/>
  20 <script type="text/javascript" src="resize.js"></script>
  21 <script type="text/javascript" src="navtreedata.js"></script>
  22 <script type="text/javascript" src="navtree.js"></script>
  23 <link href="search/search.css" rel="stylesheet" type="text/css"/>
  24 <script type="text/javascript" src="search/searchdata.js"></script>
  25 <script type="text/javascript" src="search/search.js"></script>
  26 <script type="text/javascript">
  27 /* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
  28   $(document).ready(function() { init_search(); });
  29 /* @license-end */
  30 </script>
  31 <script type="text/javascript" src="darkmode_toggle.js"></script>
  32 <link href="extra_stylesheet.css" rel="stylesheet" type="text/css"/>
  33 <link href="extra_navtree.css" rel="stylesheet" type="text/css"/>
  34 <link href="extra_search.css" rel="stylesheet" type="text/css"/>
  35 <link href="version.css" rel="stylesheet" type="text/css" />
  36 <script type="text/javascript" src="../../../version.js"></script>
  37 </head>
  38 <body>
  39 <div id="top"><!-- do not remove this div, it is closed by doxygen! -->
  40 <div id="titlearea">
  41 <table cellspacing="0" cellpadding="0">
  42  <tbody>
  43  <tr style="height: 55px;">
  44   <td id="projectlogo" style="padding: 1.5em;"><img alt="Logo" src="cmsis_logo_white_small.png"/></td>
  45   <td style="padding-left: 1em; padding-bottom: 1em;padding-top: 1em;">
  46    <div id="projectname">CMSIS-RTOS2
  47    &#160;<span id="projectnumber"><script type="text/javascript">
  48      <!--
  49      writeHeader.call(this);
  50      writeVersionDropdown.call(this);
  51      //-->
  52     </script>
  53    </span>
  54    </div>
  55    <div id="projectbrief">Real-Time Operating System API</div>
  56   </td>
  57    <td>        <div id="MSearchBox" class="MSearchBoxInactive">
  58         <span class="left">
  59           <span id="MSearchSelect"                onmouseover="return searchBox.OnSearchSelectShow()"                onmouseout="return searchBox.OnSearchSelectHide()">&#160;</span>
  60           <input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"
  61                onfocus="searchBox.OnSearchFieldFocus(true)"
  62                onblur="searchBox.OnSearchFieldFocus(false)"
  63                onkeyup="searchBox.OnSearchFieldChange(event)"/>
  64           </span><span class="right">
  65             <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.svg" alt=""/></a>
  66           </span>
  67         </div>
  68 </td>
  69   <!--END !PROJECT_NAME-->
  70  </tr>
  71  </tbody>
  72 </table>
  73 </div>
  74 <!-- end header part -->
  75 <div id="CMSISnav" class="tabs1">
  76   <ul class="tablist">
  77     <script type="text/javascript">
  78       writeComponentTabs.call(this);
  79     </script>
  80   </ul>
  81 </div>
  82 <script type="text/javascript">
  83   writeSubComponentTabs.call(this);
  84 </script>
  85 <!-- Generated by Doxygen 1.9.6 -->
  86 <script type="text/javascript">
  87 /* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
  88 var searchBox = new SearchBox("searchBox", "search/",'.html');
  89 /* @license-end */
  90 </script>
  91 </div><!-- top -->
  92 <div id="side-nav" class="ui-resizable side-nav-resizable">
  93   <div id="nav-tree">
  94     <div id="nav-tree-contents">
  95       <div id="nav-sync" class="sync"></div>
  96     </div>
  97   </div>
  98   <div id="splitbar" style="-moz-user-select:none;"
  99        class="ui-resizable-handle">
 100   </div>
 101 </div>
 102 <script type="text/javascript">
 103 /* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
 104 $(document).ready(function(){initNavTree('group__CMSIS__RTOS__MemoryMgmt.html',''); initResizable(); });
 105 /* @license-end */
 106 </script>
 107 <div id="doc-content">
 108 <!-- window showing the filter options -->
 109 <div id="MSearchSelectWindow"
 110      onmouseover="return searchBox.OnSearchSelectShow()"
 111      onmouseout="return searchBox.OnSearchSelectHide()"
 112      onkeydown="return searchBox.OnSearchSelectKey(event)">
 113 </div>
 114
 115 <!-- iframe showing the search results (closed by default) -->
 116 <div id="MSearchResultsWindow">
 117 <div id="MSearchResults">
 118 <div class="SRPage">
 119 <div id="SRIndex">
 120 <div id="SRResults"></div>
 121 <div class="SRStatus" id="Loading">Loading...</div>
 122 <div class="SRStatus" id="Searching">Searching...</div>
 123 <div class="SRStatus" id="NoMatches">No Matches</div>
 124 </div>
 125 </div>
 126 </div>
 127 </div>
 128
 129 <div class="header">
 130   <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>
 131 </div><!--header-->
 132 <div class="contents">
 133
 134 <p>Information about memory management possibilities.
 135 </p>
 136 <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>
 137 <li><a class="el" href="group__CMSIS__RTOS__MemoryMgmt.html#CMSIS_RTOS_MemoryMgmt_Automatic">Automatic Dynamic Allocation</a> (fully portable), or</li>
 138 <li><a class="el" href="group__CMSIS__RTOS__MemoryMgmt.html#CMSIS_RTOS_MemoryMgmt_Manual">Manual User-defined Allocation</a> (implementation specific).</li>
 139 </ul>
 140 <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>
 141 <h1><a class="anchor" id="CMSIS_RTOS_MemoryMgmt_Automatic"></a>
 142 Automatic Dynamic Allocation</h1>
 143 <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>
 144 <p>The actual allocation strategy used is implementation specific, i.e. whether global heap or preallocated memory pools are used.</p>
 145 <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>
 146 <div class="line">  </div>
 147 <div class="line"><a class="code hl_typedef" href="group__CMSIS__RTOS__MutexMgmt.html#ga313801836c62deb23055efb55a420e42">osMutexId_t</a> mutex_id;</div>
 148 <div class="line"><a class="code hl_typedef" href="group__CMSIS__RTOS__MutexMgmt.html#ga313801836c62deb23055efb55a420e42">osMutexId_t</a> mutex2_id;</div>
 149 <div class="line">  </div>
 150 <div class="line"><span class="keyword">const</span> <a class="code hl_struct" href="group__CMSIS__RTOS__MutexMgmt.html#structosMutexAttr__t">osMutexAttr_t</a> Thread_Mutex_attr = {</div>
 151 <div class="line">  <span class="stringliteral">&quot;myThreadMutex&quot;</span>,                              <span class="comment">// human readable mutex name</span></div>
 152 <div class="line">  <a class="code hl_define" href="group__CMSIS__RTOS__MutexMgmt.html#ga65c2482cc64a35d03871f3180f305926">osMutexRecursive</a> | <a class="code hl_define" href="group__CMSIS__RTOS__MutexMgmt.html#ga40fba270cb31a977b3bd551d41eb9599">osMutexPrioInherit</a>,        <span class="comment">// attr_bits</span></div>
 153 <div class="line">  NULL,                                         <span class="comment">// memory for control block (default)</span></div>
 154 <div class="line">  0U                                            <span class="comment">// size for control block (default)</span></div>
 155 <div class="line">};</div>
 156 <div class="line">  </div>
 157 <div class="line"><span class="keywordtype">void</span> CreateMutex (<span class="keywordtype">void</span>)  {</div>
 158 <div class="line">  mutex_id = <a class="code hl_function" href="group__CMSIS__RTOS__MutexMgmt.html#gab90920022ab944296821368ef6bb52f8">osMutexNew</a>(NULL);                  <span class="comment">// use default values for all attributes</span></div>
 159 <div class="line">  mutex2_id = <a class="code hl_function" href="group__CMSIS__RTOS__MutexMgmt.html#gab90920022ab944296821368ef6bb52f8">osMutexNew</a>(&amp;Thread_Mutex_attr);   <span class="comment">// use attributes from defined structure</span></div>
 160 <div class="line">  :</div>
 161 <div class="line">}</div>
 162 <div class="ttc" id="acmsis__os2_8h_html"><div class="ttname"><a href="cmsis__os2_8h.html">cmsis_os2.h</a></div></div>
 163 <div class="ttc" id="agroup__CMSIS__RTOS__MutexMgmt_html_ga313801836c62deb23055efb55a420e42"><div class="ttname"><a href="group__CMSIS__RTOS__MutexMgmt.html#ga313801836c62deb23055efb55a420e42">osMutexId_t</a></div><div class="ttdeci">void * osMutexId_t</div><div class="ttdef"><b>Definition:</b> cmsis_os2.h:269</div></div>
 164 <div class="ttc" id="agroup__CMSIS__RTOS__MutexMgmt_html_ga40fba270cb31a977b3bd551d41eb9599"><div class="ttname"><a href="group__CMSIS__RTOS__MutexMgmt.html#ga40fba270cb31a977b3bd551d41eb9599">osMutexPrioInherit</a></div><div class="ttdeci">#define osMutexPrioInherit</div><div class="ttdoc">Priority inherit protocol.</div><div class="ttdef"><b>Definition:</b> cmsis_os2.h:227</div></div>
 165 <div class="ttc" id="agroup__CMSIS__RTOS__MutexMgmt_html_ga65c2482cc64a35d03871f3180f305926"><div class="ttname"><a href="group__CMSIS__RTOS__MutexMgmt.html#ga65c2482cc64a35d03871f3180f305926">osMutexRecursive</a></div><div class="ttdeci">#define osMutexRecursive</div><div class="ttdoc">Recursive mutex.</div><div class="ttdef"><b>Definition:</b> cmsis_os2.h:226</div></div>
 166 <div class="ttc" id="agroup__CMSIS__RTOS__MutexMgmt_html_gab90920022ab944296821368ef6bb52f8"><div class="ttname"><a href="group__CMSIS__RTOS__MutexMgmt.html#gab90920022ab944296821368ef6bb52f8">osMutexNew</a></div><div class="ttdeci">osMutexId_t osMutexNew(const osMutexAttr_t *attr)</div><div class="ttdoc">Create and Initialize a Mutex object.</div></div>
 167 <div class="ttc" id="agroup__CMSIS__RTOS__MutexMgmt_html_structosMutexAttr__t"><div class="ttname"><a href="group__CMSIS__RTOS__MutexMgmt.html#structosMutexAttr__t">osMutexAttr_t</a></div><div class="ttdoc">Attributes structure for mutex.</div><div class="ttdef"><b>Definition:</b> cmsis_os2.h:318</div></div>
 168 </div><!-- fragment --><p>The Mutexes in this example are created using automatic memory allocation.</p>
 169 <h1><a class="anchor" id="CMSIS_RTOS_MemoryMgmt_Manual"></a>
 170 Manual User-defined Allocation</h1>
 171 <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.</p>
 172 <p><b> Code Example:</b> </p><div class="fragment"><div class="line"><span class="preprocessor">#include &quot;rtx_os.h&quot;</span>                             <span class="comment">// implementation specific</span></div>
 173 <div class="line">  </div>
 174 <div class="line"><a class="code hl_typedef" href="group__CMSIS__RTOS__MutexMgmt.html#ga313801836c62deb23055efb55a420e42">osMutexId_t</a> mutex_id;</div>
 175 <div class="line">  </div>
 176 <div class="line"><span class="keyword">static</span> osRtxMutex_t 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>
 177 <div class="line">  </div>
 178 <div class="line"><span class="keyword">const</span> <a class="code hl_struct" href="group__CMSIS__RTOS__MutexMgmt.html#structosMutexAttr__t">osMutexAttr_t</a> Thread_Mutex_attr = {</div>
 179 <div class="line">  <span class="stringliteral">&quot;myThreadMutex&quot;</span>,                              <span class="comment">// human readable mutex name</span></div>
 180 <div class="line">  <a class="code hl_define" href="group__CMSIS__RTOS__MutexMgmt.html#ga65c2482cc64a35d03871f3180f305926">osMutexRecursive</a> | <a class="code hl_define" href="group__CMSIS__RTOS__MutexMgmt.html#ga40fba270cb31a977b3bd551d41eb9599">osMutexPrioInherit</a>,        <span class="comment">// attr_bits</span></div>
 181 <div class="line">  &amp;mutex_cb,                                    <span class="comment">// memory for control block (user-defined)</span></div>
 182 <div class="line">  <span class="keyword">sizeof</span>(mutex_cb)                              <span class="comment">// size for control block (user-defined)</span></div>
 183 <div class="line">};</div>
 184 <div class="line">  </div>
 185 <div class="line"><span class="keywordtype">void</span> CreateMutex (<span class="keywordtype">void</span>)  {</div>
 186 <div class="line">  mutex_id = <a class="code hl_function" href="group__CMSIS__RTOS__MutexMgmt.html#gab90920022ab944296821368ef6bb52f8">osMutexNew</a>(&amp;Thread_Mutex_attr);    <span class="comment">// use attributes from defined structure</span></div>
 187 <div class="line">  :</div>
 188 <div class="line">}</div>
 189 </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>rtx_os.h</code> in this case. </p>
 190 </div><!-- contents -->
 191 </div><!-- doc-content -->
 192 <!-- start footer part -->
 193 <div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
 194   <ul>
 195     <li class="footer">
 196       <script type="text/javascript">
 197         <!--
 198         writeFooter.call(this);
 199         //-->
 200       </script>
 201     </li>
 202   </ul>
 203 </div>
 204 </body>
 205 </html>