arch: arm: cortex_m: Add include scb.h for scb.c

Add header file to export functions implemented
in scb.c file.

Signed-off-by: Michele Sardo <[email protected]>

Author: msmttchr

arch/arm/include/cortex_m/scb.h

@@ -0,0 +1,87 @@
+/*
+ * Copyright (c) 2020 STMicroelectronics
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @file
+ * @brief Exception/interrupt context helpers for Cortex-M CPUs
+ *
+ * Exception/interrupt context helpers.
+ */
+
+#ifndef ARM_CORTEX_M_SCB_H_
+#define ARM_CORTEX_M_SCB_H_
+
+#include <stdint.h>
+#include <cmsis_core.h>
+
+/* Define macro for SHCSR presence, as it's not directly a Kconfig option.
+   SHCSR is present in ARMv7-M (M3, M4, M7) and ARMv8-M (M23, M33) architectures. */
+#if defined(CONFIG_CPU_CORTEX_M3)  || \
+	defined(CONFIG_CPU_CORTEX_M4)  || \
+	defined(CONFIG_CPU_CORTEX_M7)  || \
+	defined(CONFIG_CPU_CORTEX_M23) || \
+	defined(CONFIG_CPU_CORTEX_M33)
+#define CONFIG_CPU_CORTEX_M_HAS_SHCSR 1
+#endif
+
+/**
+ * @brief Structure to store essential, mutable SCB register values for backup/restore.
+ *
+ * This structure explicitly lists the SCB registers that are safe and meaningful
+ * to backup and restore for common system state management. It avoids volatile,
+ * read-only, or write-only status bits that should not be directly restored.
+ */
+typedef struct {
+#if defined(CONFIG_CPU_CORTEX_M_HAS_VTOR)
+	uint32_t vtor;   /*/< Vector Table Offset Register */
+#endif
+	uint32_t aircr;  /*/< Application Interrupt and Reset Control Register
+					  * (only modifiable bits)
+					  */
+	uint32_t scr;    /*/< System Control Register */
+	uint32_t ccr;    /*/< Configuration Control Register */
+	uint32_t shpr[4]; /*/< System Handler Priority Registers (SHPR1-SHPR4) */
+#if defined(CONFIG_CPU_CORTEX_M_HAS_SHCSR)
+	uint32_t shcsr;  /*/< System Handler Control and State Register */
+#endif
+} scb_context_t;
+
+/**
+ * @name SCB Register Backup/Restore Functions
+ * @brief Functions for saving and restoring mutable SCB register state.
+ * @{
+ */
+
+/**
+ * @brief Backs up essential SCB registers into a provided context structure.
+ *
+ * This function reads the current values of critical System Control Block (SCB)
+ * registers that are safe to backup and stores them into the `context` structure.
+ *
+ * @param context Pointer to an `scb_context_t` structure where the register
+ * values will be stored. Must not be NULL.
+ */
+void scb_backup_registers(scb_context_t *context);
+
+/**
+ * @brief Restores essential SCB registers from a provided context structure.
+ *
+ * This function writes the values from the `context` structure back to the
+ * respective System Control Block (SCB) registers.
+ *
+ * @warning Extreme caution is advised when restoring SCB registers. Only
+ * mutable registers are restored. Specifically, the ICSR register
+ * is NOT restored directly due to its volatile nature and read-only/
+ * write-only bits.
+ *
+ * @param context Pointer to a `scb_context_t` structure containing the
+ * register values to be restored. Must not be NULL.
+ */
+void scb_restore_registers(const scb_context_t *context);
+
+/** @} */
+
+#endif /* ARM_CORTEX_M_SCB_H_ */