blob: 0bd71182523cb4141e4dcb18df6738d2f15d1378 [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>RTOS Context Management</title>
<title>CMSIS-Core (Cortex-M): RTOS Context 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-Core (Cortex-M)
&#160;<span id="projectnumber">Version 5.3.0</span>
</div>
<div id="projectbrief">CMSIS-Core support for Cortex-M processor-based devices</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__context__trustzone__functions.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>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark">&#160;</span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark">&#160;</span>Groups</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><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="summary">
<a href="#func-members">Functions</a> </div>
<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>
</div><!--header-->
<div class="contents">
<p>RTOS Thread Context Management for Armv8-M TrustZone.
<a href="#details">More...</a></p>
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="func-members"></a>
Functions</h2></td></tr>
<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>
<tr class="memdesc:ga926e2ec472535a6d2b8125be1a79e3c0"><td class="mdescLeft">&#160;</td><td class="mdescRight">Initialize secure context memory system. <a href="#ga926e2ec472535a6d2b8125be1a79e3c0">More...</a><br/></td></tr>
<tr class="separator:ga926e2ec472535a6d2b8125be1a79e3c0"><td class="memSeparator" colspan="2">&#160;</td></tr>
<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>
<tr class="memdesc:gacd016f166bee549a0d3e970132e64a90"><td class="mdescLeft">&#160;</td><td class="mdescRight">Allocate context memory for calling secure software modules in TrustZone. <a href="#gacd016f166bee549a0d3e970132e64a90">More...</a><br/></td></tr>
<tr class="separator:gacd016f166bee549a0d3e970132e64a90"><td class="memSeparator" colspan="2">&#160;</td></tr>
<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>
<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>. <a href="#gac84f678fbe974f8b02c683e0b8046524">More...</a><br/></td></tr>
<tr class="separator:gac84f678fbe974f8b02c683e0b8046524"><td class="memSeparator" colspan="2">&#160;</td></tr>
<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>
<tr class="memdesc:ga4748f6bcdd5fed279ac5a6cd7eca2689"><td class="mdescLeft">&#160;</td><td class="mdescRight">Load secure context (called on RTOS thread context switch) <a href="#ga4748f6bcdd5fed279ac5a6cd7eca2689">More...</a><br/></td></tr>
<tr class="separator:ga4748f6bcdd5fed279ac5a6cd7eca2689"><td class="memSeparator" colspan="2">&#160;</td></tr>
<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>
<tr class="memdesc:gac106570f4905f82922fd335aeb08a1bf"><td class="mdescLeft">&#160;</td><td class="mdescRight">Store secure context (called on RTOS thread context switch) <a href="#gac106570f4905f82922fd335aeb08a1bf">More...</a><br/></td></tr>
<tr class="separator:gac106570f4905f82922fd335aeb08a1bf"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table>
<a name="details" id="details"></a><h2 class="groupheader">Description</h2>
<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>
<h2 class="groupheader">Function Documentation</h2>
<a class="anchor" id="gacd016f166bee549a0d3e970132e64a90"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">TZ_MemoryId_t TZ_AllocModuleContext_S </td>
<td>(</td>
<td class="paramtype">TZ_ModuleId_t&#160;</td>
<td class="paramname"><em>module</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<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>
<table class="params">
<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>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>value != 0 id TrustZone memory slot identify </dd>
<dd>
value 0 no memory available or internal error </dd></dl>
</div>
</div>
<a class="anchor" id="gac84f678fbe974f8b02c683e0b8046524"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">uint32_t TZ_FreeModuleContext_S </td>
<td>(</td>
<td class="paramtype">TZ_MemoryId_t&#160;</td>
<td class="paramname"><em>id</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<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>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">id</td><td>TrustZone memory slot identifier </td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>execution status (1: success, 0: error) </dd></dl>
</div>
</div>
<a class="anchor" id="ga926e2ec472535a6d2b8125be1a79e3c0"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">uint32_t TZ_InitContextSystem_S </td>
<td>(</td>
<td class="paramtype">void&#160;</td>
<td class="paramname"></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<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>
</div>
</div>
<a class="anchor" id="ga4748f6bcdd5fed279ac5a6cd7eca2689"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">uint32_t TZ_LoadContext_S </td>
<td>(</td>
<td class="paramtype">TZ_MemoryId_t&#160;</td>
<td class="paramname"><em>id</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<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>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">id</td><td>TrustZone memory slot identifier </td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>execution status (1: success, 0: error) </dd></dl>
</div>
</div>
<a class="anchor" id="gac106570f4905f82922fd335aeb08a1bf"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">uint32_t TZ_StoreContext_S </td>
<td>(</td>
<td class="paramtype">TZ_MemoryId_t&#160;</td>
<td class="paramname"><em>id</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<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>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">id</td><td>TrustZone memory slot identifier </td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>execution status (1: success, 0: error) </dd></dl>
</div>
</div>
</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:20:26 for CMSIS-Core (Cortex-M) Version 5.3.0 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>