lib: nrf_modem: Create new module for modem traces

Created a new module that handles starting, stopping and forwarding of
modem traces to selected (compile time) transport.
This is created for the purpose of separating the tracing functionality
from the nrf_modem_os.c glue layer and also making future improvements
like deferred trace processing in a dedicated thread/work queue.

Fixes CIA-454.

Signed-off-by: Balaji Srinivasan <[email protected]>

Author: Balaji Srinivasan

CODEOWNERS

@@ -201,6 +201,7 @@ Kconfig*                                  @tejlmand
 /tests/lib/lte_lc/                        @jtguggedal
 /tests/lib/modem_jwt/                     @SeppoTakalo
 /tests/lib/sms/                           @trantanen @tokangas
+/tests/lib/modem_trace/                   @balaji-nordic
 /tests/modules/lib/cddl-gen/              @oyvindronningstad
 /tests/modules/mcuboot/external_flash/    @hakonfam @sigvartmh
 /tests/modules/tfm/                       @hakonfam @SebastianBoe

doc/nrf/libraries/modem/nrf_modem_lib.rst

@@ -9,7 +9,7 @@ Modem library integration layer
 
 
 The Modem library integration layer handles the integration of the Modem library into |NCS|.
-The integration layer is constituted by the library wrapper and functionalities like socket offloading, OS abstraction, memory reservation by the Partition manager, and diagnostics.
+The integration layer is constituted by the library wrapper and functionalities like socket offloading, OS abstraction, memory reservation by the Partition manager, handling modem traces, and diagnostics.
 
 Library wrapper
 ***************
@@ -31,6 +31,8 @@ If your application performs an update of the nRF9160 modem firmware, you must d
 The library wrapper also coordinates the shutdown operation among different parts of the application that use the Modem library.
 This is done by the :c:func:`nrf_modem_lib_shutdown` function call, by waking the sleeping threads when the modem is being shut down.
 
+When :kconfig:`CONFIG_NRF_MODEM_LIB_TRACE_ENABLED` Kconfig option is enabled, the library wrapper enables proprietary modem traces and forwards it to the `Modem trace module`_.
+
 When using the Modem library in |NCS|, the library should be initialized and shutdown using the :c:func:`nrf_modem_lib_init` and :c:func:`nrf_modem_lib_shutdown` function calls, respectively.
 
 Socket offloading
@@ -62,6 +64,23 @@ The behavior of the functions in the OS abstraction layer is dependent on the |N
 This is relevant for functions such as :c:func:`nrf_modem_os_shm_tx_alloc`, which uses :ref:`Zephyr's Heap implementation <zephyr:heap_v2>` to dynamically allocate memory.
 In this case, the characteristics of the allocations made by these functions depend on the heap implementation by Zephyr.
 
+Modem trace module
+******************
+The modem trace module is implemented in :file:`nrf\\lib\\nrf_modem_lib\\nrf_modem_lib_trace.c`.
+
+The module provides the functionality for starting, stopping, and forwarding of modem traces to a transport medium that can be set by enabling any one of the following Kconfig options:
+
+* :kconfig:`CONFIG_NRF_MODEM_LIB_TRACE_MEDIUM_UART` to send modem traces over UARTE1
+* :kconfig:`CONFIG_NRF_MODEM_LIB_TRACE_MEDIUM_RTT` to send modem traces over SEGGER RTT
+
+When :kconfig:`CONFIG_NRF_MODEM_LIB_TRACE_ENABLED` Kconfig option is enabled, :c:func:`nrf_modem_lib_init` sends the trace memory configuration to the modem.
+When this happens, the modem starts sending startup trace data.
+If the application wants the trace data, :c:func:`nrf_modem_lib_trace_init` must be called before :c:func:`nrf_modem_lib_init`.
+This is done automatically when using the OS Abstraction layer.
+If the application wants to stop an ongoing trace session, it can use the :c:func:`nrf_modem_lib_trace_stop` function.
+The :c:func:`nrf_modem_lib_trace_start` function supports activating a subset of traces or all traces.
+It is also possible to use this function to run a trace session either for a specific time interval or until a given amount of trace data is received.
+
 .. _partition_mgr_integration:
 
 Partition manager integration
@@ -125,9 +144,13 @@ The report will be printed by a dedicated work queue that is distinct from the s
 API documentation
 *****************
 
-| Header file: :file:`include/modem/nrf_modem_lib.h`
+| Header file: :file:`include/modem/nrf_modem_lib.h`, :file:`include/modem/nrf_modem_lib_trace.h`
 | Source file: :file:`lib/nrf_modem_lib.c`
 
 .. doxygengroup:: nrf_modem_lib
    :project: nrf
    :members:
+
+.. doxygengroup:: nrf_modem_lib_trace
+   :project: nrf
+   :members:

doc/nrf/releases/release-notes-changelog.rst

@@ -226,6 +226,10 @@ Modem libraries
 
   * Can now parse AT command responses containing the response result, for example, ``OK`` or ``ERROR``.
 
+* :ref:`nrf_modem_lib_readme`:
+
+  * The modem trace handling is moved from :file:`nrf_modem_os.c` to a new file :file:`nrf_modem_lib_trace.c`, which also provides the API for starting a trace session for a given time interval or until a given size of trace data is received.
+
 Event manager
 -------------
 

include/modem/nrf_modem_lib_trace.h

@@ -0,0 +1,85 @@
+/*
+ * Copyright (c) 2021 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
+ */
+
+/**@file nrf_modem_lib_trace.h
+ *
+ * @defgroup nrf_modem_lib_trace nRF91 Modem trace module
+ * @{
+ */
+#ifndef NRF_MODEM_LIB_TRACE_H__
+#define NRF_MODEM_LIB_TRACE_H__
+
+#include <stdint.h>
+
+/** @brief Initialize the modem trace module.
+ *
+ * Initializes the module and the trace transport medium.
+ *
+ * @return Zero on success, non-zero otherwise.
+ */
+int nrf_modem_lib_trace_init(void);
+
+/**@brief Trace mode
+ *
+ * The trace mode can be used to filter the traces.
+ */
+enum nrf_modem_lib_trace_mode {
+	NRF_MODEM_LIB_TRACE_COREDUMP_ONLY = 1,  /**< Coredump only. */
+	NRF_MODEM_LIB_TRACE_ALL = 2,            /**< LTE, IP, GNSS, and coredump. */
+	NRF_MODEM_LIB_TRACE_IP_ONLY = 4,        /**< IP. */
+	NRF_MODEM_LIB_TRACE_LTE_IP = 5,         /**< LTE and IP. */
+};
+
+/** @brief Start a trace session.
+ *
+ * This function sends AT command that requests the modem to start sending traces.
+ *
+ * @param trace_mode Trace mode
+ * @param duration   Trace duration in seconds. If set to 0, the trace session will
+ *                   continue until @ref nrf_modem_lib_trace_stop is called or until
+ *                   the required size of max trace data (specified by the
+ *                   @p max_size parameter) is received.
+ * @param max_size   Maximum size (in bytes) of trace data that should be received.
+ *                   The tracing will be stopped after receiving @p max_size
+ *                   bytes. If set to 0, the trace session will continue until
+ *                   @ref nrf_modem_lib_trace_stop is called or until the duration
+ *                   set via the @p duration parameter is reached.
+ *                   To ensure the integrity of the trace output, the
+ *                   modem_trace module will never skip a trace message. For
+ *                   this purpose, if it detects that a received trace won't fit
+ *                   in the maximum allowed size, it will stop the trace session
+ *                   without sending out that trace to the transport medium.
+ *
+ * @return Zero on success, non-zero otherwise.
+ */
+int nrf_modem_lib_trace_start(enum nrf_modem_lib_trace_mode trace_mode, uint16_t duration,
+			      uint32_t max_size);
+
+/** @brief Process modem trace data
+ *
+ * This function should only be called to process a trace received from the modem by the
+ * nrf_modem_os_trace_put() function. This function forwards the trace to the selected
+ * (during compile time) trace transport medium. When the maximum number of trace bytes
+ * (configured via the @ref nrf_modem_lib_trace_start) is received, this function stops the trace
+ * session.
+ *
+ * @param data Memory buffer containing the modem trace data.
+ * @param len  Memory buffer length.
+ *
+ * @return Zero on success, non-zero otherwise.
+ */
+int nrf_modem_lib_trace_process(const uint8_t *data, uint32_t len);
+
+/** @brief Stop an ongoing trace session
+ *
+ * This function stops an ongoing trace session.
+ *
+ * @return Zero on success, non-zero otherwise.
+ */
+int nrf_modem_lib_trace_stop(void);
+
+#endif /* NRF_MODEM_LIB_TRACE_H__ */
+/**@} */

lib/lte_link_control/lte_lc.c

@@ -55,11 +55,6 @@ enum lte_lc_notif_type {
 
 static bool is_initialized;
 
-#if defined(CONFIG_NRF_MODEM_LIB_TRACE_ENABLED)
-/* Enable modem trace */
-static const char mdm_trace[] = "AT%%XMODEMTRACE=1,2";
-#endif
-
 #if defined(CONFIG_LTE_LOCK_BANDS)
 /* Lock LTE bands 3, 4, 13 and 20 (volatile setting) */
 static const char lock_bands[] = "AT%%XBANDLOCK=2,\""CONFIG_LTE_LOCK_BAND_MASK
@@ -608,11 +603,6 @@ static int init_and_config(void)
 		return -EIO;
 	}
 #endif
-#if defined(CONFIG_NRF_MODEM_LIB_TRACE_ENABLED)
-	if (nrf_modem_at_printf(mdm_trace)) {
-		return -EIO;
-	}
-#endif
 #if defined(CONFIG_LTE_LOCK_BANDS)
 	/* Set LTE band lock (volatile setting).
 	 * Has to be done every time before activating the modem.

lib/nrf_modem_lib/CMakeLists.txt

@@ -7,5 +7,6 @@ zephyr_library()
 zephyr_library_sources(nrf_modem_lib.c)
 zephyr_library_sources(nrf_modem_os.c)
 zephyr_library_sources_ifdef(CONFIG_NET_SOCKETS nrf91_sockets.c)
+zephyr_library_sources_ifdef(CONFIG_NRF_MODEM_LIB_TRACE_ENABLED nrf_modem_lib_trace.c)
 zephyr_library_sources(errno_sanity.c)
 zephyr_library_sources(shmem_sanity.c)

lib/nrf_modem_lib/Kconfig

@@ -19,163 +19,6 @@ menuconfig NRF_MODEM_LIB
 
 if NRF_MODEM_LIB
 
-# Redefine this symbol here and give it a non-zero default value
-# so that the Zephyr system heap is enabled, the offloading layer
-# depends on it
-config HEAP_MEM_POOL_SIZE
-	int
-	default 512
-
-config NRF_MODEM_LIB_SYS_INIT
-	bool "Initialize during SYS_INIT"
-	default y
-	help
-	  Initialize the Modem library automatically during the SYS_INIT sequence.
-	  Please note that initialization is synchronous and can take up to one
-	  minute in case the modem firmware is updated.
-
-config NRF_MODEM_LIB_TRACE_ENABLED
-	bool
-	prompt "Enable proprietary traces"
-	help
-	  The default size of the Trace region is defined by the
-	  NRF_MODEM_LIB_SHMEM_TRACE_SIZE option.
-
-if NRF_MODEM_LIB_TRACE_ENABLED
-
-choice NRF_MODEM_LIB_TRACE_MEDIUM
-	prompt "nRF modem trace medium"
-	default NRF_MODEM_LIB_TRACE_MEDIUM_UART
-
-config NRF_MODEM_LIB_TRACE_MEDIUM_UART
-	bool "Send modem trace over UARTE1"
-	# Modem tracing over UART use the UARTE1 as dedicated peripheral.
-	# This enable UARTE1 peripheral and includes nrfx UARTE driver.
-	select NRFX_UARTE1
-
-config NRF_MODEM_LIB_TRACE_MEDIUM_RTT
-	bool "Send modem trace over SEGGER RTT"
-	select USE_SEGGER_RTT
-
-endchoice # NRF_MODEM_LIB_TRACE_MEDIUM
-
-if NRF_MODEM_LIB_TRACE_MEDIUM_RTT
-
-config NRF_MODEM_LIB_TRACE_MEDIUM_RTT_BUF_SIZE
-	int "Size of the buffer used by the RTT to write messages"
-	default 255
-
-endif # NRF_MODEM_LIB_TRACE_MEDIUM_RTT
-
-endif # NRF_MODEM_LIB_TRACE_ENABLED
-
-config NRF91_SOCKET_SEND_SPLIT_LARGE_BLOCKS
-	bool "Split large blocks passed to send() or sendto()"
-	default n
-	help
-	  Workaround a limitation in the Modem library regarding the return
-	  value for send() or sendto() calls larger than the module can handle.
-	  It should send the data up to the maximum, and return that as the return value.
-	  Instead, it returns error 22.
-
-config NRF91_SOCKET_BLOCK_LIMIT
-	int "Maximum size the modem can send"
-	default 2048
-	help
-	  Blocks larger than this value will be split into two or more
-	  send() or sendto() calls. This may not work for certain kinds
-	  of sockets or certain flag parameter values.
-
-config NRF_MODEM_LIB_SENDMSG_BUF_SIZE
-	int "Size of the sendmsg intermediate buffer"
-	default 128
-	help
-	  Size of an intermediate buffer used by `sendmsg` to repack data and
-	  therefore limit the number of `sendto` calls. The buffer is created
-	  in a static memory, so it does not impact stack/heap usage. In case
-	  the repacked message would not fit into the buffer, `sendmsg` sends
-	  each message part separately.
-
-comment "Heap and buffers"
-
-config NRF_MODEM_LIB_HEAP_SIZE
-	int "Library heap size"
-	default 1024
-	range 512 4096
-	help
-	  Size of the heap buffer used by the library.
-	  This heap is allocated in the application's RAM.
-
-config NRF_MODEM_LIB_SHMEM_CTRL_SIZE
-	hex
-	default NRF_MODEM_SHMEM_CTRL_SIZE
-	help
-	  Size of the shared memory area used for control structures.
-	  This is a constant for a given library build, and is exported
-	  by the library via NRF_MODEM_SHMEM_CTRL_SIZE.
-
-config NRF_MODEM_LIB_SHMEM_TX_SIZE
-	int "TX region size"
-	range 1024 16384
-	default 8192
-	help
-	  Size of the shared memory area owned by the application.
-	  This area holds all outgoing data from the application, e.g. buffers passed to `send()`.
-	  The size of this buffer affects directly the largest payload that can sent be on AT sockets.
-
-config NRF_MODEM_LIB_SHMEM_RX_SIZE
-	int "RX region size"
-	range 1544 16384
-	default 8192
-	help
-	  Size of the shared memory area owned by the modem.
-	  This area holds all incoming data from the modem, plus the modem's own control structures.
-	  The minimum memory requirements stem from the size of the RPC lists (264 bytes = 8 + (32 * 8)),
-	  plus the RPC messages and data buffers (1280 bytes = 256 + 1024).
-
-config NRF_MODEM_LIB_SHMEM_TRACE_SIZE_OVERRIDE
-	bool "Custom Trace region size"
-	depends on NRF_MODEM_LIB_TRACE_ENABLED
-	help
-	  Override the default size of the Trace region (16384 bytes).
-
-config NRF_MODEM_LIB_SHMEM_TRACE_SIZE
-	int "Trace region size" if NRF_MODEM_LIB_SHMEM_TRACE_SIZE_OVERRIDE
-	default 16384 if NRF_MODEM_LIB_TRACE_ENABLED
-	default 0
-	help
-	  Size of the shared memory area used to receive modem traces.
-
-menu "Diagnostics"
-
-config NRF_MODEM_LIB_DEBUG_ALLOC
-	depends on LOG
-	bool "Print allocations on the library heap"
-
-config NRF_MODEM_LIB_DEBUG_SHM_TX_ALLOC
-	depends on LOG
-	bool "Print allocations on the TX region"
-
-config NRF_MODEM_LIB_HEAP_DUMP_PERIODIC
-	bool "Periodically dump library heap contents"
-
-config NRF_MODEM_LIB_HEAP_DUMP_PERIOD_MS
-	depends on NRF_MODEM_LIB_HEAP_DUMP_PERIODIC
-	int "Period (millisec)"
-	default 20000
-
-config NRF_MODEM_LIB_SHM_TX_DUMP_PERIODIC
-	bool "Periodically dump the TX memory region contents"
-
-config NRF_MODEM_LIB_SHMEM_TX_DUMP_PERIOD_MS
-	depends on NRF_MODEM_LIB_SHM_TX_DUMP_PERIODIC
-	int "Period (millisec)"
-	default 20000
-
-endmenu
-
-module = NRF_MODEM_LIB
-module-str = Modem library
-source "subsys/logging/Kconfig.template.log_config"
+rsource "Kconfig.modemlib"
 
 endif # NRF_MODEM_LIB