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

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