nrf_modem: v2.5.0 release

See CHANGELOG file for details. Co-authored-by: Mirko Covizzi <[email protected]> Co-authored-by: Tommi Kangas <[email protected]> Co-authored-by: Emanuele Di Santo <[email protected]> Signed-off-by: Eivind Jølsgard <[email protected]>
nrfconnect · Sep 25, 2023 · 239d9cb · 239d9cb
1 parent 66ee4d7
commit 239d9cb
Show file tree

Hide file tree

Showing 23 changed files with 563 additions and 333 deletions.
diff --git a/nrf_modem/CMakeLists.txt b/nrf_modem/CMakeLists.txt
@@ -6,19 +6,22 @@
 
 if(CONFIG_NRF_MODEM_LINK_BINARY)
 
-  nrfxlib_calculate_lib_path(NRF_MODEM_LIB_DIR
-    BASE_DIR ${CMAKE_CURRENT_SOURCE_DIR}
+  nrfxlib_calculate_lib_path(NRF_MODEM_LIB_DIR SOC_MODE
     SOFT_FLOAT_FALLBACK
   )
 
+  if(NOT NRF_MODEM_LIB_DIR MATCHES "nRF9160")
+  string(REGEX REPLACE "nRF91[0-9]*" "nRF9120" NRF_MODEM_LIB_DIR ${NRF_MODEM_LIB_DIR})
+  endif()
+
   if(NOT NRF_MODEM_LIB_DIR)
      message(ERROR " This combination of SoC and floating point ABI is not supported by libmodem.")
   endif()
 
   if(CONFIG_NRF_MODEM_LOG)
-    zephyr_library_import(modem ${NRF_MODEM_LIB_DIR}/libmodem_log.a)
+    zephyr_library_import(modem ${CMAKE_CURRENT_SOURCE_DIR}/${NRF_MODEM_LIB_DIR}/libmodem_log.a)
   else()
-    zephyr_library_import(modem ${NRF_MODEM_LIB_DIR}/libmodem.a)
+    zephyr_library_import(modem ${CMAKE_CURRENT_SOURCE_DIR}/${NRF_MODEM_LIB_DIR}/libmodem.a)
   endif()
 
   zephyr_include_directories(include)

diff --git a/nrf_modem/doc/CHANGELOG.rst b/nrf_modem/doc/CHANGELOG.rst
@@ -9,6 +9,55 @@ Changelog
 
 All notable changes to this project are documented in this file.
 
+nrf_modem 2.5.0
+***************
+
+:ref:`Core library <architecture>`
+==================================
+
+* The DFU result is now returned by the :c:param:`dfu_callback` callback in :c:struct:`nrf_modem_init_params` struct.
+* It is no longer necessary to call :c:func:`nrf_modem_init` twice when applying modem firmware updates.
+* Added the SoftSIM API to use a software SIM with the nRF modem.
+
+:ref:`Sockets <nrf_sockets>`
+============================
+
+* Added
+
+  * The :c:macro:`NRF_SO_EXCEPTIONAL_DATA` socket option to enable sending data as part of exceptional events (3GPP).
+  * The :c:macro:`MSG_WAITACK` flag to request a blocking send operation until the request is acknowledged by the network.
+  * Enhanced APN rate control.
+
+* Removed:
+
+  * The :c:param:`sa_len`, :c:param:`sin_len` and :c:param:`sin6_len` from the :c:struct:`nrf_sockaddr` :c:struct:`nrf_sockaddr_in` and :c:struct:`nrf_sockaddr_in6` structs, respectively.
+
+* Replaced the :c:macro:`NRF_SO_BINDTODEVICE` socket option with :c:macro:`NRF_SO_BINDTOPDN`. The new option takes an integer for the PDN ID.
+
+
+:ref:`AT interface <nrf_modem_at>`
+==================================
+
+* Added the option to set a timeout for AT commands by calling the :c:func:`nrf_modem_at_sem_timeout_set` function.
+
+:ref:`AT interface <nrf_modem_gnss>`
+==================================
+
+* Added:
+
+  * Support for QZSS assistance.
+  * Maximum speeds for dynamics modes.
+
+:ref:`Delta DFU <nrf_modem_delta_dfu>`
+======================================
+
+  * Added a DFU callback that will be called after a DFU with the result of the update.
+
+:ref:`Delta DFU <nrf_modem_delta_dfu>`
+======================================
+
+  * The :c:func:`nrf_modem_bootloader_digest` function now takes a list of firmware segments as input. The resulting digest is an array of 32-bit integers.
+
 nrf_modem 2.4.1
 ***************
 

diff --git a/nrf_modem/doc/delta_dfu.rst b/nrf_modem/doc/delta_dfu.rst
@@ -13,7 +13,6 @@ Such updates can save significant amounts of time and bandwidth.
 
 During a firmware delta update, the application transfers the firmware into an area of flash memory in the modem, known as the *scratch area*.
 Once the firmware delta update has been transferred completely, the application schedules the update of the modem firmware, which happens the next time the application boots the modem while calling :c:func:`nrf_modem_init`.
-Finally, the application reboots the modem once more, by reinitializing the Modem library to run the updated modem firmware.
 The same delta update for updating to a new firmware version can be used to perform a rollback to the original firmware version from which the update was done.
 
 The delta update functionality is available through the Modem library :ref:`nrf_modem_delta_dfu_api`, found in :file:`nrfxlib/nrf_modem/include/nrf_modem_delta_dfu.h`.
@@ -91,9 +90,8 @@ A delta modem firmware upgrade consists of the following steps:
 #. Preparing the scratch area
 #. Transferring the new firmware
 #. Scheduling the firmware update
-#. Reinitializing the modem to perform the update
+#. Reinitializing the modem to perform the update and run the new firmware
 #. Checking the result of the update
-#. Reinitializing the modem to run the new firmware
 
 Initializing the Modem library
 ==============================
@@ -191,22 +189,16 @@ To let the modem perform the update, the application must reinitialize the modem
 Checking the result of the update
 =================================
 
-:c:func:`nrf_modem_init` will return one of the following values:
+The application is notified of the result of the update through the :c:member:`dfu_handler` callback in the :c:struct:`nrf_modem_init_params` struct with one of the following values:
 
-* ``NRF_MODEM_DFU_RESULT_OK`` - The update is successful. The modem will run the updated firmware the next time it boots.
-* ``NRF_MODEM_DFU_RESULT_AUTH_ERROR`` - The update did not take place. The modem will run the original firmware the next time it boots.
-* ``NRF_MODEM_DFU_RESULT_UUID_ERROR`` - The update did not take place. The modem will run the original firmware the next time it boots.
+* ``NRF_MODEM_DFU_RESULT_OK`` - The update is successful. The modem is running the new firmware.
+* ``NRF_MODEM_DFU_RESULT_AUTH_ERROR`` - The update did not take place. The modem is running the original firmware.
+* ``NRF_MODEM_DFU_RESULT_UUID_ERROR`` - The update did not take place. The modem is running the original firmware.
 * ``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`.
 * ``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`.
 * ``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.
 
-Reinitializing the modem to run the new firmware
-================================================
-
-Regardless of the value returned by :c:func:`nrf_modem_init`, the application must reinitialize the modem by reinitializing the Modem library in order to run the modem firmware.
-The application can reinitialize the Modem library by calling :c:func:`nrf_modem_init`.
-If the update is successful, the modem runs the new modem firmware.
-The application can verify that by reading the modem firmware UUID or reading the ``AT+CGMR`` command response.
+The application can verify that the modem runs the new modem firmware by reading the modem firmware UUID or reading the ``AT+CGMR`` command response.
 
 Rolling back to a previous firmware
 ***********************************
@@ -238,21 +230,16 @@ To let the modem perform the rollback, the application must reinitialize the mod
 Checking the result of the rollback
 ===================================
 
-:c:func:`nrf_modem_init` will return one of the following values:
+The application is notified of the result of the update through the :c:member:`dfu_handler` callback in the :c:struct:`nrf_modem_init_params` struct with one of the following values:
 
-* ``NRF_MODEM_DFU_RESULT_OK`` - The rollback is successful. The modem will run the previous firmware the next time it boots.
-* ``NRF_MODEM_DFU_RESULT_AUTH_ERROR`` - The rollback did not take place. The modem will run the same firmware the next time it boots.
-* ``NRF_MODEM_DFU_RESULT_UUID_ERROR`` - The rollback did not take place. The modem will run the same firmware the next time it boots.
+* ``NRF_MODEM_DFU_RESULT_OK`` - The rollback is successful. The modem is running the new firmware.
+* ``NRF_MODEM_DFU_RESULT_AUTH_ERROR`` - The rollback did not take place. The modem is running the original firmware.
+* ``NRF_MODEM_DFU_RESULT_UUID_ERROR`` - The rollback did not take place. The modem is running the original firmware.
 * ``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`.
 * ``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`.
+* ``NRF_MODEM_DFU_RESULT_VOLTAGE_LOW`` - The modem did not have sufficient voltage to apply the firmware rollback. The operation will be retried the next time the modem is started.
 
-Reinitializing the modem to run the firmware
-============================================
-
-Regardless of the value returned by :c:func:`nrf_modem_init`, the application must reinitialize the modem by reinitializing the :ref:`nrf_modem` to run the modem firmware.
-The application can reinitialize the Modem library by calling :c:func:`nrf_modem_init`.
-If the rollback is successful, the modem runs the previous modem firmware.
-The application can verify that by reading the modem firmware UUID or the ``AT+CGMR`` command response.
+The application can verify that the modem runs the previous modem firmware by reading the modem firmware UUID or the ``AT+CGMR`` command response.
 
 Thread safety
 *************

diff --git a/nrf_modem/doc/sockets.rst b/nrf_modem/doc/sockets.rst
@@ -52,10 +52,12 @@ The following table shows all socket options supported by the Modem library.
 +-----------------+---------------------------------+------------------------+------------+--------------------------------------------------------------------------------------------+
 | NRF_SOL_SOCKET  | NRF_SO_SNDTIMEO                 | ``struct nrf_timeval`` | get/set    | Timeout value for a socket send operation.                                                 |
 +-----------------+---------------------------------+------------------------+------------+--------------------------------------------------------------------------------------------+
-| NRF_SOL_SOCKET  | NRF_SO_BINDTODEVICE             | ``char *``             | set        | Bind this socket to a specific PDN like ``pdn0`` as specified in the passed option value.  |
+| NRF_SOL_SOCKET  | NRF_SO_BINDTOPDN                | ``int``                | set        | Bind this socket to a specific PDN ID.                                                     |
 +-----------------+---------------------------------+------------------------+------------+--------------------------------------------------------------------------------------------+
 | NRF_SOL_SOCKET  | NRF_SO_POLLCB                   | ``struct nrf_pollcb``  | set        | Set callbacks for poll() events on sockets.                                                |
 +-----------------+---------------------------------+------------------------+------------+--------------------------------------------------------------------------------------------+
+| NRF_SOL_SOCKET  | NRF_SO_EXCEPTIONAL_DATA         | ``int``                | get/set    | Send data on socket as part of exceptional event.                                          |
++-----------------+---------------------------------+------------------------+------------+--------------------------------------------------------------------------------------------+
 | NRF_SOL_SOCKET  | NRF_SO_RAI_LAST                 | ``int``                | set        | Enter Radio Resource Control (RRC) idle immediately after the next send operation.         |
 +-----------------+---------------------------------+------------------------+------------+--------------------------------------------------------------------------------------------+
 | NRF_SOL_SOCKET  | NRF_SO_RAI_ONE_RESP             | ``int``                | set        | Wait for one incoming packet after the next send operation, before entering RRC idle mode. |
@@ -127,14 +129,14 @@ NRF_SO_RCVTIMEO
 NRF_SO_SNDTIMEO
    Set a timeout value for the :c:func:`nrf_connect`, :c:func:`nrf_send`, and :c:func:`nrf_sendto` operations.
    The option accepts an :c:struct:`nrf_timeval` structure with a number of seconds and microseconds specifying the limit on how long to wait for an output operation to complete.
-   The default for this option is the value ``0``, which indicates that these operations will not time out.
+   The default for this option is the value ``0``, which indicates that these operations will not time out, or use the maximum timeout available.
 
 .. note::
    The minimum supported resolution is 1 millisecond.
 
-NRF_SO_BINDTODEVICE
-   Bind this socket to a particular packet data network like, ``pdn0``, as specified in the passed interface name.
-   The passed option is a variable-length null-terminated interface name string with a maximum size of ``NRF_IFNAMSIZ``.
+NRF_SO_BINDTOPDN
+   Bind this socket to a particular packet data network id.
+   The passed option is an integer specifying the PDN id.
    If a socket is bound to an interface, only packets received from that particular interface are processed by the socket.
 
 NRF_SO_POLLCB
@@ -147,6 +149,15 @@ NRF_SO_POLLCB
 .. important::
    The callback is invoked in an interrupt service routine.
 
+NRF_SO_EXCEPTIONAL_DATA
+   Send data on socket as part of an exceptional event.
+   Exceptional events are described in the 3GPP Release 14 specification. The feature requires network support.
+
+   Before using this socket option, the PDN associated with the socket must be configured to allow exceptional events by using the ``AT%EXCEPTIONALDATA`` AT command.
+   For more information about the ``AT%EXCEPTIONALDATA`` AT command, see the `nRF91 AT Commands Reference Guide <AT Commands Reference Guide_>`_.
+
+   The socket option is supported from modem firmware v2.0.0.
+
 NRF_SO_RAI_LAST
    This is a Release assistance indication (RAI) socket option.
    Enter RRC idle mode after the next output operation on this socket is complete.
@@ -350,15 +361,16 @@ For more information about how to configure PDP contexts, activate PDN connectio
 Configuring a socket to use a PDN
 =================================
 
-The application can select which PDN to use on a specific socket by using the :c:func:`nrf_setsockopt` function, with the :c:macro:`NRF_SO_BINDTODEVICE` option and specifying the PDN ID as a string, prefixed by ``pdn``.
-For example, to select the PDN with ID 1, the application must pass ``pdn1`` as the option value.
+The application can select which PDN to use on a specific socket by using the :c:func:`nrf_setsockopt` function, with the :c:macro:`NRF_SO_BINDTOPDN` socket option and specifying the PDN ID as an integer.
 
 The following code shows how to create an IPv4 TCP stream socket and configure it to use the PDN with ID 1:
 
 .. code-block:: c
 
+   int pdn_id = 1;
+
    fd = nrf_socket(NRF_AF_INET, NRF_SOCK_STREAM, NRF_IPPROTO_TCP);
-   nrf_setsockopt(fd, NRF_SOL_SOCKET, NRF_SO_BINDTODEVICE, "pdn1", strlen("pdn1"));
+   nrf_setsockopt(fd, NRF_SOL_SOCKET, NRF_SO_BINDTOPDN, &pdn_id, sizeof(pdn_id));
 
 
 Routing a DNS query on a PDN

diff --git a/nrf_modem/include/nrf_modem.h b/nrf_modem/include/nrf_modem.h
@@ -41,25 +41,23 @@ extern "C" {
  */
 
 /** Modem firmware update successful.
- * The modem will run the updated firmware on reboot.
+ *  The modem is running the updated modem firmware.
  */
 #define NRF_MODEM_DFU_RESULT_OK 0x5500001u
 /** Modem firmware update failed.
- * The modem encountered a fatal internal error during firmware update.
+ *  The modem encountered a fatal internal error during firmware update.
  */
 #define NRF_MODEM_DFU_RESULT_INTERNAL_ERROR 0x4400001u
 /** Modem firmware update failed.
- * The modem encountered a fatal hardware error during firmware update.
+ *  The modem encountered a fatal hardware error during firmware update.
  */
 #define NRF_MODEM_DFU_RESULT_HARDWARE_ERROR 0x4400002u
 /** Modem firmware update failed, due to an authentication error.
- * The modem will automatically run the previous (non-updated)
- * firmware on reboot.
+ *  The modem is running the previous (non-updated) firmware.
  */
 #define NRF_MODEM_DFU_RESULT_AUTH_ERROR 0x4400003u
 /** Modem firmware update failed, due to UUID mismatch.
- * The modem will automatically run the previous (non-updated)
- * firmware on reboot.
+ *  The modem is running the previous (non-updated) firmware.
  */
 #define NRF_MODEM_DFU_RESULT_UUID_ERROR 0x4400004u
 /** Modem firmware update not executed due to low voltage.
@@ -182,6 +180,11 @@ struct nrf_modem_fault_info {
  */
 typedef void (*nrf_modem_fault_handler_t)(struct nrf_modem_fault_info *fault_info);
 
+/**
+ * @brief Modem DFU handler.
+ */
+typedef void (*nrf_modem_dfu_handler_t)(uint32_t dfu_result);
+
 /**@} */
 
 /** @brief Modem library initialization parameters. */
@@ -192,6 +195,8 @@ struct nrf_modem_init_params {
 	uint32_t ipc_irq_prio;
 	/** Modem fault handler */
 	nrf_modem_fault_handler_t fault_handler;
+	/** Modem DFU handler */
+	nrf_modem_dfu_handler_t dfu_handler;
 };
 
 /** @brief Modem library bootloader initialization parameters. */
@@ -222,16 +227,17 @@ char *nrf_modem_build_version(void);
  * @param[in] init_params Initialization parameters.
  *
  * @retval Zero on success.
- * @retval A positive value from @ref nrf_modem_dfu when executing
- *         Modem firmware updates.
+ *
  * @retval -NRF_EPERM The Modem library is already initialized.
  * @retval -NRF_EFAULT @c init_params is @c NULL.
  * @retval -NRF_ENOLCK Not enough semaphores.
  * @retval -NRF_ENOMEM Not enough shared memory.
- * @retval -NRF_EINVAL Control region size is incorrect.
+ * @retval -NRF_EINVAL Control region size is incorrect or missing handlers in @c init_params.
  * @retval -NRF_ENOTSUPP RPC version mismatch.
  * @retval -NRF_ETIMEDOUT Operation timed out.
  * @retval -NRF_ACCESS Modem firmware authentication failure.
+ * @retval -NRF_EAGAIN Modem firmware update not executed due to insufficient voltage, try again.
+ * @retval -NRF_EIO Modem firmware update failure. Modem must be reprogrammed.
  */
 int nrf_modem_init(const struct nrf_modem_init_params *init_params);
 
@@ -245,16 +251,16 @@ int nrf_modem_init(const struct nrf_modem_init_params *init_params);
  * @param[in] init_params Bootloader initialization parameters.
  *
  * @retval Zero on success.
- * @retval A positive value from @ref nrf_modem_dfu when executing
- *         Modem firmware updates.
  *
  * @retval -NRF_EPERM The Modem library is already initialized.
  * @retval -NRF_EFAULT @c init_params is @c NULL.
  * @retval -NRF_ENOLCK Not enough semaphores.
  * @retval -NRF_ENOMEM Not enough shared memory.
+ * @retval -NRF_EINVAL Missing handler in @c init_params.
  * @retval -NRF_EACCES Bad root digest.
  * @retval -NRF_ETIMEDOUT Operation timed out.
  * @retval -NRF_EIO Bootloader fault.
+ * @retval -NRF_ENOSYS Operation not available.
  */
 int nrf_modem_bootloader_init(const struct nrf_modem_bootloader_init_params *init_params);