diff --git a/nrf_modem/doc/CHANGELOG.rst b/nrf_modem/doc/CHANGELOG.rst index 8db526679c..d4d354e899 100644 --- a/nrf_modem/doc/CHANGELOG.rst +++ b/nrf_modem/doc/CHANGELOG.rst @@ -20,6 +20,14 @@ Core library DECT NR+ ======== +* Added the DECT clock synchronization API for precise timing with external 1 PPS signals. See the :ref:`nrf_modem_dect_clock_sync` for more information. + + * The :c:func:`nrf_modem_dect_clock_sync_enable` and :c:func:`nrf_modem_dect_clock_sync_disable` functions to control external clock synchronization. + * The :c:func:`nrf_modem_dect_clock_sync_get_pulse_info` function to query synchronization pulse timing. + * The :c:func:`nrf_modem_dect_clock_sync_get_state` function to retrieve synchronization status and accuracy. + * The :c:func:`nrf_modem_dect_clock_sync_enable_ref_output` and :c:func:`nrf_modem_dect_clock_sync_disable_ref_output` functions to control reference signal output on the **COEX1** pin. + * The :c:func:`nrf_modem_dect_clock_sync_event_handler_set` function to set the event handler for asynchronous operations. + * Added: * The :c:func:`nrf_modem_dect_phy_test_rf_tx_cw_control` function to control continuous wave transmission for device certification purposes. diff --git a/nrf_modem/doc/api.rst b/nrf_modem/doc/api.rst index 25aa3a4759..d79be42080 100644 --- a/nrf_modem/doc/api.rst +++ b/nrf_modem/doc/api.rst @@ -172,6 +172,13 @@ DECT NR+ PHY API .. doxygengroup:: nrf_modem_dect_phy +.. _nrf_modem_dect_clock_sync: + +DECT clock sync API +=================== + +.. doxygengroup:: nrf_modem_dect_clock_sync + .. _nrf_modem_gnss_api: GNSS API diff --git a/nrf_modem/include/nrf_modem.h b/nrf_modem/include/nrf_modem.h index 6782f29683..55de3b54fe 100644 --- a/nrf_modem/include/nrf_modem.h +++ b/nrf_modem/include/nrf_modem.h @@ -22,7 +22,7 @@ extern "C" { #endif /** - * @defgroup nrf_modem_limits Limits of the Modem library + * @defgroup nrf_modem_limits Limits of the Modem library. * @ingroup nrf_modem * @{ * @brief Modem library constants. @@ -69,7 +69,7 @@ extern "C" { /** @} */ /** - * @defgroup nrf_modem_shmem_config Shared memory configuration + * @defgroup nrf_modem_shmem_config Shared memory configuration. * Only the lower 128k of RAM may be shared with the modem core. * * @ingroup nrf_modem diff --git a/nrf_modem/include/nrf_modem_dect_clock_sync.h b/nrf_modem/include/nrf_modem_dect_clock_sync.h new file mode 100644 index 0000000000..e5e92f1bf4 --- /dev/null +++ b/nrf_modem/include/nrf_modem_dect_clock_sync.h @@ -0,0 +1,365 @@ +/* + * Copyright (c) 2025 Nordic Semiconductor ASA + * + * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause + */ + +/** + * @file nrf_modem_dect_clock_sync.h + * + * @defgroup nrf_modem_dect_clock_sync DECT clock sync interface + * @{ + * @brief DECT clock sync API. + * + */ +#ifndef NRF_MODEM_DECT_CLOCK_SYNC_H__ +#define NRF_MODEM_DECT_CLOCK_SYNC_H__ + + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief DECT CS errors. + */ +enum nrf_modem_dect_clock_sync_err { + /** + * @brief Success. + */ + NRF_MODEM_DECT_CLOCK_SYNC_NO_ERROR = 0, + /** + * @brief Clock synchronization not active. + */ + NRF_MODEM_DECT_CLOCK_SYNC_NOT_ACTIVE = 0xFFFE, + /** + * @brief Error. + */ + NRF_MODEM_DECT_CLOCK_SYNC_ERROR = 0xFFFF +}; + +/** + * @brief Clock synchronization enable event. + */ +struct nrf_modem_dect_clock_sync_enable_event { + /** + * @brief Operation result. + * + * Can be one of the following values: + * + * - @ref NRF_MODEM_DECT_CLOCK_SYNC_NO_ERROR + * - @ref NRF_MODEM_DECT_CLOCK_SYNC_ERROR + */ + enum nrf_modem_dect_clock_sync_err err; +}; + +/** + * @brief Clock synchronization pulse info event. + */ +struct nrf_modem_dect_clock_sync_pulse_info_event { + /** + * @brief Operation result. + * + * Can be one of the following values: + * + * - @ref NRF_MODEM_DECT_CLOCK_SYNC_NO_ERROR + * - @ref NRF_MODEM_DECT_CLOCK_SYNC_NOT_ACTIVE + * - @ref NRF_MODEM_DECT_CLOCK_SYNC_ERROR + */ + enum nrf_modem_dect_clock_sync_err err; + + /** @brief Queried pulse direction (copied from request) */ + uint16_t pulse_direction; + + /** Padding */ + uint8_t pad[2]; + + /** @brief Pulse occurrence time in modem time units */ + uint64_t pulse_time; +}; + +/** + * @brief Clock synchronization disable event. + */ +struct nrf_modem_dect_clock_sync_disable_event { + /** + * @brief Operation result. + * + * Can be one of the following values: + * + * - @ref NRF_MODEM_DECT_CLOCK_SYNC_NO_ERROR + * - @ref NRF_MODEM_DECT_CLOCK_SYNC_ERROR + */ + enum nrf_modem_dect_clock_sync_err err; +}; + +/** + * @brief Clock synchronization state event. + */ +struct nrf_modem_dect_clock_sync_state_event { + /** + * @brief Operation result. + * + * Can be one of the following values: + * + * - @ref NRF_MODEM_DECT_CLOCK_SYNC_NO_ERROR + * - @ref NRF_MODEM_DECT_CLOCK_SYNC_ERROR + */ + enum nrf_modem_dect_clock_sync_err err; + + /** + * @brief Clock synchronization status. + * + * Indicates whether the modem clock is synchronized to the external clock. + * - true - synchronized + * - false - not synchronized + */ + bool synchronized; + + /** + * @brief Clock synchronization error standard deviation. + * + * Standard deviation of the clock error in parts per million (ppm) when synchronized. + * Only valid when synchronized is true. + * + * Value is encoded in Q3.12 fixed-point format: + * - Bit 15: Sign bit (0 = positive, 1 = negative) + * - Bits 14-12: Integer part (3 bits) + * - Bits 11-0: Fractional part (12 bits) + * + * To convert to floating-point ppm: value / 4096.0 + * + * Example: 0x1000 (4096 decimal) = 1.0 ppm standard deviation + */ + int16_t clock_std_ppm; +}; + +/** + * @brief Clock synchronization ref output enable event. + */ +struct nrf_modem_dect_clock_sync_enable_ref_output_event { + /** + * @brief Operation result. + * + * Can be one of the following values: + * + * - @ref NRF_MODEM_DECT_CLOCK_SYNC_NO_ERROR + * - @ref NRF_MODEM_DECT_CLOCK_SYNC_ERROR + */ + enum nrf_modem_dect_clock_sync_err err; +}; + +/** + * @brief Clock synchronization ref output disable event. + */ +struct nrf_modem_dect_clock_sync_disable_ref_output_event { + /** + * @brief Operation result. + * + * Can be one of the following values: + * + * - @ref NRF_MODEM_DECT_CLOCK_SYNC_NO_ERROR + * - @ref NRF_MODEM_DECT_CLOCK_SYNC_ERROR + */ + enum nrf_modem_dect_clock_sync_err err; +}; + + +enum nrf_modem_dect_clock_sync_event_id { + /** + * @brief Event to indicate the completion of clock synchronization enable + * operation. + */ + NRF_MODEM_DECT_CLOCK_SYNC_EVT_ENABLE, + /** + * @brief Event to indicate the completion of clock synchronization disable + * operation. + */ + NRF_MODEM_DECT_CLOCK_SYNC_EVT_DISABLE, + /** + * @brief Event carrying synchronization signal information. + */ + NRF_MODEM_DECT_CLOCK_SYNC_EVT_PULSE_INFO, + /** + * @brief Event carrying clock synchronization state information. + */ + NRF_MODEM_DECT_CLOCK_SYNC_EVT_STATE, + /** + * @brief Event to indicate the completion of clock synchronization ref output + * enable operation. + */ + NRF_MODEM_DECT_CLOCK_SYNC_EVT_ENABLE_REF_OUTPUT, + /** + * @brief Event to indicate the completion of clock synchronization ref output + * disable operation. + */ + NRF_MODEM_DECT_CLOCK_SYNC_EVT_DISABLE_REF_OUTPUT, +}; + +/** + * @brief Clock synchronization event. + */ +struct nrf_modem_dect_clock_sync_event { + /** + * @brief Event ID. + */ + enum nrf_modem_dect_clock_sync_event_id id; + /** + * @brief Event data. + */ + union { + struct nrf_modem_dect_clock_sync_enable_event clock_sync_enable; + struct nrf_modem_dect_clock_sync_disable_event clock_sync_disable; + struct nrf_modem_dect_clock_sync_pulse_info_event clock_sync_pulse_info; + struct nrf_modem_dect_clock_sync_state_event clock_sync_state; + struct nrf_modem_dect_clock_sync_enable_ref_output_event + clock_sync_enable_ref_output; + struct nrf_modem_dect_clock_sync_disable_ref_output_event + clock_sync_disable_ref_output; + }; +}; + +/** + * @brief Application handler prototype for clock sync events. + */ +typedef void (*nrf_modem_dect_clock_sync_event_handler_t)( + const struct nrf_modem_dect_clock_sync_event *event); + +/** + * @brief Set the application event handler for clock sync events. + * + * The application must set the handler for events coming for the DECT clock sync before attempting + * other clock synchronization operations. + * + * @param handler Event handler. + * + * @return 0 On success. + * @retval -NRF_EFAULT @p handler is @c NULL. + */ +int nrf_modem_dect_clock_sync_event_handler_set(nrf_modem_dect_clock_sync_event_handler_t handler); + +/** + * @brief Clock synchronization pulse direction. + */ +enum nrf_modem_dect_clock_sync_pulse_direction { + /** + * @brief Received/incoming sync pulse time. + */ + NRF_MODEM_DECT_CLOCK_SYNC_PULSE_INCOMING = 0, + /** + * @brief Transmitted/outgoing sync pulse time. + */ + NRF_MODEM_DECT_CLOCK_SYNC_PULSE_OUTGOING = 1, +}; + +/** + * @brief Enable external clock synchronization. + * + * The external clock signal is expected to be a 1 PPS (pulse-per-second) signal. When + * synchronization is enabled, the modem's clock rate aligns with the external signal, + * ensuring that exactly NRF_MODEM_DECT_MODEM_TIME_TICK_RATE_KHZ clock cycles occur + * between consecutive external clock pulses. + * + * Synchronization accuracy (jitter) is 0.001 ppm (parts per million). + * + * This operation is performed asynchronously. + * Completion of this operation is indicated by the @ref NRF_MODEM_DECT_CLOCK_SYNC_EVT_ENABLE + * event. + * + * @retval 0 Request was sent to modem. + * @retval -NRF_EPERM The Modem library is not initialized. + * @retval -NRF_EFAULT No event handler is set. + * @retval -NRF_ENOMEM Not enough shared memory for this request. + */ +int nrf_modem_dect_clock_sync_enable(void); + +/** + * @brief Disable external clock synchronization. + * + * Once complete, the modem's clock will not be synchronized to the external clock signal anymore. + * + * This operation is performed asynchronously. + * Completion of this operation is indicated by the @ref NRF_MODEM_DECT_CLOCK_SYNC_EVT_DISABLE + * event. + * + * @retval 0 Request was sent to modem. + * @retval -NRF_EPERM The Modem library is not initialized. + * @retval -NRF_EFAULT No event handler is set. + * @retval -NRF_ENOMEM Not enough shared memory for this request. + */ +int nrf_modem_dect_clock_sync_disable(void); + +/** + * @brief Query the modem for the next synchronization signal. + * + * Can be used to query when the next synchronization signal is expected to happen. + * + * This operation is performed asynchronously. + * Completion of this operation is indicated by the + * @ref NRF_MODEM_DECT_CLOCK_SYNC_EVT_PULSE_INFO event. + * + * @param direction Direction of the pulse to query information about. + * + * @retval 0 Request was sent to modem. + * @retval -NRF_EPERM The Modem library is not initialized. + * @retval -NRF_EFAULT No event handler is set. + * @retval -NRF_ENOMEM Not enough shared memory for this request. + */ +int nrf_modem_dect_clock_sync_get_pulse_info( + enum nrf_modem_dect_clock_sync_pulse_direction direction); + +/** + * @brief Query the modem for the synchronization state. + * + * This operation is performed asynchronously. + * Completion of this operation is indicated by the + * @ref NRF_MODEM_DECT_CLOCK_SYNC_EVT_STATE event. + * + * @retval 0 Request was sent to modem. + * @retval -NRF_EPERM The Modem library is not initialized. + * @retval -NRF_EFAULT No event handler is set. + * @retval -NRF_ENOMEM Not enough shared memory for this request. + */ +int nrf_modem_dect_clock_sync_get_state(void); + +/** + * @brief Enable external clock synchronization reference output. + * + * When reference output is enabled, the modem outputs a signal on COEX1 + * pin. The output signal is sent once per second as seen in modem internal + * time. The output signal has 100 ms pulse width. + * + * This operation is performed asynchronously. + * Completion of this operation is indicated by the + * @ref NRF_MODEM_DECT_CLOCK_SYNC_EVT_ENABLE_REF_OUTPUT event. + * + * @retval 0 Request was sent to modem. + * @retval -NRF_EPERM The Modem library is not initialized. + * @retval -NRF_EFAULT No event handler is set. + * @retval -NRF_ENOMEM Not enough shared memory for this request. + */ +int nrf_modem_dect_clock_sync_enable_ref_output(void); + +/** + * @brief Disable external clock synchronization reference output. + * + * Once complete, the modem will not output the reference signal on COEX1 pin + * anymore. + * + * This operation is performed asynchronously. + * Completion of this operation is indicated by the + * @ref NRF_MODEM_DECT_CLOCK_SYNC_EVT_DISABLE_REF_OUTPUT event. + * + * @retval 0 Request was sent to modem. + * @retval -NRF_EPERM The Modem library is not initialized. + * @retval -NRF_EFAULT No event handler is set. + * @retval -NRF_ENOMEM Not enough shared memory for this request. + */ +int nrf_modem_dect_clock_sync_disable_ref_output(void); + +#ifdef __cplusplus +} +#endif + +#endif /* NRF_MODEM_DECT_CLOCK_SYNC_H__ */ +/** @} */ diff --git a/nrf_modem/include/nrf_modem_rs_capture.h b/nrf_modem/include/nrf_modem_rs_capture.h index 4bfe59fb17..93c9e59115 100644 --- a/nrf_modem/include/nrf_modem_rs_capture.h +++ b/nrf_modem/include/nrf_modem_rs_capture.h @@ -10,6 +10,10 @@ * @defgroup nrf_modem_rs_capture RS capture API * @{ * @brief API for accessing the RS capture module on the modem. + * + * @note This is only supported by the following modem firmware: + * - mfw_nrf91x1 >= v2.0.3 + * - mfw_nrf9151-ntn */ #ifndef NRF_MODEM_RS_CAPTURE_H__ #define NRF_MODEM_RS_CAPTURE_H__ diff --git a/nrf_modem/include/nrf_socket.h b/nrf_modem/include/nrf_socket.h index 6f526ef487..098e8ac3db 100644 --- a/nrf_modem/include/nrf_socket.h +++ b/nrf_modem/include/nrf_socket.h @@ -51,13 +51,10 @@ extern "C" { #endif /** + * @brief Maximum number of IP sockets. * @addtogroup nrf_modem_limits - * @{ */ - - /** @brief Maximum number of IP sockets. */ #define NRF_MODEM_MAX_SOCKET_COUNT 8 -/** @} */ /** * @addtogroup nrf_socket_address_resolution @@ -106,7 +103,7 @@ extern "C" { */ /** - * @defgroup nrf_socket_families Socket family + * @defgroup nrf_socket_families Socket family. * @{ */ /** Unspecified address family */ @@ -120,7 +117,7 @@ extern "C" { /** @} */ /** - * @defgroup nrf_socket_types Socket type + * @defgroup nrf_socket_types Socket type. * @{ */ /** TCP socket type. */ @@ -1189,16 +1186,17 @@ int nrf_getifaddrs(struct nrf_ifaddrs **ifa); void nrf_freeifaddrs(struct nrf_ifaddrs *ifa); /** - * @brief Set a fallback DNS address. + * @brief Set or unset a fallback DNS address. * * @details * The fallback DNS address is used only when the network-provided DNS addresses are * missing or unreachable. The fallback DNS does not override the network-provided DNS. * * @param family Address family, either NRF_AF_INET or NRF_AF_INET6. - * @param in_addr An IPv4 or IPv6 address encoded in a nrf_in_addr or - * nrf_in6_addr structure, respectively. - * @param in_size Size of the structure pointed to by in_addr. + * @param in_addr An IPv4 or IPv6 address encoded in a nrf_in_addr or nrf_in6_addr structure, + * respectively. To unset the fallback DNS address, @p in_addr must be NULL. + * @param in_size Size of the structure pointed to by @p in_addr. To unset the fallback DNS + * address, @p in_size must be 0 (when @p in_addr is NULL). * * @retval 0 On success * @retval -1 On error, and set @c errno to indicate the reason. diff --git a/nrf_modem/lib/cellular/nrf9120/hard-float/libmodem.a b/nrf_modem/lib/cellular/nrf9120/hard-float/libmodem.a index f096bcc3fb..ef059df883 100644 Binary files a/nrf_modem/lib/cellular/nrf9120/hard-float/libmodem.a and b/nrf_modem/lib/cellular/nrf9120/hard-float/libmodem.a differ diff --git a/nrf_modem/lib/cellular/nrf9120/hard-float/libmodem_log.a b/nrf_modem/lib/cellular/nrf9120/hard-float/libmodem_log.a index 0ce551aaca..b9e94975ea 100644 Binary files a/nrf_modem/lib/cellular/nrf9120/hard-float/libmodem_log.a and b/nrf_modem/lib/cellular/nrf9120/hard-float/libmodem_log.a differ diff --git a/nrf_modem/lib/cellular/nrf9120/soft-float/libmodem.a b/nrf_modem/lib/cellular/nrf9120/soft-float/libmodem.a index 598206d9f6..bc585617da 100644 Binary files a/nrf_modem/lib/cellular/nrf9120/soft-float/libmodem.a and b/nrf_modem/lib/cellular/nrf9120/soft-float/libmodem.a differ diff --git a/nrf_modem/lib/cellular/nrf9120/soft-float/libmodem_log.a b/nrf_modem/lib/cellular/nrf9120/soft-float/libmodem_log.a index 016e187bd9..3782e9073f 100644 Binary files a/nrf_modem/lib/cellular/nrf9120/soft-float/libmodem_log.a and b/nrf_modem/lib/cellular/nrf9120/soft-float/libmodem_log.a differ diff --git a/nrf_modem/lib/cellular/nrf9160/hard-float/libmodem.a b/nrf_modem/lib/cellular/nrf9160/hard-float/libmodem.a index fe2bdfa1c2..bb69d4846c 100644 Binary files a/nrf_modem/lib/cellular/nrf9160/hard-float/libmodem.a and b/nrf_modem/lib/cellular/nrf9160/hard-float/libmodem.a differ diff --git a/nrf_modem/lib/cellular/nrf9160/hard-float/libmodem_log.a b/nrf_modem/lib/cellular/nrf9160/hard-float/libmodem_log.a index 2177431733..b1a86681d2 100644 Binary files a/nrf_modem/lib/cellular/nrf9160/hard-float/libmodem_log.a and b/nrf_modem/lib/cellular/nrf9160/hard-float/libmodem_log.a differ diff --git a/nrf_modem/lib/cellular/nrf9160/soft-float/libmodem.a b/nrf_modem/lib/cellular/nrf9160/soft-float/libmodem.a index 89f115cc95..91db9072d4 100644 Binary files a/nrf_modem/lib/cellular/nrf9160/soft-float/libmodem.a and b/nrf_modem/lib/cellular/nrf9160/soft-float/libmodem.a differ diff --git a/nrf_modem/lib/cellular/nrf9160/soft-float/libmodem_log.a b/nrf_modem/lib/cellular/nrf9160/soft-float/libmodem_log.a index 52fa529d2b..3927387f95 100644 Binary files a/nrf_modem/lib/cellular/nrf9160/soft-float/libmodem_log.a and b/nrf_modem/lib/cellular/nrf9160/soft-float/libmodem_log.a differ diff --git a/nrf_modem/lib/cellular/nrf9230/hard-float/libmodem.a b/nrf_modem/lib/cellular/nrf9230/hard-float/libmodem.a index 6787efe2b9..8742754774 100644 Binary files a/nrf_modem/lib/cellular/nrf9230/hard-float/libmodem.a and b/nrf_modem/lib/cellular/nrf9230/hard-float/libmodem.a differ diff --git a/nrf_modem/lib/cellular/nrf9230/hard-float/libmodem_log.a b/nrf_modem/lib/cellular/nrf9230/hard-float/libmodem_log.a index 184b6ecbf5..96caef5bff 100644 Binary files a/nrf_modem/lib/cellular/nrf9230/hard-float/libmodem_log.a and b/nrf_modem/lib/cellular/nrf9230/hard-float/libmodem_log.a differ diff --git a/nrf_modem/lib/cellular/nrf9230/soft-float/libmodem.a b/nrf_modem/lib/cellular/nrf9230/soft-float/libmodem.a index c8bb602f7c..127f7d232d 100644 Binary files a/nrf_modem/lib/cellular/nrf9230/soft-float/libmodem.a and b/nrf_modem/lib/cellular/nrf9230/soft-float/libmodem.a differ diff --git a/nrf_modem/lib/cellular/nrf9230/soft-float/libmodem_log.a b/nrf_modem/lib/cellular/nrf9230/soft-float/libmodem_log.a index db72a1962a..c98b54c85d 100644 Binary files a/nrf_modem/lib/cellular/nrf9230/soft-float/libmodem_log.a and b/nrf_modem/lib/cellular/nrf9230/soft-float/libmodem_log.a differ diff --git a/nrf_modem/lib/dect_phy/nrf9120/hard-float/libmodem.a b/nrf_modem/lib/dect_phy/nrf9120/hard-float/libmodem.a index add18a9f08..6b0bcfe2d9 100644 Binary files a/nrf_modem/lib/dect_phy/nrf9120/hard-float/libmodem.a and b/nrf_modem/lib/dect_phy/nrf9120/hard-float/libmodem.a differ diff --git a/nrf_modem/lib/dect_phy/nrf9120/hard-float/libmodem_log.a b/nrf_modem/lib/dect_phy/nrf9120/hard-float/libmodem_log.a index 7b15775b18..b2d5171ee2 100644 Binary files a/nrf_modem/lib/dect_phy/nrf9120/hard-float/libmodem_log.a and b/nrf_modem/lib/dect_phy/nrf9120/hard-float/libmodem_log.a differ diff --git a/nrf_modem/lib/dect_phy/nrf9120/soft-float/libmodem.a b/nrf_modem/lib/dect_phy/nrf9120/soft-float/libmodem.a index 2f34a35bb3..4b382ef42f 100644 Binary files a/nrf_modem/lib/dect_phy/nrf9120/soft-float/libmodem.a and b/nrf_modem/lib/dect_phy/nrf9120/soft-float/libmodem.a differ diff --git a/nrf_modem/lib/dect_phy/nrf9120/soft-float/libmodem_log.a b/nrf_modem/lib/dect_phy/nrf9120/soft-float/libmodem_log.a index 36670edc4b..217922d810 100644 Binary files a/nrf_modem/lib/dect_phy/nrf9120/soft-float/libmodem_log.a and b/nrf_modem/lib/dect_phy/nrf9120/soft-float/libmodem_log.a differ