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