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, and diagnostics.
The library wrapper provides an encapsulation over the core Modem library functions such as initialization and shutdown.
The library wrapper is implemented in
The library wrapper encapsulates the
nrf_modem_shutdown() calls of the Modem library with
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
The library wrapper can also initialize the Modem library during system initialization using
CONFIG_NRF_MODEM_LIB_SYS_INIT Kconfig option can be used to control the initialization.
Some libraries in nRF Connect SDK, such as the AT command interface and 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.
Zephyr Socket API offers the socket offloading functionality to redirect or offload function calls to BSD socket APIs such as
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
The socket offloading functionality in the integration layer is implemented in
Modem library socket API sets errnos as defined in
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_send() remain available.
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
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.
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:
The size of the RX, TX and the Trace regions can be configured by the following Kconfig options of the integration layer:
CONFIG_NRF_MODEM_LIB_SHMEM_RX_SIZEfor the RX region
CONFIG_NRF_MODEM_LIB_SHMEM_TX_SIZEfor the TX region
CONFIG_NRF_MODEM_LIB_SHMEM_TRACE_SIZEfor the Trace region
The size of the Control region is fixed.
The Modem library exports the size value through
This value is automatically passed by the integration layer to the library during the initialization through
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
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
The contents of both the Modem library heap and the TX memory region can be examined through the
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_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 of the SMS nRF Modem library wrapper module.
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.
mode – [in] Library mode.
int Zero on success, non-zero otherwise.
Makes a thread sleep until next time nrf_modem_lib_init() is called.
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.
int The last return value of nrf_modem_lib_init.
Shutdown the Modem library, releasing its resources.
int Zero on success, non-zero otherwise.
Print diagnostic information for the TX heap.
Print diagnostic information for the library heap.