arch: arm: cortex_m: Add API for SCB save and restore

Add new API to save and restore SCB context. This is typically useful when
entering and exiting suspend-to-RAM low-power modes.

The scb_context_t and the backup/restore functions are designed to only
handle SCB registers that are:
- Mutable: Their values can be changed by software.
- Configurable: They control system behavior or features.
- Stateful: Their values represent a specific configuration that an
            application might want to preserve and restore.

Registers excluded from backup/restore are:
1. CPU/feature identification registers
	Motivation: These registers are fixed in hardware and read-only.
2. ICSR (Interrupt Control and State Register)
	Motivation: Most bits of ICSR bits are read-only or write-only
	and represent volatile system state. STTNS is the only read-write
	field and could be considered part of the system state, but it is
	only present on certain ARMv8-M CPUs, and Zephyr does not use it.
3. CFSR (Configurable Fault Status Register)
   HFSR (HardFault Status Register)
   DFSR (Debug Fault Status Register)
   AFSR (Auxiliary Fault Status Register)
   MMFAR (MemManage Fault Address Register)
   BFAR (BusFault Address Register)
	Motivation: These registers are read/write-one-to-clear and
	contain only fault-related information (which is volatile).

Signed-off-by: Mathieu Choplain <[email protected]>
Co-authored-by: Michele Sardo <[email protected]>

Author: msmttchr

arch/arm/core/cortex_m/scb.c

@@ -1,5 +1,6 @@
 /*
  * Copyright (c) 2013-2014 Wind River Systems, Inc.
+ * Copyright (c) 2025 STMicroelectronics
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -22,6 +23,7 @@
 #include <zephyr/linker/linker-defs.h>
 #include <zephyr/cache.h>
 #include <zephyr/arch/cache.h>
+#include <zephyr/arch/arm/cortex_m/scb.h>
 
 #if defined(CONFIG_CPU_HAS_NXP_SYSMPU)
 #include <fsl_sysmpu.h>
@@ -151,3 +153,99 @@ void z_arm_init_arch_hw_at_boot(void)
 	barrier_isync_fence_full();
 }
 #endif /* CONFIG_INIT_ARCH_HW_AT_BOOT */
+
+/**
+ * @brief Save 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.
+ * Access to SCB registers requires atomicity and consistency, so calling code
+ * should guarantee that interrupts are disabled.
+ *
+ * @param context Pointer to an `scb_context` structure where the register
+ * values will be stored. Must not be NULL.
+ */
+void z_arm_save_scb_context(struct scb_context *context)
+{
+	__ASSERT_NO_MSG(context != NULL);
+
+#if defined(CONFIG_CPU_CORTEX_M_HAS_VTOR)
+	context->vtor  = SCB->VTOR;
+#endif
+	context->aircr = SCB->AIRCR;
+	context->scr   = SCB->SCR;
+	context->ccr   = SCB->CCR;
+
+	/*
+	 * Backup the System Handler Priority Registers.
+	 * SCB->SHPR is defined as u8[] or u32[] depending
+	 * on the target Cortex-M core, but it can always
+	 * be accessed using word-sized reads and writes.
+	 * Make u32 pointer using explicit cast to allow
+	 * access on all cores without compiler warnings.
+	 */
+	volatile uint32_t *shpr = (volatile uint32_t *)SCB->SHPR;
+
+	for (int i = 0; i < SHPR_SIZE_W; i++) {
+		context->shpr[i] = shpr[i];
+	}
+
+	context->shcsr = SCB->SHCSR;
+#if defined(CPACR_PRESENT)
+	context->cpacr = SCB->CPACR;
+#endif /* CPACR_PRESENT */
+}
+
+/**
+ * @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. Access to SCB registers
+ * requires atomicity and consistency, so calling code should guarantee that
+ * interrupts are disabled.
+ *
+ * @param context Pointer to a `scb_context` structure containing the
+ * register values to be restored. Must not be NULL.
+ */
+void z_arm_restore_scb_context(const struct scb_context *context)
+{
+	__ASSERT_NO_MSG(context != NULL);
+
+#if defined(CONFIG_CPU_CORTEX_M_HAS_VTOR)
+	/* Restore VTOR if present on this CPU */
+	SCB->VTOR = context->vtor;
+#endif
+	/* Restoring AIRCR requires writing VECTKEY along with desired bits.
+	 * Mask backed up data to ensure only modifiable bits are restored.
+	 */
+	SCB->AIRCR = (context->aircr & ~SCB_AIRCR_VECTKEY_Msk) |
+		     (AIRCR_VECT_KEY_PERMIT_WRITE << SCB_AIRCR_VECTKEY_Pos);
+
+	SCB->SCR = context->scr;
+	SCB->CCR = context->ccr;
+
+	/* Restore System Handler Priority Registers */
+	volatile uint32_t *shpr = (volatile uint32_t *)SCB->SHPR;
+
+	for (int i = 0; i < SHPR_SIZE_W; i++) {
+		shpr[i] = context->shpr[i];
+	}
+
+	/* Restore SHCSR */
+	SCB->SHCSR = context->shcsr;
+
+#if defined(CPACR_PRESENT)
+	/* Restore CPACR */
+	SCB->CPACR = context->cpacr;
+#endif /* CPACR_PRESENT */
+
+	/**
+	 * Ensure that updates to the SCB are visible by executing a DSB followed by ISB.
+	 * This sequence is recommended in the M-profile Architecture Reference Manuals:
+	 *   - ARMv6: DDI0419 Issue E - §B2.5 "Barrier support for system correctness"
+	 *   - ARMv7: DDI0403 Issue E.e - §A3.7.3 "Memory barriers" (at end of section)
+	 *   - ARMv8: DDI0553 Version B.Y - §B7.2.16 "Synchronization requirements [...]"
+	 */
+	__DSB();
+	__ISB();
+}

include/zephyr/arch/arm/cortex_m/scb.h

@@ -0,0 +1,88 @@
+/*
+ * Copyright (c) 2025 STMicroelectronics
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @file
+ * @brief System control block context helpers for Cortex-M CPUs
+ *
+ * System control block context helpers for backup and restore
+ */
+
+#ifndef ARM_CORTEX_M_SCB_H_
+#define ARM_CORTEX_M_SCB_H_
+
+#include <stdint.h>
+#include <cmsis_core.h>
+
+/* Define macros for CPU-conditional features */
+#if defined(CONFIG_CPU_CORTEX_M0)  || \
+	defined(CONFIG_CPU_CORTEX_M0PLUS)  || \
+	defined(CONFIG_CPU_CORTEX_M1) || \
+	defined(CONFIG_CPU_CORTEX_M23)
+#define SHPR_SIZE_W 2
+#else
+#define SHPR_SIZE_W 3
+#define CPACR_PRESENT 1
+#endif
+
+/**
+ * @brief Structure to store essential, mutable SCB register values for backup/restore.
+ *
+ * This structure only contains SCB registers that are safe and meaningful to backup
+ * and restore. In particular, registers that are read-only (such as CPUID) or contain
+ * volatile information (ICSR / CFSR) are ignored, since their value is tied to the
+ * system state or fixed in hardware, rather than related to a configuration option.
+ */
+struct scb_context {
+#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 */
+	uint32_t scr;    /*!< System Control Register */
+	uint32_t ccr;    /*!< Configuration Control Register */
+	uint32_t shpr[SHPR_SIZE_W]; /*!< System Handler Priority Registers */
+	uint32_t shcsr;  /*!< System Handler Control and State Register */
+#if defined(CPACR_PRESENT)
+	uint32_t cpacr;  /*!< Coprocessor Access Control Register */
+#endif /* CPACR_PRESENT */
+};
+
+/**
+ * @name SCB Register Backup/Restore Functions
+ * @brief Functions for saving and restoring mutable SCB register state.
+ * @{
+ */
+
+/**
+ * @brief Save 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` structure where the register
+ * values will be stored. Must not be NULL.
+ */
+void z_arm_save_scb_context(struct scb_context *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` structure containing the
+ * register values to be restored. Must not be NULL.
+ */
+void z_arm_restore_scb_context(const struct scb_context *context);
+
+/** @} */
+
+#endif /* ARM_CORTEX_M_SCB_H_ */