begriffs open source - cmsis/blob - main/Core/using_TrustZone_pg.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): Using TrustZone for Armv8-M</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-Core (Cortex-M)
  47    &#160;<span id="projectnumber"><script type="text/javascript">
  48      <!--
  49      writeHeader.call(this);
  50      writeVersionDropdown.call(this, "CMSIS-Core (Cortex-M)");
  51      //-->
  52     </script>
  53    </span>
  54    </div>
  55    <div id="projectbrief">CMSIS-Core support for Cortex-M processor-based devices</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('using_TrustZone_pg.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">Using TrustZone for Armv8-M </div></div>
 131 </div><!--header-->
 132 <div class="contents">
 133 <div class="toc"><h3>Table of Contents</h3>
 134 <ul><li class="level1"><a href="#useCase_TrustZone">Simplified Use Case with TrustZone</a></li>
 135 <li class="level1"><a href="#Example_TrustZone">Program Examples</a></li>
 136 <li class="level1"><a href="#Model_TrustZone">Programmers Model with TrustZone</a></li>
 137 <li class="level1"><a href="#RTOS_TrustZone_stacksealing">Stack Sealing</a></li>
 138 <li class="level1"><a href="#CMSIS_Files_TrustZone">CMSIS Files for TrustZone</a></li>
 139 <li class="level1"><a href="#RTOS_TrustZone">RTOS Thread Context Management</a></li>
 140 </ul>
 141 </div>
 142 <div class="textblock"><p><a class="anchor" id="md_src_using_tz"></a></p>
 143 <p>The <a href="https://www.arm.com/technologies/trustzone-for-cortex-m">TrustZone for Cortex-M</a> is a security extension for Armv8-M architecture that is optimized for ultra-low power embedded applications. It enables software security domains that restrict access to secure memory and I/O only for trusted software.</p>
 144 <p>TrustZone for Armv8-M:</p>
 145 <ul>
 146 <li>preserves low interrupt latencies for both Secure and Non-secure domains.</li>
 147 <li>does not impose code overhead, cycle overhead or the complexity of a virtualization based solution.</li>
 148 <li>introduces the Secure Gateway (SG) processor instruction for calls to the secure domain.</li>
 149 </ul>
 150 <p><b>Notations</b></p>
 151 <p>This manual uses the following notations to identify functions and hardware resources that are related to TrustZone for Armv8-M:</p>
 152 <ul>
 153 <li>prefix <code>TZ</code> or <code>__TZ</code> indicates a function that is available only in Armv8-M TrustZone enabled devices.</li>
 154 <li>postfix <code>_NS</code> indicates a hardware resource that belongs to the Non-secure state.</li>
 155 <li>postfix <code>_S</code> indicates a hardware resource that belongs to the Secure state.</li>
 156 </ul>
 157 <h1><a class="anchor" id="useCase_TrustZone"></a>
 158 Simplified Use Case with TrustZone</h1>
 159 <p>An Armv8-M TrustZone enabled device has restricted access for data, code, and I/O access to trusted software that runs in the Secure state. Typical applications are secure IoT nodes, firmware IP protection, or multi-party embedded software deployments.</p>
 160 <p>The figure <b>Simplified Use Case</b> shows and embedded application that is split into a <b>User Project</b> (executed in Non-secure state) and a <b>Firmware Project</b> (executed in Secure state).</p>
 161 <ul>
 162 <li><b>System Start:</b> after power on or reset, an Armv8-M system starts code execution in the <b>Secure state</b>. The access rights for the <b>Non-secure state</b> is configured.</li>
 163 <li><b>User Application:</b> control can be transferred to <b>Non-secure state</b> to execute user code. This code can only call functions in the <b>secure state</b> that are marked for execution with the <b>SG</b> (secure gate) instruction and memory attributes. Any attempt to access memory or peripherals that are assigned to the <b>Secure state</b> triggers a security exception.</li>
 164 <li><b>Firmware callbacks:</b> code running in the <b>Secure state</b> can execute code in the <b>Non-secure state</b> using call-back function pointers. For example, a communication stack (protected firmware) could use an I/O driver that is configured in user space.</li>
 165 </ul>
 166 <p><a class="anchor" id="SimpleUseCase"></a> </p><div class="image">
 167 <img src="SimpleUseCase.png" alt=""/>
 168 <div class="caption">
 169 Simplified Use Case</div></div>
 170     <p>Program execution in the <b>Secure state</b> is further protected by TrustZone hardware from software failures.</p>
 171 <p>For example, an Armv8-M system may implement two independent SYSTICK timers which allows to stop code execution in <b>Non-secure state</b> in case of timing violations. Also function pointer callbacks from <b>Secure state</b> to <b>Non-secure state</b> protected by a special CPU instruction and the address bit 0 which prevents anciently executing code in <b>Non-secure state</b>.</p>
 172 <h1><a class="anchor" id="Example_TrustZone"></a>
 173 Program Examples</h1>
 174 <p>This <a href="https://github.com/ARM-software/CMSIS-RTX">CMSIS-RTX</a> contains the following program examples that show the usage of TrustZone for Armv8-M on Cortex-M33 devices:</p>
 175 <table class="markdownTable">
 176 <tr class="markdownTableHead">
 177 <th class="markdownTableHeadLeft">Example   </th><th class="markdownTableHeadLeft">Description    </th></tr>
 178 <tr class="markdownTableRowOdd">
 179 <td class="markdownTableBodyLeft">TrustZone for Armv8-M No RTOS   </td><td class="markdownTableBodyLeft">bare-metal secure/non-secure programming without RTOS (shows the Simplified Use Case).    </td></tr>
 180 <tr class="markdownTableRowEven">
 181 <td class="markdownTableBodyLeft">TrustZone for Armv8-M RTOS   </td><td class="markdownTableBodyLeft">secure/non-secure RTOS example with thread context management    </td></tr>
 182 <tr class="markdownTableRowOdd">
 183 <td class="markdownTableBodyLeft">TrustZone for Armv8-M RTOS Security Tests   </td><td class="markdownTableBodyLeft">secure/non-secure RTOS example with security test cases and system recovery   </td></tr>
 184 </table>
 185 <p>Other sample application that reflects this <a href="#SimpleUseCase"><b>Simplified Use Case</b></a> is the <b>Armv8MBL Secure/Non-Secure example</b> that is available in the Software Pack <b>Keil - Arm V2M-MPS2 Board Support PACK for Cortex-M System Design Kit Devices</b> (Keil:V2M-MPS2_CMx_BSP.1.2.0.pack or higher).</p>
 186 <h1><a class="anchor" id="Model_TrustZone"></a>
 187 Programmers Model with TrustZone</h1>
 188 <p>The figure <a href="#MemoryMap_S"><b>Secure Memory Map</b></a> shows the memory view for the <b>Secure state</b>. In the Secure state all memory and peripherals can be accessed. The <b>System Control and Debug</b> area provides access to secure peripherals and non-secure peripherals that are mirrored at a memory alias.</p>
 189 <p>The secure peripherals are only accessible during program execution in <b>Secure state</b>. The Secure Attribute Unit (SAU) configures the non-secure memory, peripheral, and interrupt access. Also available are a secure MPU (memory protection unit), secure SCB (system control block), and secure SysTick timer.</p>
 190 <p>The system supports two separate interrupt vector tables for secure and non-secure code execution.</p>
 191 <p>This interrupt assignment is controlled during <b>Secure state</b> code execution via the NVIC (nested vector interrupt controller).</p>
 192 <p><a class="anchor" id="MemoryMap_S"></a> </p><div class="image">
 193 <img src="MemoryMap_S.png" alt=""/>
 194 <div class="caption">
 195 Secure Memory Map</div></div>
 196     <p>The figure <a href="#MemoryMap_NS"><b>Non-Secure Memory Map</b></a> shows the memory view for the Non-secure state. This memory view is identical to the traditional Cortex-M memory map. Access to any secure memory or peripheral space triggers the secure exception that executes a handler in <b>Secure state</b>.</p>
 197 <p>The <a class="el" href="partition_h_pg.html">TrustZone setup: partition_&lt;Device&gt;.h</a> defines the initial setup of the <a href="#MemoryMap_NS"><b>Non-Secure Memory Map</b></a> during system start in the Secure state (refer to functions <a class="el" href="group__system__init__gr.html#ga93f514700ccf00d08dbdcff7f1224eb2">SystemInit</a> and <a class="el" href="group__sau__trustzone__functions.html#ga6093bc5939ea8924fbcfdffb8f0553f1">TZ_SAU_Setup</a>).</p>
 198 <p><a class="anchor" id="MemoryMap_NS"></a> </p><div class="image">
 199 <img src="MemoryMap_NS.png" alt=""/>
 200 <div class="caption">
 201 Non-Secure Memory Map</div></div>
 202     <p>The figure <b>Registers</b> shows the register view of the Armv8-M system with TrustZone. As the general purpose registers are can be accessed from any state (secure or non-secure), function calls between the states use these registers for parameter and return values.</p>
 203 <p>The register R13 is the stack pointer alias, and the actual stack pointer (PSP_NS, MSP_NS, PSP_S, MSP_S) accessed depends on state (Secure or Non-secure) and mode (handler=exception/interrupt execution or thread=normal code execution).</p>
 204 <p>In Armv8-M Mainline, each stack pointer has a limit register (PSPLIM_NS, MSPLIM_NS, PSPLIM_S, MSPLIM_S) that traps stack overflows with the <b>UsageFault</b> exception (register UFSR bit STKOF=1).</p>
 205 <p>An Armv8-M system with TrustZone has an independent <b>CONTROL</b> register for each state (Secure or Non-secure).</p>
 206 <p>The interrupt/exception control registers (PRIMASK, FAULTMASK, BASEPRI) are banked between the states (Secure or Non-secure), however the interrupt priority for the Non-Secure state can be lowered (SCB_AIRCR register bit PRIS) so that secure interrupts have always higher priority.</p>
 207 <p>The core registers of the current state (Secure or Non-secure) are accessed using the standard <a class="el" href="group__Core__Register__gr.html">Core Register Access</a> functions. In Secure state all non-secure registers are accessible using the <a class="el" href="group__coreregister__trustzone__functions.html">Core Register Access Functions</a> related to TrustZone for Armv8-M.</p>
 208 <div class="image">
 209 <img src="Registers.png" alt=""/>
 210 <div class="caption">
 211 Registers</div></div>
 212     <h1><a class="anchor" id="RTOS_TrustZone_stacksealing"></a>
 213 Stack Sealing</h1>
 214 <p>CMSIS-Core <a class="el" href="group__stacksealing__support__trustzone__functions.html">Stack Sealing Support Functions</a> provide standard interface for implementing the <a href="https://developer.arm.com/Arm%20Security%20Center/Armv8-M%20Stack%20Sealing%20Vulnerability">Secure Stack Sealing technique</a> recommended for mitigating some security vulnerabilities on Armv8-M systems with TrustZone.</p>
 215 <p><a class="el" href="startup_c_pg.html#startup_c_sec">startup_Device.c Template File</a> demonstrates how this functionality can be used in a device startup file.</p>
 216 <p>Stack Sealing also requires an application project to have a linker script that explicitly reserves 8 bytes for the stack seal on top of the secure main stack. Linker files provided with <a class="el" href="cmsis_files_dfps.html#device_examples">Device Examples</a> for Armv8-M cores demonstrate how this can be implemented. For example see .\Device\ARM\ARMCM33\Source\ARM\ARMCM33_ac6.sct.</p>
 217 <p>To learn more about the stack sealing implementation in CMSIS projects for Armv8-M devices, refer to <a href="https://developer.arm.com/documentation/kan335" target="_blank"><b>Application Note 335</b></a>.</p>
 218 <h1><a class="anchor" id="CMSIS_Files_TrustZone"></a>
 219 CMSIS Files for TrustZone</h1>
 220 <p>The CMSIS-Core files are extended by the header files <a class="el" href="partition_h_pg.html">TrustZone setup: partition_&lt;Device&gt;.h</a> and <a class="el" href="partition_h_pg.html#partition_gen_h_pg">Region/ISR setup: partition_gen.h</a> :</p>
 221 <ul>
 222 <li>The file <a class="el" href="partition_h_pg.html">partition_&lt;Device&gt;.h</a> defines the initial system configuration and during SystemInit in Secure state.</li>
 223 <li>The file <a class="el" href="partition_h_pg.html#partition_gen_h_pg">partition_gen.h</a> is optional and contains SAU region and interrupt target assignments. This file may be generated using CMSIS-Zone.</li>
 224 </ul>
 225 <blockquote class="doxtable">
 226 <p>&zwj;<b>Note</b></p><ul>
 227 <li>Refer to <a class="el" href="using_pg.html">Using CMSIS-Core</a> for a general description of the CMSIS-Core (Cortex-M) files. </li>
 228 </ul>
 229 </blockquote>
 230 <p><img src="CMSIS_TZ_files.png" alt="" class="inline" title="CMSIS with extensions for TrustZone"/>    </p>
 231 <h1><a class="anchor" id="RTOS_TrustZone"></a>
 232 RTOS Thread Context Management</h1>
 233 <p>To provide a consistent RTOS thread context management for Armv8-M TrustZone across the various real-time operating systems (RTOS), the CMSIS-Core (Cortex-M) includes header file <b>tz_context.h</b> with API definitions.</p>
 234 <p>A <em>non-secure application</em> which uses an RTOS and calls <em>secure</em> library modules requires the management of the <em>secure</em> stack space. Since <em>secure state</em> registers cannot be accessed by the RTOS that runs in <em>non-secure state</em> secure functions implement the thread context switch.</p>
 235 <p>As the <em>non-secure state</em> and <em>secure state</em> parts of an application are separated, the API for managing the <em>secure</em> stack space should be standardized. Otherwise the <em>secure</em> library modules would force the <em>non-secure state</em> application to use a matching RTOS implementation.</p>
 236 <div class="image">
 237 <img src="TZ_context.png" alt=""/>
 238 <div class="caption">
 239 RTOS Thread Context Management for Armv8-M TrustZone</div></div>
 240     <p>To allocate the context memory for threads, an RTOS kernel that runs in <em>non-secure state</em> calls the interface functions defined by the header file <b>tz_context.h</b>. The <b>TZ Context</b> functions themselves are part of the <em>secure state</em> application. An minimum implementation is provided as part of RTOS2 and should handle the secure stack for the thread execution. However it is also possible to implement the context memory management system with additional features such as access control to <em>secure state</em> memory regions using an MPU.</p>
 241 <p>The API functions of <b>TZ Context</b> are described in the chapter <a href="modules.html">API Reference</a> under <a class="el" href="group__trustzone__functions.html">TrustZone for Armv8-M/v8.1-M</a> - <a class="el" href="group__context__trustzone__functions.html">RTOS Context Management</a>.</p>
 242 <p>CMSIS-Core provides a template implementation of <b>TZ Contenxt</b> in <code>CMSIS\Core\Template\ARMv8-M\tz_context.c</code> file.</p>
 243 <p>Refer to <a class="el" href="using_TrustZone_pg.html#Example_TrustZone">Program Examples</a> for RTOS examples that demonstrate how to use the RTOS Thread Context Management. </p>
 244 </div></div><!-- contents -->
 245 </div><!-- PageDoc -->
 246 </div><!-- doc-content -->
 247 <!-- start footer part -->
 248 <div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
 249   <ul>
 250     <li class="footer">
 251       <script type="text/javascript">
 252         <!--
 253         writeFooter.call(this);
 254         //-->
 255       </script>
 256     </li>
 257   </ul>
 258 </div>
 259 </body>
 260 </html>