nrf_modem: doc: AT cfun callbacks and mutexes

* Add CFUN callbacks to doc.
* Add mutexes to documentation.

Signed-off-by: Eivind Jølsgard <[email protected]>

nrf_modem/doc/CHANGELOG.rst

@@ -12,6 +12,16 @@ All notable changes to this project are documented in this file.
 nrf_modem 2.6.0
 ***************
 
+Core library
+============
+
+* Added the :c:func:`nrf_modem_os_mutex_init`, :c:func:`nrf_modem_os_mutex_lock` and :c:func:`nrf_modem_os_mutex_unlock` functions to the OS requirements.
+
+AT interface
+============
+
+* Added the CFUN handler for getting callbacks on functional mode changes.
+
 sockets
 =======
 

nrf_modem/doc/at_interface.rst

@@ -219,6 +219,38 @@ In this case, the application need not provide any intermediate buffers and can
 Conversely, :c:func:`nrf_modem_at_cmd` is the only function in the AT interface that copies the whole response of the modem from the shared memory into the provided input buffer, which is owned by the application.
 Therefore, this function can be used when the application needs the whole AT command response, as received from the modem, or in those cases when the stack requirements of :c:func:`nrf_modem_at_scanf` are too high for the calling thread, or when parsing the response using a :c:func:`scanf` format is hard.
 
+CFUN handler
+************
+
+The Modem library allows the application to be notified on functional mode changes in the modem by adding a CFUN handler through the :c:func:`nrf_modem_at_cfun_handler_set` function.
+The handler is called after an CFUN AT command is successfully processed by the modem.
+
+.. note::
+   The CFUN handler is not supported with :c:func:`nrf_modem_at_cmd_async`.
+
+.. note::
+   After the CFUN handler is done processing the event, it must call :c:func:`nrf_modem_at_cfun_handler_completed` to notify the modem library that the event is complete.
+
+The following code snippet shows how to define and set a CFUN handler:
+
+.. code-block:: c
+
+	static void cfun_callback(int mode)
+	{
+		printk("CFUN changed to %d\n", mode);
+
+		if (mode == 0) {
+			/* Resubscribe to network registration status notifications. */
+			nrf_modem_at_printf("AT+CEREG=1");
+		}
+	}
+
+	nrf_modem_at_cfun_handler_set(cfun_callback);
+
+.. important::
+   If you are building an |NCS| application, do not use the :c:func:`nrf_modem_at_cfun_handler_set` function to register your callback.
+   Instead, use the :c:macro:`NRF_MODEM_LIB_ON_CFUN` macro to register to functional mode changes where you need them in your application, to ensure compatibility with other |NCS| libraries.
+
 Custom AT commands
 ******************
 

nrf_modem/doc/ug_nrf_modem_porting_os.rst

@@ -241,12 +241,11 @@ This function is called by the library to allocate and initialize a semaphore.
 *Required action*:
 
 * Allocate and initialize a semaphore.
-* If an address of an already allocated semaphore is provided as an input, the allocation part is skipped and the semaphore is only reinitialized.
+* If the address of an already allocated semaphore is provided as an input, the allocation part is skipped and the semaphore is only reinitialized.
 
 .. note::
-
-   Semaphores are not required if multithreaded access to modem functionality is not needed.
-   In this case, the function can blindly return ``0``.
+   Semaphores are not required if multithreaded access to modem functionalities is not needed.
+   In this case, the function must blindly return ``0``.
 
 nrf_modem_os_sem_give()
 -----------------------
@@ -263,6 +262,30 @@ nrf_modem_os_sem_count_get()
 
 This function is called to retrieve the count of a semaphore.
 
+nrf_modem_os_mutex_init()
+-------------------------
+
+This function is called by the library to allocate and initialize a mutex.
+
+*Required action*:
+
+* Allocate and initialize a mutex.
+* If the address of an already allocated mutex is provided as an input, the allocation part is skipped and the mutex is only reinitialized.
+
+.. note::
+   Mutexes are not required if multithreaded access to modem functionalities is not needed.
+   In this case, the function must blindly return ``0``.
+
+nrf_modem_os_mutex_lock()
+-----------------------
+
+This function is called by the library to lock a mutex.
+
+nrf_modem_os_mutex_unlock()
+-----------------------
+
+This function is called by the library to unlock a mutex.
+
 nrf_modem_os_log()
 ------------------
 
@@ -365,9 +388,13 @@ You can use it as a starting point and customize it for your OS or scheduler.
 
     int nrf_modem_os_sem_init(void **sem, unsigned int initial_count, unsigned int limit)
     {
-        /* The function shall allocate and initialize a semaphore and return its address
-           through the `sem` parameter. If an address of an already allocated semaphore is provided as
-           an input, the allocation part is skipped and the semaphore is only reinitialized. */
+        /*  If multithreaded access to modem functionalities is needed, the function must allocate
+         * and initialize a semaphore and return its address through the `sem` parameter. If the
+         * address of an already allocated semaphore is provided as an input, the allocation part is
+         * skipped and the semaphore is only reinitialized.
+         * Semaphores are not required if multithreaded access to modem functionalities is not
+         * needed. In this case, the function must blindly return ``0``.
+         */
         return 0;
     }
 
@@ -388,6 +415,29 @@ You can use it as a starting point and customize it for your OS or scheduler.
         return 0;
     }
 
+     int nrf_modem_os_mutex_init(void **mutex)
+    {
+        /* If multithreaded access to modem functionalities is needed, the function must allocate
+         * and initialize a reentrant mutex and return its address through the `mutex` parameter.
+         * If the address of an already allocated mutex is provided as an input, the allocation part
+         * is skipped and the mutex is only reinitialized.
+         * Mutexes are not required if multithreaded access to modem functionalities is not needed.
+         * In this case, the function must blindly return ``0``.
+         */
+        return 0;
+    }
+
+    void nrf_modem_os_mutex_unlock(void *sem)
+    {
+        /* Unlock a mutex. */
+    }
+
+    int nrf_modem_os_mutex_lock(void *sem, int timeout)
+    {
+        /* Try to lock a reentrant mutex with the given timeout. */
+        return 0;
+    }
+
     void nrf_modem_os_log(int level, const char *fmt, ...)
     {
         /* Generic logging procedure. */

nrf_modem/include/nrf_modem_gnss.h

@@ -146,6 +146,9 @@ extern "C" {
  * to supply assistance data to the GNSS. It is also possible to use this option without A-GNSS,
  * but it should be noted that in that case GNSS will never get some data (for example ionospheric
  * corrections), which may affect the accuracy.
+ *
+ * This option is only valid in periodic navigation mode, because scheduled downloads are not
+ * performed in other navigation modes.
  */
 #define NRF_MODEM_GNSS_USE_CASE_SCHED_DOWNLOAD_DISABLE 0x04
 /** @} */
@@ -185,6 +188,14 @@ extern "C" {
 #define NRF_MODEM_GNSS_PVT_FLAG_NOT_ENOUGH_WINDOW_TIME 0x10
 /** @brief The velocity estimate is valid. */
 #define NRF_MODEM_GNSS_PVT_FLAG_VELOCITY_VALID         0x20
+/** @brief The PVT notification was sent because of a scheduled download.
+ *
+ * @details Indicates that GNSS is running because of a scheduled download. This flag is only used
+ *          in the periodic navigation mode.
+ *
+ * @note This flag is only supported by modem firmware v2.0.0 or later.
+ */
+#define NRF_MODEM_GNSS_PVT_FLAG_SCHED_DOWNLOAD         0x40
 /** @} */
 
 /** @defgroup nrf_modem_gnss_sv_flag_bitmask Satellite flags bitmask values
@@ -269,6 +280,9 @@ extern "C" {
 /** @brief GNSS fix event.
  *
  * @details Payload is of type @ref nrf_modem_gnss_pvt_data_frame.
+ *
+ * @note In periodic navigation mode with modem firmware v2.0.0 or later, this event is not sent
+ *       when GNSS is running because of a scheduled download.
  */
 #define NRF_MODEM_GNSS_EVT_FIX                 2
 /** @brief NMEA event.
@@ -431,7 +445,7 @@ struct nrf_modem_gnss_sv {
 	 *  193...202 for QZSS.
 	 */
 	uint16_t sv;
-	/** Signal type, see @ref nrf_modem_gnss_signal_types. */
+	/** Signal type, see @ref nrf_modem_gnss_signal_id. */
 	uint8_t signal;
 	/** 0.1 dB/Hz. */
 	uint16_t cn0;

nrf_modem/include/nrf_socket.h

@@ -187,7 +187,7 @@ extern "C" {
 
 /** @brief
  * Write-only socket option to select which ciphersuites to use.
- * This option accepts a prioritized list of @sa nrf_sec_cipher_t with selected cipher suites.
+ * This option accepts a prioritized array of selected cipher suites.
  * See @ref nrf_socket_tls_cipher_suites for a list of allowed values.
  */
 #define NRF_SO_SEC_CIPHERSUITE_LIST 3
@@ -201,22 +201,19 @@ extern "C" {
 
 /** @brief
  * Socket option to set peer verification level.
- * See @ref nrf_socket_sec_peer_verify_options for a list of allowed values of type
- * @sa nrf_sec_peer_verify_t.
+ * See @ref nrf_socket_sec_peer_verify_options for a list of allowed values.
  */
 #define NRF_SO_SEC_PEER_VERIFY 5
 
 /** @brief
  * Write-only socket option to set role for the connection.
- * See @ref nrf_socket_sec_roles for a list of allowed values of type
- * @sa nrf_sec_role_t.
+ * See @ref nrf_socket_sec_roles for a list of allowed values.
  */
 #define NRF_SO_SEC_ROLE 6
 
 /** @brief
  * Socket option to control TLS session caching.
- * See @ref nrf_socket_session_cache_options for a list of allowed values of type
- * @sa nrf_sec_session_cache_t.
+ * See @ref nrf_socket_session_cache_options for a list of allowed values.
  */
 #define NRF_SO_SEC_SESSION_CACHE 12
 
@@ -388,7 +385,7 @@ extern "C" {
 
 /**
  * @defgroup nrf_socket_sec_peer_verify_options TLS peer verification options
- * @brief Allowed TLS peer verification options
+ * @brief Allowed TLS peer verification options. By default, peer verification is optional.
  *
  * @ingroup nrf_socket_tls
  * @{
@@ -416,7 +413,8 @@ extern "C" {
 
 /**
  * @defgroup nrf_socket_session_cache_options TLS session cache options
- * @brief Allowed options for the TLS session cache.
+ * @brief Allowed options for the TLS session cache. By default, the session cache is enabled.
+ * @note Session cache may not be used if the peer does not support it.
  *
  * @ingroup nrf_socket_tls
  * @{
@@ -455,7 +453,7 @@ extern "C" {
 
 /**
  * @defgroup nrf_socket_tls_cipher_suites TLS Cipher suites
- * @brief Allowed cipher suites for the nRF modem.
+ * @brief Allowed IANA cipher suites for the nRF modem.
  * @ingroup nrf_socket_tls
  * @{
  */
@@ -698,6 +696,8 @@ struct nrf_ifaddrs {
  * TLS role for the connection.
  *  - 0 - TLS client role.
  *  - 1 - TLS server role.
+ *
+ * @deprecated since v2.6.0, use type int instead.
  */
 typedef uint32_t nrf_sec_role_t;
 
@@ -707,7 +707,7 @@ typedef uint32_t nrf_sec_role_t;
  * More than one security tags may be used on a socket.
  * If more than one tag is used on the socket, pass an array of security tags.
  *
- * A maximum of 8 tags can be set per socket.
+ * A maximum of @ref NRF_SOCKET_TLS_MAX_SEC_TAG_LIST_SIZE tags can be set per socket.
  */
 typedef uint32_t nrf_sec_tag_t;
 
@@ -718,6 +718,8 @@ typedef uint32_t nrf_sec_tag_t;
  *
  * By default, the session cache is enabled.
  * @note Session cache, may not be used if the peer does not support it.
+ *
+ * @deprecated since v2.6.0, use type int instead.
  */
 typedef uint32_t nrf_sec_session_cache_t;
 
@@ -728,11 +730,15 @@ typedef uint32_t nrf_sec_session_cache_t;
  *  - 2 - Required.
  *
  * By default, peer verification is optional.
+ *
+ * @deprecated since v2.6.0, use type int instead.
  */
 typedef uint32_t nrf_sec_peer_verify_t;
 
 /** @brief
  * An IANA cipher suite identifier.
+ *
+ * @deprecated since v2.6.0, use type int instead.
  */
 typedef uint32_t nrf_sec_cipher_t;