Line data    Source code

       1            1 : /*
       2              :  * Copyright (c) 2025 STMicroelectronics
       3              :  *
       4              :  * SPDX-License-Identifier: Apache-2.0
       5              :  */
       6              : 
       7              : /**
       8              :  * @file
       9              :  * @brief System control block context helpers for Cortex-M CPUs
      10              :  *
      11              :  * System control block context helpers for backup and restore
      12              :  */
      13              : 
      14              : #ifndef ARM_CORTEX_M_SCB_H_
      15              : #define ARM_CORTEX_M_SCB_H_
      16              : 
      17              : #include <stdint.h>
      18              : #include <cmsis_core.h>
      19              : 
      20              : /* Define macros for CPU-conditional features */
      21              : #if defined(CONFIG_CPU_CORTEX_M0)  || \
      22              :         defined(CONFIG_CPU_CORTEX_M0PLUS)  || \
      23              :         defined(CONFIG_CPU_CORTEX_M1) || \
      24              :         defined(CONFIG_CPU_CORTEX_M23)
      25              : #define SHPR_SIZE_W 2
      26              : #else
      27            0 : #define SHPR_SIZE_W 3
      28            0 : #define CPACR_PRESENT 1
      29              : #endif
      30              : 
      31              : /**
      32              :  * @brief Structure to store essential, mutable SCB register values for backup/restore.
      33              :  *
      34              :  * This structure only contains SCB registers that are safe and meaningful to backup
      35              :  * and restore. In particular, registers that are read-only (such as CPUID) or contain
      36              :  * volatile information (ICSR / CFSR) are ignored, since their value is tied to the
      37              :  * system state or fixed in hardware, rather than related to a configuration option.
      38              :  */
      39            1 : struct scb_context {
      40              : #if defined(CONFIG_CPU_CORTEX_M_HAS_VTOR)
      41              :         uint32_t vtor;   /*!< Vector Table Offset Register */
      42              : #endif
      43            1 :         uint32_t aircr;  /*!< Application Interrupt and Reset Control Register */
      44            1 :         uint32_t scr;    /*!< System Control Register */
      45            1 :         uint32_t ccr;    /*!< Configuration Control Register */
      46            1 :         uint32_t shpr[SHPR_SIZE_W]; /*!< System Handler Priority Registers */
      47            1 :         uint32_t shcsr;  /*!< System Handler Control and State Register */
      48              : #if defined(CPACR_PRESENT)
      49            1 :         uint32_t cpacr;  /*!< Coprocessor Access Control Register */
      50              : #endif /* CPACR_PRESENT */
      51              : };
      52              : 
      53              : /**
      54              :  * @name SCB Register Backup/Restore Functions
      55              :  * @brief Functions for saving and restoring mutable SCB register state.
      56              :  * @{
      57              :  */
      58              : 
      59              : /**
      60              :  * @brief Save essential SCB registers into a provided context structure.
      61              :  *
      62              :  * This function reads the current values of critical System Control Block (SCB)
      63              :  * registers that are safe to backup and stores them into the `context` structure.
      64              :  *
      65              :  * @param context Pointer to an `scb_context` structure where the register
      66              :  * values will be stored. Must not be NULL.
      67              :  */
      68              : void z_arm_save_scb_context(struct scb_context *context);
      69              : 
      70              : /**
      71              :  * @brief Restores essential SCB registers from a provided context structure.
      72              :  *
      73              :  * This function writes the values from the `context` structure back to the
      74              :  * respective System Control Block (SCB) registers.
      75              :  *
      76              :  * @warning Extreme caution is advised when restoring SCB registers. Only
      77              :  * mutable registers are restored. Specifically, the ICSR register
      78              :  * is NOT restored directly due to its volatile nature and read-only/
      79              :  * write-only bits.
      80              :  *
      81              :  * @param context Pointer to a `scb_context` structure containing the
      82              :  * register values to be restored. Must not be NULL.
      83              :  */
      84              : void z_arm_restore_scb_context(const struct scb_context *context);
      85              : 
      86              : /** @} */
      87              : 
      88              : #endif /* ARM_CORTEX_M_SCB_H_ */