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

Add two API to save SCB context and restore it, typically
used in suspend to RAM use case.

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.

Register excluded from backup/restore are:
1.	CPUID (CPUID Base Register)
	Motivation for Exclusion: This is a read-only identification register.
2.	ICSR (Interrupt Control and State Register)
	Motivation for Exclusion (from restoration): While its current value can be read, directly restoring a saved
	ICSR value is highly dangerous and generally unsafe in an RTOS context.
	Contains Read-Only Status Bits: A significant portion of ICSR consists of read-only bits
	(VECTACTIVE, VECTPENDING, ISRPREEMPT, TSRUNPEND). These bits reflect the current state of the exception
	system (e.g., which exception is active, which are pending) and are managed dynamically by the CPU and the RTOS.
	Forcing a previous state onto these bits would corrupt the live system's interrupt handling.
	Contains Write-Only Set/Clear Bits: Some bits are write-only to set or clear a pending interrupt (PENDSVSET,
	PENDSVCLR, SYSTICKSET, SYSTICKCLR). If these bits were set in the saved context, restoring them might
	immediately trigger an interrupt or change its pending state unexpectedly, outside the RTOS's control.
	RTOS Management: In Zephyr (and other RTOSes), the kernel tightly manages the interrupt and exception state.
	Direct manipulation of ICSR's volatile bits could conflict with the RTOS's internal state machine, leading to
	crashes or unpredictable behavior.
3.	CFSR (Configurable Fault Status Register)
	Motivation for Exclusion: This is a read-only status register that reports the current state of Memory
	Management, Bus Fault, and Usage Faults. It's used by fault handlers to determine the cause of a fault.
4.	HFSR (HardFault Status Register)
	Motivation for Exclusion: Similar to CFSR, this is a read-only status register that reports the current state
	of HardFaults. It's for reporting, not for configuration or restoration.
5.	DFSR (Debug Fault Status Register)
	Motivation for Exclusion: This is a read-only status register that reports debug-related faults. It's primarily
	used by debuggers and is not part of the application's runtime context to be saved/restored.
6.	MMFAR (MemManage Fault Address Register)
	Motivation for Exclusion: This is a read-only register that stores the address that caused a Memory Management
	fault. It's a diagnostic register, not a configurable parameter.
7.	BFAR (BusFault Address Register)
	Motivation for Exclusion: Similar to MMFAR, this is a read-only register that stores the address that caused a
	BusFault. It's a diagnostic register.
8.	AFSR (Auxiliary Fault Status Register)
	Motivation for Exclusion: This register is implementation-defined and read-only.

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

Author: msmttchr

arch/arm/core/cortex_m/scb.c

@@ -22,6 +22,21 @@
 #include <zephyr/linker/linker-defs.h>
 #include <zephyr/cache.h>
 #include <zephyr/arch/cache.h>
+#include <cortex_m/scb.h>
+
+/* For historical reason, in Cortex-M family, CMSIS code calls System Handler Priority
+ * register SHP or SHPR_FIELD_NAME. This code define the name of the register
+ * according to the specific Cortex-M variant.
+ */
+#if defined(CONFIG_CPU_CORTEX_M0)  || \
+	defined(CONFIG_CPU_CORTEX_M0PLUS)  || \
+	defined(CONFIG_CPU_CORTEX_M1)  || \
+	defined(CONFIG_CPU_CORTEX_M3) || \
+	defined(CONFIG_CPU_CORTEX_M4)
+#define SHPR_FIELD_NAME SHP
+#else
+#define SHPR_FIELD_NAME SHPR
+#endif
 
 #if defined(CONFIG_CPU_HAS_NXP_SYSMPU)
 #include <fsl_sysmpu.h>
@@ -151,3 +166,78 @@ 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 guaranteed that interrupts are disabled.
+ *
+ * @param context Pointer to an `scb_context_t` structure where the register
+ * values will be stored. Must not be NULL.
+ */
+void z_arm_save_scb_context(scb_context_t *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 System Handler Priority Registers */
+	__IOM uint32_t *shpr = (__IOM uint32_t *) SCB->SHPR_FIELD_NAME;
+	for (int i = 0; i < SHPR_SIZE_W; i++) {
+		context->shpr[i] = shpr[i];
+	}
+
+	context->shcsr = SCB->SHCSR;
+}
+
+/**
+ * @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 guaranteed that
+ * interrupts are disabled.
+ *
+ * @warning The ICSR register is NOT restored directly due to its volatile nature
+ * and presence of read-only status bits and write-only clear/set bits.
+ * Direct restoration can lead to undefined behavior or corrupt interrupt state.
+ * If specific ICSR bits need to be managed as part of a context,
+ * a separate, highly controlled mechanism should be implemented.
+ *
+ * @param context Pointer to a `scb_context_t` structure containing the
+ * register values to be restored. Must not be NULL.
+ */
+void z_arm_restore_scb_context(const scb_context_t *context)
+{
+	__ASSERT_NO_MSG(context != NULL);
+
+#if defined(CONFIG_CPU_CORTEX_M_HAS_VTOR)
+	/* Restore Vector Table Offset Register first if it was modified. */
+	SCB->VTOR = context->vtor;
+#endif
+	/* Restore AIRCR: Must write the VECTKEY (0x05FA) along with the desired bits.
+	 * Ensure only the relevant modifiable bits are restored.
+	 */
+	SCB->AIRCR = (context->aircr & ~SCB_AIRCR_VECTKEY_Msk) |
+					(0x05FAUL << SCB_AIRCR_VECTKEY_Pos);
+
+	SCB->SCR = context->scr;
+	SCB->CCR = context->ccr;
+
+	/* Restore System Handler Priority Registers */
+	__IOM uint32_t *shpr = (__IOM uint32_t *) SCB->SHPR_FIELD_NAME;
+	for (int i = 0; i < SHPR_SIZE_W; i++) {
+		shpr[i] = context->shpr[i];
+	}
+
+	/* Restore SHCSR */
+	SCB->SHCSR = context->shcsr;
+}