begriffs open source - cmsis/blob - dev/v6.0.0-dev53/RTOS2/html/rtos_process_isolation_mpu.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: MPU Protected Zones</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('rtos_process_isolation_mpu.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><div class="header">
 130   <div class="headertitle"><div class="title">MPU Protected Zones </div></div>
 131 </div><!--header-->
 132 <div class="contents">
 133 <div class="textblock"><p>Memory Protection Unit (MPU) is available on many Cortex-M devices and allows to execute code with restricted access to memory regions and peripherals. Detailed information about the MPU can be found in <a href="../../Core/html/index.html#ref_man_sec">Cortex-M Reference Manuals</a>.</p>
 134 <p>CMSIS-RTOS2 provides a concept of <b>MPU Protected Zones</b> as a simple and flexible mechanism for using MPUs with RTOS threads. MPU Protected Zones are defined by a user as a set of memory regions and peripherals with specified access rights, and each RTOS threads gets assigned to a specific MPU Protected Zone that it is allowed to use.</p>
 135 <p>The figure below illustrates the concept for MPU Protected Zones for isolating threads.</p>
 136 <div class="image">
 137 <img src="rtos_mpu.png" alt=""/>
 138 <div class="caption">
 139 System partitioning with MPU Protected Zones</div></div>
 140     <p>Sections below explain in details how to define and use MPU Protected Zones:</p><ul>
 141 <li><a class="el" href="rtos_process_isolation_mpu.html#rtos_process_isolation_mpu_def">Define MPU Protected Zones</a></li>
 142 <li><a class="el" href="rtos_process_isolation_mpu.html#rtos_process_isolation_mpu_load">Load MPU Protected Zone</a></li>
 143 <li><a class="el" href="rtos_process_isolation_mpu.html#rtos_process_isolation_mpu_objects">RTOS Objects and MPU Protection</a></li>
 144 <li><a class="el" href="rtos_process_isolation_mpu.html#rtos_process_isolation_mpu_fault">Handle Memory Access Faults</a></li>
 145 </ul>
 146 <p><b>Function references</b></p>
 147 <p>Following functions implement and use MPU Protected Zone functionality:</p>
 148 <ul>
 149 <li><a class="el" href="group__CMSIS__RTOS__ThreadMgmt.html#ga48d68b8666d99d28fa646ee1d2182b8f">osThreadNew</a> :  Create a thread and add it to Active Threads.  </li>
 150 <li><a class="el" href="group__CMSIS__RTOS__ThreadMgmt.html#gaefca370070d0b1616421bc3311acfecc">osThreadZone</a> :  MPU zone value in attribute bit field format.  </li>
 151 <li><a class="el" href="group__CMSIS__RTOS__ThreadMgmt.html#ga4101737fa4fd303d4b41fdca6b994f8e">osThreadGetZone</a> :  Get MPU protected zone of a thread.  </li>
 152 <li><a class="el" href="group__CMSIS__RTOS__ThreadMgmt.html#ga99ce311cc620c65fbac043d04dc7d755">osThreadTerminateZone</a> :  Terminate execution of threads assigned to a specified MPU protected zone.  </li>
 153 <li><a class="el" href="group__CMSIS__RTOS__ThreadMgmt.html#ga79d4b26de0bfcdaf142f83e585532f93">osZoneSetup_Callback</a> :  Setup MPU protected zone (called when zone changes).  </li>
 154 </ul>
 155 <h1><a class="anchor" id="rtos_process_isolation_mpu_def"></a>
 156 Define MPU Protected Zones</h1>
 157 <p>In the architectural design phase an application is logically split into functionalities with the same integrity level (same safety requirements). They can safely operate within the same MPU Protected Zone and hence access same memory areas and peripherals.</p>
 158 <p>MPU protected zones are defined in an MPU table where each row describes an individual MPU zone and each cell in the row specifies an MPU region within that zone. For details see section <a href="../../Core/html/group__mpu__functions.html">MPU Functions</a> in CMSIS-Core(M) documentation.</p>
 159 <dl class="section note"><dt>Note</dt><dd>Interrupt handlers bypass the MPU protection. For this reason, it is required that potential impact of all interrupt handlers is strictly analyzed to exclude unintended memory accesses.</dd></dl>
 160 <p><b>Zone Identifier</b> (Zone ID) is used to refer to a specific MPU protected zone. Zone ID value equals to the row index (starting from 0) in the MPU table that describes corresponding MPU Protected Zone.</p>
 161 <p>An MPU Protected Zone is assigned to one or more RTOS threads. This is done by providing the Zone ID value in thread attributes <a class="el" href="group__CMSIS__RTOS__ThreadMgmt.html#structosThreadAttr__t">osThreadAttr_t</a> when creating the thread with the <a class="el" href="group__CMSIS__RTOS__ThreadMgmt.html#ga48d68b8666d99d28fa646ee1d2182b8f">osThreadNew</a> function.</p>
 162 <p><b>Example:</b></p>
 163 <div class="fragment"><div class="line"><span class="comment">/* ThreadA thread attributes */</span></div>
 164 <div class="line"><span class="keyword">const</span> <a class="code hl_struct" href="group__CMSIS__RTOS__ThreadMgmt.html#structosThreadAttr__t" title="Attributes structure for thread.">osThreadAttr_t</a> thread_A_attr = {</div>
 165 <div class="line">  .<a class="code hl_variable" href="group__CMSIS__RTOS__ThreadMgmt.html#ab74e6bf80237ddc4109968cedc58c151" title="name of the thread">name</a>       = <span class="stringliteral">&quot;ThreadA&quot;</span>,       <span class="comment">// human readable thread name</span></div>
 166 <div class="line">  .attr_bits  = <a class="code hl_define" href="group__CMSIS__RTOS__ThreadMgmt.html#gaefca370070d0b1616421bc3311acfecc" title="MPU zone value in attribute bit field format.">osThreadZone</a>(3U) <span class="comment">// assign thread to MPU protected zone with Zone Id 3</span></div>
 167 <div class="line">};</div>
 168 <div class="line"><a class="code hl_function" href="group__CMSIS__RTOS__ThreadMgmt.html#ga48d68b8666d99d28fa646ee1d2182b8f" title="Create a thread and add it to Active Threads.">osThreadNew</a>(ThreadA, NULL, &amp;thread_A_attr);</div>
 169 </div><!-- fragment --><p><a href="https://arm-software.github.io/CMSIS_5/Zone/html/index.html">CMSIS-Zone</a> provides a utility that allows graphic configuration of MPU protected zones and generates MPU table in the CMSIS format.</p>
 170 <h1><a class="anchor" id="rtos_process_isolation_mpu_load"></a>
 171 Load MPU Protected Zone</h1>
 172 <p>When switching threads the RTOS kernel compares Zone IDs of the currently running thread and the next thread to be executed. If the Zone Ids are different then a callback function <a class="el" href="group__CMSIS__RTOS__ThreadMgmt.html#ga79d4b26de0bfcdaf142f83e585532f93">osZoneSetup_Callback</a> is called. This callback function shall be implemented in the user application code to actually switch to the new MPU Protected Zone. In the function the user should load the MPU Protected Zone according to the Zone Id provided in the argument.</p>
 173 <p><b>Example:</b> </p><div class="fragment"><div class="line"><span class="comment">/* Update MPU settings for newly activating Zone */</span></div>
 174 <div class="line"><span class="keywordtype">void</span> <a class="code hl_function" href="group__CMSIS__RTOS__ThreadMgmt.html#ga79d4b26de0bfcdaf142f83e585532f93" title="Setup MPU protected zone (called when zone changes).">osZoneSetup_Callback</a> (uint32_t zone) {</div>
 175 <div class="line"> </div>
 176 <div class="line">  <span class="keywordflow">if</span> (zone &gt;= ZONES_NUM) {</div>
 177 <div class="line">    <span class="comment">// Here issue an error for incorrect zone value</span></div>
 178 <div class="line">  }</div>
 179 <div class="line"> </div>
 180 <div class="line">  ARM_MPU_Load(mpu_table[zone], MPU_REGIONS);</div>
 181 <div class="line">}</div>
 182 </div><!-- fragment --><h1><a class="anchor" id="rtos_process_isolation_mpu_objects"></a>
 183 RTOS Objects and MPU Protection</h1>
 184 <p>To access RTOS objects from the application RTOS APIs rely on a numeric <code>xxx_id</code> parameter associated with the object as explained in <a class="el" href="usingOS2.html#rtos_objects">Lifecycle of RTOS Objects</a>. For example as <code>evt_flags</code> in this code:</p>
 185 <div class="fragment"><div class="line"><a class="code hl_typedef" href="group__CMSIS__RTOS__EventFlags.html#gafdbab933146d6d81d7cca7287e267a50">osEventFlagsId_t</a> evt_flags;</div>
 186 <div class="line">evt_flags = <a class="code hl_function" href="group__CMSIS__RTOS__EventFlags.html#gab14b1caeb12ffa42cce1bfe889cd07df" title="Create and Initialize an Event Flags object.">osEventFlagsNew</a>(NULL);</div>
 187 <div class="line"><a class="code hl_function" href="group__CMSIS__RTOS__EventFlags.html#ga33b71d14cecf90b4e72639dd19f23a5e" title="Set the specified Event Flags.">osEventFlagsSet</a>(evt_flags, 1);</div>
 188 </div><!-- fragment --><p>The allocation of an RTOS object to the memory in a specific MPU Protected Zone does not provide access restriction. The access restriction can be bypassed if another thread calls the CMSIS-RTOS2 API with the object ID of the RTOS object as argument. The CMSIS-RTOS2 function is executed in handler mode and therefore can access and modify the RTOS object without raising a Memory Fault.</p>
 189 <p>To enable access control for RTOS objects the <a class="el" href="rtos_process_isolation_safety_class.html">Safety Classes</a> concept is introduced in CMSIS-RTOS2.</p>
 190 <h1><a class="anchor" id="rtos_process_isolation_mpu_fault"></a>
 191 Handle Memory Access Faults</h1>
 192 <p>A memory access fault is triggered when a thread tries to access memory or peripherals outside of the MPU Protected Zone loaded while the thread is running. In such case Memory Management Interrupt <a href="../../Core/html/group__NVIC__gr.html">MemoryManagement_IRQn</a> is triggered by the processor and its handling function is executed according to the exception vector table specified in the device startup file (by default <span class="XML-Token">MemManage_Handler(void)</span> ).</p>
 193 <p>The <em>MemManage_Handler()</em> interrupt handler is application specific and needs to be implemented by the user. In the handler it is possible to identify the thread that caused the memory access fault, the corresponding zone id and the safety class. This information can be used to define actions for entering a safe state. <a class="el" href="rtos_process_isolation_faults.html">Fault Handling</a> provides more details on the available system recovery possibilities. </p>
 194 </div></div><!-- contents -->
 195 </div><!-- PageDoc -->
 196 </div><!-- doc-content -->
 197 <!-- start footer part -->
 198 <div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
 199   <ul>
 200     <li class="footer">
 201       <script type="text/javascript">
 202         <!--
 203         writeFooter.call(this);
 204         //-->
 205       </script>
 206     </li>
 207   </ul>
 208 </div>
 209 </body>
 210 </html>