net_core_monitor: Add network core monitor module

The Network Core Monitor module provides network core status monitoring
by application core for the nRF5340 processor.
It allows detection of network processor suspensions and resets.
After a reset occurs, it is possible to read the cause of the reset.

Ref: NCSDK-22746

Signed-off-by: Marcin Jelinski <[email protected]>
(cherry picked from commit 30c05e3)

CODEOWNERS

@@ -233,6 +233,7 @@ Kconfig*                                  @tejlmand
 /subsys/nrf_profiler/                     @pdunaj
 /subsys/shell/                            @nordic-krch
 /subsys/nonsecure/                        @SebastianBoe
+/subsys/net_core_monitor/                 @maje-emb
 /modules/                                 @tejlmand
 /modules/tfm/                             @SebastianBoe @joerchan
 /subsys/zigbee/                           @tomchy @sebastiandraus

doc/nrf/libraries/others/network_core_monitor.rst

@@ -0,0 +1,119 @@
+.. _network_core_monitor:
+
+Network core monitor
+####################
+
+.. contents::
+   :local:
+   :depth: 2
+
+This library monitors the network core status of the nRF5340 processor.
+
+Overview
+********
+
+It detects suspensions and resets in the network processor.
+When a reset occurs, you can read the cause of the reset.
+
+Implementation
+==============
+
+The library uses two general-purpose registers of the IPC peripheral in the application core and writes the state of the network processor to them.
+
+.. figure:: images/ncm_register.svg
+   :alt: Application of IPC peripheral registers
+
+   IPC peripheral registers
+
+The ``GPMEM[0]`` register is divided into two 16-bit parts.
+
+The ``COUNTER`` value is incremented by the network core every :kconfig:option:`CONFIG_NCM_APP_FEEDING_INTERVAL_MSEC`.
+The application core periodically calls the :c:func:`ncm_net_status_check` function to check the status of the network core.
+If the network core is suspended, the counter value is not updated.
+The :c:func:`ncm_net_status_check` function returns error code ``-EBUSY``.
+
+To correctly detect the network core status, the :c:func:`ncm_net_status_check` function should be called less frequently than the value set in the :kconfig:option:`CONFIG_NCM_APP_FEEDING_INTERVAL_MSEC` Kconfig option.
+
+The ``FLAGS`` field has the ``Reset`` flag as the bit 0.
+
+The reset bit is set at the boot of the network core.
+It informs the application core that a reset of the network core has occurred.
+
+During the startup of the network core, the reset bit is set and the cause of the reset is written to the IPC register ``GPMEM[1]``.
+This value is rewritten from the network core's ``RESET.RESETREAS`` register.
+For a detailed description of the bits in this register, see the `RESETREAS`_ section for nRF5340.
+
+The :c:func:`ncm_net_status_check` function returns the following error codes:
+
+* ``-EBUSY`` if the network core is suspended
+* ``-EFAULT`` if a network core reset has occurred
+
+The function takes a pointer to a variable of type uint32_t as a parameter.
+When a network core reset is detected, the cause of the reset is stored in this pointer.
+
+Configuration
+*************
+
+To enable this library, set the :kconfig:option:`CONFIG_NET_CORE_MONITOR` Kconfig option to ``y`` on both network and application cores.
+
+The :kconfig:option:`CONFIG_NCM_APP_FEEDING_INTERVAL_MSEC` Kconfig option specifies how often the counter is updated by the network core.
+The default value is 500 milliseconds.
+
+The :kconfig:option:`CONFIG_NCM_RESET_INIT_PRIORITY` Kconfig option sets priority for the initialization function.
+The function reads the cause of the processor reset and passes this information to the application core.
+It is executed at the network core boot.
+
+Usage
+*****
+
+To enable the Network core monitor library, set the :kconfig:option:`CONFIG_NET_CORE_MONITOR` Kconfig option.
+
+On the application core, periodically call the :c:func:`ncm_net_status_check` function to monitor the state of the network core.
+See the following usage example.
+
+.. code-block::
+
+   #include "net_core_monitor.h"
+   ...
+   static void print_reset(uint32_t reset_reas)
+   {
+      if (reset_reas & NRF_RESET_RESETREAS_RESETPIN_MASK) {
+         printk("Reset by pin-reset\n");
+      } else if (reset_reas & NRF_RESET_RESETREAS_DOG0_MASK) {
+         printk("Reset by application watchdog timer 0 \n");
+      } else if (reset_reas & NRF_RESET_RESETREAS_SREQ_MASK) {
+         printk("Reset by soft-reset\n");
+      } else if (reset_reas) {
+         printk("Reset by a different source (0x%08X)\n", reset_reas);
+      }
+   }
+
+   int main(void)
+   {
+      uint32_t reset_reas;
+      ...
+      for (;;) {
+         ret = ncm_net_status_check(&reset_reas);
+         if (ret == -EBUSY) {
+            /* do something*/
+         } else if (ret == -EFAULT) {
+            print_reset(reset_reas);
+         }
+         k_sleep(K_MSEC(1000));
+      }
+   }
+
+Dependencies
+************
+
+The module uses two general-purpose registers, ``GPMEM[0]`` and ``GPMEM[1]``, of the application core's IPC peripheral.
+
+API documentation
+*****************
+
+| Header file: :file:`include/net_core_monitor.h`
+| Source files: :file:`subsys/net_core_monitor/`
+
+.. doxygengroup:: net_core_monitor
+   :project: nrf
+   :members:

doc/nrf/links.txt

@@ -490,6 +490,8 @@
 .. _`nRF5340 Audio DK Hardware`: https://infocenter.nordicsemi.com/topic/ug_nrf5340_audio/UG/nrf5340_audio/intro.html
 .. _`Requirements for external flash memory DFU`: https://infocenter.nordicsemi.com/topic/ug_nrf5340_audio/UG/nrf5340_audio/hw_external_memory.html
 
+.. _`RESETREAS`: https://infocenter.nordicsemi.com/index.jsp?topic=%2Fps_nrf5340%2Fchapters%2Freset%2Fdoc%2Freset.html&cp=4_0_0_3_9_10_0&anchor=register.RESETREAS
+
 .. _`nRF52840 Product Specification`: https://infocenter.nordicsemi.com/topic/ps_nrf52840/keyfeatures_html5.html
 .. _`System OFF mode`: https://infocenter.nordicsemi.com/topic/ps_nrf52840/power.html?cp=5_0_0_4_2_2#unique_220399309
 .. _`nRF52840 DK User Guide`: https://infocenter.nordicsemi.com/topic/ug_nrf52840_dk/UG/dk/intro.html

include/net_core_monitor.h

@@ -0,0 +1,45 @@
+/*
+ * Copyright (c) 2023 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
+ */
+
+#ifndef NET_CORE_MONITOR_H_
+#define NET_CORE_MONITOR_H_
+
+/**
+ * @file
+ * @defgroup net_core_monitor Network Core Monitor API
+ * @{
+ * @brief API for the Network Core Monitor.
+ */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** @brief Check the status of the network core.
+ *
+ *  The function should be called less frequently than
+ *  @kconfig{CONFIG_NCM_APP_FEEDING_INTERVAL_MSEC} to correctly detect the network core status.
+ *
+ *  @param[out]  reset_reas  Reason for network core reset.
+ *                           When the -EFAULT code is returned, the variable is set.
+ *                           This value is rewritten from the network core's RESET.RESETREAS
+ *                           register.
+ *
+ *  @retval 0       If network core works properly.
+ *  @retval -EBUSY  If network core failure occurred.
+ *  @retval -EFAULT If network core restart occurred.
+ */
+int ncm_net_status_check(uint32_t * const reset_reas);
+
+#ifdef __cplusplus
+}
+#endif
+
+/**
+ * @}
+ */
+
+#endif /* NET_CORE_MONITOR_H_ */

subsys/CMakeLists.txt

@@ -68,3 +68,4 @@ add_subdirectory_ifdef(CONFIG_NRF_RPC nrf_rpc)
 add_subdirectory_ifdef(CONFIG_NRF_802154_RADIO_DRIVER ieee802154)
 add_subdirectory_ifdef(CONFIG_NRF_DM dm)
 add_subdirectory_ifdef(CONFIG_EMDS emds)
+add_subdirectory_ifdef(CONFIG_NET_CORE_MONITOR net_core_monitor)

subsys/Kconfig

@@ -54,3 +54,5 @@ rsource "caf/Kconfig"
 rsource "ieee802154/Kconfig"
 
 rsource "dm/Kconfig"
+
+rsource "net_core_monitor/Kconfig"

subsys/net_core_monitor/CMakeLists.txt

@@ -0,0 +1,13 @@
+#
+# Copyright (c) 2023 Nordic Semiconductor
+#
+# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
+#
+
+if(CONFIG_SOC_NRF5340_CPUAPP)
+	zephyr_library_sources(app_core.c)
+endif()
+
+if(CONFIG_SOC_NRF5340_CPUNET)
+	zephyr_library_sources(net_core.c)
+endif()

subsys/net_core_monitor/Kconfig

@@ -0,0 +1,32 @@
+#
+# Copyright (c) 2023 Nordic Semiconductor
+#
+# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
+#
+
+config NET_CORE_MONITOR
+	bool "NCM (Network Core Monitor) module [EXPERIMENTAL]"
+	select EXPERIMENTAL
+	depends on (SOC_NRF5340_CPUAPP || SOC_NRF5340_CPUNET)
+	help
+	  Enable the Network Core Monitor module.
+
+if NET_CORE_MONITOR
+
+menu "Net Core Monitor"
+
+config NCM_APP_FEEDING_INTERVAL_MSEC
+	default 500
+	int "Application core feeding interval (in ms)"
+
+config NCM_RESET_INIT_PRIORITY
+	int "Reset init priority"
+	default KERNEL_INIT_PRIORITY_DEFAULT
+
+endmenu
+
+module = NET_CORE_MONITOR
+module-str = NET_CORE_MONITOR
+source "${ZEPHYR_BASE}/subsys/logging/Kconfig.template.log_config"
+
+endif #NET_CORE_MONITOR