Modem library integration layer

The Modem library integration layer handles the integration of the Modem library into nRF Connect SDK. 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

The library wrapper provides an encapsulation over the core Modem library functions such as initialization and shutdown. The library wrapper is implemented in nrf/lib/nrf_modem_lib/nrf_modem_lib.c.

The library wrapper encapsulates the nrf_modem_init() and nrf_modem_shutdown() calls of the Modem library with nrf_modem_lib_init() and nrf_modem_lib_shutdown() calls, respectively. The library wrapper eases the task of initializing the Modem library by automatically passing the size and address of all the shared memory regions of the Modem library to the nrf_modem_init() call.

Partition Manager is the component that reserves the RAM memory for the shared memory regions used by the Modem library. For more information, see Partition manager integration.

The library wrapper also provides callbacks for the initialization and shutdown operations. The application can set up a callback for nrf_modem_lib_init() function using the NRF_MODEM_LIB_ON_INIT macro, and a callback for nrf_modem_lib_shutdown() function using the NRF_MODEM_LIB_ON_SHUTDOWN macro. These compile-time callbacks allow any part of the application to perform any set up steps that require the modem to be in a certain state. Further, the callbacks ensure that said steps are repeated any time another part of the application turns the modem on or off. The callbacks defined using NRF_MODEM_LIB_ON_INIT are executed after the library is initialized, and report the result of the initialization. The callbacks defined using NRF_MODEM_LIB_ON_SHUTDOWN are executed before the library is shut down.

The library wrapper can also initialize the Modem library during system initialization using SYS_INIT. The CONFIG_NRF_MODEM_LIB_SYS_INIT Kconfig option can be used to control the initialization. Some libraries in nRF Connect SDK, such as the LTE link controller have similar configuration options to initialize during system initialization and these options depend on the configuration option of the integration layer. If your application performs an update of the nRF9160 modem firmware, you must disable this functionality to have full control on the initialization of the library.

The library wrapper also coordinates the shutdown operation among different parts of the application that use the Modem library. This is done by the nrf_modem_lib_shutdown() function call, by waking the sleeping threads when the modem is being shut down.

When CONFIG_NRF_MODEM_LIB_TRACE_ENABLED Kconfig option is enabled, the modem traces are enabled in the modem and are forwarded to the Modem trace module.

When using the Modem library in nRF Connect SDK, the library should be initialized and shutdown using the nrf_modem_lib_init() and nrf_modem_lib_shutdown() function calls, respectively.

CONFIG_NRF_MODEM_LIB_LOG_FW_VERSION_UUID can be enabled for printing logs of both FW version and UUID at the end of the library initialization step.

Socket offloading

Zephyr Socket API offers the socket offloading functionality to redirect or offload function calls to BSD socket APIs such as socket() and send(). The integration layer utilizes this functionality to offload the socket API calls to the Modem library and thus eases the task of porting the networking code to the nRF9160 by providing a wrapper for Modem library’s native socket API such as nrf_socket() and nrf_send().

The socket offloading functionality in the integration layer is implemented in nrf/lib/nrf_modem_lib/nrf91_sockets.c.

Modem library socket API sets errnos as defined in nrf_errno.h. The socket offloading support in the integration layer in nRF Connect SDK converts those errnos to the errnos that adhere to the selected C library implementation.

The socket offloading functionality is enabled by default. To disable the functionality, set the CONFIG_NET_SOCKETS_OFFLOAD Kconfig option to n in your project configuration. If you disable the socket offloading functionality, the socket calls will no longer be offloaded to the nRF9160 modem firmware. Instead, the calls will be relayed to the native Zephyr TCP/IP implementation. This can be useful to switch between an emulator and a real device while running networking code on these devices. Note that the even if the socket offloading is disabled, Modem library’s own socket APIs such as nrf_socket() and nrf_send() remain available.

OS abstraction layer

For functioning, the Modem library requires the implementation of an OS abstraction layer, which is an interface over the operating system functionalities such as interrupt setup, threads, and heap. The integration layer provides an implementation of the OS abstraction layer using nRF Connect SDK components. The OS abstraction layer is implemented in the nrfxlib/nrf_modem/include/nrf_modem_os.c.

The behavior of the functions in the OS abstraction layer is dependent on the nRF Connect SDK components that are used in their implementation. This is relevant for functions such as nrf_modem_os_shm_tx_alloc(), which uses Zephyr’s Heap implementation 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 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:

If the application wants the trace data, nrf_modem_lib_trace_init() must be called before 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 nrf_modem_lib_trace_stop() function. The nrf_modem_lib_trace_start() function supports activating a subset of traces or all traces.

Partition manager integration

The Modem library, which runs on the application core, shares an area of RAM memory with the nRF9160 modem core. During the initialization, the Modem library accepts the boundaries of this area of RAM and configures the communication with the modem core accordingly.

However, it is the responsibility of the application to reserve that RAM during linking, so that this memory area is not used for other purposes and remain dedicated for use by the Modem library.

In nRF Connect SDK, the application can configure the size of the memory area dedicated to the Modem library through the integration layer. The integration layer provides a set of Kconfig options that help the application reserve the required amount of memory for the Modem library by integrating with another nRF Connect SDK component, the Partition Manager.

The RAM area that the Modem library shares with the nRF9160 modem core is divided into the following four regions:

  • Control

  • RX

  • TX

  • Trace

The size of the RX, TX and the Trace regions can be configured by the following Kconfig options of the integration layer:

The size of the Control region is fixed. The Modem library exports the size value through CONFIG_NRF_MODEM_SHMEM_CTRL_SIZE. This value is automatically passed by the integration layer to the library during the initialization through nrf_modem_lib_init().

When the application is built using CMake, the Partition Manager automatically reads the Kconfig options of the integration layer. Partition manager decides about the placement of the regions in RAM and reserves memory according to the given size. As a result, the Partition manager generates the following parameters:

  • PM_NRF_MODEM_LIB_CTRL_ADDRESS - Address of the Control region

  • PM_NRF_MODEM_LIB_TX_ADDRESS - Address of the TX region

  • PM_NRF_MODEM_LIB_RX_ADDRESS - Address of the RX region

  • PM_NRF_MODEM_LIB_TRACE_ADDRESS - Address of the Trace region

Partition manager also generates the following additional parameters:

  • PM_NRF_MODEM_LIB_CTRL_SIZE - Size of the Control region

  • PM_NRF_MODEM_LIB_TX_SIZE - Size of the TX region

  • PM_NRF_MODEM_LIB_RX_SIZE - Size of the RX region

  • PM_NRF_MODEM_LIB_TRACE_SIZE - Size of the Trace region

These parameters will have identical values as the CONFIG_NRF_MODEM_LIB_SHMEM_*_SIZE configuration options.

When the Modem library is initialized by the integration layer in nRF Connect SDK, the integration layer automatically passes the boundaries of each shared memory region to the Modem library during the nrf_modem_lib_init() call.

Diagnostic functionality

The Modem library integration layer in nRF Connect SDK provides some diagnostic functionalities to log the allocations on the Modem library heap and the TX memory region. These functionalities can be turned on by the CONFIG_NRF_MODEM_LIB_DEBUG_ALLOC and CONFIG_NRF_MODEM_LIB_DEBUG_SHM_TX_ALLOC options.

The contents of both the Modem library heap and the TX memory region can be examined through the nrf_modem_lib_heap_diagnose() and nrf_modem_lib_shm_tx_diagnose() functions, respectively. Additionally, it is possible to schedule a periodic report of the contents of these two areas of memory by using the CONFIG_NRF_MODEM_LIB_HEAP_DUMP_PERIODIC and CONFIG_NRF_MODEM_LIB_SHM_TX_DUMP_PERIODIC options, respectively. The report will be printed by a dedicated work queue that is distinct from the system work queue at configurable time intervals.

API documentation

Header file: include/modem/nrf_modem_lib.h, include/modem/nrf_modem_lib_trace.h
Source file: lib/nrf_modem_lib.c
group nrf_modem_lib

API of the SMS nRF Modem library wrapper module.

Defines

NRF_MODEM_LIB_ON_INIT(name, _callback, _context)

Define a callback for nrf_modem_lib_init calls.

The callback function _callback is invoked after the library has been initialized.

Parameters

  • name – Callback name

  • _callback – Callback function name

  • _context – User-defined context for the callback

NRF_MODEM_LIB_ON_SHUTDOWN(name, _callback, _context)

Define a callback for nrf_modem_lib_shutdown calls.

The callback function _callback is invoked before the library is shutdown.

Parameters

  • name – Callback name

  • _callback – Callback function name

  • _context – User-defined context for the callback

Functions

int nrf_modem_lib_init(enum nrf_modem_mode_t mode)

Initialize the Modem library.

This function synchronously turns on the modem; it could block for a few minutes when the modem firmware is being updated.

If your application supports modem firmware updates, consider initializing the library manually to have control of what the application should do while initialization is ongoing.

The library has two operation modes, normal mode and full DFU mode. The full DFU mode is used to update the whole modem firmware.

When the library is initialized in full DFU mode, all shared memory regions are reserved for the firmware update operation, and no other functionality can be used. In particular, sockets won’t be available to the application.

To switch between the full DFU mode and normal mode, shutdown the modem with nrf_modem_lib_shutdown() and re-initialize it in the desired operation mode.

Parameters

  • mode – [in] Library mode.

Returns

int Zero on success, non-zero otherwise.

void nrf_modem_lib_shutdown_wait(void)

Makes a thread sleep until next time nrf_modem_lib_init() is called.

When nrf_modem_lib_shutdown() is called a thread can call this function to be woken up next time nrf_modem_lib_init() is called.

int nrf_modem_lib_get_init_ret(void)

Get the last return value of nrf_modem_lib_init.

This function can be used to access the last return value of nrf_modem_lib_init. This can be used to check the state of a modem firmware exchange when the Modem library was initialized at boot-time.

Returns

int The last return value of nrf_modem_lib_init.

int nrf_modem_lib_shutdown(void)

Shutdown the Modem library, releasing its resources.

Returns

int Zero on success, non-zero otherwise.

void nrf_modem_lib_shm_tx_diagnose(void)

Print diagnostic information for the TX heap.

void nrf_modem_lib_heap_diagnose(void)

Print diagnostic information for the library heap.

struct nrf_modem_lib_init_cb
#include <nrf_modem_lib.h>

Modem library initialization callback struct.

Public Members

void (*callback)(int ret, void *ctx)

Callback function.

Param ret

The return value of nrf_modem_init()

Param ctx

User-defined context

void *context

User defined context

struct nrf_modem_lib_shutdown_cb
#include <nrf_modem_lib.h>

Modem library shutdown callback struct.

Public Members

void (*callback)(void *ctx)

Callback function.

Param ctx

User-defined context

void *context

User defined context

group nrf_modem_lib_trace

Enums

enum nrf_modem_lib_trace_mode

Trace mode.

The trace mode can be used to filter the traces.

Values:

enumerator NRF_MODEM_LIB_TRACE_COREDUMP_ONLY

Coredump only.

enumerator NRF_MODEM_LIB_TRACE_ALL

LTE, IP, GNSS, and coredump.

enumerator NRF_MODEM_LIB_TRACE_IP_ONLY

IP.

enumerator NRF_MODEM_LIB_TRACE_LTE_IP

LTE and IP.

Functions

int nrf_modem_lib_trace_init(void)

Initialize the modem trace module.

Initializes the module and the trace transport medium.

Returns

Zero on success, non-zero otherwise.

int nrf_modem_lib_trace_start(enum nrf_modem_lib_trace_mode trace_mode)

Start a trace session.

This function sends AT command that requests the modem to start sending traces.

Parameters

  • trace_mode – Trace mode

Returns

Zero on success, non-zero otherwise.

int nrf_modem_lib_trace_process(const uint8_t *data, uint32_t len)

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 nrf_modem_lib_trace_start) is received, this function stops the trace session.

Parameters

  • data – Memory buffer containing the modem trace data.

  • len – Memory buffer length.

Returns

Zero on success, non-zero otherwise.

int nrf_modem_lib_trace_stop(void)

Stop an ongoing trace session.

This function stops an ongoing trace session.

Returns

Zero on success, non-zero otherwise.