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

   1 /**
   2 \cond (ARMv8M)
   3 */
   4
   5 /**
   6 \defgroup trustzone_functions TrustZone for Armv8-M/v8.1-M
   7 \brief Functions that related to optional Armv8-M and Armv8.1-M security extension
   8   @{
   9 \details
  10 The Armv8-M architecture has optional Armv8-M security extension based on Arm TrustZone technology.
  11 To access Arm TrustZone extensions for Armv8-M additional CMSIS functions are provided:
  12  - \ref coreregister_trustzone_functions
  13  - \ref nvic_trustzone_functions
  14  - \ref systick_trustzone_functions
  15  - \ref sau_trustzone_functions
  16  - \ref context_trustzone_functions
  17 */
  18
  19 /**
  20   \defgroup coreregister_trustzone_functions Core Register Access Functions
  21   \brief Core register Access functions related to TrustZone for Armv8-M.
  22   @{
  23 */
  24
  25 /**
  26   \brief   Get Control register (non-secure)
  27   \details Returns the content of the non-secure Control register when in secure mode.
  28   \return               non-secure Control register value
  29   \sa
  30     - \ref __get_CONTROL; CONTROL_Type
  31  */
  32 uint32_t __TZ_get_CONTROL_NS(void);
  33
  34 /**
  35   \brief   Set Control register (non-secure)
  36   \details Writes the given value to the non-secure Control register when in secure state.
  37   \param [in]    control  Control register value to set
  38   \sa
  39     - \ref __set_CONTROL; CONTROL_Type
  40  */
  41 void __TZ_set_CONTROL_NS(uint32_t control);
  42
  43 /**
  44   \brief   Get Process Stack Pointer (non-secure)
  45   \details Returns the current value of the non-secure Process Stack Pointer (PSP) when in secure state.
  46   \return               PSP register value
  47   \sa
  48     - \ref __get_PSP
  49  */
  50 uint32_t __TZ_get_PSP_NS(void);
  51
  52 /**
  53   \brief   Set Process Stack Pointer (non-secure)
  54   \details Assigns the given value to the non-secure Process Stack Pointer (PSP) when in secure state.
  55   \param [in]    topOfProcStack  Process Stack Pointer value to set
  56   \sa
  57     - \ref __set_PSP
  58  */
  59 void __TZ_set_PSP_NS(uint32_t topOfProcStack);
  60
  61 /**
  62   \brief   Get Main Stack Pointer (non-secure)
  63   \details Returns the current value of the non-secure Main Stack Pointer (MSP) when in secure state.
  64   \return               MSP register value
  65   \sa
  66     - \ref __get_MSP
  67  */
  68 uint32_t __TZ_get_MSP_NS(void);
  69
  70 /**
  71   \brief   Set Main Stack Pointer (non-secure)
  72   \details Assigns the given value to the non-secure Main Stack Pointer (MSP) when in secure state.
  73   \param [in]    topOfMainStack  Main Stack Pointer value to set
  74   \sa
  75     - \ref __set_MSP
  76  */
  77 void __TZ_set_MSP_NS(uint32_t topOfMainStack);
  78
  79 /**
  80   \brief   Get Stack Pointer (non-secure)
  81   \details Returns the current value of the non-secure Stack Pointer (SP) when in secure state.
  82   \return               SP register value
  83  */
  84 uint32_t __TZ_get_SP_NS(void);
  85
  86 /**
  87   \brief   Set Stack Pointer (non-secure)
  88   \details Assigns the given value to the non-secure Stack Pointer (SP) when in secure state.
  89   \param [in]    topOfStack  Stack Pointer value to set
  90  */
  91 void __TZ_set_SP_NS(uint32_t topOfStack);
  92
  93 /**
  94   \brief   Get Priority Mask (non-secure)
  95   \details Returns the current state of the non-secure priority mask bit from the Priority Mask register when in secure state.
  96   \return               Priority Mask value
  97   \sa
  98     - \ref __get_PRIMASK
  99  */
 100 uint32_t __TZ_get_PRIMASK_NS(void);
 101
 102 /**
 103   \brief   Set Priority Mask (non-secure)
 104   \details Assigns the given value to the non-secure Priority Mask register when in secure state.
 105   \param [in]    priMask  Priority Mask
 106   \sa
 107     - \ref __set_PRIMASK
 108  */
 109 void __TZ_set_PRIMASK_NS(uint32_t priMask);
 110
 111 /**
 112   \brief   Get Base Priority (non-secure)
 113   \details Returns the current value of the non-secure Base Priority register when in secure state.
 114   \return               Base Priority register value
 115   \sa
 116     - \ref __get_BASEPRI
 117  */
 118 uint32_t __TZ_get_BASEPRI_NS(void);
 119
 120 /**
 121   \brief   Set Base Priority (non-secure)
 122   \details Assigns the given value to the non-secure Base Priority register when in secure state.
 123   \param [in]    basePri  Base Priority value to set
 124   \sa
 125     - \ref __set_BASEPRI
 126  */
 127 void __TZ_set_BASEPRI_NS(uint32_t basePri);
 128
 129 /**
 130   \brief   Get Fault Mask (non-secure)
 131   \details Returns the current value of the non-secure Fault Mask register when in secure state.
 132   \return               Fault Mask register value
 133   \sa
 134     - \ref __get_FAULTMASK
 135  */
 136 uint32_t __TZ_get_FAULTMASK_NS(void);
 137
 138 /**
 139   \brief   Set Fault Mask (non-secure)
 140   \details Assigns the given value to the non-secure Fault Mask register when in secure state.
 141   \param [in]    faultMask  Fault Mask value to set
 142   \sa
 143     - \ref __set_FAULTMASK
 144  */
 145 void __TZ_set_FAULTMASK_NS(uint32_t faultMask);
 146
 147 /**
 148   \brief   Get Process Stack Pointer Limit (non-secure)
 149   Devices without Armv8-M Main Extensions (i.e. Cortex-M23) lack the non-secure
 150   Stack Pointer Limit register hence zero is returned always.
 151
 152   \details Returns the current value of the non-secure Process Stack Pointer Limit (PSPLIM) when in secure state.
 153   \return               PSPLIM register value
 154  */
 155 uint32_t __TZ_get_PSPLIM_NS(void);
 156
 157 /**
 158   \brief   Set Process Stack Pointer (non-secure)
 159   Devices without Armv8-M Main Extensions (i.e. Cortex-M23) lack the non-secure
 160   Stack Pointer Limit register hence zero is returned always.
 161
 162   \details Assigns the given value to the non-secure Process Stack Pointer Limit (PSPLIM) when in secure state.
 163   \param [in]    ProcStackPtrLimit  Process Stack Pointer Limit value to set
 164  */
 165 void __TZ_set_PSPLIM_NS(uint32_t ProcStackPtrLimit);
 166
 167 /**
 168   \brief   Get Main Stack Pointer Limit (non-secure)
 169   Devices without Armv8-M Main Extensions (i.e. Cortex-M23) lack the non-secure
 170   Stack Pointer Limit register hence zero is returned always.
 171
 172   \details Returns the current value of the non-secure Main Stack Pointer Limit(MSPLIM) when in secure state.
 173   \return               MSPLIM register value
 174  */
 175 uint32_t __TZ_get_MSPLIM_NS(void);
 176
 177 /**
 178   \brief   Set Main Stack Pointer Limit (non-secure)
 179   Devices without Armv8-M Main Extensions (i.e. Cortex-M23) lack the non-secure
 180   Stack Pointer Limit register hence zero is returned always.
 181
 182   \details Assigns the given value to the non-secure Main Stack Pointer Limit (MSPLIM) when in secure state.
 183   \param [in]    MainStackPtrLimit  Main Stack Pointer value to set
 184  */
 185 void __TZ_set_MSPLIM_NS(uint32_t MainStackPtrLimit);
 186
 187 /** close coreregister_trustzone_functions
 188   @}
 189 */
 190
 191 /**
 192   \defgroup nvic_trustzone_functions NVIC Functions
 193   \brief Nested Vector Interrupt Controller (NVIC) functions related to TrustZone for Armv8-M
 194   @{
 195 */
 196
 197 /**
 198   \brief   Set Priority Grouping (non-secure)
 199   \details Sets the non-secure priority grouping field when in secure state using the required unlock sequence.
 200            The parameter PriorityGroup is assigned to the field SCB->AIRCR [10:8] PRIGROUP field.
 201            Only values from 0..7 are used.
 202            In case of a conflict between priority grouping and available
 203            priority bits (__NVIC_PRIO_BITS), the smallest possible priority group is set.
 204   \param [in]      PriorityGroup  Priority grouping field.
 205   \note    Only available for Armv8-M Mainline.
 206   \sa
 207     - \ref NVIC_SetPriorityGrouping
 208  */
 209 void TZ_NVIC_SetPriorityGrouping_NS(uint32_t PriorityGroup);
 210
 211 /**
 212   \brief   Get Priority Grouping (non-secure)
 213   \details Reads the priority grouping field from the non-secure NVIC when in secure state.
 214   \return                Priority grouping field (SCB->AIRCR [10:8] PRIGROUP field).
 215   \note    Only available for Armv8-M Mainline.
 216   \sa
 217     - \ref NVIC_GetPriorityGrouping
 218  */
 219 uint32_t TZ_NVIC_GetPriorityGrouping_NS(void);
 220
 221 /**
 222   \brief   Enable External Interrupt (non-secure)
 223   \details Enables a device-specific interrupt in the non-secure NVIC when in secure state.
 224   \param [in]      IRQn  External interrupt number. Value cannot be negative.
 225   \sa
 226     - \ref NVIC_EnableIRQ
 227  */
 228 void TZ_NVIC_EnableIRQ_NS(IRQn_Type IRQn);
 229
 230
 231 /**
 232   \brief   Get Interrupt Enable status (non-secure)
 233   \details Returns a device specific interrupt enable status from the non-secure NVIC interrupt controller when in secure state.
 234   \param [in]      IRQn  Interrupt number.
 235   \return             0  Interrupt is not enabled.
 236   \return             1  Interrupt is enabled.
 237   \sa
 238     - \ref NVIC_EnableIRQ; NVIC_DisableIRQ;
 239  */
 240 uint32_t TZ_NVIC_GetEnableIRQ_NS(IRQn_Type IRQn);
 241
 242 /**
 243   \brief   Disable External Interrupt (non-secure)
 244   \details Disables a device-specific interrupt in the non-secure NVIC when in secure state.
 245   \param [in]      IRQn  External interrupt number. Value cannot be negative.
 246   \sa
 247     - \ref NVIC_DisableIRQ
 248  */
 249 void TZ_NVIC_DisableIRQ_NS(IRQn_Type IRQn);
 250
 251 /**
 252   \brief   Get Pending Interrupt (non-secure)
 253   \details Reads the pending register in the non-secure NVIC when in secure state and returns the pending bit for the specified interrupt.
 254   \param [in]      IRQn  Interrupt number.
 255   \return             0  Interrupt status is not pending.
 256   \return             1  Interrupt status is pending.
 257   \sa
 258     - \ref NVIC_GetPendingIRQ
 259  */
 260 uint32_t TZ_NVIC_GetPendingIRQ_NS(IRQn_Type IRQn);
 261
 262 /**
 263   \brief   Set Pending Interrupt (non-secure)
 264   \details Sets the pending bit of an non-secure external interrupt when in secure state.
 265   \param [in]      IRQn  Interrupt number. Value cannot be negative.
 266   \sa
 267     - \ref NVIC_SetPendingIRQ
 268  */
 269 void TZ_NVIC_SetPendingIRQ_NS(IRQn_Type IRQn);
 270
 271 /**
 272   \brief   Clear Pending Interrupt (non-secure)
 273   \details Clears the pending bit of an non-secure external interrupt when in secure state.
 274   \param [in]      IRQn  External interrupt number. Value cannot be negative.
 275   \sa
 276     - \ref NVIC_ClearPendingIRQ
 277  */
 278 void TZ_NVIC_ClearPendingIRQ_NS(IRQn_Type IRQn);
 279
 280 /**
 281   \brief   Get Active Interrupt (non-secure)
 282   \details Reads the active register in non-secure NVIC when in secure state and returns the active bit.
 283   \param [in]      IRQn  Interrupt number.
 284   \return             0  Interrupt status is not active.
 285   \return             1  Interrupt status is active.
 286   \sa
 287     - \ref NVIC_GetActive
 288  */
 289 uint32_t TZ_NVIC_GetActive_NS(IRQn_Type IRQn);
 290
 291 /**
 292   \brief   Set Interrupt Priority (non-secure)
 293   \details Sets the priority of an non-secure interrupt when in secure state.
 294   \note    The priority cannot be set for every core interrupt.
 295   \param [in]      IRQn  Interrupt number.
 296   \param [in]  priority  Priority to set.
 297   \sa
 298     - \ref NVIC_SetPriority
 299  */
 300 void TZ_NVIC_SetPriority_NS(IRQn_Type IRQn, uint32_t priority);
 301
 302 /**
 303   \brief   Get Interrupt Priority (non-secure)
 304   \details Reads the priority of an non-secure interrupt when in secure state.
 305            The interrupt number can be positive to specify an external (device specific) interrupt,
 306            or negative to specify an internal (core) interrupt.
 307   \param [in]   IRQn  Interrupt number.
 308   \return             Interrupt Priority. Value is aligned automatically to the implemented priority bits of the microcontroller.
 309   \sa
 310     - \ref NVIC_GetPriority
 311  */
 312 uint32_t TZ_NVIC_GetPriority_NS(IRQn_Type IRQn);
 313
 314 /** close nvic_trustzone_functions
 315   @}
 316 */
 317
 318
 319 /**
 320   \defgroup systick_trustzone_functions SysTick Functions
 321   \brief SysTick functions related to TrustZone for Armv8-M.
 322   @{
 323 */
 324
 325 /**
 326   \brief   System Tick Configuration (non-secure)
 327   \details Initializes the non-secure System Timer and its interrupt when in secure state, and starts the System Tick Timer.
 328            Counter is in free running mode to generate periodic interrupts.
 329   \param [in]  ticks  Number of ticks between two interrupts.
 330   \return          0  Function succeeded.
 331   \return          1  Function failed.
 332   \note    When the variable <b>__Vendor_SysTickConfig</b> is set to 1, then the
 333            function <b>TZ_SysTick_Config_NS</b> is not included. In this case, the file <b><i>device</i>.h</b>
 334            must contain a vendor-specific implementation of this function.
 335   \sa
 336     - \ref SysTick_Config
 337  */
 338 uint32_t TZ_SysTick_Config_NS(uint32_t ticks);
 339
 340 /** close systick_trustzone_functions
 341   @}
 342 */
 343
 344
 345 /**
 346   \defgroup sau_trustzone_functions SAU Functions
 347   \brief Secure Attribution Unit (SAU) functions related to TrustZone for Armv8-M.
 348   @{
 349 \details
 350 The Secure Attribution Unit (SAU) functions SAU
 351
 352 \note
 353 A SAU is always present if the security extension is available.
 354 The functionality differs if the SAU contains SAU regions.
 355 If SAU regions are available is configured with the macro __SAUREGION_PRESENT (see \ref core_config_sect).
 356
 357  */
 358
 359 /**
 360 \brief   Setup Secure Attribute Unit (SAU) and non-secure interrupts
 361 \details
 362 The function \ref TZ_SAU_Setup uses the settings in the \ref partition_h_pg to initialize
 363 the Secure Attribute Unit (SAU) and define non-secure interrupts.  It is called from
 364 the function \ref SystemInit.
 365  */
 366 void TZ_SAU_Setup (void);
 367
 368 /**
 369   \brief   Enable Security Attribution Unit (SAU)
 370   \details Enables the Security Attribution Unit (SAU).
 371  */
 372 void TZ_SAU_Enable(void);
 373
 374 /**
 375   \brief   Disable Security Attribution Unit (SAU)
 376   \details Disables the Security Attribution Unit (SAU).
 377  */
 378 void TZ_SAU_Disable(void);
 379
 380 /** close sau_trustzone_functions
 381   @}
 382 */
 383
 384
 385
 386
 387
 388 /**
 389   \defgroup context_trustzone_functions RTOS Context Management
 390   \brief RTOS Thread Context Management for Armv8-M TrustZone.
 391   @{
 392   \details 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 \ref RTOS_TrustZone.
 393 */
 394
 395 /**
 396   \brief Initialize secure context memory system
 397   \details Initializes the memory allocation management for the secure memory regions. As a minimum the secure thread mode stack will be provided.
 398   \return execution status (1: success, 0: error)
 399  */
 400 uint32_t TZ_InitContextSystem_S (void);
 401
 402 /**
 403   \brief Allocate context memory for calling secure software modules in TrustZone
 404   \details
 405     Allocates the secure memory regions for thread execution. The parameter \em module describes
 406     the set of secure functions that are called by the non-secure thread.
 407     Set \em module to zero if no secure calls are used/allowed. This leads to no secure memory to be assigned
 408     which results in zero being returned as memory id as well.
 409     This function should be called by an RTOS kernel at the start of a thread.
 410   \param[in]  module   A non-zero value identifies software modules called from non-secure mode. zero is used if no secure calls are used/allowed.
 411   \return value != 0 id TrustZone memory slot identify
 412   \return value 0    no memory available or internal error
 413  */
 414 TZ_MemoryId_t TZ_AllocModuleContext_S (TZ_ModuleId_t module);
 415
 416 /**
 417   \brief Free context memory that was previously allocated with \ref TZ_AllocModuleContext_S
 418   \details
 419     De-allocates the secure memory regions.
 420     The parameter \em id refers to a TrustZone memory slot that has been obtained with \ref TZ_AllocModuleContext_S.
 421     This function should be called by an RTOS kernel at the termination of a thread.
 422   \param[in]  id  TrustZone memory slot identifier
 423   \return execution status (1: success, 0: error)
 424  */
 425 uint32_t TZ_FreeModuleContext_S (TZ_MemoryId_t id);
 426
 427 /**
 428   \brief Load secure context (called on RTOS thread context switch)
 429   \details
 430     Prepare the secure context for execution so that a thread in the non-secure state can
 431     call secure library modules. The parameter \em id refers to a TrustZone memory slot that has been
 432     obtained with \ref TZ_AllocModuleContext_S which might be zero if not used.
 433     This function should be called by an RTOS kernel at thread context switch before running a thread.
 434   \param[in]  id  TrustZone memory slot identifier
 435   \return execution status (1: success, 0: error)
 436  */
 437 uint32_t TZ_LoadContext_S (TZ_MemoryId_t id);
 438
 439 /**
 440   \brief Store secure context (called on RTOS thread context switch)
 441   \details
 442     Free the secure context that has been previously loaded with \ref TZ_LoadContext_S. The parameter
 443     \em id refers to a TrustZone memory slot that has been obtained with \ref TZ_AllocModuleContext_S
 444     which might be zero if not used.
 445     This function should be called by an RTOS kernel at thread context switch after running a thread.
 446   \param[in]  id  TrustZone memory slot identifier
 447   \return execution status (1: success, 0: error)
 448  */
 449 uint32_t TZ_StoreContext_S (TZ_MemoryId_t id);
 450
 451
 452 /** close context_trustzone_functions
 453   @}
 454 */
 455
 456
 457 /** close trustzone_functions
 458 @}
 459 */
 460
 461 /**
 462 \endcond
 463 */