From 18ca70ba4d68918cb0c6b8b02e4dd0da95e500d7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Eivind=20J=C3=B8lsgard?= Date: Tue, 20 Feb 2024 14:49:28 +0100 Subject: [PATCH 1/2] nrf_modem: doc: use :c:macro for errnos MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Use :c:macro: for errnos. Signed-off-by: Eivind Jølsgard --- nrf_modem/doc/fault_handling.rst | 10 +++++----- nrf_modem/doc/modem_trace.rst | 2 +- nrf_modem/doc/sockets/pdn.rst | 6 +++--- nrf_modem/doc/sockets/socket_options_func.rst | 12 ++++++------ nrf_modem/doc/ug_nrf_modem_porting_os.rst | 6 +++--- 5 files changed, 18 insertions(+), 18 deletions(-) diff --git a/nrf_modem/doc/fault_handling.rst b/nrf_modem/doc/fault_handling.rst index 65a40589d2..931289a03d 100644 --- a/nrf_modem/doc/fault_handling.rst +++ b/nrf_modem/doc/fault_handling.rst @@ -35,19 +35,19 @@ The application can reinitialize the modem by reinitializing the Modem library t .. important:: If modem traces are enabled, the modem continues to output trace data (a coredump) in the event of a fault, even after signaling the fault to the application. To make sure the application is able to retrieve the coredump correctly, the application must not re-initialize the modem until all the outstanding trace data has been processed. - The :c:func:`nrf_modem_trace_get()` function will return ``-ENODATA`` when all outstanding trace data has been processed by the application. + The :c:func:`nrf_modem_trace_get()` function will return negative :c:macro:`NRF_ENODATA` when all outstanding trace data has been processed by the application. When the Modem library is used in |NCS|, the :ref:`nrf_modem_lib_readme` handles synchronizing modem re-initialization with tracing operations. Networking sockets ****************** -Socket APIs that require communication with the modem, return ``-1`` and set ``errno`` to ``NRF_ESHUTDOWN`` if the modem has crashed or if it is uninitialized. +Socket APIs that require communication with the modem, return ``-1`` and set ``errno`` to :c:macro:`NRF_ESHUTDOWN` if the modem has crashed or if it is uninitialized. Although the modem has crashed, any data which was stored by the Modem library, including data that was delivered to the Modem library by the modem, remains available until the Modem library is shut down. This includes incoming network data, which was received before the crash but has not been read by the application. The application can read that data as normal, using the :c:func:`recv` function. -When no more data is available, the :c:func:`recv` function returns ``-1`` and sets ``errno`` to ``NRF_ESHUTDOWN``. +When no more data is available, the :c:func:`recv` function returns ``-1`` and sets ``errno`` to :c:macro:`NRF_ESHUTDOWN`. Ongoing API calls ***************** @@ -57,5 +57,5 @@ When the Modem library detects that a fault has occurred in the modem, it immedi Following are the two categories of APIs in the Modem library and their behavior after a modem fault: -* Socket APIs - Exit immediately returning ``-1`` and sets errno to ``NRF_ESHUTDOWN`` -* Non-Socket APIs - Exit immediately returning ``-NRF_ESHUTDOWN`` +* Socket APIs - Exit immediately returning ``-1`` and sets errno to :c:macro:`NRF_ESHUTDOWN`. +* Non-Socket APIs - Exit immediately returning negative :c:macro:`NRF_ESHUTDOWN`. diff --git a/nrf_modem/doc/modem_trace.rst b/nrf_modem/doc/modem_trace.rst index f81c336385..96395408e9 100644 --- a/nrf_modem/doc/modem_trace.rst +++ b/nrf_modem/doc/modem_trace.rst @@ -53,7 +53,7 @@ Tracing and modem faults When a fault occurs in the modem and traces are enabled, the modem will send a coredump using the trace interface. The :c:func:`nrf_modem_trace_get` function returns trace fragments until there are no more fragments to process. -In the case where there are no more trace fragments after a modem coredump is complete, the :c:func:`nrf_modem_trace_get` function returns ``-NRF_ENODATA`` as shown in the following figure: +In the case where there are no more trace fragments after a modem coredump is complete, the :c:func:`nrf_modem_trace_get` function returns negative :c:macro:`NRF_ENODATA` as shown in the following figure: .. figure:: images/nrf_modem_trace_sequence_coredump.svg :alt: Modem library coredump trace sequence diff --git a/nrf_modem/doc/sockets/pdn.rst b/nrf_modem/doc/sockets/pdn.rst index bc1d8381cd..9c9a4d20c2 100644 --- a/nrf_modem/doc/sockets/pdn.rst +++ b/nrf_modem/doc/sockets/pdn.rst @@ -52,9 +52,9 @@ Handling PDN errors on sockets ****************************** During operation, an active PDN connection may be deactivated due to loss of connectivity or other reasons. -When a socket operation is attempted on a socket that no longer has an active PDN connection, the operation will return ``-1`` and set ``errno`` to ``NRF_ENETDOWN``. -If the socket is being polled, the :c:func:`nrf_poll` function will set the ``POLLERR`` flag and set the socket error to ``NRF_ENETDOWN``. +When a socket operation is attempted on a socket that no longer has an active PDN connection, the operation will return ``-1`` and set ``errno`` to :c:macro:`NRF_ENETDOWN`. +If the socket is being polled, the :c:func:`nrf_poll` function will set the ``POLLERR`` flag and set the socket error to :c:macro:`NRF_ENETDOWN`. The socket error can be retrieved using the :c:macro:`NRF_SO_ERROR` socket option. -When the ``NRF_ENETDOWN`` error is detected, the socket is no longer usable and must be closed by the application. +When the :c:macro:`NRF_ENETDOWN` error is detected, the socket is no longer usable and must be closed by the application. The application is responsible for detecting when the PDN connection is activated again, before re-creating the socket and attempting the failed operation again. diff --git a/nrf_modem/doc/sockets/socket_options_func.rst b/nrf_modem/doc/sockets/socket_options_func.rst index 28c66bc491..afcc51d101 100644 --- a/nrf_modem/doc/sockets/socket_options_func.rst +++ b/nrf_modem/doc/sockets/socket_options_func.rst @@ -113,7 +113,7 @@ NRF_SO_REUSEADDR NRF_SO_RCVTIMEO Set a timeout value for the :c:func:`nrf_recv` and :c:func:`nrf_recvfrom` operations. This 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 input operation to complete. - If a receive operation has blocked for this much time without receiving additional data, it returns with a partial count, or ``errno`` is set to ``NRF_EAGAIN`` or ``NRF_EWOULDBLOCK`` if no data were received. + If a receive operation has blocked for this much time without receiving additional data, it returns with a partial count, or ``errno`` is set to :c:macro:`NRF_EAGAIN` or :c:macro:`NRF_EWOULDBLOCK` if no data were received. The default for this option is the value ``0``, which indicates that a receive operation will not time out. .. note:: @@ -308,21 +308,21 @@ NRF_SO_SEC_DTLS_CONN_SAVE Once the DTLS context is saved, the socket can't be used before the DTLS context is loaded with :c:macro:`NRF_SO_SEC_DTLS_CONN_LOAD`. - This option fails with nrf_errno ``NRF_EAGAIN`` if an error happened during serialization of the SSL context. + This option fails with nrf_errno :c:macro:`NRF_EAGAIN` if an error happened during serialization of the SSL context. This can occur, for instance, when the modem cannot allocate enough memory or if the socket is busy sending or receiving data. In this case, the SSL context is still present in the socket, so data sending is still possible. - The option fails with nrf_errno ``NRF_EINVAL`` if the socket option is not supported with the current configuration, for instance because the DTLS handshake is not completed, + The option fails with nrf_errno :c:macro:`NRF_EINVAL` if the socket option is not supported with the current configuration, for instance because the DTLS handshake is not completed, the connection is not an DTLS v1.2 connection with renegotiation disabled, or the connection does not use an AEAD cipher suite (AES-CCM or AES-GCM). - The option fails with nrf_errno ``NRF_ENOMEM`` if the amount of saved connections exceeds four. + The option fails with nrf_errno :c:macro:`NRF_ENOMEM` if the amount of saved connections exceeds four. NRF_SO_SEC_DTLS_CONN_LOAD Load DTLS connection. This option is write-only. The socket option is supported from modem firmware v1.3.x, where x is greater than or equal to 5, and v2.x.x. - This option fails with nrf_errno ``NRF_EAGAIN`` if an error happened during deserialization of the SSL context. + This option fails with nrf_errno :c:macro:`NRF_EAGAIN` if an error happened during deserialization of the SSL context. This can occur, for instance, when the modem cannot allocate enough memory or the connection is not saved. - The option fails with nrf_errno ``NRF_EINVAL`` if the socket option is not supported with the current configuration. + The option fails with nrf_errno :c:macro:`NRF_EINVAL` if the socket option is not supported with the current configuration. NRF_SO_SEC_CIPHERSUITE_USED Get chosen TLS cipher suite. diff --git a/nrf_modem/doc/ug_nrf_modem_porting_os.rst b/nrf_modem/doc/ug_nrf_modem_porting_os.rst index d8239ed6c4..2392ef8180 100644 --- a/nrf_modem/doc/ug_nrf_modem_porting_os.rst +++ b/nrf_modem/doc/ug_nrf_modem_porting_os.rst @@ -178,12 +178,12 @@ This function is called by the Modem library to put a thread to sleep for a cert * Put the thread to sleep, if applicable, or otherwise wait until the amount of time specified by ``timeout`` has elapsed, or until :c:func:`nrf_modem_os_event_notify` is called with the same ``context`` parameter, or with ``context`` equal to ``0``. * After the wait is complete, update the ``timeout`` parameter with the amount of time left to sleep. This will be ``0`` if the timeout has elapsed or the amount of time left to sleep if the wait was interrupted by a call to :c:func:`nrf_modem_os_event_notify`. -* Check the Modem library initialization status using :c:func:`nrf_modem_is_initialized` and return ``-NRF_ESHUTDOWN`` if that call returns ``false``. +* Check the Modem library initialization status using :c:func:`nrf_modem_is_initialized` and return negative :c:macro:`NRF_ESHUTDOWN` if that call returns ``false``. The following points decide the *Function return value*: -* If the modem is not initialized, that is, if :c:func:`nrf_modem_is_initialized` returns false, function return value will be ``-NRF_ESHUTDOWN``. -* If there is a time out, function return value will be ``-NRF_EAGAIN``. +* If the modem is not initialized, that is, if :c:func:`nrf_modem_is_initialized` returns false, function return value will be negative :c:macro:`NRF_ESHUTDOWN`. +* If there is a time out, function return value will be negative :c:macro:`NRF_EAGAIN`. * In all other cases, function return value will be ``0``. nrf_modem_os_event_notify() From b47de7e89f7ea8698a360a4742dd33323a4411f9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Eivind=20J=C3=B8lsgard?= Date: Thu, 22 Feb 2024 08:10:37 +0100 Subject: [PATCH 2/2] nrf_modem: doc: update NRF_SO_RCVTIMEO for accept MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The NRF_SO_RCVTIMEO is used to set the timeout in accept. Signed-off-by: Eivind Jølsgard --- nrf_modem/doc/sockets/socket_options_func.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/nrf_modem/doc/sockets/socket_options_func.rst b/nrf_modem/doc/sockets/socket_options_func.rst index afcc51d101..4096c7272a 100644 --- a/nrf_modem/doc/sockets/socket_options_func.rst +++ b/nrf_modem/doc/sockets/socket_options_func.rst @@ -49,7 +49,7 @@ The following table shows all socket options supported by the Modem library. +-----------------+---------------------------------+------------------------+------------+--------------------------------------------------------------------------------------------+ | NRF_SOL_SOCKET | NRF_SO_REUSEADDR | ``int`` | set | Non-zero requests reuse of local addresses in :c:func:`nrf_bind` (protocol-specific). | +-----------------+---------------------------------+------------------------+------------+--------------------------------------------------------------------------------------------+ -| NRF_SOL_SOCKET | NRF_SO_RCVTIMEO | ``struct nrf_timeval`` | get/set | Timeout value for a socket receive operation. | +| NRF_SOL_SOCKET | NRF_SO_RCVTIMEO | ``struct nrf_timeval`` | get/set | Timeout value for a socket receive and accept operations. | +-----------------+---------------------------------+------------------------+------------+--------------------------------------------------------------------------------------------+ | NRF_SOL_SOCKET | NRF_SO_SNDTIMEO | ``struct nrf_timeval`` | get/set | Timeout value for a socket send operation. | +-----------------+---------------------------------+------------------------+------------+--------------------------------------------------------------------------------------------+ @@ -111,10 +111,11 @@ NRF_SO_REUSEADDR The default value for :c:macro:`NRF_SO_REUSEADDR` is ``off``, that is, reuse of local addresses is not permitted. NRF_SO_RCVTIMEO - Set a timeout value for the :c:func:`nrf_recv` and :c:func:`nrf_recvfrom` operations. + Set a timeout value for the :c:func:`nrf_recv`, :c:func:`nrf_recvfrom` and :c:func:`nrf_accept` operations. This 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 input operation to complete. If a receive operation has blocked for this much time without receiving additional data, it returns with a partial count, or ``errno`` is set to :c:macro:`NRF_EAGAIN` or :c:macro:`NRF_EWOULDBLOCK` if no data were received. - The default for this option is the value ``0``, which indicates that a receive operation will not time out. + If an accept operation has blocked for this much time without receiving an incoming connection, it returns ``-1`` and ``errno`` is set to :c:macro:`NRF_EAGAIN`. + The default for this option is the value ``0``, which indicates that a receive or accept operation will not time out. .. note:: The minimum supported resolution is 1 millisecond.