[nrf fromlist] soc: nordic: common: nrf_sys_event: Add API for registering an event

Add API for indicating that a deterministic interrupt will occur at
certain point in time in the future. Implementation is ensuring that
there will be no latency due to NVM memory waking up. There are 2
ways of ensuring that:
- setting low latency power mode in RRAMC (higher power consumption
  in idle (not available in non-secure build)
- using PPI and GRTC to trigger the RRAMC wake up task right before
  an expected interrupt

Module has a pool of GRTC channels and dynamically allocates and
frees those channels when events are registered and unregistered.

If GRTC channel is not available then algorithm falls back to power
mode setting (in secure build).

API offers registering an event using relative and absolute timing.

API can be used from Zero Latency interrupts.

Upstream PR #: 99377

Signed-off-by: Krzysztof Chruściński <[email protected]>

Author: nordic-krch

soc/nordic/common/Kconfig

@@ -21,15 +21,44 @@ config NRF_SYS_EVENT
 	bool "nRF system event support"
 	select NRFX_POWER if !NRF_PLATFORM_HALTIUM
 
+if NRF_SYS_EVENT
+
+config NRF_SYS_EVENT_IRQ_LATENCY
+	bool "Register events to reduce interrupt handling latency"
+	default y
+	depends on HAS_HW_NRF_RRAMC && !TRUSTED_EXECUTION_NONSECURE
+
+config NRF_SYS_EVENT_IRQ_LATENCY_MANUAL
+	def_bool !RISCV
+	depends on NRF_SYS_EVENT_IRQ_LATENCY
+	help
+	  If enabled, that indicates that manual control of NVM memory power
+	  mode is available.
+
+config NRF_SYS_EVENT_GRTC_CHAN_CNT
+	int "GRTC channel for RRAMC wake up"
+	default 1
+	range 0 16
+	depends on NRF_SYS_EVENT_IRQ_LATENCY
+	help
+	  Maximum number of GRTC channel dedicated for waking up RRAMC using DPPI
+	  connection between GRTC compare channel and RRAMC wake up task.
+
+config NRF_SYS_EVENT_USE_GPPI
+	def_bool NRF_SYS_EVENT_GRTC_CHAN_CNT > 0
+	select NRFX_GPPI
+
 config SOC_NRF_FORCE_CONSTLAT
 	bool "Force constant latency mode in system ON"
-	depends on NRF_SYS_EVENT && !RISCV
+	depends on !RISCV
 	help
 	  In constant latency mode the CPU wakeup latency and the PPI task response
 	  will be constant and kept at a minimum. This is secured by forcing a set
 	  of base resources on while in sleep. The advantage of having a constant
 	  and predictable latency will be at the cost of having increased power consumption.
 
+endif # NRF_SYS_EVENT
+
 config MRAM_LATENCY
 	bool "MRAM latency manager"
 	depends on NRFS_HAS_MRAM_SERVICE

soc/nordic/common/nrf_sys_event.c

@@ -5,6 +5,16 @@
  */
 
 #include <nrf_sys_event.h>
+#include <helpers/nrfx_gppi.h>
+#include <zephyr/logging/log.h>
+#ifdef CONFIG_NRF_SYS_EVENT_IRQ_LATENCY
+#include <nrfx_grtc.h>
+#include <zephyr/drivers/timer/nrf_grtc_timer.h>
+#ifdef RRAMC_PRESENT
+#include <hal/nrf_rramc.h>
+#endif
+#endif
+LOG_MODULE_DECLARE(soc, CONFIG_SOC_LOG_LEVEL);
 
 #if CONFIG_SOC_SERIES_NRF54HX
 
@@ -93,3 +103,174 @@ int nrf_sys_event_release_global_constlat(void)
 }
 
 #endif
+
+#ifdef CONFIG_NRF_SYS_EVENT_IRQ_LATENCY
+BUILD_ASSERT(IS_ENABLED(CONFIG_NRF_SYS_EVENT_IRQ_LATENCY_MANUAL) ||
+	     (CONFIG_NRF_SYS_EVENT_GRTC_CHAN_CNT > 0),
+	     "If manual mode is not available then at least 1 GRTC channel need to be used.");
+
+static uint32_t event_ref_cnt;
+static uint32_t chan_mask;
+
+#define NVM_HW_WAKEUP_US 16
+#define NVM_MANUAL_SUPPORT IS_ENABLED(CONFIG_NRF_SYS_EVENT_IRQ_LATENCY_MANUAL)
+/* Due to software performance and risk of waking up too early (then RRAMC may go
+ * to sleep before interrupt), it's better to adjust a bit.
+ */
+#define NVM_WAKEUP_US (NVM_HW_WAKEUP_US - 1)
+
+static void irq_low_latency_on(bool enable)
+{
+#ifdef RRAMC_POWER_LOWPOWERCONFIG_MODE_Standby
+	nrf_rramc_lp_mode_set(NRF_RRAMC, enable ? NRF_RRAMC_LP_STANDBY : NRF_RRAMC_LP_POWER_OFF);
+#endif
+}
+
+#ifdef CONFIG_ZERO_LATENCY_IRQS
+static uint32_t full_irq_lock(void)
+{
+	uint32_t mcu_critical_state;
+
+	mcu_critical_state = __get_PRIMASK();
+	__disable_irq();
+
+	return mcu_critical_state;
+}
+
+static void full_irq_unlock(uint32_t mcu_critical_state)
+{
+	__set_PRIMASK(mcu_critical_state);
+}
+
+#define LOCKED(lock) \
+	for (uint32_t __tmp = 0, __key = full_irq_lock(); !__tmp; full_irq_unlock(__key), __tmp = 1)
+#else
+static struct k_spinlock event_lock;
+#define LOCKED() K_SPINLOCK(&event_lock)
+#endif
+
+union nrf_sys_evt_us {
+	uint32_t rel;
+	uint64_t abs;
+};
+
+int event_register(union nrf_sys_evt_us us, bool force, bool abs)
+{
+	int rv;
+
+	LOCKED() {
+		if ((CONFIG_NRF_SYS_EVENT_GRTC_CHAN_CNT > 0) &&
+		    ((abs == false) && ((us.rel >= NVM_WAKEUP_US) || !NVM_MANUAL_SUPPORT)) &&
+		    (chan_mask != 0)) {
+			rv = __builtin_ctz(chan_mask);
+			chan_mask &= ~BIT(rv);
+			if (abs) {
+				nrfy_grtc_sys_counter_cc_set(NRF_GRTC, rv,
+							us.abs - NVM_WAKEUP_US);
+			} else {
+				uint32_t val = (NVM_MANUAL_SUPPORT || (us.rel >= NVM_WAKEUP_US)) ?
+					(us.rel - NVM_WAKEUP_US) : 1;
+
+				nrfx_grtc_syscounter_cc_rel_set(rv, val,
+								NRFX_GRTC_CC_RELATIVE_SYSCOUNTER);
+			}
+		} else if ((chan_mask == 0) && (force == false)) {
+			rv = -ENOSYS;
+		} else {
+			if (event_ref_cnt == 0) {
+				irq_low_latency_on(true);
+			}
+			event_ref_cnt++;
+			rv = 32;
+		}
+	}
+
+	return rv;
+}
+
+int nrf_sys_event_register(uint32_t us, bool force)
+{
+	return event_register((union nrf_sys_evt_us)us, force, false);
+}
+
+int nrf_sys_event_abs_register(uint64_t us, bool force)
+{
+	return event_register((union nrf_sys_evt_us)us, force, true);
+}
+
+int nrf_sys_event_unregister(int handle, bool cancel)
+{
+	__ASSERT_NO_MSG(handle >= 0);
+	int rv = 0;
+
+	if (handle < 32) {
+		if (cancel) {
+			nrf_grtc_sys_counter_compare_event_disable(NRF_GRTC, handle);
+		}
+		atomic_or((atomic_t *)&chan_mask, BIT(handle));
+	}
+
+	LOCKED() {
+		if (IS_ENABLED(CONFIG_TRUSTED_EXECUTION_NONSECURE)) {
+			rv = -EINVAL;
+		} else {
+			__ASSERT_NO_MSG(event_ref_cnt > 0);
+			event_ref_cnt--;
+			if (event_ref_cnt == 0) {
+				irq_low_latency_on(false);
+			}
+		}
+	}
+
+	return rv;
+}
+
+#if CONFIG_NRF_SYS_EVENT_GRTC_CHAN_CNT > 0
+int nrf_sys_event_init(void)
+{
+	/* Attempt to allocate requested amount of GRTC channels. */
+	for (int i = 0; i < CONFIG_NRF_SYS_EVENT_GRTC_CHAN_CNT; i++) {
+		int ch = z_nrf_grtc_timer_chan_alloc();
+
+		if (ch < 0) {
+			LOG_WRN("Allocated less GRTC channels (%d) than requested (%d)",
+				i, CONFIG_NRF_SYS_EVENT_GRTC_CHAN_CNT);
+			break;
+		}
+		chan_mask |= BIT(ch);
+	}
+
+	uint32_t chan_mask_cpy = chan_mask;
+	uint32_t tsk = nrf_rramc_task_address_get(NRF_RRAMC, NRF_RRAMC_TASK_WAKEUP);
+	bool first = true;
+	nrfx_gppi_handle_t ppi_handle;
+	nrf_grtc_event_t cc_evt;
+	uint32_t evt;
+	uint32_t ch;
+	int err;
+
+	/* Setup a PPI connection between allocated GRTC channels and RRAMC wake up task. */
+	while (chan_mask_cpy) {
+		ch = __builtin_ctz(chan_mask_cpy);
+		chan_mask_cpy &= ~BIT(ch);
+		cc_evt = nrf_grtc_sys_counter_compare_event_get(ch);
+		evt = nrf_grtc_event_address_get(NRF_GRTC, cc_evt);
+		if (first) {
+			first = false;
+			err = nrfx_gppi_conn_alloc(evt, tsk, &ppi_handle);
+			if (err < 0) {
+				return err;
+			}
+		} else {
+			nrfx_gppi_ep_attach(evt, ppi_handle);
+		}
+	}
+
+	nrfx_gppi_conn_enable(ppi_handle);
+
+	return 0;
+}
+
+SYS_INIT(nrf_sys_event_init, PRE_KERNEL_1, 0);
+#endif /* CONFIG_NRF_SYS_EVENT_GRTC_CHAN_CNT > 0 */
+#endif /* CONFIG_NRF_SYS_EVENT_IRQ_LATENCY */

soc/nordic/common/nrf_sys_event.h

@@ -28,3 +28,58 @@ int nrf_sys_event_request_global_constlat(void);
  * @retval -errno code otherwise
  */
 int nrf_sys_event_release_global_constlat(void);
+
+/**
+ * @brief Register an event (interrupt) using relative time.
+ *
+ * Registering an event allows system to prepare for wake up minimizing power consumption
+ * and latency. There are 2 ways of minimizing interrupt latency:
+ * - Setting low latency power mode for NVM memory. This option is not available in non-secure
+ *   build.
+ * - Using DPPI to wake up memory before the expected interrupt (if enabled). This option requires
+ *   additional resource (DPPI and GRTC) which are allocated during registration and freed in
+ *   nrf_sys_event_unregister. If resources are not available then algorithm falls back
+ *   to the option 1. Timing should be precise as if memory is woken up it will go back to
+ *   sleep if it is not used for certain amount of time (in case of RRAMC 4 us by default).
+ *   CONFIG_NRF_SYS_EVENT_GRTC_CHAN_CNT configures target amount of GRTC channels. During
+ *   the initialization those channels are dynamically allocated so it is possible that less
+ *   are available.
+ *
+ * @param us Time (in microseconds) from now when interrupt is expected to be triggered.
+ *
+ * @param force If true then low latency mode if forced when there is no resources available
+ * for NVM memory wake up.
+ *
+ * @retval non-negative Handle which shall be used to unregister the event.
+ * @retval -ENOTSUP Feature is not supported.
+ */
+int nrf_sys_event_register(uint32_t us, bool force);
+
+/**
+ * @brief Register an event (interrupt) using absolute time.
+ *
+ * See nrf_sys_event_register for more details.
+ *
+ * @param us Absolute time (in microseconds) when interrupt is expected to be triggered.
+ *
+ * @param force If true then low latency mode if forced when there is no resources available
+ * for NVM memory wake up.
+ *
+ * @retval non-negative Handle which shall be used to unregister the event.
+ * @retval -ENOTSUP Feature is not supported.
+ */
+int nrf_sys_event_abs_register(uint64_t us, bool force);
+
+/** @brief Unregister an event.
+ *
+ * It must be called after the registered event occurred or if it was canceled.
+ *
+ * @param handle Handle returned by @ref nrf_sys_event_register.
+ * @param cancel True to indicate that event is unregistered due to cancellation. Setting to true
+ * when event executed results only in slight longer duration of the operation.
+ *
+ * @retval 0 Successful operation.
+ * @retval -EINVAL Invalid handle.
+ * @retval -ENOTSUP Not supported.
+ */
+int nrf_sys_event_unregister(int handle, bool cancel);