begriffs open source - cmsis/blob - CMSIS/DoxyGen/Core/src/UsingTrustZone.txt

   1 /**
   2 \cond (ARMv8M)
   3 */
   4
   5 /**
   6 \page using_TrustZone_pg  Using TrustZone for Armv8-M
   7
   8
   9 \details
  10 The optional Armv8-M Security Extension is similar to Arm TrustZone technology used in Cortex-A processors, but is
  11 optimized for ultra-low power embedded applications. TrustZone for Armv8-M enables of multiple software security
  12 domains that restrict access to secure memory and I/O only for trusted software.
  13
  14 TrustZone for Armv8-M:
  15   - preserves low interrupt latencies for both Secure and Non-secure domains.
  16   - does not impose code overhead, cycle overhead or the complexity of a virtualization based solution.
  17   - introduces the Secure Gateway (SG) processor instruction for calls to the secure domain.
  18
  19 \b Notations
  20
  21 This manual uses the following notations to identify functions and hardware resources that are related to TrustZone for Armv8-M:
  22
  23  - prefix \b TZ or \b __TZ indicates a function that is available only in Armv8-M TrustZone enabled devices.
  24  - postfix \b _NS indicates a hardware resource that belongs to the Non-secure state.
  25  - postfix \b _S indicates a hardware resource that belongs to the Secure state.
  26
  27
  28 \section useCase_TrustZone Simplified Use Case with TrustZone
  29
  30 An Armv8-M TrustZone enabled device has restricted access for data, code, and I/O access to trusted
  31 software that runs in the Secure state. Typical applications are secure IoT nodes, firmware IP protection,
  32 or multi-party embedded software deployments.
  33
  34 The figure <b>Simplified Use Case</b> shows and embedded application that is split into a <b>User Project</b>
  35 (executed in Non-secure state) and a <b>Firmware Project</b> (executed in Secure state).
  36
  37  - <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.
  38
  39  - <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.
  40
  41  - <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.
  42
  43 \anchor SimpleUseCase
  44 \image html "SimpleUseCase.png" "Simplified Use Case"
  45
  46 Program execution in the <b>Secure state</b> is further protected by TrustZone hardware from software failures.
  47 For example, an Armv8-M system may implement two independent SYSTICK timers which allows to stop code execution
  48 in <b>Non-secure state</b> in case of timing violations. Also function pointer callbacks from <b>Secure state</b>
  49 to <b>Non-secure state</b> protected by a special CPU instruction and the address bit 0 which prevents anciently
  50 executing code in <b>Non-secure state</b>.
  51
  52 \subsection Example_TrustZone Program Examples
  53
  54 This CMSIS software pack contains the following program examples that show the usage of TrustZone for Armv8-M on Cortex-M33 devices:
  55
  56 Example                                     | Description
  57 :-------------------------------------------|:----------------
  58 TrustZone for Armv8-M No RTOS               | bare-metal secure/non-secure programming without RTOS (shows the Simplified Use Case).
  59 TrustZone for Armv8-M RTOS                  | secure/non-secure RTOS example with thread context management
  60 TrustZone for Armv8-M RTOS Security Tests   | secure/non-secure RTOS example with security test cases and system recovery
  61
  62 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
  63 the Software Pack <b>Keil - Arm V2M-MPS2 Board Support PACK for Cortex-M System Design Kit Devices</b>
  64 (Keil:V2M-MPS2_CMx_BSP.1.2.0.pack or higher).
  65
  66 \section Model_TrustZone Programmers Model with TrustZone
  67
  68 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
  69 memory and peripherals can be accessed. The <b>System Control and Debug</b> area provides access to secure peripherals
  70 and non-secure peripherals that are mirrored at a memory alias.
  71
  72 The secure peripherals are only accessible during program execution in <b>Secure state</b>. The Secure Attribute Unit (SAU)
  73 configures the non-secure memory, peripheral, and interrupt access. Also available are a secure MPU (memory protection
  74 unit), secure SCB (system control block), and secure SysTick timer.
  75
  76 The system supports two separate interrupt vector tables for secure and non-secure code execution.
  77 This interrupt assignment is controlled during <b>Secure state</b> code execution via the NVIC
  78 (nested vector interrupt controller).
  79
  80 \anchor MemoryMap_S
  81 \image html "MemoryMap_S.png" "Secure Memory Map"
  82
  83 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
  84 to the traditional Cortex-M memory map. Access to any secure memory or peripheral space triggers the secure exception
  85 that executes a handler in <b>Secure state</b>.
  86
  87 The \ref partition_h_pg defines the initial setup of the <a href="#MemoryMap_NS"><b>Non-Secure Memory Map</b></a> during system start in the Secure state
  88 (refer to functions \ref SystemInit and \ref TZ_SAU_Setup).
  89
  90 <!-- <img id="MemoryMap_NS" src="MemoryMap_NS.png"><CENTER><b>Non-Secure Memory Map</b></CENTER> -->
  91
  92 \anchor MemoryMap_NS
  93 \image html "MemoryMap_NS.png" "Non-Secure Memory Map"
  94
  95 The figure <b>Registers</b> shows the register view of the Armv8-M system with TrustZone. As the general purpose registers
  96 are can be accessed from any state (secure or non-secure), function calls between the states use these registers for parameter
  97 and return values.
  98
  99 The register R13 is the stack pointer alias, and the actual stack pointer (PSP_NS, MSP_NS, PSP_S, MSP_S)
 100 accessed depends on state (Secure or Non-secure) and mode (handler=exception/interrupt execution or
 101 thread=normal code execution).
 102
 103 In Armv8-M Mainline, each stack pointer has a limit register (PSPLIM_NS, MSPLIM_NS, PSPLIM_S, MSPLIM_S)
 104 that traps stack overflows with the \b UsageFault exception (register UFSR bit STKOF=1).
 105
 106 An Armv8-M system with TrustZone has an independent \b CONTROL register for each state (Secure or Non-secure).
 107 The interrupt/exception control registers (PRIMASK, FAULTMASK, BASEPRI) are banked between the states (Secure or Non-secure),
 108 however the interrupt priority for the Non-Secure state can be lowered (SCB_AIRCR register bit PRIS) so that
 109 secure interrupts have always higher priority.
 110
 111 The core registers of the current state (Secure or Non-secure) are accessed using the standard \ref Core_Register_gr
 112 functions. In Secure state all non-secure registers are accessible using the \ref coreregister_trustzone_functions
 113 related to TrustZone for Armv8-M.
 114
 115 \image html "Registers.png" "Registers"
 116
 117 \section CMSIS_Files_TrustZone CMSIS Files for TrustZone
 118
 119 The CMSIS-Core files are extended by the \ref partition_h_pg which defines the initial system configuration and
 120 during \ref SystemInit in Secure state.
 121
 122 \image html "CMSIS_TZ_files.png" "CMSIS with extensions for TrustZone"
 123
 124 \note
 125 Refer to \ref using_pg for a general description of the CMSIS-Core (Cortex-M) files.
 126
 127
 128 \subsection RTOS_TrustZone RTOS Thread Context Management
 129
 130 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.
 131 An <i>non-secure application</i> which uses an RTOS and calls <i>secure</i> library modules requires the management of the <i>secure</i> stack space.   Since <i>secure state</i> registers cannot be accessed
 132 by the RTOS that runs in <i>non-secure state</i> secure functions implement the thread context switch.
 133
 134 As the <i>non-secure state</i> and <i>secure state</i> parts of an application are separated, the API for managing the <i>secure</i> stack space should be standardized. Otherwise the <i>secure</i> library modules
 135 would force the <i>non-secure state</i> application to use a matching RTOS implementation.
 136
 137 \image html "TZ_context.png" "RTOS Thread Context Management for Armv8-M TrustZone"
 138
 139 To allocate the context memory for threads, an RTOS kernel that runs in <i>non-secure state</i> calls the interface functions defined by the header file <b>TZ_context.h</b>. The <b>TZ_context</b> functions itself are
 140 part of the <i>secure state</i> 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
 141 management system with additional features such as access control to <i>secure state</i> memory regions using an MPU.
 142
 143 The API functions of <b>TZ_context</b> are described in the chapter <a href="Modules.html">\b Reference </a> under \ref trustzone_functions - \ref context_trustzone_functions.
 144
 145 Refer to \ref Example_TrustZone for RTOS examples that provide a template implementation for <b>TZ_context.c</b>.
 146
 147 */
 148
 149 /**
 150 \endcond
 151 */