Skip to content

Commit 161b58f

Browse files
lemreytmon-nordic
lemrey
authored and
tmon-nordic
committed
nrf_modem: v2.3.0
See CHANGELOG file for details. Signed-off-by: Emanuele Di Santo <[email protected]>
1 parent fe3f47a commit 161b58f

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

42 files changed

+1085
-890
lines changed

‎doc/links.txt‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,8 @@
4242

4343
.. _`%XMODEMTRACE AT command documentation`: https://infocenter.nordicsemi.com/topic/ref_at_commands/REF/at_commands/mob_termination_ctrl_status/xmodemtrace.html
4444

45+
.. _`nRF Trace collector`: https://infocenter.nordicsemi.com/index.jsp?topic=%2Fug_trace_collector%2FUG%2Ftrace_collector%2Fintro.html
46+
4547
.. ### Source: www.nordicsemi.com
4648

4749
.. _`nRF9160 modem firmware zip file`: https://www.nordicsemi.com/Products/Low-power-cellular-IoT/nRF9160/Download#0B34B59935AF4AFCB7AB93E9646C1F53

‎nrf_modem/README.rst‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,10 +20,11 @@ For more information, see :ref:`nrf_modem_ug_porting`.
2020
doc/sockets
2121
doc/at_interface
2222
doc/gnss_interface
23-
doc/full_dfu
23+
doc/bootloader
2424
doc/delta_dfu
25-
doc/modem_trace
2625
doc/fault_handling
26+
doc/modem_trace
27+
doc/logging
2728
doc/ug_nrf_modem_porting_os
2829
doc/limitations
2930
doc/CHANGELOG

‎nrf_modem/doc/CHANGELOG.rst‎

Lines changed: 44 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,49 @@ Changelog
99

1010
All notable changes to this project are documented in this file.
1111

12+
nrf_modem 2.3.0
13+
***************
14+
15+
:ref:`Core library <architecture>`
16+
==================================
17+
18+
* The :c:func:`nrf_modem_init` function is now used only to initialize the library in normal operating mode.
19+
Use :c:func:`nrf_modem_bootloader_init` to initialize the library in bootloader mode.
20+
* Added a ``context`` parameter to :c:func:`nrf_modem_os_event_notify` to allow waking up only a subset of sleeping threads.
21+
* Added the :c:func:`nrf_modem_os_sleep` function.
22+
* The :file:`nrf_modem_limits.h` file has been removed.
23+
24+
:ref:`Sockets <nrf_sockets>`
25+
============================
26+
27+
* Added the ``NRF_SO_POLLCB`` socket option to receive callbacks for poll events occurring on a socket.
28+
* Added the :c:func:`nrf_getifaddrs` and :c:func:`nrf_freeifaddrs` functions to retrieve network interface data.
29+
* Fixed a bug where not reading incoming network data in a timely manner could hang the communication with the modem.
30+
* Fixed a bug in :c:func:`nrf_connect` where a blocking call could in certain cases time out and set the wrong ``errno`` (``EBUSY`` instead of ``ETIMEDOUT``).
31+
* Fixed a bug in :c:func:`nrf_poll` where only the first :c:struct:`nrf_pollfd` structure would be updated in case the modem was shut down.
32+
* Fixed a bug in :c:func:`nrf_setsockopt` where setting ``NRF_SO_RAI_NO_DATA`` on a TCP socket where the peer had closed the connection would return an error.
33+
* Fixed a bug in :c:func:`nrf_send` and :c:func:`nrf_sendto` where the functions would hang when attempting to send a data payload larger than the TX region.
34+
* Fixed a possible concurrency bug in :c:func:`nrf_socket`.
35+
* Fixed a possible concurrency bug in :c:func:`nrf_accept`.
36+
37+
:ref:`AT interface <nrf_modem_at>`
38+
==================================
39+
40+
* Improved error checking in :c:func:`nrf_modem_at_cmd` and :c:func:`nrf_modem_at_printf`.
41+
42+
:ref:`GNSS interface <gnss_interface>`
43+
======================================
44+
45+
* Added the :c:member:`nrf_modem_gnss_agps_expiry.position_expiry` field to :c:struct:`nrf_modem_gnss_agps_expiry` to retrieve the position assistance expiry time.
46+
47+
:ref:`Bootloader <nrf_modem_bootloader_api>`
48+
============================================
49+
50+
* The Full DFU API (:file:`nrf_modem_full_dfu.h`) has been moved to (:file:`nrf_modem_bootloader.h`) and renamed accordingly.
51+
The ``nrf_modem_full_dfu_apply()`` function has been renamed to :c:func:`nrf_modem_bootloader_update`.
52+
* The order of parameters to functions which accepted a buffer and its length has changed, so that the buffer parameter is always passed before the length parameter.
53+
* The ``MODEM_DFU_RESULT_`` macros have been prefixed with ``NRF_``.
54+
1255
nrf_modem 2.2.1
1356
***************
1457

@@ -154,7 +197,7 @@ nrf_modem 1.4.0
154197
* The GNSS socket has been removed.
155198
* nrf_errno errno values have been aligned with those of newlibc.
156199
* The :ref:`Modem API <nrf_modem_api>` (:file:`nrf_modem.h`) has been updated to return negative errno values on error.
157-
* The :ref:`Full Modem DFU API <nrf_modem_full_dfu_api>` (:file:`nrf_modem_full_dfu.h`) has been updated to return negative errno values on error.
200+
* The :ref:`Full Modem DFU API <nrf_modem_bootloader_api>` (:file:`nrf_modem_full_dfu.h`) has been updated to return negative errno values on error.
158201
* The :ref:`GNSS API <nrf_modem_gnss_api>` (:file:`nrf_modem_gnss.h`) has been updated to return negative errno values on error.
159202
* The :c:func:`nrf_modem_gnss_init` and :c:func:`nrf_modem_gnss_deinit` functions have been removed.
160203
* Added the GNSS velocity estimate validity bit ``NRF_MODEM_GNSS_PVT_FLAG_VELOCITY_VALID``.

‎nrf_modem/doc/api.rst‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -98,6 +98,10 @@ fcntl parameters
9898
:project: nrfxlib
9999
:members:
100100

101+
.. doxygengroup:: nrf_fcnt_flags
102+
:project: nrfxlib
103+
:members:
104+
101105
Socket API
102106
**********
103107

@@ -145,12 +149,13 @@ AT API
145149
:project: nrfxlib
146150
:members:
147151

152+
.. _nrf_modem_bootloader_api:
148153
.. _nrf_modem_full_dfu_api:
149154

150-
Full DFU API
151-
************
155+
Bootloader API
156+
**************
152157

153-
.. doxygengroup:: nrf_modem_full_dfu
158+
.. doxygengroup:: nrf_modem_bootloader
154159
:project: nrfxlib
155160
:members:
156161

‎nrf_modem/doc/architecture.rst‎

Lines changed: 15 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -19,30 +19,30 @@ The following figure shows a simplified Modem library architecture:
1919
Shared memory configuration
2020
***************************
2121

22-
The shared memory area can be located anywhere within the first 128 kilobytes of RAM (lowest addresses) and it is logically divided into the following four regions:
22+
The shared memory between the application and modem cores must reside within the lowest 128 kilobytes of RAM.
23+
The application is responsible for reserving the memory area before passing it onto the library.
24+
25+
In bootloader mode, the shared memory area must be as large as the value of ``NRF_MODEM_SHMEM_BOOTLOADER_SIZE`` and its base address must be 4-bytes aligned.
26+
The library accepts the shared memory base address and size as parameters to the :c:func:`nrf_modem_bootloader_init` function through the :c:struct:`nrf_modem_bootloader_init_params` structure.
27+
28+
In normal operating mode, the shared memory is divided into the following four regions:
2329

2430
* Control
2531
* TX
2632
* RX
2733
* Trace
2834

29-
The application can configure the size and location of these regions.
30-
The application is responsible for reserving the memory area by setting the values of these parameters before passing them onto the library.
31-
The library accepts these values as parameters to the :c:func:`nrf_modem_init` function through :c:enum:`nrf_modem_shmem_cfg`.
32-
33-
.. note::
34-
The size of the Control area is fixed.
35-
36-
The application can adjust the size of these regions based on the needs to minimize the RAM requirements of the library.
37-
35+
The application can adjust the size of these regions based on its requirements, with the exception of the control region, which has a fixed size that must be equal to the value of ``NRF_MODEM_SHMEM_CTRL_SIZE``.
36+
The base address of all regions must be 4-bytes aligned.
37+
The library accepts the layout of these regions as parameters to the :c:func:`nrf_modem_init` function through the :c:struct:`nrf_modem_init_params` structure.
3838

3939
For |NCS| users, the Partition Manager will automatically reserve some RAM for each region during linking, according to the size of each region as specified in the glue.
4040

4141
Control area
4242
============
4343

4444
The control area contains the data structures that are used to setup the communication between the modem core and the application core.
45-
Among the sizes of the memory regions, only the size of the control area is fixed, and it is exported in the :file:`nrf_modem_platform.h` file.
45+
Among the sizes of the memory regions, only the size of the control area is fixed, and it is exported in the :file:`nrf_modem.h` file.
4646

4747
For |NCS| users, the build system and the glue implementation will automatically take care of passing the correct size to the :c:func:`nrf_modem_init` call.
4848

@@ -57,6 +57,10 @@ The library OS abstraction layer defines the following functions to allocate and
5757
* :c:func:`nrf_modem_os_shm_tx_alloc`
5858
* :c:func:`nrf_modem_os_shm_tx_free`
5959

60+
.. important::
61+
It must be possible for the Modem library to allocate up to the number of bytes passed by the TX region size in the :c:struct:`nrf_modem_init_params` structure.
62+
If the OS implementation of :c:func:`nrf_modem_os_shm_tx_alloc` requires any overhead, additional memory must be set aside by the application.
63+
6064
RX area
6165
=======
6266

‎nrf_modem/doc/bootloader.rst‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
.. _nrf_modem_bootloader:
2+
3+
Full firmware updates
4+
#####################
5+
6+
.. contents::
7+
:local:
8+
:depth: 2
9+
10+
Initializing the Modem library in bootloader mode gives access to the functionality of the modem bootloader, through the :file:`nrf_modem_bootloader.h` interface.
11+
The modem bootloader can be used to perform a full update of the modem firmware.
12+
Full modem firmware update is the only operation that can be performed when the library is initialized in bootloader mode.
13+
AT commands and networking sockets are not available to the application when the modem is in bootloader mode.
14+
15+
It is possible to switch between the bootloader and normal operation modes by reinitializing the library, by calling :c:func:`nrf_modem_shutdown` before :c:func:`nrf_modem_bootloader_init` or :c:func:`nrf_modem_init`, respectively.
16+
17+
Memory requirements
18+
*******************
19+
20+
The bootloader mode requires a shared memory area of size equal to the value of ``NRF_MODEM_SHMEM_BOOTLOADER_SIZE``.
21+
22+
.. note::
23+
24+
When using the |NCS|, the library is initialized by the glue, which configures the size and position of the shared memory regions in RAM.
25+
26+
Modem library initialization
27+
============================
28+
29+
To perform a full firmware update of the modem, the library must be initialized in bootloader mode as shown in the following code:
30+
31+
.. code-block:: c
32+
33+
/* Initialize modem to prepare for full modem firmware update */
34+
nrf_modem_bootloader_init(bootloader_init_params);
35+
36+
If the library has already been initialized in normal mode, it must be shut down through the :c:func:`nrf_modem_shutdown` function and reinitialized as shown in the following code:
37+
38+
.. code-block:: c
39+
40+
nrf_modem_init(init_params);
41+
/* Shutdown and re-initialize modem to prepare for full modem firmware update */
42+
nrf_modem_shutdown();
43+
nrf_modem_bootloader_init(bootloader_init_params);
44+
45+
Considerations for corrupted modem firmware
46+
===========================================
47+
48+
When designing your application, you might have to consider an interrupted modem firmware update process, which can lead to corrupted modem firmware.
49+
There can be various reasons, for example power loss, which can cause an interruption in a firmware update.
50+
The modem does not have a back-up ROM and hence, an interruption in the modem firmware update process can prevent the modem from further boot up.
51+
52+
As a workaround to the above scenario, either the application must tolerate the situation or another means of recovery must be provided, for example, reprogramming the modem with PC tools.
53+
54+
The Modem library must then be manually initialized with the following code:
55+
56+
.. code-block:: c
57+
58+
int main(void)
59+
{
60+
int rc = nrf_modem_init(init_params);
61+
62+
if (rc < 0) {
63+
// Recover the modem firmware from external flash
64+
nrf_modem_bootloader_init(bootloader_init_params);
65+
// Perform the full modem firmware update.
66+
nrf_modem_shutdown();
67+
nrf_modem_init(init_params);
68+
}
69+
// Modem firmware updated, continue as normal
70+
}
71+
72+
73+
Bootloader API
74+
**************
75+
76+
A full firmware update of the modem consists of the following steps:
77+
78+
1. Initialization
79+
#. Programming the bootloader
80+
#. Programming the modem firmware
81+
#. Verification
82+
83+
Bootloader forms the first segment of the firmware package and it must be programmed initially.
84+
If any failures happen, the sequence of steps must be restarted from the initialization phase.
85+
86+
Initialization
87+
==============
88+
89+
To initialize the full firmware update process for the modem, call the following function:
90+
91+
.. code-block:: c
92+
93+
int nrf_modem_bootloader_init(struct nrf_modem_bootloader_digest *digest_buffer);
94+
95+
Programming the bootloader
96+
==========================
97+
98+
To program a bootloader, call the following function:
99+
100+
.. code-block:: c
101+
102+
int nrf_modem_bootloader_bl_write(void *src, uint32_t len)
103+
104+
The bootloader may be written in smaller chunks, which are internally appended together by the library.
105+
When all pieces are written, call the following function:
106+
107+
.. code-block:: c
108+
109+
int nrf_modem_bootloader_update(void)
110+
111+
After a successful call, the modem changes to the DFU mode.
112+
At this stage, you can write firmware segments or issue any other DFU commands like ``verify``.
113+
114+
Programming the modem firmware
115+
==============================
116+
117+
Firmware segments are written by using the following function call:
118+
119+
.. code-block:: c
120+
121+
int nrf_modem_bootloader_fw_write(uint32_t addr, void *src, uint32_t len)
122+
123+
The Modem library buffers the data with the same destination address, until one of the following conditions occur:
124+
125+
* The buffered data reaches 8kb.
126+
* The destination address changes.
127+
128+
At this point, the buffer is written to the flash.
129+
When all the segments are written, you must call the following function:
130+
131+
.. code-block:: c
132+
133+
int nrf_modem_bootloader_update(void)
134+
135+
Verification
136+
============
137+
138+
To verify the content of the modem flash, use the following function:
139+
140+
.. code-block:: c
141+
142+
nrf_modem_bootloader_digest(uint32_t addr, uint32_t size, struct nrf_modem_bootloader_digest *digest_buffer);
143+
144+
This function calculates SHA-256 hash over the given flash area.
145+
Compare the hash to the precalculated value that comes with the modem firmware package, to ensure that the image is programmed successfully.

‎nrf_modem/doc/delta_dfu.rst‎

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -98,7 +98,7 @@ A delta modem firmware upgrade consists of the following steps:
9898
Initializing the Modem library
9999
==============================
100100

101-
The Delta DFU interface can be used once the application initializes the Modem library in :c:enum:`NORMAL_MODE` by calling :c:func:`nrf_modem_init`.
101+
The Delta DFU interface can be used once the application initializes the Modem library in normal mode by calling :c:func:`nrf_modem_init`.
102102

103103
Preparing the scratch area
104104
==========================
@@ -193,12 +193,12 @@ Checking the result of the update
193193

194194
:c:func:`nrf_modem_init` will return one of the following values:
195195

196-
* ``MODEM_DFU_RESULT_OK`` - The update is successful. The modem will run the updated firmware the next time it boots.
197-
* ``MODEM_DFU_RESULT_AUTH_ERROR`` - The update did not take place. The modem will run the original firmware the next time it boots.
198-
* ``MODEM_DFU_RESULT_UUID_ERROR`` - The update did not take place. The modem will run the original firmware the next time it boots.
199-
* ``MODEM_DFU_RESULT_INTERNAL_ERROR`` - The modem encountered an internal error while updating, and it will not boot to prevent executing unintended operations. The next firmware update operation may only be attempted through the :ref:`nrf_modem_full_dfu_api`.
200-
* ``MODEM_DFU_RESULT_HARDWARE_ERROR`` - The modem encountered a hardware error while updating, and it will not boot to prevent executing unintended operations. The next firmware update operation may only be attempted through the :ref:`nrf_modem_full_dfu_api`.
201-
* ``MODEM_DFU_RESULT_VOLTAGE_LOW`` - The modem did not have sufficient voltage to apply the firmware update. The operation will be retried the next time the modem is started.
196+
* ``NRF_MODEM_DFU_RESULT_OK`` - The update is successful. The modem will run the updated firmware the next time it boots.
197+
* ``NRF_MODEM_DFU_RESULT_AUTH_ERROR`` - The update did not take place. The modem will run the original firmware the next time it boots.
198+
* ``NRF_MODEM_DFU_RESULT_UUID_ERROR`` - The update did not take place. The modem will run the original firmware the next time it boots.
199+
* ``NRF_MODEM_DFU_RESULT_INTERNAL_ERROR`` - The modem encountered an internal error while updating, and it will not boot to prevent executing unintended operations. The next firmware update operation can only be attempted through the :ref:`nrf_modem_bootloader_api`.
200+
* ``NRF_MODEM_DFU_RESULT_HARDWARE_ERROR`` - The modem encountered a hardware error while updating, and it will not boot to prevent executing unintended operations. The next firmware update operation can only be attempted through the :ref:`nrf_modem_bootloader_api`.
201+
* ``NRF_MODEM_DFU_RESULT_VOLTAGE_LOW`` - The modem did not have sufficient voltage to apply the firmware update. The operation will be retried the next time the modem is started.
202202

203203
Reinitializing the modem to run the new firmware
204204
================================================
@@ -240,11 +240,11 @@ Checking the result of the rollback
240240

241241
:c:func:`nrf_modem_init` will return one of the following values:
242242

243-
* ``MODEM_DFU_RESULT_OK`` - The rollback is successful. The modem will run the previous firmware the next time it boots.
244-
* ``MODEM_DFU_RESULT_AUTH_ERROR`` - The rollback did not take place. The modem will run the same firmware the next time it boots.
245-
* ``MODEM_DFU_RESULT_UUID_ERROR`` - The rollback did not take place. The modem will run the same firmware the next time it boots.
246-
* ``MODEM_DFU_RESULT_INTERNAL_ERROR`` - The modem encountered an internal error while executing the rollback, and it will not boot to prevent executing unintended operations. For subsequent programming, the modem can only be programmed through the :ref:`nrf_modem_full_dfu_api`.
247-
* ``MODEM_DFU_RESULT_HARDWARE_ERROR`` - The modem encountered a hardware error while executing the rollback, and it will not boot to prevent executing unintended operations. For subsequent programming, the modem can only be programmed through the :ref:`nrf_modem_full_dfu_api`.
243+
* ``NRF_MODEM_DFU_RESULT_OK`` - The rollback is successful. The modem will run the previous firmware the next time it boots.
244+
* ``NRF_MODEM_DFU_RESULT_AUTH_ERROR`` - The rollback did not take place. The modem will run the same firmware the next time it boots.
245+
* ``NRF_MODEM_DFU_RESULT_UUID_ERROR`` - The rollback did not take place. The modem will run the same firmware the next time it boots.
246+
* ``NRF_MODEM_DFU_RESULT_INTERNAL_ERROR`` - The modem encountered an internal error while executing the rollback, and it will not boot to prevent executing unintended operations. For subsequent programming, the modem can only be programmed through the :ref:`nrf_modem_bootloader_api`.
247+
* ``NRF_MODEM_DFU_RESULT_HARDWARE_ERROR`` - The modem encountered a hardware error while executing the rollback, and it will not boot to prevent executing unintended operations. For subsequent programming, the modem can only be programmed through the :ref:`nrf_modem_bootloader_api`.
248248

249249
Reinitializing the modem to run the firmware
250250
============================================

0 commit comments

Comments
 (0)