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   \details Returns the current value of the non-secure Process Stack Pointer Limit (PSPLIM) when in secure state.
 146   \return               PSPLIM register value
 147   \note    Only available for ARMv8-M Mainline.
 148  */
 149 uint32_t __TZ_get_PSPLIM_NS(void);
 150
 151 /**
 152   \brief   Set Process Stack Pointer (non-secure)
 153   \details Assigns the given value to the non-secure Process Stack Pointer Limit (PSPLIM) when in secure state.
 154   \param [in]    ProcStackPtrLimit  Process Stack Pointer Limit value to set
 155   \note    Only available for ARMv8-M Mainline.
 156  */
 157 void __TZ_set_PSPLIM_NS(uint32_t ProcStackPtrLimit);
 158
 159 /**
 160   \brief   Get Main Stack Pointer Limit (non-secure)
 161   \details Returns the current value of the non-secure Main Stack Pointer Limit(MSPLIM) when in secure state.
 162   \return               MSPLIM register value
 163   \note    Only available for ARMv8-M Mainline.
 164  */
 165 uint32_t __TZ_get_MSPLIM_NS(void);
 166
 167 /**
 168   \brief   Set Main Stack Pointer Limit (non-secure)
 169   \details Assigns the given value to the non-secure Main Stack Pointer Limit (MSPLIM) when in secure state.
 170   \param [in]    MainStackPtrLimit  Main Stack Pointer value to set
 171   \note    Only available for ARMv8-M Mainline.
 172  */
 173 void __TZ_set_MSPLIM_NS(uint32_t MainStackPtrLimit);
 174
 175 /** close coreregister_trustzone_functions
 176   @}
 177 */
 178
 179 /**
 180   \defgroup nvic_trustzone_functions NVIC Functions
 181   \brief Nested Vector Interrupt Controller (NVIC) functions related to TrustZone for ARMv8-M
 182   @{
 183 */
 184
 185 /**
 186   \brief   Set Priority Grouping (non-secure)
 187   \details Sets the non-secure priority grouping field when in secure state using the required unlock sequence.
 188            The parameter PriorityGroup is assigned to the field SCB->AIRCR [10:8] PRIGROUP field.
 189            Only values from 0..7 are used.
 190            In case of a conflict between priority grouping and available
 191            priority bits (__NVIC_PRIO_BITS), the smallest possible priority group is set.
 192   \param [in]      PriorityGroup  Priority grouping field.
 193   \note    Only available for ARMv8-M Mainline.
 194   \sa
 195     - \ref NVIC_SetPriorityGrouping
 196  */
 197 void TZ_NVIC_SetPriorityGrouping_NS(uint32_t PriorityGroup);
 198
 199 /**
 200   \brief   Get Priority Grouping (non-secure)
 201   \details Reads the priority grouping field from the non-secure NVIC when in secure state.
 202   \return                Priority grouping field (SCB->AIRCR [10:8] PRIGROUP field).
 203   \note    Only available for ARMv8-M Mainline.
 204   \sa
 205     - \ref NVIC_GetPriorityGrouping
 206  */
 207 uint32_t TZ_NVIC_GetPriorityGrouping_NS(void);
 208
 209 /**
 210   \brief   Enable External Interrupt (non-secure)
 211   \details Enables a device-specific interrupt in the non-secure NVIC when in secure state.
 212   \param [in]      IRQn  External interrupt number. Value cannot be negative.
 213   \sa
 214     - \ref NVIC_EnableIRQ
 215  */
 216 void TZ_NVIC_EnableIRQ_NS(IRQn_Type IRQn);
 217
 218
 219 /**
 220   \brief   Get Interrupt Enable status (non-secure)
 221   \details Returns a device specific interrupt enable status from the non-secure NVIC interrupt controller when in secure state.
 222   \param [in]      IRQn  Interrupt number.
 223   \return             0  Interrupt is not enabled.
 224   \return             1  Interrupt is enabled.
 225   \sa
 226     - \ref NVIC_EnableIRQ; NVIC_DisableIRQ;
 227  */
 228 uint32_t TZ_NVIC_GetEnableIRQ_NS(IRQn_Type IRQn);
 229
 230 /**
 231   \brief   Disable External Interrupt (non-secure)
 232   \details Disables a device-specific interrupt in the non-secure NVIC when in secure state.
 233   \param [in]      IRQn  External interrupt number. Value cannot be negative.
 234   \sa
 235     - \ref NVIC_DisableIRQ
 236  */
 237 void TZ_NVIC_DisableIRQ_NS(IRQn_Type IRQn);
 238
 239 /**
 240   \brief   Get Pending Interrupt (non-secure)
 241   \details Reads the pending register in the non-secure NVIC when in secure state and returns the pending bit for the specified interrupt.
 242   \param [in]      IRQn  Interrupt number.
 243   \return             0  Interrupt status is not pending.
 244   \return             1  Interrupt status is pending.
 245   \sa
 246     - \ref NVIC_GetPendingIRQ
 247  */
 248 uint32_t TZ_NVIC_GetPendingIRQ_NS(IRQn_Type IRQn);
 249
 250 /**
 251   \brief   Set Pending Interrupt (non-secure)
 252   \details Sets the pending bit of an non-secure external interrupt when in secure state.
 253   \param [in]      IRQn  Interrupt number. Value cannot be negative.
 254   \sa
 255     - \ref NVIC_SetPendingIRQ
 256  */
 257 void TZ_NVIC_SetPendingIRQ_NS(IRQn_Type IRQn);
 258
 259 /**
 260   \brief   Clear Pending Interrupt (non-secure)
 261   \details Clears the pending bit of an non-secure external interrupt when in secure state.
 262   \param [in]      IRQn  External interrupt number. Value cannot be negative.
 263   \sa
 264     - \ref NVIC_ClearPendingIRQ
 265  */
 266 void TZ_NVIC_ClearPendingIRQ_NS(IRQn_Type IRQn);
 267
 268 /**
 269   \brief   Get Active Interrupt (non-secure)
 270   \details Reads the active register in non-secure NVIC when in secure state and returns the active bit.
 271   \param [in]      IRQn  Interrupt number.
 272   \return             0  Interrupt status is not active.
 273   \return             1  Interrupt status is active.
 274   \sa
 275     - \ref NVIC_GetActive
 276  */
 277 uint32_t TZ_NVIC_GetActive_NS(IRQn_Type IRQn);
 278
 279 /**
 280   \brief   Set Interrupt Priority (non-secure)
 281   \details Sets the priority of an non-secure interrupt when in secure state.
 282   \note    The priority cannot be set for every core interrupt.
 283   \param [in]      IRQn  Interrupt number.
 284   \param [in]  priority  Priority to set.
 285   \sa
 286     - \ref NVIC_SetPriority
 287  */
 288 void TZ_NVIC_SetPriority_NS(IRQn_Type IRQn, uint32_t priority);
 289
 290 /**
 291   \brief   Get Interrupt Priority (non-secure)
 292   \details Reads the priority of an non-secure interrupt when in secure state.
 293            The interrupt number can be positive to specify an external (device specific) interrupt,
 294            or negative to specify an internal (core) interrupt.
 295   \param [in]   IRQn  Interrupt number.
 296   \return             Interrupt Priority. Value is aligned automatically to the implemented priority bits of the microcontroller.
 297   \sa
 298     - \ref NVIC_GetPriority
 299  */
 300 uint32_t TZ_NVIC_GetPriority_NS(IRQn_Type IRQn);
 301
 302 /** close nvic_trustzone_functions
 303   @}
 304 */
 305
 306
 307 /**
 308   \defgroup systick_trustzone_functions SysTick Functions
 309   \brief SysTick functions related to TrustZone for ARMv8-M.
 310   @{
 311 */
 312
 313 /**
 314   \brief   System Tick Configuration (non-secure)
 315   \details Initializes the non-secure System Timer and its interrupt when in secure state, and starts the System Tick Timer.
 316            Counter is in free running mode to generate periodic interrupts.
 317   \param [in]  ticks  Number of ticks between two interrupts.
 318   \return          0  Function succeeded.
 319   \return          1  Function failed.
 320   \note    When the variable <b>__Vendor_SysTickConfig</b> is set to 1, then the
 321            function <b>TZ_SysTick_Config_NS</b> is not included. In this case, the file <b><i>device</i>.h</b>
 322            must contain a vendor-specific implementation of this function.
 323   \sa
 324     - \ref SysTick_Config
 325  */
 326 uint32_t TZ_SysTick_Config_NS(uint32_t ticks);
 327
 328 /** close systick_trustzone_functions
 329   @}
 330 */
 331
 332
 333 /**
 334   \defgroup sau_trustzone_functions SAU Functions
 335   \brief Secure Attribution Unit (SAU) functions related to TrustZone for ARMv8-M.
 336   @{
 337 \details
 338 The Secure Attribution Unit (SAU) functions SAU
 339
 340 \note
 341 A SAU is always present if the security extension is available.
 342 The functionality differs if the SAU contains SAU regions.
 343 If SAU regions are available is configured with the macro __SAUREGION_PRESENT (see \ref core_config_sect).
 344
 345  */
 346
 347 /**
 348 \brief   Setup Secure Attribute Unit (SAU) and non-secure interrupts
 349 \details
 350 The function \ref TZ_SAU_Setup uses the settings in the \ref partition_h_pg to initialize
 351 the Secure Attribute Unit (SAU) and define non-secure interrupts.  It is called from
 352 the function \ref SystemInit.
 353  */
 354 void TZ_SAU_Setup (void);
 355
 356 /**
 357   \brief   Enable Security Attribution Unit (SAU)
 358   \details Enables the Security Attribution Unit (SAU).
 359  */
 360 void TZ_SAU_Enable(void);
 361
 362 /**
 363   \brief   Disable Security Attribution Unit (SAU)
 364   \details Disables the Security Attribution Unit (SAU).
 365  */
 366 void TZ_SAU_Disable(void);
 367
 368 /** close sau_trustzone_functions
 369   @}
 370 */
 371
 372
 373
 374
 375
 376 /**
 377   \defgroup context_trustzone_functions RTOS Context Management
 378   \brief RTOS Thread Context Management for ARMv8-M TrustZone.
 379   @{
 380   \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.
 381 */
 382
 383 /**
 384   \brief Initialize secure context memory system
 385   \details Initializes the memory allocation management for the secure memory regions. As a minimum the secure thread mode stack will be provided.
 386   \return execution status (1: success, 0: error)
 387  */
 388 uint32_t TZ_InitContextSystem_S (void);
 389
 390 /**
 391   \brief Allocate context memory for calling secure software modules in TrustZone
 392   \details Allocates the secure memory regions for thread execution. The parameter \em module describes the set of secure functions that are called by the non-secure thread. This function should be called by an RTOS kernel at the start of a thread.
 393   \param[in]  module   identifies software modules called from non-secure mode
 394   \return value != 0 id TrustZone memory slot identify
 395   \return value 0    no memory available or internal error
 396  */
 397 TZ_MemoryId_t TZ_AllocModuleContext_S (TZ_ModuleId_t module);
 398
 399 /**
 400   \brief Free context memory that was previously allocated with \ref TZ_AllocModuleContext_S
 401   \details De-allocates the secure memory regions. The parameter \em id refers to a TrustZone memory slot that has been obtained with \ref TZ_AllocModuleContext_S.  This function should be called by an RTOS kernel at the termination of a thread.
 402   \param[in]  id  TrustZone memory slot identifier
 403   \return execution status (1: success, 0: error)
 404  */
 405 uint32_t TZ_FreeModuleContext_S (TZ_MemoryId_t id);
 406
 407 /**
 408   \brief Load secure context (called on RTOS thread context switch)
 409   \details Prepare the secure context for execution so that a thread in the non-secure state can call secure library modules. The parameter \em id refers to a TrustZone memory slot that has been obtained with \ref TZ_AllocModuleContext_S. This function should be called by an RTOS kernel at thread context switch before running a thread.
 410   \param[in]  id  TrustZone memory slot identifier
 411   \return execution status (1: success, 0: error)
 412  */
 413 uint32_t TZ_LoadContext_S (TZ_MemoryId_t id);
 414
 415 /**
 416   \brief Store secure context (called on RTOS thread context switch)
 417   \details Free the secure context that has been previously loaded with \ref TZ_LoadContext_S. The parameter \em id refers to a TrustZone memory slot that has been obtained with \ref TZ_AllocModuleContext_S. This function should be called by an RTOS kernel at thread context switch after running a thread.
 418   \param[in]  id  TrustZone memory slot identifier
 419   \return execution status (1: success, 0: error)
 420  */
 421 uint32_t TZ_StoreContext_S (TZ_MemoryId_t id);
 422
 423
 424 /** close context_trustzone_functions
 425   @}
 426 */
 427
 428
 429 /** close trustzone_functions
 430 @}
 431 */