begriffs open source - cmsis/blob - main/Core/group__context__trustzone__functions.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-Core (Cortex-M): RTOS Context Management</title>
   9 <link href="doxygen.css" rel="stylesheet" type="text/css" />
  10 <script type="text/javascript" src="jquery.js"></script>
  11 <script type="text/javascript" src="dynsections.js"></script>
  12 <script type="text/javascript" src="tabs.js"></script>
  13 <script type="text/javascript" src="footer.js"></script>
  14 <script type="text/javascript" src="navtree.js"></script>
  15 <link href="navtree.css" rel="stylesheet" type="text/css"/>
  16 <script type="text/javascript" src="resize.js"></script>
  17 <script type="text/javascript" src="navtreedata.js"></script>
  18 <script type="text/javascript" src="navtree.js"></script>
  19 <link href="search/search.css" rel="stylesheet" type="text/css"/>
  20 <script type="text/javascript" src="search/searchdata.js"></script>
  21 <script type="text/javascript" src="search/search.js"></script>
  22 <script type="text/javascript">
  23 /* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
  24   $(document).ready(function() { init_search(); });
  25 /* @license-end */
  26 </script>
  27 <script type="text/javascript" src="darkmode_toggle.js"></script>
  28 <link href="extra_stylesheet.css" rel="stylesheet" type="text/css"/>
  29 <link href="extra_navtree.css" rel="stylesheet" type="text/css"/>
  30 <link href="extra_search.css" rel="stylesheet" type="text/css"/>
  31 <link href="extra_tabs.css" rel="stylesheet" type="text/css"/>
  32 <link href="version.css" rel="stylesheet" type="text/css"/>
  33 <script type="text/javascript" src="../../version.js"></script>
  34 </head>
  35 <body>
  36 <div id="top"><!-- do not remove this div, it is closed by doxygen! -->
  37 <div id="titlearea">
  38 <table cellspacing="0" cellpadding="0">
  39  <tbody>
  40  <tr style="height: 55px;">
  41   <td id="projectlogo" style="padding: 1.5em;"><img alt="Logo" src="cmsis_logo_white_small.png"/></td>
  42   <td style="padding-left: 1em; padding-bottom: 1em;padding-top: 1em;">
  43    <div id="projectname">CMSIS-Core (Cortex-M)
  44    &#160;<span id="projectnumber"><script type="text/javascript">
  45      <!--
  46      writeHeader.call(this);
  47      writeVersionDropdown.call(this, "CMSIS-Core (Cortex-M)");
  48      //-->
  49     </script>
  50    </span>
  51    </div>
  52    <div id="projectbrief">CMSIS-Core support for Cortex-M processor-based devices</div>
  53   </td>
  54    <td>        <div id="MSearchBox" class="MSearchBoxInactive">
  55         <span class="left">
  56           <span id="MSearchSelect"                onmouseover="return searchBox.OnSearchSelectShow()"                onmouseout="return searchBox.OnSearchSelectHide()">&#160;</span>
  57           <input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"
  58                onfocus="searchBox.OnSearchFieldFocus(true)"
  59                onblur="searchBox.OnSearchFieldFocus(false)"
  60                onkeyup="searchBox.OnSearchFieldChange(event)"/>
  61           </span><span class="right">
  62             <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.svg" alt=""/></a>
  63           </span>
  64         </div>
  65 </td>
  66   <!--END !PROJECT_NAME-->
  67  </tr>
  68  </tbody>
  69 </table>
  70 </div>
  71 <!-- end header part -->
  72 <div id="CMSISnav" class="tabs1">
  73   <ul class="tablist">
  74     <script type="text/javascript">
  75       writeComponentTabs.call(this);
  76     </script>
  77   </ul>
  78 </div>
  79 <script type="text/javascript">
  80   writeSubComponentTabs.call(this);
  81 </script>
  82 <!-- Generated by Doxygen 1.9.6 -->
  83 <script type="text/javascript">
  84 /* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
  85 var searchBox = new SearchBox("searchBox", "search/",'.html');
  86 /* @license-end */
  87 </script>
  88 </div><!-- top -->
  89 <div id="side-nav" class="ui-resizable side-nav-resizable">
  90   <div id="nav-tree">
  91     <div id="nav-tree-contents">
  92       <div id="nav-sync" class="sync"></div>
  93     </div>
  94   </div>
  95   <div id="splitbar" style="-moz-user-select:none;"
  96        class="ui-resizable-handle">
  97   </div>
  98 </div>
  99 <script type="text/javascript">
 100 /* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
 101 $(document).ready(function(){initNavTree('group__context__trustzone__functions.html',''); initResizable(); });
 102 /* @license-end */
 103 </script>
 104 <div id="doc-content">
 105 <!-- window showing the filter options -->
 106 <div id="MSearchSelectWindow"
 107      onmouseover="return searchBox.OnSearchSelectShow()"
 108      onmouseout="return searchBox.OnSearchSelectHide()"
 109      onkeydown="return searchBox.OnSearchSelectKey(event)">
 110 </div>
 111
 112 <!-- iframe showing the search results (closed by default) -->
 113 <div id="MSearchResultsWindow">
 114 <div id="MSearchResults">
 115 <div class="SRPage">
 116 <div id="SRIndex">
 117 <div id="SRResults"></div>
 118 <div class="SRStatus" id="Loading">Loading...</div>
 119 <div class="SRStatus" id="Searching">Searching...</div>
 120 <div class="SRStatus" id="NoMatches">No Matches</div>
 121 </div>
 122 </div>
 123 </div>
 124 </div>
 125
 126 <div class="header">
 127   <div class="summary">
 128 <a href="#func-members">Functions</a>  </div>
 129   <div class="headertitle"><div class="title">RTOS Context Management<div class="ingroups"><a class="el" href="group__trustzone__functions.html">TrustZone for Armv8-M/v8.1-M</a></div></div></div>
 130 </div><!--header-->
 131 <div class="contents">
 132
 133 <p>RTOS Thread Context Management for Armv8-M TrustZone.
 134 <a href="#details">More...</a></p>
 135 <table class="memberdecls">
 136 <tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="func-members" name="func-members"></a>
 137 Functions</h2></td></tr>
 138 <tr class="memitem:gacd016f166bee549a0d3e970132e64a90"><td class="memItemLeft" align="right" valign="top">TZ_MemoryId_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__context__trustzone__functions.html#gacd016f166bee549a0d3e970132e64a90">TZ_AllocModuleContext_S</a> (TZ_ModuleId_t module)</td></tr>
 139 <tr class="memdesc:gacd016f166bee549a0d3e970132e64a90"><td class="mdescLeft">&#160;</td><td class="mdescRight">Allocate context memory for calling secure software modules in TrustZone.  <br /></td></tr>
 140 <tr class="separator:gacd016f166bee549a0d3e970132e64a90"><td class="memSeparator" colspan="2">&#160;</td></tr>
 141 <tr class="memitem:gac84f678fbe974f8b02c683e0b8046524"><td class="memItemLeft" align="right" valign="top">uint32_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__context__trustzone__functions.html#gac84f678fbe974f8b02c683e0b8046524">TZ_FreeModuleContext_S</a> (TZ_MemoryId_t id)</td></tr>
 142 <tr class="memdesc:gac84f678fbe974f8b02c683e0b8046524"><td class="mdescLeft">&#160;</td><td class="mdescRight">Free context memory that was previously allocated with <a class="el" href="group__context__trustzone__functions.html#gacd016f166bee549a0d3e970132e64a90">TZ_AllocModuleContext_S</a>.  <br /></td></tr>
 143 <tr class="separator:gac84f678fbe974f8b02c683e0b8046524"><td class="memSeparator" colspan="2">&#160;</td></tr>
 144 <tr class="memitem:ga926e2ec472535a6d2b8125be1a79e3c0"><td class="memItemLeft" align="right" valign="top">uint32_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__context__trustzone__functions.html#ga926e2ec472535a6d2b8125be1a79e3c0">TZ_InitContextSystem_S</a> (void)</td></tr>
 145 <tr class="memdesc:ga926e2ec472535a6d2b8125be1a79e3c0"><td class="mdescLeft">&#160;</td><td class="mdescRight">Initialize secure context memory system.  <br /></td></tr>
 146 <tr class="separator:ga926e2ec472535a6d2b8125be1a79e3c0"><td class="memSeparator" colspan="2">&#160;</td></tr>
 147 <tr class="memitem:ga4748f6bcdd5fed279ac5a6cd7eca2689"><td class="memItemLeft" align="right" valign="top">uint32_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__context__trustzone__functions.html#ga4748f6bcdd5fed279ac5a6cd7eca2689">TZ_LoadContext_S</a> (TZ_MemoryId_t id)</td></tr>
 148 <tr class="memdesc:ga4748f6bcdd5fed279ac5a6cd7eca2689"><td class="mdescLeft">&#160;</td><td class="mdescRight">Load secure context (called on RTOS thread context switch)  <br /></td></tr>
 149 <tr class="separator:ga4748f6bcdd5fed279ac5a6cd7eca2689"><td class="memSeparator" colspan="2">&#160;</td></tr>
 150 <tr class="memitem:gac106570f4905f82922fd335aeb08a1bf"><td class="memItemLeft" align="right" valign="top">uint32_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__context__trustzone__functions.html#gac106570f4905f82922fd335aeb08a1bf">TZ_StoreContext_S</a> (TZ_MemoryId_t id)</td></tr>
 151 <tr class="memdesc:gac106570f4905f82922fd335aeb08a1bf"><td class="mdescLeft">&#160;</td><td class="mdescRight">Store secure context (called on RTOS thread context switch)  <br /></td></tr>
 152 <tr class="separator:gac106570f4905f82922fd335aeb08a1bf"><td class="memSeparator" colspan="2">&#160;</td></tr>
 153 </table>
 154 <a name="details" id="details"></a><h2 class="groupheader">Description</h2>
 155 <p>RTOS Thread Context Management for Armv8-M TrustZone. </p>
 156 <p>The CMSIS-Core provides the file <b>tz_context.h</b> which defines an API to standardize the context memory system for real-time operating systems. For more information refer to <a class="el" href="using_TrustZone_pg.html#RTOS_TrustZone">RTOS Thread Context Management</a>. </p>
 157 <h2 class="groupheader">Function Documentation</h2>
 158 <a id="gacd016f166bee549a0d3e970132e64a90" name="gacd016f166bee549a0d3e970132e64a90"></a>
 159 <h2 class="memtitle"><span class="permalink"><a href="#gacd016f166bee549a0d3e970132e64a90">&#9670;&#160;</a></span>TZ_AllocModuleContext_S()</h2>
 160
 161 <div class="memitem">
 162 <div class="memproto">
 163       <table class="memname">
 164         <tr>
 165           <td class="memname">TZ_MemoryId_t TZ_AllocModuleContext_S </td>
 166           <td>(</td>
 167           <td class="paramtype">TZ_ModuleId_t&#160;</td>
 168           <td class="paramname"><em>module</em></td><td>)</td>
 169           <td></td>
 170         </tr>
 171       </table>
 172 </div><div class="memdoc">
 173
 174 <p>Allocate context memory for calling secure software modules in TrustZone. </p>
 175 <p>Allocates the secure memory regions for thread execution. The parameter <em>module</em> describes the set of secure functions that are called by the non-secure thread. Set <em>module</em> to zero if no secure calls are used/allowed. This leads to no secure memory to be assigned which results in zero being returned as memory id as well. This function should be called by an RTOS kernel at the start of a thread. </p><dl class="params"><dt>Parameters</dt><dd>
 176   <table class="params">
 177     <tr><td class="paramdir">[in]</td><td class="paramname">module</td><td>A non-zero value identifies software modules called from non-secure mode. zero is used if no secure calls are used/allowed. </td></tr>
 178   </table>
 179   </dd>
 180 </dl>
 181 <dl class="section return"><dt>Returns</dt><dd>value != 0 id TrustZone memory slot identify </dd>
 182 <dd>
 183 value 0 no memory available or internal error </dd></dl>
 184
 185 </div>
 186 </div>
 187 <a id="gac84f678fbe974f8b02c683e0b8046524" name="gac84f678fbe974f8b02c683e0b8046524"></a>
 188 <h2 class="memtitle"><span class="permalink"><a href="#gac84f678fbe974f8b02c683e0b8046524">&#9670;&#160;</a></span>TZ_FreeModuleContext_S()</h2>
 189
 190 <div class="memitem">
 191 <div class="memproto">
 192       <table class="memname">
 193         <tr>
 194           <td class="memname">uint32_t TZ_FreeModuleContext_S </td>
 195           <td>(</td>
 196           <td class="paramtype">TZ_MemoryId_t&#160;</td>
 197           <td class="paramname"><em>id</em></td><td>)</td>
 198           <td></td>
 199         </tr>
 200       </table>
 201 </div><div class="memdoc">
 202
 203 <p>Free context memory that was previously allocated with <a class="el" href="group__context__trustzone__functions.html#gacd016f166bee549a0d3e970132e64a90">TZ_AllocModuleContext_S</a>. </p>
 204 <p>De-allocates the secure memory regions. The parameter <em>id</em> refers to a TrustZone memory slot that has been obtained with <a class="el" href="group__context__trustzone__functions.html#gacd016f166bee549a0d3e970132e64a90">TZ_AllocModuleContext_S</a>. This function should be called by an RTOS kernel at the termination of a thread. </p><dl class="params"><dt>Parameters</dt><dd>
 205   <table class="params">
 206     <tr><td class="paramdir">[in]</td><td class="paramname">id</td><td>TrustZone memory slot identifier </td></tr>
 207   </table>
 208   </dd>
 209 </dl>
 210 <dl class="section return"><dt>Returns</dt><dd>execution status (1: success, 0: error) </dd></dl>
 211
 212 </div>
 213 </div>
 214 <a id="ga926e2ec472535a6d2b8125be1a79e3c0" name="ga926e2ec472535a6d2b8125be1a79e3c0"></a>
 215 <h2 class="memtitle"><span class="permalink"><a href="#ga926e2ec472535a6d2b8125be1a79e3c0">&#9670;&#160;</a></span>TZ_InitContextSystem_S()</h2>
 216
 217 <div class="memitem">
 218 <div class="memproto">
 219       <table class="memname">
 220         <tr>
 221           <td class="memname">uint32_t TZ_InitContextSystem_S </td>
 222           <td>(</td>
 223           <td class="paramtype">void&#160;</td>
 224           <td class="paramname"></td><td>)</td>
 225           <td></td>
 226         </tr>
 227       </table>
 228 </div><div class="memdoc">
 229
 230 <p>Initialize secure context memory system. </p>
 231 <p>Initializes the memory allocation management for the secure memory regions. As a minimum the secure thread mode stack will be provided. </p><dl class="section return"><dt>Returns</dt><dd>execution status (1: success, 0: error) </dd></dl>
 232
 233 </div>
 234 </div>
 235 <a id="ga4748f6bcdd5fed279ac5a6cd7eca2689" name="ga4748f6bcdd5fed279ac5a6cd7eca2689"></a>
 236 <h2 class="memtitle"><span class="permalink"><a href="#ga4748f6bcdd5fed279ac5a6cd7eca2689">&#9670;&#160;</a></span>TZ_LoadContext_S()</h2>
 237
 238 <div class="memitem">
 239 <div class="memproto">
 240       <table class="memname">
 241         <tr>
 242           <td class="memname">uint32_t TZ_LoadContext_S </td>
 243           <td>(</td>
 244           <td class="paramtype">TZ_MemoryId_t&#160;</td>
 245           <td class="paramname"><em>id</em></td><td>)</td>
 246           <td></td>
 247         </tr>
 248       </table>
 249 </div><div class="memdoc">
 250
 251 <p>Load secure context (called on RTOS thread context switch) </p>
 252 <p>Prepare the secure context for execution so that a thread in the non-secure state can call secure library modules. The parameter <em>id</em> refers to a TrustZone memory slot that has been obtained with <a class="el" href="group__context__trustzone__functions.html#gacd016f166bee549a0d3e970132e64a90">TZ_AllocModuleContext_S</a> which might be zero if not used. This function should be called by an RTOS kernel at thread context switch before running a thread. </p><dl class="params"><dt>Parameters</dt><dd>
 253   <table class="params">
 254     <tr><td class="paramdir">[in]</td><td class="paramname">id</td><td>TrustZone memory slot identifier </td></tr>
 255   </table>
 256   </dd>
 257 </dl>
 258 <dl class="section return"><dt>Returns</dt><dd>execution status (1: success, 0: error) </dd></dl>
 259
 260 </div>
 261 </div>
 262 <a id="gac106570f4905f82922fd335aeb08a1bf" name="gac106570f4905f82922fd335aeb08a1bf"></a>
 263 <h2 class="memtitle"><span class="permalink"><a href="#gac106570f4905f82922fd335aeb08a1bf">&#9670;&#160;</a></span>TZ_StoreContext_S()</h2>
 264
 265 <div class="memitem">
 266 <div class="memproto">
 267       <table class="memname">
 268         <tr>
 269           <td class="memname">uint32_t TZ_StoreContext_S </td>
 270           <td>(</td>
 271           <td class="paramtype">TZ_MemoryId_t&#160;</td>
 272           <td class="paramname"><em>id</em></td><td>)</td>
 273           <td></td>
 274         </tr>
 275       </table>
 276 </div><div class="memdoc">
 277
 278 <p>Store secure context (called on RTOS thread context switch) </p>
 279 <p>Free the secure context that has been previously loaded with <a class="el" href="group__context__trustzone__functions.html#ga4748f6bcdd5fed279ac5a6cd7eca2689">TZ_LoadContext_S</a>. The parameter <em>id</em> refers to a TrustZone memory slot that has been obtained with <a class="el" href="group__context__trustzone__functions.html#gacd016f166bee549a0d3e970132e64a90">TZ_AllocModuleContext_S</a> which might be zero if not used. This function should be called by an RTOS kernel at thread context switch after running a thread. </p><dl class="params"><dt>Parameters</dt><dd>
 280   <table class="params">
 281     <tr><td class="paramdir">[in]</td><td class="paramname">id</td><td>TrustZone memory slot identifier </td></tr>
 282   </table>
 283   </dd>
 284 </dl>
 285 <dl class="section return"><dt>Returns</dt><dd>execution status (1: success, 0: error) </dd></dl>
 286
 287 </div>
 288 </div>
 289 </div><!-- contents -->
 290 </div><!-- doc-content -->
 291 <!-- start footer part -->
 292 <div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
 293   <ul>
 294     <li class="footer">
 295       <script type="text/javascript">
 296         <!--
 297         writeFooter.call(this);
 298         //-->
 299       </script>
 300     </li>
 301   </ul>
 302 </div>
 303 </body>
 304 </html>