diff --git a/nrf_modem/doc/CHANGELOG.rst b/nrf_modem/doc/CHANGELOG.rst index 5278f053b9..06405f4d01 100644 --- 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 +********* + +Core library +============ + +* Fixed a bug introduced in the :c:func:`nrf_modem_init()` function in version 2.3.0, where the library would use the function's input parameter after the function had returned. + This could cause several socket functions to return an error and set ``errno`` to ``NRF_EINVAL``. + If you use a version of this library from v2.3.0 to v2.9.0 outside of the |NCS| and are initializing the library by calling the :c:func:`nrf_modem_init()` function, ensure that the parameter of the :c:func:`nrf_modem_init` function is always ``static``. + +DECT NR+ +======== + +Added support for DECT PHY firmware v1.1.0 with new features and improvements, notably: + +* Hardware and software initialization of the stack are now separate operations. +* Full support for scheduled operations. +* Extended operation latency and band information. +* Automatic voltage measurement and reporting during operation. + +.. important:: + Due to incompatibilities between the DECT PHY 1.0.x and 1.1.0 firmware versions, this version of the library is only compatible with DECT PHY firmware version 1.1.0 and newer. + +* Added: + + * The event types for all operations, and the :c:enum:`nrf_modem_dect_phy_event_id` event ID enumeration. + * Transaction IDs to the PCC and PDC events to map the two together. + * The :c:func:`nrf_modem_dect_phy_activate` function to activate the DECT PHY stack. + * The :c:func:`nrf_modem_dect_phy_deactivate` function to deactivate the DECT PHY stack. + * The :c:func:`nrf_modem_dect_phy_configure` function to configure the DECT PHY stack. + * The :c:func:`nrf_modem_dect_phy_radio_config` function to configure the radio mode. + * The :c:func:`nrf_modem_dect_phy_band_get` function to retrieve the bands supported by the firmware. + * The :c:func:`nrf_modem_dect_phy_latency_get` function to retrieve the operation latencies. + * The :c:macro:`NRF_MODEM_DECT_PHY_VOLTAGE_NOT_MEASURED` macro to indicate the voltage was not measured. + * The :c:enumerator:`NRF_MODEM_DECT_PHY_ERR_RADIO_MODE_CONFLICT` and :c:enumerator:`NRF_MODEM_DECT_PHY_ERR_TX_POWER_OVER_MAX_LIMIT` enumeration values. + +* Updated: + + * The ``nrf_modem_dect_phy_rx_stop`` function was renamed to :c:func:`nrf_modem_dect_phy_cancel` and can now be used to cancel any operation. + * The ``nrf_modem_dect_phy_callback_set`` function was renamed to :c:func:`nrf_modem_dect_phy_event_handler_set`. + Instead of providing a set of callbacks, one for each operation, the application now sets a single event handler function to receive events. + +* Removed: + + * The ``nrf_modem_dect_phy_callbacks`` struct. + The application now sets a single event handler using the :c:func:`nrf_modem_dect_phy_event_handler_set` function instead. + * The ``nrf_modem_dect_phy_modem_cfg`` struct. + * The ``NRF_MODEM_DECT_PHY_ERR_NO_ONGOING_OP`` enumeration value. + nrf_modem 2.9.0 *************** diff --git a/nrf_modem/doc/dectphy.rst b/nrf_modem/doc/dectphy.rst index ca78402423..63b6aa71c2 100644 --- a/nrf_modem/doc/dectphy.rst +++ b/nrf_modem/doc/dectphy.rst @@ -23,7 +23,7 @@ Regulations *********** DECT NR+ operates on free but regulated radio channels. -The availability of the channels and the exact regulation to use them varies in different countries. +The availability of these channels and the exact regulations covering their use varies in different countries. .. note:: It is your responsibility to operate the devices according to the local regulation, in all situations. @@ -57,106 +57,200 @@ The DECT NR+ PHY firmware implements only the physical layer of the protocol sta General operation ***************** -This section describes the characteristics and general operation of the DECT PHY interface. +The DECT PHY stack has the following three states: + +* deinitialized, deactivated +* initialized, deactivated +* initialized, activated + +The DECT PHY interface offers four functions to manipulate the DECT PHY stack state: + +* :c:func:`nrf_modem_dect_phy_init` +* :c:func:`nrf_modem_dect_phy_deinit` +* :c:func:`nrf_modem_dect_phy_activate` +* :c:func:`nrf_modem_dect_phy_deactivate` Initialization ============== -The DECT PHY interface in the Modem library requires explicit initialization. +Initializing the DECT PHY readies the hardware resources for the PHY in the modem. + +Before initializing the DECT PHY, the application must: + +#. Initialize the Modem library by calling the :c:func:`nrf_modem_init` function. + This also turns on the modem. +#. Register the event handler for DECT PHY operations by calling the :c:func:`nrf_modem_dect_phy_event_handler_set` function. -Before initializing the DECT PHY interface of the Modem library, the application must: +Afterwards, the application can initialize the DECT PHY by calling the :c:func:`nrf_modem_dect_phy_init` function. -#. Initialize the Modem library by calling the :c:func:`nrf_modem_init` function. This also turns on the modem core. -#. Register callbacks for DECT PHY operations by calling the :c:func:`nrf_modem_dect_phy_callback_set` function. +On nRF9131 Series devices only, the DECT NR+ PHY firmware locks the calibration data the very first time the DECT PHY is initialized. -Afterwards, the application can initialize the DECT PHY interface by calling the :c:func:`nrf_modem_dect_phy_init` function. -Upon successful initialization, both the DECT PHY interface and DECT NR+ physical layer in the modem are ready for operation. +To begin receiving and transmitting data, the DECT PHY must be configured and activated first. -On nRF9151 Series devices only, the application can configure band 4 support during initialization by setting the :c:member:`nrf_modem_dect_phy_init_params.band4_support` field to ``1``. +Configuration +============= + +The DECT PHY must be configured using the :c:func:`nrf_modem_dect_phy_configure` function each time before it is activated. + +On nRF9151 Series devices only, the application can configure band 4 support during initialization by setting the :c:member:`nrf_modem_dect_phy_config_params.band_group_index` field to ``1``. .. note:: DECT NR+ band 4 is supported by the nRF9151 LACA A0 SiP for R&D evaluation purposes. The nRF9151 LACA A0AB SiP will be qualified for DECT NR+ band 4 support. .. important:: - When operating on band 4, you must not use the carries outside the range of 525 to 551 as they interfere with other radio devices, including LTE devices. + When operating on band 4, you must not use the carriers outside the range of 525 to 551 as they interfere with other radio devices, including LTE devices. -On nRF9131 Series devices only, the DECT NR+ PHY firmware locks the calibration data the very first time the DECT PHY interface is initialized. +Activation +========== -The DECT PHY interface can be de-initialized, which in turn de-initializes the physical layer in the modem, cancelling all scheduled operations. +Once the DECT PHY has been configured, it can be activated in a given radio mode using the :c:func:`nrf_modem_dect_phy_activate` function. +When the DECT PHY is in an activated state, it is possible to start receiving and transmitting data. +Different radio modes have different performance and latency. -.. note:: - De-initializing the DECT PHY interface does not unset any callbacks set by the application using the :c:func:`nrf_modem_dect_phy_callback_set` function. - It also does not affect the modem core power status (on/off), which is instead controlled by the :c:func:`nrf_modem_init` and :c:func:`nrf_modem_shutdown` functions. +Radio modes +=========== -Once de-initialized, the DECT PHY interface can be re-initialized by only calling the :c:func:`nrf_modem_dect_phy_init` function. +The radio modes have implications on operation latency and power consumption. + +The radio can be configured in one of three modes described in the following sections. + +Low latency +----------- + +This mode has the lowest latency, the best RX/TX switching performance, and the highest power consumption. +This is the only mode that supports immediate starting operations, that is, operations whose configured start time is zero. + +Low latency with standby +------------------------ + +This mode has the same RX/TX switching performance as the low latency mode, but higher operation start-up latency due to the radio entering standby mode when possible. +Power consumption is thus lower compared to the low latency mode. + +No LBT with standby +------------------- + +This mode has the lowest power consumption, due to the modem entering standby mode when possible and not using Listen-Before-Talk, at the cost of higher start-up latency and worse RX/TX switching performance compared to the other radio modes. -Radio states +Deactivation ============ -The radio states have implications for latency and power consumption. -During operation, the radio can be in one of several states. +The DECT PHY can be deactivated using the :c:func:`nrf_modem_dect_phy_deactivate` function. +When in the deactivated state, the DECT PHY can be configured with different parameters. -When a radio operation is being executed, the stack is in one of the following states: +Deinitialization +================ + +The DECT PHY can be de-initialized using the :c:func:`nrf_modem_dect_phy_deinit` function, releasing all hardware resources. +Once de-initialized, the DECT PHY interface can be re-initialized by only calling the :c:func:`nrf_modem_dect_phy_init` function. + +Temperature monitoring +====================== + +The DECT PHY interface reports the current SiP temperature as measured by the DECT NR+ PHY firmware in all radio operation events, and upon initialization. +This allows the application to track the changes in temperature and adjust further scheduling of operations accordingly, to ensure the device remains within safe operating temperatures. + +The DECT NR+ PHY firmware has an internal temperature protection mechanism that prevents the SiP from operating above safe temperature limits. +The operating temperature limit is reported upon initialization by the :c:enumerator:`NRF_MODEM_DECT_PHY_EVT_INIT` event, in the :c:member:`nrf_modem_dect_phy_init_event.temperature_limit` parameter. + +If the temperature threshold is reached, the modem rejects further scheduling of radio operations with the :c:enumerator:`NRF_MODEM_DECT_PHY_ERR_TEMP_HIGH` error. + +In this event, the application must de-initialize the DECT PHY by calling the :c:func:`nrf_modem_dect_phy_deinit` function and allow the device to cool. +This will cancel all scheduled operations, with the :c:enumerator:`NRF_MODEM_DECT_PHY_ERR_OP_CANCELED` error in their relative events. -* TX active- The radio is transmitting, no reception is ongoing. -* RX active- The radio is receiving, no transmission is ongoing. +The application can then re-initialize the DECT PHY interface by calling :c:func:`nrf_modem_dect_phy_init`, and read the current measured temperature in the :c:struct:`nrf_modem_dect_phy_init_event` event to ensure the temperature has decreased below the allowed threshold. -When no radio operations are being executed, the stack is in the radio idle state. -In this state, the radio is powered on and able to start a radio operation with relatively low latency, at the cost of increased power consumption compared to sleep or off states. +Voltage monitoring +================== -Currently, the DECT PHY layer in the DECT NR+ PHY firmware does not support deep sleep states. +The DECT PHY interface reports the voltage as measured by the DECT NR+ PHY firmware in all radio operation events, and upon initialization. +This allows the application to track the changes in voltage and adjust accordingly to ensure the device operates within expected voltage levels. + +Physical layer capabilities +=========================== + +The application can retrieve the DECT NR+ PHY firmware physical layer capabilities by calling the :c:func:`nrf_modem_dect_phy_capability_get` function. +The list of supported capabilities is returned to the application in the :c:enumerator:`NRF_MODEM_DECT_PHY_EVT_CAPABILITY` event. Scheduling operations -===================== +********************* The DECT PHY interface allows to schedule radio operations for execution by the scheduler of the DECT NR+ physical layer in the DECT NR+ PHY firmware. -Due to the nature of a radio scheduler, which allows radio operations to be executed at a specific time in the future, all radio operations in the DECT PHY interface are asynchronous and their completion is signaled to the application using callbacks. - -All scheduling is final, which means that it is not possible to unschedule operations. +Due to the nature of a radio scheduler, which allows radio operations to be executed at a specific time in the future, all radio operations in the DECT PHY interface are asynchronous and their completion is signaled to the application using events. -A radio operation may be scheduled to execute at a specific time in the future, or immediately, if the radio is not currently executing any other operation. +A radio operation may be scheduled to execute at a specific time in the future or immediately if the radio is not currently executing any other operation. -All radio operations have an application-defined handle, which can be used to identify the operation and that is returned by the callback signaling the completion of an operation. -The operation handle is entirely opaque to all underlying layers, including the DECT PHY interface. +All events for radio operations carry an application-defined handle that can be used to identify the operation. Modem time and operation latency --------------------------------- +================================ Operation execution is scheduled by the application according to the modem time, which is a 64-bit counter kept by the modem. -All radio operation callbacks provide the value that the modem time counter had at the moment the callback was sent by the modem core to the application core. -This provides a way for the application to track the modem time without explicitly querying the modem for it. +All DECT PHY events provide the value of the modem time counter at the moment the event was sent by the modem core to the application core. +This provides a way for the application to track the modem time without explicitly querying the modem for it. If necessary, the application can retrieve the modem time counter value by calling the :c:func:`nrf_modem_dect_phy_time_get` function. -Both radio state transitions between operations in the modem core and the interprocessor communication (IPC) mechanism between the application and modem cores have latency. -The latency of both radio state transitions and IPC is measured and provided by the DECT PHY interface upon initialization, by the :c:member:`nrf_modem_dect_phy_callbacks.init` callback function, in the :c:member:`nrf_modem_dect_phy_modem_cfg.latency` parameter. +The current radio mode, the radio state transitions between operations, and scheduling overhead all affect the total operation latency and must be taken into account during scheduling of operations. -.. note:: - The application must account for operations' latency when scheduling operations. +These latencies are measured and can be retrieved by the application using the :c:func:`nrf_modem_dect_phy_latency_get` function. -Temperature monitoring +Examples of scheduling ====================== -The DECT PHY interface reports the current SiP temperature as measured by the DECT NR+ PHY firmware in all radio operation callbacks, and upon initialization. -This allows the application to track the changes in temperature and adjust further scheduling of operations accordingly, to ensure the device remains within safe operating temperatures. +Example 1: Immediate execution -The DECT NR+ PHY firmware has an internal temperature protection mechanism that prevents the SiP from operating above safe temperature limits. -The operating temperature limit is reported upon initialization by the :c:member:`nrf_modem_dect_phy_callbacks.init` callback function, in the :c:member:`nrf_modem_dect_phy_modem_cfg.temperature_limit` parameter. +Pre-conditions: -If the temperature threshold is reached, the modem rejects further scheduling of radio operations with the :c:enum:`nrf_modem_dect_phy_err.NRF_MODEM_DECT_PHY_ERR_TEMP_HIGH` error. +* The DECT PHY radio mode is :c:enumerator:`NRF_MODEM_DECT_PHY_RADIO_MODE_LOW_LATENCY`. +* There are no scheduled or ongoing operations. -In this event, the application must de-initialize the DECT PHY interface (and thus the firmware DECT NR+ physical layer) by calling the :c:func:`nrf_modem_dect_phy_deinit` function and allow the device to cool. -This will cancel all scheduled operations, with the :c:enum:`nrf_modem_dect_phy_err.NRF_MODEM_DECT_PHY_ERR_OP_CANCELED` error in their relative callbacks. +Let ``t`` be the current modem time. -The application can then re-initialize the DECT PHY interface by calling :c:func:`nrf_modem_dect_phy_init`, and read the current measured temperature in the :c:member:`nrf_modem_dect_phy_callbacks.init` function parameters, -to ensure the temperature has decreased below the allowed threshold. +The operation startup latency ``startup`` is indicated: -Physical layer capabilities -=========================== +* For RX operations (RX, RSSI or RX with RSSI) by :c:member:`nrf_modem_dect_phy_latency_info.idle_to_active` +* For TX operations by :c:member:`nrf_modem_dect_phy_latency_info.idle_to_active` -The application can retrieve the DECT NR+ PHY firmware physical layer capabilities by calling the :c:func:`nrf_modem_dect_phy_capability_get` function. -The list of supported capabilities is returned to the application in the :c:member:`nrf_modem_dect_phy_callbacks.capability_get` callback function. +The actual start time of the operation can be calculated as ``t + startup``. + +Stopping the operation also incurs latency, which includes the time to close the RF channel and send the operation response after the operation's duration. + +The stop latency ``stop`` depends on the operation, and is indicated: + +* For an RX operation- :c:member:`nrf_modem_dect_phy_latency_info.active_to_idle_rx` +* For an RSSI operation- :c:member:`nrf_modem_dect_phy_latency_info.active_to_idle_rssi` +* For an RX operation with RSSI measurements- :c:member:`nrf_modem_dect_phy_latency_info.active_to_idle_rx_rssi` +* For a TX operation- :c:member:`nrf_modem_dect_phy_latency_info.active_to_idle` +* For a TX_RX operation- :c:member:`nrf_modem_dect_phy_latency_info.active_to_idle_rx` + +Thus, for a given operation duration of ``duration``, the earliest time at which the next operation can be executed can be calculated as: ``t + startup + duration + stop``. + +Example 2: Scheduling one operation after another + +Pre-conditions: + +* The DECT PHY is activated. +* There is one scheduled or ongoing operation (operation 1). + +Let ``t`` represent the current modem time. +Let ``start_time_op1`` and ``duration_op1`` be the start time and duration of operation 1 respectively. + +The operation startup latency ``startup`` is indicated: + +* For RX operations (RX, RSSI or RX with RSSI) by: :c:member:`nrf_modem_dect_phy_latency_info.idle_to_active` +* For TX operations by: :c:member:`nrf_modem_dect_phy_latency_info.idle_to_active` + +Since the operation is scheduled, we must include the additional startup delay associated with scheduled operations for the current radio mode. +Let ``sched_startup`` be the value of this delay, as indicated by :c:member:`nrf_modem_dect_phy_latency_info.scheduled_operation_startup`. + +The earliest start time of the operation is then calculated by adding both the initial startup delay and the scheduled startup delay to the current modem time, +expressed as: ``t + startup + sched_startup``. + +The earliest time at which the operation can be scheduled after another one must include the additional delay associated with transitioning from one scheduled operation to the next, according to the current radio mode. +Let ``sched_transition`` be the value of this delay, as indicated by :c:member:`nrf_modem_dect_phy_latency_info.scheduled_operation_transition`. + +In conclusion, the start time of the operation being scheduled must be at least as large as the minimum between ``t + startup + sched_startup`` and ``start_time_op1 + duration_op1 + sched_transition``. Radio operations **************** @@ -169,8 +263,9 @@ The DECT PHY interface offers the following three radio operations: Each of these operations can be performed with different parameters. -The completion of a radio operation is signaled to the application by the invocation of the :c:member:`nrf_modem_dect_phy_callbacks.op_complete` callback function. -The callback receives the same handle that was specified by the application at the time the operation was scheduled. +The completion of a radio operation is signaled to the application by the invocation of the :c:enumerator:`NRF_MODEM_DECT_PHY_EVT_COMPLETED` event. + +The event carries the same handle that was specified by the application at the time the operation was scheduled. Transmission ============ @@ -178,8 +273,8 @@ Transmission The application can schedule a transmission by calling the :c:func:`nrf_modem_dect_phy_tx` function. The operation is asynchronous, and the successful completion of the :c:func:`nrf_modem_dect_phy_tx` function only signals that the request was sent to the modem. -When the operation has completed, its result is signaled to the application in the :c:member:`nrf_modem_dect_phy_callbacks.op_complete` callback function. -If any error has occurred in scheduling or executing the operation, it is returned in the callback. +When the operation has completed, its result is signaled to the application in the :c:enumerator:`NRF_MODEM_DECT_PHY_EVT_COMPLETED` event. +If any error has occurred in scheduling or executing the operation, it is returned in the event. The operation has several parameters, including Listen Before Talk (LBT) period and threshold. @@ -246,7 +341,7 @@ Hybrid ARQ The application can schedule a hybrid ARQ response transmission (HARQ feedback) by calling the :c:func:`nrf_modem_dect_phy_tx_harq` function. A HARQ response transmission can be scheduled after a reception on the physical control channel (PCC). -Scheduling a HARQ response is time critical and therefore it must be done directly from the :c:member:`nrf_modem_dect_phy_callbacks.pcc` callback. +Scheduling a HARQ response is time critical and therefore it must be done directly from the :c:enumerator:`NRF_MODEM_DECT_PHY_EVT_PCC` event. The MAC must have prepared data towards possible HARQ recipients in advance, so that it can directly call this function without further delays. .. note:: @@ -261,11 +356,11 @@ The application can schedule a reception by calling the :c:func:`nrf_modem_dect_ The operation is asynchronous, and the completion of the :c:func:`nrf_modem_dect_phy_rx` function only signals that the request was sent to the modem. -During reception, data received on the physical control channel (PCC) and on the physical data channel (PDC) is sent to the application in the :c:member:`nrf_modem_dect_phy_callbacks.pcc` and :c:member:`nrf_modem_dect_phy_callbacks.pdc` callback functions, respectively. -Any CRC errors on the physical control channel and on the physical data channel are sent to the application in the :c:member:`nrf_modem_dect_phy_callbacks.pcc_crc_err` and :c:member:`nrf_modem_dect_phy_callbacks.pdc_crc_err` callback functions, respectively. +During reception, data received on the physical control channel (PCC) and on the physical data channel (PDC) is sent to the application in the :c:enumerator:`NRF_MODEM_DECT_PHY_EVT_PCC` and :c:enumerator:`NRF_MODEM_DECT_PHY_EVT_PDC` events, respectively. +Any CRC errors on the physical control channel and on the physical data channel are sent to the application in the :c:enumerator:`NRF_MODEM_DECT_PHY_EVT_PCC_ERROR` and :c:enumerator:`NRF_MODEM_DECT_PHY_EVT_PDC_ERROR` events, respectively. -When the operation has completed, its result is signaled to the application in the :c:member:`nrf_modem_dect_phy_callbacks.op_complete` callback function. -If any error has occurred in scheduling or executing the operation, it is returned in the callback. +When the operation has completed, its result is signaled to the application in the :c:enumerator:`NRF_MODEM_DECT_PHY_EVT_COMPLETED` event. +If any error has occurred in scheduling or executing the operation, it is returned in the event. Reception modes --------------- @@ -283,15 +378,6 @@ Reception with RSSI measurement A reception operation may be combined with an RSSI measurement operation by configuring the :c:member:`nrf_modem_dect_phy_rx_params.rssi_interval` parameter. -Stopping reception ------------------- - -It is possible to stop the execution of reception operations by calling the :c:func:`nrf_modem_dect_phy_rx_stop` function. - -A reception operation may only be stopped when it is currently being executed. - -It is not possible to unschedule the execution of reception operations (or any others). - RSSI measurement ================ @@ -299,10 +385,10 @@ The application can schedule an RSSI measurement by operation by calling the :c: The operation is asynchronous, and the completion of the :c:func:`nrf_modem_dect_phy_rssi` function only signals that the request was sent to the modem. -RSSI measurements are sent to the application in the :c:member:`nrf_modem_dect_phy_callbacks.rssi` callback function at a configurable interval, as specified by the :c:member:`nrf_modem_dect_phy_rssi_params.reporting_interval` field in the operation parameters. +RSSI measurements are sent to the application in the :c:enumerator:`NRF_MODEM_DECT_PHY_EVT_RSSI` event at a configurable interval, as specified by the :c:member:`nrf_modem_dect_phy_rssi_params.reporting_interval` field in the operation parameters. -When the operation has completed, its result is signaled to the application in the :c:member:`nrf_modem_dect_phy_callbacks.op_complete` callback function. -If any error has occurred in scheduling or executing the operation, it is returned in the callback. +When the operation has completed, its result is signaled to the application in the :c:enumerator:`NRF_MODEM_DECT_PHY_EVT_COMPLETED` event. +If any error has occurred in scheduling or executing the operation, it is returned in the event. Combined TX and RX operation ============================ @@ -310,9 +396,20 @@ Combined TX and RX operation You can schedule a combined TX and RX operation by calling the :c:func:`nrf_modem_dect_phy_tx_rx` function. Scheduling two operations at once has the advantage of being faster, that is, it has a lower latency than scheduling the two halves of the operation separately. +The start time of the RX operation is relative to the completion of the TX operation. + The operations will be executed one after the other, starting with the TX operation. The RX operation will be executed only if the TX operation has been completed successfully. -The start time of the RX operation is relative to the completion of the TX operation. +When the TX or RX part of the operation has completed, either successfully or unsuccessfully, its result is sent to the :c:enumerator:`NRF_MODEM_DECT_PHY_EVT_COMPLETED` event. + +Canceling operations +==================== + +The application can cancel operations using the :c:func:`nrf_modem_dect_phy_cancel` function and specifying the handle of the operation to be canceled. + +When an operation is canceled, one :c:enumerator:`NRF_MODEM_DECT_PHY_EVT_COMPLETED` event is sent to the application. + +If the operation was not executing, the event carries the error :c:enumerator:`NRF_MODEM_DECT_PHY_ERR_OP_CANCELED`, otherwise it reports a success. -When the TX or RX part of the operation has completed, either successfully or unsuccessfully, its result is sent to the :c:member:`nrf_modem_dect_phy_callbacks.op_complete` callback function. +Afterwards, one :c:enumerator:`NRF_MODEM_DECT_PHY_EVT_CANCELED` event is sent to the application to indicate that the cancellation operation has completed. diff --git a/nrf_modem/include/nrf_modem_dect_phy.h b/nrf_modem/include/nrf_modem_dect_phy.h index 50e8553ec1..64ce153aa0 100644 --- a/nrf_modem/include/nrf_modem_dect_phy.h +++ b/nrf_modem/include/nrf_modem_dect_phy.h @@ -42,18 +42,21 @@ extern "C" { /** @brief Minimum LBT measurement period in modem time units. */ #define NRF_MODEM_DECT_LBT_PERIOD_MIN (2 * NRF_MODEM_DECT_SYMBOL_DURATION) +/** @brief Signal to noise ratio not measured. */ +#define NRF_MODEM_DECT_PHY_SNR_NOT_MEASURED -32768 /** @brief Symbol RSSI not measured. */ #define NRF_MODEM_DECT_PHY_RSSI_NOT_MEASURED 0 -/** @brief Temperature not measured. */ -#define NRF_MODEM_DECT_PHY_TEMP_NOT_MEASURED 999 /** @brief RSSI-2 not measured. */ #define NRF_MODEM_DECT_PHY_RSSI2_NOT_MEASURED -32768 -/** @brief Signal to noise ratio not measured. */ -#define NRF_MODEM_DECT_PHY_SNR_NOT_MEASURED -32768 +/** @brief Temperature not measured. */ +#define NRF_MODEM_DECT_PHY_TEMP_NOT_MEASURED 999 +/** @brief Voltage not measured. */ +#define NRF_MODEM_DECT_PHY_VOLTAGE_NOT_MEASURED 0 +/** @brief Special handle to cancel all operations in @ref nrf_modem_dect_phy_cancel */ +#define NRF_MODEM_DECT_PHY_HANDLE_CANCEL_ALL UINT32_MAX /** @brief Buffer status and Channel quality indicator not used. */ #define NRF_MODEM_DECT_PHY_BS_CQI_NOT_USED 0 - /** @brief Unspecified link identifier. */ #define NRF_MODEM_DECT_PHY_LINK_UNSPECIFIED ((struct nrf_modem_dect_phy_link_id){ 0 }) @@ -74,9 +77,9 @@ enum nrf_modem_dect_phy_err { */ NRF_MODEM_DECT_PHY_ERR_UNSUPPORTED_OP = 0x2, /** - * @brief Operation is not executing; it cannot be stopped. + * @brief Operation not found. */ - NRF_MODEM_DECT_PHY_ERR_NO_ONGOING_OP = 0x3, + NRF_MODEM_DECT_PHY_ERR_NOT_FOUND = 0x3, /** * @brief Modem out of memory. */ @@ -135,6 +138,10 @@ enum nrf_modem_dect_phy_err { * @brief Operation not executed because combined operation failed. */ NRF_MODEM_DECT_PHY_ERR_COMBINED_OP_FAILED = 0x100A, + /** + * @brief Operation is not allowed in the current radio mode. + */ + NRF_MODEM_DECT_PHY_ERR_RADIO_MODE_CONFLICT = 0x100B, /** * @brief Unsupported carrier. */ @@ -159,6 +166,10 @@ enum nrf_modem_dect_phy_err { * @brief Invalid parameter. */ NRF_MODEM_DECT_PHY_ERR_INVALID_PARAMETER = 0x6005, + /** + * @brief TX power limit exceeded. + */ + NRF_MODEM_DECT_PHY_ERR_TX_POWER_OVER_MAX_LIMIT = 0x6006, /** * @brief Modem error. */ @@ -177,74 +188,6 @@ enum nrf_modem_dect_phy_err { NRF_MODEM_DECT_PHY_ERR_PROD_LOCK = 0x7003, }; -/** - * @brief Modem PHY configuration. - * - * Includes radio state transition latencies and operating temperature limit. - */ -struct nrf_modem_dect_phy_modem_cfg { - /** - * @brief Maximum operating temperature, in degrees Celsius. - * - * The minimum resolution is 1 degree Celsius. - */ - int16_t temperature_limit; - /** - * @brief Latency of radio state transitions, in modem time units. - */ - struct { - /** - * @brief From Idle to RSSI RF sampling start. - */ - uint32_t idle_to_rssi; - /** - * @brief From RF sampling of RSSI to Idle. - */ - uint32_t rssi_to_idle; - /** - * @brief From Idle to RX RF sampling start. - */ - uint32_t idle_to_rx; - /** - * @brief From RF sampling of RX to Idle. - */ - uint32_t rx_to_idle; - /** - * @brief From RF sampling of RX with RSSI measurement to Idle. - */ - uint32_t rx_rssi_to_idle; - /** - * @brief From RX stop request to RF sampling stop. - */ - uint32_t rx_stop_to_rf_off; - /** - * @brief From RX with RSSI measurement stop request to RF sampling stop. - */ - uint32_t rx_rssi_stop_to_rf_off; - /** - * @brief From Idle to TX RF sample transmission start. - */ - uint32_t idle_to_tx; - /** - * @brief From Idle to TX with LBT monitoring RF sampling start. - */ - uint32_t idle_to_tx_with_lbt; - /** - * @brief From TX RF sample transmission end (with or without LBT) to Idle. - */ - uint32_t tx_to_idle; - /** - * @brief From Idle to TX with LBT monitoring RF sampling start in TX-RX operation. - */ - uint32_t idle_to_txrx_with_lbt; - /** - * @brief From TX RF sample transmission end - * to RX RF sampling start in TX-RX operation. - */ - uint32_t txrx_tx_to_rx; - } latency; -}; - /** * @brief Modem PHY capabilities. */ @@ -261,10 +204,6 @@ struct nrf_modem_dect_phy_capability { * @brief Capability variants. */ struct { - /** - * @brief Power class. - */ - uint8_t power_class; /** * @brief Supported reception capability of spatial stream transmissions. */ @@ -273,10 +212,6 @@ struct nrf_modem_dect_phy_capability { * @brief Reception capability of TX diversity transmission. */ uint8_t rx_tx_diversity; - /** - * @brief Receiver sensitivity in dB. - */ - int8_t rx_gain; /** * @brief Maximum supported modulation and coding scheme for reception. */ @@ -304,6 +239,39 @@ struct nrf_modem_dect_phy_capability { } variant[]; }; +/** + * @brief Band information. + */ +struct nrf_modem_dect_phy_band { + /** + * @brief Band group index. + * + * Value 0 refers to RF frequencies operating near 2GHz and + * value 1 to RF frequencies near 1 GHz. + */ + uint8_t band_group_index; + /** + * @brief Band number. + */ + uint8_t band_number; + /** + * @brief Receiver sensitivity capability in dB. + */ + int8_t rx_gain; + /** + * @brief Power class. + */ + uint8_t power_class; + /** + * @brief Minimum carrier number. + */ + uint16_t min_carrier; + /** + * @brief Maximum carrier number. + */ + uint16_t max_carrier; +}; + /** * @brief Reception mode. */ @@ -351,7 +319,7 @@ enum nrf_modem_dect_phy_rssi_interval { /** * @brief Physical header type 1. * - * See 6.2 of [2]. + * See 6.2 in @ref DECT-SPEC "DECT-2020 NR Part 4". */ struct nrf_modem_dect_phy_hdr_type_1 { /** @@ -395,7 +363,7 @@ struct nrf_modem_dect_phy_hdr_type_1 { /** * @brief Feedback format types. * - * See 6.2.2 of [2]. + * See 6.2.2 in @ref DECT-SPEC "DECT-2020 NR Part 4". */ union nrf_modem_dect_phy_feedback { struct { @@ -451,10 +419,9 @@ union nrf_modem_dect_phy_feedback { /** * @brief Physical header type 2. * - * See 6.2 of [2]. + * See 6.2 in @ref DECT-SPEC "DECT-2020 NR Part 4". */ struct nrf_modem_dect_phy_hdr_type_2 { - /** * @brief Packet length in subslots or slots. */ @@ -568,8 +535,7 @@ enum nrf_modem_dect_phy_hdr_status { /** * @brief Radio link identifier. * - * Radio link identifier identifies a radio link using fields that are available in Physical Layer - * Control Field. + * Identifies a radio link using fields that are available in Physical Layer Control Field. */ struct nrf_modem_dect_phy_link_id { /** @@ -594,7 +560,7 @@ struct nrf_modem_dect_phy_link_id { * element value for the PCC to be accepted. PCC rejection will stop PDC reception and return * processing to synchronization search. * - * See 6.2.1 in @ref DECT-SPEC "DECT-2020 NR Part 4". + * See 6.2.1 in @ref DECT-SPEC "DECT-2020 NR Part 4". */ struct nrf_modem_dect_phy_rx_filter { /** @@ -626,155 +592,6 @@ struct nrf_modem_dect_phy_rx_filter { uint16_t receiver_identity; }; -/** - * @brief Reception parameters (PCC). - */ -struct nrf_modem_dect_phy_rx_pcc_status { - /** - * @brief Synchronization Training Field start time. - * - * Start time of the STF of this reception in modem time. - */ - uint64_t stf_start_time; - /** - * @brief Physical layer control field type. - * - * Valid values are 0 and 1 corresponding types 1 and 2, respectively. - * - * See 6.2.1 in @ref DECT-SPEC "DECT-2020 NR Part 4". - */ - uint8_t phy_type; - /** - * @brief Validity of the physical header. - */ - enum nrf_modem_dect_phy_hdr_status header_status; - /** - * @brief Received signal strength indicator (RSSI-2). - * - * Values are in dBm with 0.5 dBm resolution (Q14.1). - * - * See 8.3 in @ref DECT-SPEC "DECT-2020 NR Part 2". - */ - int16_t rssi_2; - /** - * @brief Received signal to noise indicator (SNR). - * - * Values are dB values with 0.25 dB resolution (Q13.2). - * - * See 8.4 in @ref DECT-SPEC "DECT-2020 NR Part 2". - */ - int16_t snr; -}; - -/** - * @brief Reception parameters (PDC). - */ -struct nrf_modem_dect_phy_rx_pdc_status { - /** - * @brief Received signal strength indicator (RSSI-2). - * - * Values are in dBm with 0.5 dBm resolution (Q14.1). - * - * See 8.3 in @ref DECT-SPEC "DECT-2020 NR Part 2". - */ - int16_t rssi_2; - /** - * @brief Received signal to noise indicator (SNR). - * - * Values are dB values with 0.25 dB resolution (Q13.2). - * - * See 8.4 in @ref DECT-SPEC "DECT-2020 NR Part 2". - */ - int16_t snr; -}; - -/** - * @brief Reception parameters for PCC CRC failures. - */ -struct nrf_modem_dect_phy_rx_pcc_crc_failure { - /** - * @brief Synchronization Training Field start time. - * - * Start time of the STF of this reception in modem time. - */ - uint64_t stf_start_time; - /** - * @brief Received signal strength indicator (RSSI-2). - * - * Values are in dBm with 0.5 dBm resolution (Q14.1). - * - * See 8.3 in @ref DECT-SPEC "DECT-2020 NR Part 2". - */ - int16_t rssi_2; - /** - * @brief Received signal to noise indicator (SNR). - * - * Values are dB values with 0.25 dB resolution (Q13.2). - * - * See 8.4 in @ref DECT-SPEC "DECT-2020 NR Part 2". - */ - int16_t snr; -}; - -/** - * @brief Reception parameters for PDC CRC failures. - */ -struct nrf_modem_dect_phy_rx_pdc_crc_failure { - /** - * @brief Received signal strength indicator (RSSI-2). - * - * Values are in dBm with 0.5 dBm resolution (Q14.1). - * - * If this value is not measured, it is reported as - * @ref NRF_MODEM_DECT_PHY_RSSI2_NOT_MEASURED. - * - * See 8.3 in @ref DECT-SPEC "DECT-2020 NR Part 2". - */ - int16_t rssi_2; - /** - * @brief Received signal to noise indicator (SNR). - * - * Values are dB values with 0.25 dB resolution (Q13.2). - * - * If this value is not measured, it is reported as - * @ref NRF_MODEM_DECT_PHY_SNR_NOT_MEASURED. - * - * See 8.4 in @ref DECT-SPEC "DECT-2020 NR Part 2". - */ - int16_t snr; -}; - -/** - * @brief RSSI measurement. - */ -struct nrf_modem_dect_phy_rssi_meas { - /** - * @brief Measurement start time, in modem time units. - */ - uint64_t meas_start_time; - /** - * @brief Handle of the operation. - */ - uint32_t handle; - /** - * @brief The absolute channel frequency number on which the measurements were made. - */ - uint16_t carrier; - /** - * @brief Number of measurements in @ref meas. - */ - uint16_t meas_len; - /** - * @brief RSSI measurements, in dBm. - * - * If a symbol is measured, its measurement is in the interval [-140, -1]. - * If the measurement is saturated, the measured signal strength is reported - * as a positive integer. If a symbol is not measured, its value is reported - * as @ref NRF_MODEM_DECT_PHY_RSSI_NOT_MEASURED. - */ - int8_t *meas; -}; - /** * @brief RX operation. */ @@ -788,7 +605,7 @@ struct nrf_modem_dect_phy_rx_params { */ uint64_t start_time; /** - * @brief Handle for the RX operation. + * @brief Handle for the operation. * * An application-defined handle for the operation. */ @@ -826,7 +643,7 @@ struct nrf_modem_dect_phy_rx_params { * signal level. * * If the duration of the RX operation is long enough to receive multiple slots, - * `rssi_level` will only be used for the first successful reception. Subsequent receptions + * this value will only be used for the first successful reception. Subsequent receptions * during the same RX operation are initiated using a level that has been adjusted based on * the previous successful reception (slow AGC). */ @@ -860,7 +677,7 @@ struct nrf_modem_dect_phy_tx_params { */ uint64_t start_time; /** - * @brief Handle for the TX operation. + * @brief Handle for the operation. * * An application-defined handle for the operation. */ @@ -908,21 +725,20 @@ struct nrf_modem_dect_phy_tx_params { /** * @brief Listen before talk period in modem time units. * - * The period that the channel needs to be measured "free" or "possible" before initiating - * transmission. - * - * The period is split into up to 64 individual integration periods, each period - * being an integer multiple of a symbol duration (2880 modem time units). All integration - * periods have the same length, maximum 7 symbols. The maximum number of integration - * periods is used. For example, LBT periods of up to 64 symbols will be split into one - * symbol long integration periods, and LBT periods of 65-128 symbols will be split into two - * symbol long integration periods. If necessary the LBT period may be shortened slightly - * to fit these constraints while still not exceeding the given LBT length, e.g. - * a period of 71 symbols will effectively be 70 symbols long (35 periods of 2 symbols). - * - * In case the channel is initially detected "busy" the modem will not continue measuring - * the channel. Instead the modem will report an error. Rescheduling a transmission is left - * up to the higher layer. + * This is the required duration for the channel to be assessed as "free" or "available" + * before starting transmission. This duration is divided into as many as 64 separate + * integration periods, with each period being a multiple of the symbol duration. + * Each integration period is of equal length, up to a maximum of 7 symbols. + * The maximum number of integration periods is utilized. For instance, LBT durations of + * up to 64 symbols are divided into integration periods of one symbol each, and + * LBT durations of 65-128 symbols are divided into two-symbol integration periods. + * The LBT duration may be adjusted slightly to meet these requirements without exceeding + * the specified LBT length, for example, a duration of 71 symbols would be adjusted to + * 70 symbols (35 periods of 2 symbols each). + * + * If the channel is initially found to be "busy," the modem will cease further measurement + * of the channel and will report an error instead. It is then the responsibility of the + * higher layer to reschedule the transmission. * * If set to zero, LBT is not used. Otherwise the acceptable value range is * [@ref NRF_MODEM_DECT_LBT_PERIOD_MIN, @ref NRF_MODEM_DECT_LBT_PERIOD_MAX]. @@ -982,7 +798,7 @@ struct nrf_modem_dect_phy_rssi_params { */ uint64_t start_time; /** - * @brief Handle for the RSSI operation. + * @brief Handle for the operation. * * An application-defined handle for the operation. */ @@ -1007,69 +823,256 @@ struct nrf_modem_dect_phy_rssi_params { }; /** - * @brief Link configuration parameters. + * @brief Radio modes. + * + * Different radio modes yield different performance and power consumption. */ -struct nrf_modem_dect_phy_link_config_params { +enum nrf_modem_dect_phy_radio_mode { /** - * @brief Primary link. + * @brief Low latency. * - * The modem tracks the frequency of the primary link for Automatic Frequency Control - * purposes. This frequency is propagated down the tree, that is, the Radio Device uses - * this frequency for all its radio operations except those directed to secondary links. + * This mode has the lowest latency, the best RX/TX switching performance, + * and the highest power consumption. This is the only mode that supports + * starting operations immediately, that is, operations whose configured + * start time is zero. */ - struct nrf_modem_dect_phy_link_id primary_link_id; + NRF_MODEM_DECT_PHY_RADIO_MODE_LOW_LATENCY, /** - * @brief Number of secondary links. + * @brief Low latency with standby. + * + * This mode has the same RX/TX switching performance as the low latency mode, + * but higher operation start-up latency due to radio entering standby mode + * when possible. Power consumption is thus lower compared to the low latency mode. */ - uint8_t secondary_link_count; + NRF_MODEM_DECT_PHY_RADIO_MODE_LOW_LATENCY_WITH_STANDBY, /** - * @brief Secondary links. + * @brief Listen-before-talk disabled, with standby. * - * The modem tracks the frequency of secondary links for Automatic Frequency Control - * purposes. When communicating with a secondary link the modem compensates the frequency - * difference between the secondary link and the primary link. + * This mode has the lowest power consumption, due the to modem entering + * standby mode when possible and not using Listen-Before-Talk, at the cost + * of higher start-up latency and worse RX/TX switching performance compared + * to the other radio modes. */ - struct nrf_modem_dect_phy_link_id secondary_link_ids[]; + NRF_MODEM_DECT_PHY_RADIO_MODE_NON_LBT_WITH_STANDBY, + /** + * @brief Number of radio modes available. + */ + NRF_MODEM_DECT_PHY_RADIO_MODE_COUNT, }; /** - * @brief DECT PHY callbacks. - * - * Callbacks for user operations and incoming data. - * - * @note - * All callbacks are executed in ISR. + * @brief Radio configuration operation. */ -struct nrf_modem_dect_phy_callbacks { +struct nrf_modem_dect_phy_radio_config_params { /** - * @brief DECT PHY initialization callback. + * @brief Operation start time as modem time. * - * The @p err parameter indicates the result of the operation. - * It can be one of the following values: + * If zero, the operation will be executed immediately. * - * - @ref NRF_MODEM_DECT_PHY_SUCCESS - * - @ref NRF_MODEM_DECT_PHY_ERR_NOT_ALLOWED - * - @ref NRF_MODEM_DECT_PHY_ERR_TEMP_HIGH - * - @ref NRF_MODEM_DECT_PHY_ERR_PROD_LOCK + * This kind of scheduling can only be done when the modem is idle. + */ + uint64_t start_time; + /** + * @brief Handle for the operation. * - * @param[in] time Modem time, in modem time units. - * @param temp Temperature in degrees Celsius. - * @param err Operation result. - * @param[in] cfg Modem configuration. + * An application-defined handle for the operation. */ - void (*init)(const uint64_t *time, int16_t temp, enum nrf_modem_dect_phy_err err, - const struct nrf_modem_dect_phy_modem_cfg *cfg); + uint32_t handle; + /** + * @brief Desired radio mode. + */ + enum nrf_modem_dect_phy_radio_mode radio_mode; +}; +/** + * @brief DECT PHY latency information. + * + * Includes radio state transition and configuration latencies. + */ +struct nrf_modem_dect_phy_latency_info { /** - * @brief Callback to indicate the completion of RX, TX and RSSI measurement operations. - * - * The @p err parameter indicates the result of the operation. - * It can be one of the following values: + * @brief Radio mode specific latencies. * - * - @ref NRF_MODEM_DECT_PHY_SUCCESS - * - @ref NRF_MODEM_DECT_PHY_ERR_LBT_CHANNEL_BUSY - * - @ref NRF_MODEM_DECT_PHY_ERR_NO_MEMORY - * - @ref NRF_MODEM_DECT_PHY_ERR_NOT_ALLOWED + * These latencies must be used according to the currently active radio mode + * and operation type (immediate or scheduled). + */ + struct { + /** + * @brief Scheduled operation transition delay. + * + * The delay between transitioning from one scheduled operation to the next. + * + * The start time of a scheduled operation must account for the start time + * of the previous operation, plus its duration, plus the operation + * transition delay in the current radio mode. + */ + uint32_t scheduled_operation_transition; + /** + * @brief Additional delay for scheduled operations. + * + * Used together with the values in @ref operation to calculate the total + * operation start latency for scheduled operations. + */ + uint32_t scheduled_operation_startup; + /** + * @brief Delay in transitioning from one radio mode to another. + */ + uint32_t radio_mode_transition[NRF_MODEM_DECT_PHY_RADIO_MODE_COUNT]; + } radio_mode[NRF_MODEM_DECT_PHY_RADIO_MODE_COUNT]; + + /** + * @brief Duration of radio state transitions. + * + * Immediate operations can use these values directly. + * Scheduled operations must account for this value plus the value + * of @ref scheduled_operation_startup. + */ + struct { + struct { + /** + * @brief Receive operation start latency (IDLE to RF ON). + */ + uint32_t idle_to_active; + /** + * @brief RSSI operation end latency (RF OFF to IDLE). + */ + uint32_t active_to_idle_rssi; + /** + * @brief RX operation end latency (RF OFF to IDLE). + */ + uint32_t active_to_idle_rx; + /** + * @brief RX with RSSI operation end latency (RF OFF to IDLE). + */ + uint32_t active_to_idle_rx_rssi; + /** + * @brief Operation stop latency (STOP_REQ to RF OFF). + */ + uint32_t stop_to_rf_off; + } receive; + struct { + /** + * @brief Transmit operation start latency (IDLE to RF ON). + */ + uint32_t idle_to_active; + /** + * @brief Transmit operation end latency (RF OFF to IDLE). + */ + uint32_t active_to_idle; + } transmit; + } operation; + + /** + * @brief Duration of DECT PHY stack operations. + */ + struct { + /** + * @brief Duration of DECT PHY stack initialization. + * + * Duration of @ref nrf_modem_dect_phy_init(). + */ + uint32_t initialization; + /** + * @brief Duration of DECT PHY stack deinitialization. + * + * Duration of @ref nrf_modem_dect_phy_deinit(). + */ + uint32_t deinitialization; + /** + * @brief Duration of DECT PHY stack configuration. + * + * Duration of @ref nrf_modem_dect_phy_configure(). + */ + uint32_t configuration; + /** + * @brief Duration of DECT PHY stack activation. + * + * Duration of @ref nrf_modem_dect_phy_activate(). + */ + uint32_t activation; + /** + * @brief Duration of DECT PHY stack deactivation. + * + * Duration of @ref nrf_modem_dect_phy_deactivate(). + */ + uint32_t deactivation; + } stack; +}; + +/** + * @brief Link configuration parameters. + */ +struct nrf_modem_dect_phy_link_config_params { + /** + * @brief Primary link. + * + * The modem tracks the frequency of the primary link for Automatic Frequency Control + * purposes. This frequency is propagated down the tree, that is, the Radio Device uses + * this frequency for all its radio operations except those directed to secondary links. + */ + struct nrf_modem_dect_phy_link_id primary_link_id; + /** + * @brief Number of secondary links. + */ + uint8_t secondary_link_count; + /** + * @brief Secondary links. + * + * The modem tracks the frequency of secondary links for Automatic Frequency Control + * purposes. When communicating with a secondary link the modem compensates the frequency + * difference between the secondary link and the primary link. + */ + struct nrf_modem_dect_phy_link_id secondary_link_ids[]; +}; + +/** Events */ + +/** + * @brief Initialization event. + */ +struct nrf_modem_dect_phy_init_event { + /** + * @brief Operation result. + * + * Can be one of the following values: + * + * - @ref NRF_MODEM_DECT_PHY_SUCCESS + * - @ref NRF_MODEM_DECT_PHY_ERR_NOT_ALLOWED + * - @ref NRF_MODEM_DECT_PHY_ERR_TEMP_HIGH + * - @ref NRF_MODEM_DECT_PHY_ERR_PROD_LOCK + */ + enum nrf_modem_dect_phy_err err; + /** + * @brief Temperature in degrees Celsius. + */ + int16_t temp; + /** + * @brief Voltage in millivolts. + */ + uint16_t voltage; + /** + * @brief Operating temperature limit, in degrees Celsius. + */ + uint16_t temperature_limit; +}; + +/** + * @brief Operation complete event. + */ +struct nrf_modem_dect_phy_op_complete_event { + /** + * @brief Handle of the operation. + */ + uint32_t handle; + /** + * @brief Operation result. + * + * Can be one of the following values: + * + * - @ref NRF_MODEM_DECT_PHY_SUCCESS + * - @ref NRF_MODEM_DECT_PHY_ERR_LBT_CHANNEL_BUSY + * - @ref NRF_MODEM_DECT_PHY_ERR_NO_MEMORY + * - @ref NRF_MODEM_DECT_PHY_ERR_NOT_ALLOWED * - @ref NRF_MODEM_DECT_PHY_OK_WITH_HARQ_RESET * - @ref NRF_MODEM_DECT_PHY_ERR_OP_START_TIME_LATE * - @ref NRF_MODEM_DECT_PHY_ERR_LBT_START_TIME_LATE @@ -1089,163 +1092,574 @@ struct nrf_modem_dect_phy_callbacks { * - @ref NRF_MODEM_DECT_PHY_ERR_INVALID_DURATION * - @ref NRF_MODEM_DECT_PHY_ERR_INVALID_PARAMETER * - @ref NRF_MODEM_DECT_PHY_ERR_TEMP_HIGH - * - * @param[in] time Modem time, in modem time units. - * @param temp Temperature in degrees Celsius. - * @param err Operation result. - * @param handle Operation handle. */ - void (*op_complete)(const uint64_t *time, int16_t temperature, - enum nrf_modem_dect_phy_err err, uint32_t handle); + enum nrf_modem_dect_phy_err err; + /** + * @brief Temperature in degrees Celsius. + */ + int16_t temp; + /** + * @brief Voltage in millivolts. + */ + uint16_t voltage; +}; +/** + * @brief RSSI measurement event. + */ +struct nrf_modem_dect_phy_rssi_event { /** - * @brief Callback to receive RSSI measurements. - * - * Callback function to receive the RSSI measurements requested - * with @ref nrf_modem_dect_phy_rssi or @ref nrf_modem_dect_phy_rx. + * @brief Handle of the operation. + */ + uint32_t handle; + /** + * @brief Measurement start time, in modem time units. + */ + uint64_t meas_start_time; + /** + * @brief The absolute channel frequency number on which the measurements were made. + */ + uint16_t carrier; + /** + * @brief Number of measurements in @ref meas. + */ + uint16_t meas_len; + /** + * @brief RSSI measurements, in dBm. * - * @param[in] time Modem time, in modem time units. - * @param[in] meas RSSI measurement. + * If a symbol is measured, its measurement is in the interval [-140, -1]. + * If the measurement is saturated, the measured signal strength is reported + * as a positive integer. If a symbol is not measured, its value is reported + * as @ref NRF_MODEM_DECT_PHY_RSSI_NOT_MEASURED. */ - void (*rssi)(const uint64_t *time, const struct nrf_modem_dect_phy_rssi_meas *meas); + int8_t *meas; +}; +struct nrf_modem_dect_phy_cancel_event { /** - * @brief Callback for @ref nrf_modem_dect_phy_rx_stop. + * @brief Handle of the operation. + */ + uint32_t handle; + /** + * @brief Operation result. * - * When an RX operation is stopped, the operation complete callback will be called - * once the operation has fully stopped. That is, it is possible that the - * operation hasn't been fully stopped at the time this callback is called. - - * The @p err parameter indicates the result of the operation. - * It can be one of the following values: + * Can be one of the following values: * * - @ref NRF_MODEM_DECT_PHY_SUCCESS * - @ref NRF_MODEM_DECT_PHY_ERR_UNSUPPORTED_OP - * - @ref NRF_MODEM_DECT_PHY_ERR_NO_ONGOING_OP + * - @ref NRF_MODEM_DECT_PHY_ERR_NOT_FOUND * - @ref NRF_MODEM_DECT_PHY_ERR_NOT_ALLOWED + */ + enum nrf_modem_dect_phy_err err; +}; + +/** + * @brief PCC reception event. + */ +struct nrf_modem_dect_phy_pcc_event { + /** + * @brief Synchronization Training Field start time. + * + * Start time of the STF of this reception in modem time. + */ + uint64_t stf_start_time; + /** + * @brief Handle for the operation. + */ + uint32_t handle; + /** + * @brief Validity of the physical header. + */ + enum nrf_modem_dect_phy_hdr_status header_status; + /** + * @brief Physical layer control field type. + * + * Valid values are 0 and 1 corresponding types 1 and 2, respectively. + * + * See 6.2.1 in @ref DECT-SPEC "DECT-2020 NR Part 4". + */ + uint8_t phy_type; + /** + * @brief PHY header. + */ + union nrf_modem_dect_phy_hdr hdr; + /** + * @brief Received signal strength indicator (RSSI-2). + * + * Values are in dBm with 0.5 dBm resolution (Q14.1). + * + * See 8.3 in @ref DECT-SPEC "DECT-2020 NR Part 2". + */ + int16_t rssi_2; + /** + * @brief Received signal to noise indicator (SNR). + * + * Values are dB values with 0.25 dB resolution (Q13.2). + * + * See 8.4 in @ref DECT-SPEC "DECT-2020 NR Part 2". + */ + int16_t snr; + /** + * @brief Transaction ID. * - * @param[in] time Modem time, in modem time units. - * @param err Operation result. - * @param handle Operation handle. + * Used to map PCC data with corresponding PDC data. */ - void (*rx_stop)(const uint64_t *time, enum nrf_modem_dect_phy_err err, uint32_t handle); + uint16_t transaction_id; +}; +/** + * @brief PCC reception CRC failure event. + */ +struct nrf_modem_dect_phy_pcc_crc_failure_event { + /** + * @brief Synchronization Training Field start time. + * + * Start time of the STF of this reception in modem time. + */ + uint64_t stf_start_time; + /** + * @brief Handle for the operation. + */ + uint32_t handle; + /** + * @brief Received signal strength indicator (RSSI-2). + * + * Values are in dBm with 0.5 dBm resolution (Q14.1). + * + * See 8.3 in @ref DECT-SPEC "DECT-2020 NR Part 2". + */ + int16_t rssi_2; /** - * @brief Callback for control channel reception. + * @brief Received signal to noise indicator (SNR). + * + * Values are dB values with 0.25 dB resolution (Q13.2). * - * @param[in] time Modem time, in modem time units. - * @param status Reception data. - * @param[in] hdr Physical layer control header. + * See 8.4 in @ref DECT-SPEC "DECT-2020 NR Part 2". */ - void (*pcc)(const uint64_t *time, const struct nrf_modem_dect_phy_rx_pcc_status *status, - const union nrf_modem_dect_phy_hdr *hdr); + int16_t snr; + /** + * @brief Transaction ID. + * + * Used to map PCC data with corresponding PDC data. + */ + uint16_t transaction_id; +}; + +/** + * @brief PDC reception event. + */ +struct nrf_modem_dect_phy_pdc_event { + /** + * @brief Handle for the operation. + */ + uint32_t handle; + /** + * @brief Received signal strength indicator (RSSI-2). + * + * Values are in dBm with 0.5 dBm resolution (Q14.1). + * + * See 8.3 in @ref DECT-SPEC "DECT-2020 NR Part 2". + */ + int16_t rssi_2; + /** + * @brief Received signal to noise indicator (SNR). + * + * Values are dB values with 0.25 dB resolution (Q13.2). + * + * See 8.4 in @ref DECT-SPEC "DECT-2020 NR Part 2". + */ + int16_t snr; + /** + * @brief Transaction ID. + * + * Used to map PCC data with corresponding PDC data. + */ + uint16_t transaction_id; + /** + * @brief Received data payload. + */ + void *data; + /** + * @brief Data payload length, in bytes. + */ + size_t len; +}; +/** + * @brief PDC CRC failure event. + */ +struct nrf_modem_dect_phy_pdc_crc_failure_event { + /** + * @brief Handle for the operation. + */ + uint32_t handle; + /** + * @brief Received signal strength indicator (RSSI-2). + * + * Values are in dBm with 0.5 dBm resolution (Q14.1). + * + * If this value is not measured, it is reported as + * @ref NRF_MODEM_DECT_PHY_RSSI2_NOT_MEASURED. + * + * See 8.3 in @ref DECT-SPEC "DECT-2020 NR Part 2". + */ + int16_t rssi_2; /** - * @brief Callback for CRC failures on the physical control channel. + * @brief Received signal to noise indicator (SNR). + * + * Values are dB values with 0.25 dB resolution (Q13.2). * - * @param[in] time Modem time, in modem time units. - * @param[in] crc_failure CRC failure information. + * If this value is not measured, it is reported as + * @ref NRF_MODEM_DECT_PHY_SNR_NOT_MEASURED. + * + * See 8.4 in @ref DECT-SPEC "DECT-2020 NR Part 2". */ - void (*pcc_crc_err)(const uint64_t *time, - const struct nrf_modem_dect_phy_rx_pcc_crc_failure *crc_failure); + int16_t snr; + /** + * @brief Transaction ID. + * + * Used to map PCC data with corresponding PDC data. + */ + uint16_t transaction_id; +}; +/** + * @brief DECT PHY stack configuration event. + */ +struct nrf_modem_dect_phy_configure_event { /** - * @brief Callback for data channel reception. + * @brief Operation result. * - * @param[in] time Modem time, in modem time units. - * @param status Reception data. - * @param[in] data Data received. - * @param len Size of received data. + * Can be one of the following values: + * + * - @ref NRF_MODEM_DECT_PHY_SUCCESS + * - @ref NRF_MODEM_DECT_PHY_ERR_NOT_ALLOWED + * - @ref NRF_MODEM_DECT_PHY_ERR_INVALID_PARAMETER + */ + enum nrf_modem_dect_phy_err err; + /** + * @brief Temperature in degrees Celsius. + */ + int16_t temp; + /** + * @brief Voltage in millivolts. */ - void (*pdc)(const uint64_t *time, const struct nrf_modem_dect_phy_rx_pdc_status *status, - const void *data, uint32_t len); + uint16_t voltage; +}; +/** + * @brief Radio configuration event. + */ +struct nrf_modem_dect_phy_radio_config_event { + /** + * @brief Handle of the operation. + */ + uint32_t handle; /** - * @brief Callback for CRC failures on the physical data channel. + * @brief Operation result. * - * @param[in] time Modem time, in modem time units. - * @param[in] crc_failure CRC failure information. + * Can be one of the following values: + * + * - @ref NRF_MODEM_DECT_PHY_SUCCESS */ - void (*pdc_crc_err)(const uint64_t *time, - const struct nrf_modem_dect_phy_rx_pdc_crc_failure *crc_failure); + enum nrf_modem_dect_phy_err err; +}; +struct nrf_modem_dect_phy_link_config_event { /** - * @brief Callback for @ref nrf_modem_dect_phy_link_config. + * @brief Operation result. * - * The @p err parameter indicates the result of the operation. - * It can be one of the following values: + * Can be one of the following values: * * - @ref NRF_MODEM_DECT_PHY_SUCCESS * - @ref NRF_MODEM_DECT_PHY_ERR_NO_MEMORY * - @ref NRF_MODEM_DECT_PHY_ERR_NOT_ALLOWED * - @ref NRF_MODEM_DECT_PHY_ERR_INVALID_PARAMETER - * - * @param[in] time Modem time, in modem time units. - * @param err Operation result. */ - void (*link_config)(const uint64_t *time, enum nrf_modem_dect_phy_err err); + enum nrf_modem_dect_phy_err err; +}; +/** + * @brief Time get event. + */ +struct nrf_modem_dect_phy_time_get_event { /** - * @brief Callback for @ref nrf_modem_dect_phy_time_get. + * @brief Operation result. * - * The @p err parameter indicates the result of the operation. - * It can be one of the following values: + * Can be one of the following values: * * - @ref NRF_MODEM_DECT_PHY_SUCCESS + */ + enum nrf_modem_dect_phy_err err; +}; + +/** + * @brief Capability get event. + */ +struct nrf_modem_dect_phy_capability_get_event { + /** + * @brief Operation result. + * + * Can be one of the following values: * - * @param[in] time Modem time, in modem time units. - * @param err Operation result. + * - @ref NRF_MODEM_DECT_PHY_SUCCESS + */ + enum nrf_modem_dect_phy_err err; + /** + * @brief PHY capability. */ - void (*time_get)(const uint64_t *time, enum nrf_modem_dect_phy_err err); + struct nrf_modem_dect_phy_capability *capability; +}; +/** + * @brief Band information event. + */ +struct nrf_modem_dect_phy_band_get_event { /** - * @brief Callback for @ref nrf_modem_dect_phy_capability_get. + * @brief Operation result. * - * The @p err parameter indicates the result of the operation. - * It can be one of the following values: + * Can be one of the following values: * * - @ref NRF_MODEM_DECT_PHY_SUCCESS + */ + enum nrf_modem_dect_phy_err err; + /** + * @brief Supported bands as a bitmap. + */ + uint32_t supported_bands; + /** + * @brief Number of elements in @c band. + */ + uint32_t band_count; + /** + * @brief Band information. + */ + struct nrf_modem_dect_phy_band *band; +}; + +/** + * @brief STF cover sequence control event. + */ +struct nrf_modem_dect_phy_stf_control_event { + /** + * @brief Operation result. + * + * Can be one of the following values: * - * @param[in] time Modem time, in modem time units. - * @param err Operation result. - * @param[in] capability PHY capabilities. + * - @ref NRF_MODEM_DECT_PHY_SUCCESS + * - @ref NRF_MODEM_DECT_PHY_ERR_NOT_ALLOWED */ - void (*capability_get)(const uint64_t *time, enum nrf_modem_dect_phy_err err, - const struct nrf_modem_dect_phy_capability *capability); + enum nrf_modem_dect_phy_err err; +}; +/** + * @brief Deinitialization event. + */ +struct nrf_modem_dect_phy_deinit_event { /** - * @brief Callback for @ref nrf_modem_dect_phy_stf_cover_seq_control. + * @brief Operation result. * - * The @p err parameter indicates the result of the operation. - * It can be one of the following values: + * Can be one of the following values: * * - @ref NRF_MODEM_DECT_PHY_SUCCESS * - @ref NRF_MODEM_DECT_PHY_ERR_NOT_ALLOWED + */ + enum nrf_modem_dect_phy_err err; +}; + +/** + * @brief Activation event. + */ +struct nrf_modem_dect_phy_activate_event { + /** + * @brief Operation result. * - * @param[in] time Modem time, in modem time units. - * @param err Operation result. + * Can be one of the following values: + * + * - @ref NRF_MODEM_DECT_PHY_SUCCESS + * - @ref NRF_MODEM_DECT_PHY_ERR_NOT_ALLOWED + */ + enum nrf_modem_dect_phy_err err; + /** + * @brief Temperature in degrees Celsius. + */ + int16_t temp; + /** + * @brief Voltage in millivolts. */ - void (*stf_cover_seq_control)(const uint64_t *time, enum nrf_modem_dect_phy_err err); + uint16_t voltage; +}; +/** + * @brief Deactivation event. + */ +struct nrf_modem_dect_phy_deactivate_event { /** - * @brief Callback for @ref nrf_modem_dect_phy_deinit. + * @brief Operation result. * - * The @p err parameter indicates the result of the operation. - * It can be one of the following values: + * Can be one of the following values: * * - @ref NRF_MODEM_DECT_PHY_SUCCESS * - @ref NRF_MODEM_DECT_PHY_ERR_NOT_ALLOWED + */ + enum nrf_modem_dect_phy_err err; +}; + +/** + * @brief Latency event. + */ +struct nrf_modem_dect_phy_latency_info_event { + /** + * @brief Operation result. + * + * Can be one of the following values: * - * @param[in] time Modem time, in modem time units. - * @param err Operation result. + * - @ref NRF_MODEM_DECT_PHY_SUCCESS + * - @ref NRF_MODEM_DECT_PHY_ERR_NOT_ALLOWED + */ + enum nrf_modem_dect_phy_err err; + /** + * @brief PHY latency info. + */ + struct nrf_modem_dect_phy_latency_info *latency_info; +}; + +enum nrf_modem_dect_phy_event_id { + /** + * @brief Event to indicate the completion of the DECT PHY stack initialization. + */ + NRF_MODEM_DECT_PHY_EVT_INIT, + /** + * @brief Event to indicate the completion of the DECT PHY stack deinitialization. + */ + NRF_MODEM_DECT_PHY_EVT_DEINIT, + /** + * @brief Event to indicate the completion of the DECT PHY stack configuration. */ - void (*deinit)(const uint64_t *time, enum nrf_modem_dect_phy_err err); + NRF_MODEM_DECT_PHY_EVT_CONFIGURE, + /** + * @brief Event to indicate the completion of radio mode configuration. + */ + NRF_MODEM_DECT_PHY_EVT_RADIO_CONFIG, + /** + * @brief Event to indicate the completion of the DECT PHY stack activation. + */ + NRF_MODEM_DECT_PHY_EVT_ACTIVATE, + /** + * @brief Event to indicate the completion of the DECT PHY stack deactivation. + */ + NRF_MODEM_DECT_PHY_EVT_DEACTIVATE, + /** + * @brief Event to indicate the completion of RX, TX and RSSI measurement operations. + */ + NRF_MODEM_DECT_PHY_EVT_COMPLETED, + /** + * @brief Event to indicate the cancellation of an operation. + */ + NRF_MODEM_DECT_PHY_EVT_CANCELED, + /** + * @brief Event carrying RSSI measurements. + */ + NRF_MODEM_DECT_PHY_EVT_RSSI, + /** + * @brief Event for control channel reception. + */ + NRF_MODEM_DECT_PHY_EVT_PCC, + /** + * @brief Event for CRC failures on the physical control channel. + */ + NRF_MODEM_DECT_PHY_EVT_PCC_ERROR, + /** + * @brief Event for data channel reception. + */ + NRF_MODEM_DECT_PHY_EVT_PDC, + /** + * @brief Event for CRC failures on the physical data channel. + */ + NRF_MODEM_DECT_PHY_EVT_PDC_ERROR, + /** + * @brief Event carrying modem time. + */ + NRF_MODEM_DECT_PHY_EVT_TIME, + /** + * @brief Event carrying capabilities. + */ + NRF_MODEM_DECT_PHY_EVT_CAPABILITY, + /** + * @brief Event carrying band information. + */ + NRF_MODEM_DECT_PHY_EVT_BANDS, + /** + * @brief Event carrying latency information. + */ + NRF_MODEM_DECT_PHY_EVT_LATENCY, + /** + * @brief Event to indicate the completion of link configuration. + */ + NRF_MODEM_DECT_PHY_EVT_LINK_CONFIG, + /** + * @brief Event to indicate the completion of STF configuration. + */ + NRF_MODEM_DECT_PHY_EVT_STF_CONFIG, +}; + +/** + * @brief DECT PHY event. + */ +struct nrf_modem_dect_phy_event { + /** + * @brief Event ID. + */ + enum nrf_modem_dect_phy_event_id id; + /** + * @brief Modem time, in modem time units. + */ + uint64_t time; + /** + * @brief Event data. + */ + union { + struct nrf_modem_dect_phy_init_event init; + struct nrf_modem_dect_phy_deinit_event deinit; + struct nrf_modem_dect_phy_activate_event activate; + struct nrf_modem_dect_phy_deactivate_event deactivate; + struct nrf_modem_dect_phy_configure_event configure; + struct nrf_modem_dect_phy_radio_config_event radio_config; + struct nrf_modem_dect_phy_op_complete_event op_complete; + struct nrf_modem_dect_phy_rssi_event rssi; + struct nrf_modem_dect_phy_cancel_event cancel; + struct nrf_modem_dect_phy_pcc_event pcc; + struct nrf_modem_dect_phy_pcc_crc_failure_event pcc_crc_err; + struct nrf_modem_dect_phy_pdc_event pdc; + struct nrf_modem_dect_phy_pdc_crc_failure_event pdc_crc_err; + struct nrf_modem_dect_phy_time_get_event time_get; + struct nrf_modem_dect_phy_capability_get_event capability_get; + struct nrf_modem_dect_phy_band_get_event band_get; + struct nrf_modem_dect_phy_latency_info_event latency_get; + struct nrf_modem_dect_phy_stf_control_event stf_cover_seq_control; + struct nrf_modem_dect_phy_link_config_event link_config; + }; }; /** - * @brief Configuration for DECT PHY interface. + * @brief DECT PHY configuration parameters. */ -struct nrf_modem_dect_phy_init_params { +struct nrf_modem_dect_phy_config_params { + /** + * @brief Band group index. + * + * Allowed values: 0 or 1. + * Value 0 refers to RF frequencies operating near 2GHz and + * value 1 to RF frequencies near 1 GHz. + */ + uint8_t band_group_index; + /** + * @brief Number of HARQ processes. + * + * The HARQ reception buffer is divided equally between processes. + * Supported values: 1, 2, 4, 8. + */ + uint8_t harq_rx_process_count; /** * @brief HARQ RX buffer expiry time, in microseconds. * @@ -1255,113 +1669,119 @@ struct nrf_modem_dect_phy_init_params { * Maximum supported value: 5000000. */ uint32_t harq_rx_expiry_time_us; - struct { - /** - * @brief Number of HARQ processes. - * - * The HARQ reception buffer is divided equally between processes. - * Supported values: 1, 2, 4, 8. - */ - uint8_t harq_rx_process_count : 4; - /** - * @brief Reserved for future use. - */ - uint8_t reserved : 3; - /** - * @brief Band 4 support. - * - * 1 - Enables band 4 operation. - * 0 - Disables band 4 operation. - * - * Band 4 support is only available for nRF9151 devices. - * - * @warning - * When operating on band 4, carriers outside the [525, 551] range - * shall not be used as they interfere with other radio devices, - * including LTE devices, car keys, and others. - * - * @note - * Band 4 support may only be toggled when de-initialized. - * Toggling band 4 support when already initialized is not supported. - */ - uint8_t band4_support : 1; - }; }; /** - * @brief Set application callbacks for PHY operations. + * @brief Application handler prototype for PHY events. + */ +typedef void (*nrf_modem_dect_phy_event_handler_t)(const struct nrf_modem_dect_phy_event *event); + +/** + * @brief Set the application event handler for PHY events. * - * The application must set the callbacks for PHY operations before attempting other operations. - * That includes PHY initialization itself, that is, nrf_modem_dect_phy_init(). + * The application must set the handler for events coming the DECT PHY before attempting + * other operations. * - * @param cb Application callbacks. + * @param handler Event handler. * * @return 0 On success. - * @retval -NRF_EFAULT @p cb is @c NULL. - * @retval -NRF_EINVAL One of the fields in @p cb is @c NULL. + * @retval -NRF_EFAULT @p handler is @c NULL. */ -int nrf_modem_dect_phy_callback_set(const struct nrf_modem_dect_phy_callbacks *cb); +int nrf_modem_dect_phy_event_handler_set(nrf_modem_dect_phy_event_handler_t handler); /** * @brief Retrieve DECT PHY capabilities. * - * This operation is asynchronous. The result of the operation is sent to the - * @ref nrf_modem_dect_phy_callbacks.capability_get callback. + * This operation is performed asynchronously. + * Completion of this operation is indicated by the @ref NRF_MODEM_DECT_PHY_EVT_CAPABILITY event. * * @return 0 On success. * @retval -NRF_EPERM The Modem library is not initialized. - * @retval -NRF_EFAULT Callback configuration is invalid. + * @retval -NRF_EFAULT No event handler is set. * @retval -NRF_ENOMEM Not enough shared memory for this request. */ int nrf_modem_dect_phy_capability_get(void); /** - * @brief Initialize DECT PHY interface. + * @brief Initialize the DECT PHY interface. * - * This operation is asynchronous. The result of the operation is sent to the - * @ref nrf_modem_dect_phy_callbacks.init callback. + * Initialize the DECT PHY interface and associated hardware resources. * - * @param[in] params Configuration parameters. + * This operation is performed asynchronously. + * Completion of this operation is indicated by the @ref NRF_MODEM_DECT_PHY_EVT_INIT event. * * @retval 0 Request was sent to modem. * @retval -NRF_EPERM The Modem library is not initialized. - * @retval -NRF_EFAULT Callback configuration is invalid, or @p params is @c NULL. + * @retval -NRF_EFAULT No event handler is set. * @retval -NRF_ENOMEM Not enough shared memory for this request. */ -int nrf_modem_dect_phy_init(const struct nrf_modem_dect_phy_init_params *params); +int nrf_modem_dect_phy_init(void); /** - * @brief De-initialize DECT PHY interface. + * @brief Deinitialize the DECT PHY interface. * - * Cancel all operations and de-initialize the PHY. + * Deinitialize the DECT PHY interface and all associated hardware resources. + * This implicitly cancels all operations, both executing or scheduled for execution. * - * This operation is asynchronous. The result of the operation is sent to the - * @ref nrf_modem_dect_phy_callbacks.deinit callback. + * This operation is performed asynchronously. + * Completion of this operation is indicated by the @ref NRF_MODEM_DECT_PHY_EVT_DEINIT event. * * @retval 0 Request was sent to modem. * @retval -NRF_EPERM The Modem library is not initialized. - * @retval -NRF_EFAULT Callback configuration is invalid. + * @retval -NRF_EFAULT No event handler is set. * @retval -NRF_ENOMEM Not enough shared memory for this request. */ int nrf_modem_dect_phy_deinit(void); +/** + * @brief Activate the DECT PHY software stack in given radio mode. + * + * Before each activation, the DECT PHY software stack must be configured using + * @ref nrf_modem_dect_phy_configure. + * + * This operation is performed asynchronously. + * Completion of this operation is indicated by the @ref NRF_MODEM_DECT_PHY_EVT_ACTIVATE event. + * + * @param mode Desired radio mode. + * + * @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_phy_activate(enum nrf_modem_dect_phy_radio_mode mode); + +/** + * @brief Deactivate the DECT PHY software stack. + * + * Deactivation implicitly cancels all operations, both executing or scheduled for execution. + * + * This operation is performed asynchronously. + * Completion of this operation is indicated by the @ref NRF_MODEM_DECT_PHY_EVT_DEACTIVATE 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_phy_deactivate(void); + /** * @brief Schedule a reception. * - * Schedule a continuous, semicontinuous or single shot reception at a given time, with parameters. + * Schedule a reception with given parameters. * - * Incoming data received on the physical layer control and data channels is sent to the - * @ref nrf_modem_dect_phy_callbacks.pcc and @ref nrf_modem_dect_phy_callbacks.pdc callbacks. + * This operation is performed asynchronously. + * Completion of this operation is indicated by the @ref NRF_MODEM_DECT_PHY_EVT_COMPLETED event. * - * When the operation has completed, either successfully or unsuccessfully, the result is sent - * to the @ref nrf_modem_dect_phy_callbacks.op_complete callback, with a `handle` - * parameter equal to the `handle` specified in @p params. + * Data received on the physical layer control and data channels is sent to the application + * in the @ref NRF_MODEM_DECT_PHY_EVT_PCC and @ref NRF_MODEM_DECT_PHY_EVT_PDC events respectively. * * @param[in] params Operation parameters. * * @retval 0 Request was sent to modem. * @retval -NRF_EPERM The Modem library is not initialized. - * @retval -NRF_EFAULT Callback configuration is invalid, or @p params is @c NULL. + * @retval -NRF_EFAULT No event handler is set, or @p params is @c NULL. * @retval -NRF_ENOMEM Not enough shared memory for this request. */ int nrf_modem_dect_phy_rx(const struct nrf_modem_dect_phy_rx_params *params); @@ -1371,15 +1791,14 @@ int nrf_modem_dect_phy_rx(const struct nrf_modem_dect_phy_rx_params *params); * * Schedule a data transmission with given parameters. * - * When the operation has completed, either successfully or unsuccessfully, the result is sent - * to the @ref nrf_modem_dect_phy_callbacks.op_complete callback, with a `handle` - * parameter equal to the `handle` specified in @p params. + * This operation is performed asynchronously. + * Completion of this operation is indicated by the @ref NRF_MODEM_DECT_PHY_EVT_COMPLETED event. * * @param[in] params Operation parameters. * * @retval 0 Request was sent to modem. * @retval -NRF_EPERM The Modem library is not initialized. - * @retval -NRF_EFAULT Callback configuration is invalid, or @p params is @c NULL. + * @retval -NRF_EFAULT No event handler is set, or @p params is @c NULL. * @retval -NRF_ENOMEM Not enough shared memory for this request. */ int nrf_modem_dect_phy_tx(const struct nrf_modem_dect_phy_tx_params *params); @@ -1399,15 +1818,14 @@ int nrf_modem_dect_phy_tx(const struct nrf_modem_dect_phy_tx_params *params); * received. In that case modem will inject ACK or NACK feedback into the Transmission feedback * field based on the PDC reception result once the reception is complete. * - * When the operation has completed, either successfully or unsuccessfully, the result is sent - * to the @ref nrf_modem_dect_phy_callbacks.op_complete callback, with a `handle` - * parameter equal to the `handle` specified in @p params. + * This operation is performed asynchronously. + * Completion of this operation is indicated by the @ref NRF_MODEM_DECT_PHY_EVT_COMPLETED event. * * @param[in] params Operation parameters. * * @retval 0 Request was sent to modem. * @retval -NRF_EPERM The Modem library is not initialized. - * @retval -NRF_EFAULT Callback configuration is invalid, or @p params is @c NULL. + * @retval -NRF_EFAULT No event handler is set, or @p params is @c NULL. * @retval -NRF_ENOMEM Not enough shared memory for this request. */ int nrf_modem_dect_phy_tx_harq(const struct nrf_modem_dect_phy_tx_params *params); @@ -1422,19 +1840,14 @@ int nrf_modem_dect_phy_tx_harq(const struct nrf_modem_dect_phy_tx_params *params * The RX operation scheduling is relative to the end of the TX operation and must include * the guard time. * - * When the TX operation has completed, either successfully or unsuccessfully, the result is sent - * to the @ref nrf_modem_dect_phy_callbacks.op_complete callback, with a `handle` - * parameter equal to the `handle` specified in @p params.tx. - * - * When the RX operation has completed, either successfully or unsuccessfully, the result is sent - * to the @ref nrf_modem_dect_phy_callbacks.op_complete callback, with a `handle` - * parameter equal to the `handle` specified in @p params.rx. + * These operations are performed asynchronously. + * Completion of each of operation is indicated by one @ref NRF_MODEM_DECT_PHY_EVT_COMPLETED event. * * @param[in] params Operation parameters. * * @retval 0 Request was sent to the modem. * @retval -NRF_EPERM The Modem library is not initialized. - * @retval -NRF_EFAULT Callback configuration is invalid, or @p params is @c NULL. + * @retval -NRF_EFAULT No event handler is set, or @p params is @c NULL. * @retval -NRF_ENOMEM Not enough shared memory for this request. */ int nrf_modem_dect_phy_tx_rx(const struct nrf_modem_dect_phy_tx_rx_params *params); @@ -1443,69 +1856,135 @@ int nrf_modem_dect_phy_tx_rx(const struct nrf_modem_dect_phy_tx_rx_params *param * @brief Schedule an RSSI measurement operation. * * Schedule an RSSI measurement operation with given parameters. - * The measurements are sent to the @ref nrf_modem_dect_phy_callbacks.rssi callback. * - * When the operation has completed, either successfully or unsuccessfully, the result is sent - * to the @ref nrf_modem_dect_phy_callbacks.op_complete callback, with a `handle` - * parameter equal to the `handle` specified in @p params. + * This operation is performed asynchronously. + * Completion of this operation is indicated by the @ref NRF_MODEM_DECT_PHY_EVT_COMPLETED event. + * The measurements are sent in the @ref NRF_MODEM_DECT_PHY_EVT_RSSI event. * * @param[in] params Operation parameters. * * @retval 0 Request was sent to modem. * @retval -NRF_EPERM The Modem library is not initialized. - * @retval -NRF_EFAULT Callback configuration is invalid, or @p params is @c NULL. + * @retval -NRF_EFAULT No event handler is set, or @p params is @c NULL. * @retval -NRF_ENOMEM Not enough shared memory for this request. */ int nrf_modem_dect_phy_rssi(const struct nrf_modem_dect_phy_rssi_params *params); /** - * @brief Stop an ongoing reception. + * @brief Cancel an operation. * - * Stop an ongoing reception before its duration has ended; this can take more or less - * time depending on the internal state of the operation at the time the request is received. + * Cancel an ongoing operation or an operation scheduled to be executed. * - * This operation is asynchronous. The result of the operation is sent to the - * @ref nrf_modem_dect_phy_callbacks.rx_stop callback. + * This operation is performed asynchronously. + * Completion of this operation is indicated by the @ref NRF_MODEM_DECT_PHY_EVT_CANCELED event. * - * @note - * Only RX operations can be stopped. + * When an operation is canceled, a @ref NRF_MODEM_DECT_PHY_EVT_COMPLETED event is sent to the + * application. If the operation is canceled while it is executing, the event reports that the + * operation completed successfully. If the operation was scheduled but not yet executing, the + * @ref NRF_MODEM_DECT_PHY_EVT_COMPLETED event will indicate the status as + * @ref NRF_MODEM_DECT_PHY_ERR_OP_CANCELED. * - * @param handle Handle of the operation to be stopped. + * @param handle Handle of the operation to be canceled, + * or @ref NRF_MODEM_DECT_PHY_HANDLE_CANCEL_ALL to cancel all operations. * * @retval 0 Request was sent to modem. * @retval -NRF_EPERM The Modem library is not initialized. - * @retval -NRF_EFAULT Callback configuration is invalid. + * @retval -NRF_EFAULT No event handler is set. * @retval -NRF_ENOMEM Not enough shared memory for this request. */ -int nrf_modem_dect_phy_rx_stop(uint32_t handle); +int nrf_modem_dect_phy_cancel(uint32_t handle); + +/** + * @brief Configure the PHY stack. + * + * This operation can only be performed when the DECT PHY is deactivated. + * + * This operation is performed asynchronously. + * Completion of this operation is indicated by the @ref NRF_MODEM_DECT_PHY_EVT_CONFIGURE event. + * + * @param[in] params PHY configuration parameters. + * + * @retval 0 Request was sent to modem. + * @retval -NRF_EPERM The Modem library is not initialized. + * @retval -NRF_EFAULT No event handler is set, or @p params is @c NULL. + * @retval -NRF_ENOMEM Not enough shared memory for this request. + */ +int nrf_modem_dect_phy_configure(const struct nrf_modem_dect_phy_config_params *params); + +/** + * @brief Configure radio mode. + * + * Configure the radio for the desired operation latency, RX/TX performance and power consumption. + * + * This operation is performed asynchronously. + * Completion of this operation is indicated by the @ref NRF_MODEM_DECT_PHY_EVT_RADIO_CONFIG event. + * + * @param[in] params Radio mode configuration parameters. + * + * @retval 0 Request was sent to modem. + * @retval -NRF_EPERM The Modem library is not initialized. + * @retval -NRF_EFAULT No event handler is set, or @p params is @c NULL. + * @retval -NRF_ENOMEM Not enough shared memory for this request. + */ +int nrf_modem_dect_phy_radio_config(const struct nrf_modem_dect_phy_radio_config_params *params); /** * @brief Configure links. * - * This operation is asynchronous. The result of the operation is sent to the - * @ref nrf_modem_dect_phy_callbacks.link_config callback. + * This operation is performed asynchronously. + * Completion of this operation is indicated by the @ref NRF_MODEM_DECT_PHY_EVT_LINK_CONFIG event. * * @param[in] params Link configuration parameters. * * @retval 0 Request was sent to modem. * @retval -NRF_EPERM The Modem library is not initialized. - * @retval -NRF_EFAULT Callback configuration is invalid, or @p params is @c NULL. + * @retval -NRF_EFAULT No event handler is set, or @p params is @c NULL. * @retval -NRF_ENOMEM Not enough shared memory for this request. * @retval -NRF_ENOSYS Functionality not implemented. */ int nrf_modem_dect_phy_link_config(const struct nrf_modem_dect_phy_link_config_params *params); /** - * @brief Query modem time. + * @brief Retrieve band information. + * + * This operation can only be performed when the DECT PHY is deactivated. + * + * This operation is performed asynchronously. + * Completion of this operation is indicated by the @ref NRF_MODEM_DECT_PHY_EVT_BANDS 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_phy_band_get(void); + +/** + * @brief Retrieve latency information. + * + * This operation can only be performed when the DECT PHY is deactivated. + * + * This operation is performed asynchronously. + * Completion of this operation is indicated by the @ref NRF_MODEM_DECT_PHY_EVT_LATENCY 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_phy_latency_get(void); + +/** + * @brief Retrieve modem time. * * Retrieve modem time, in modem time units. * - * This operation is asynchronous. The result of the operation is sent to the - * @ref nrf_modem_dect_phy_callbacks.time_get callback. + * This operation is performed asynchronously. + * Completion of this operation is indicated by the @ref NRF_MODEM_DECT_PHY_EVT_TIME event. * * @retval 0 Request was sent to modem. * @retval -NRF_EPERM The Modem library is not initialized. - * @retval -NRF_EFAULT Callback configuration is invalid. + * @retval -NRF_EFAULT No event handler is set. * @retval -NRF_ENOMEM Not enough shared memory for this request. */ int nrf_modem_dect_phy_time_get(void); @@ -1514,20 +1993,21 @@ int nrf_modem_dect_phy_time_get(void); * @brief STF cover sequence control. * * Enable or disable STF cover sequence. + * The default, applied at each initialization, is enabled. * * @note * This API is intended for certification purposes only. * It should not be used for normal operation. * - * This operation is asynchronous. The result of the operation is sent to the - * @ref nrf_modem_dect_phy_callbacks.stf_cover_seq_control callback. + * This operation is performed asynchronously. + * Completion of this operation is indicated by the @ref NRF_MODEM_DECT_PHY_EVT_STF_CONFIG event. * * @param rx_enable Enable STF cover sequence for reception. * @param tx_enable Enable STF cover sequence for transmission. * * @retval 0 Request was sent to modem. * @retval -NRF_EPERM The Modem library is not initialized. - * @retval -NRF_EFAULT Callback configuration is invalid. + * @retval -NRF_EFAULT No event handler is set. * @retval -NRF_ENOMEM Not enough shared memory for this request. */ int nrf_modem_dect_phy_stf_cover_seq_control(bool rx_enable, bool tx_enable); diff --git a/nrf_modem/include/nrf_modem_softsim.h b/nrf_modem/include/nrf_modem_softsim.h index 8dd3125a8b..6749f19fdc 100644 --- a/nrf_modem/include/nrf_modem_softsim.h +++ b/nrf_modem/include/nrf_modem_softsim.h @@ -36,9 +36,10 @@ enum nrf_modem_softsim_cmd { * * @details This handler lets the application process a SoftSIM request. * The application must then call @ref nrf_modem_softsim_res with the response data - * requested. + * requested, and @ref nrf_modem_softsim_data_free when the request is not referenced + * anymore and can be freed. * - * @note This handler is executed in an interrupt service routine. + * @note This handler is executed in an interrupt service routine (ISR). * Offload any intensive operations as necessary. * * @param cmd SoftSIM request command. @@ -52,7 +53,7 @@ typedef void (*nrf_modem_softsim_req_handler_t)(enum nrf_modem_softsim_cmd cmd, /** * @brief Set a handler function for SoftSIM requests. * - * @note The handler is executed in an interrupt service routine. + * @note The handler is executed in an interrupt service routine (ISR). * Take care to offload any processing as appropriate. * * @param handler The SoftSIM request handler. Use @c NULL to unset handler. @@ -67,6 +68,9 @@ int nrf_modem_softsim_req_handler_set(nrf_modem_softsim_req_handler_t handler); * @details This function is used to respond to the Modem with the data requested by a specific * request. * + * @note This function takes care of copying @p data to an internal buffer, so any + * heap allocation for @p data can be freed immediately after calling this function. + * * @param cmd SoftSIM response command. * @param req_id Request ID used to match request and response. * @param[in] data Pointer to the data of the SoftSIM response. diff --git a/nrf_modem/lib/cellular/nrf9120/hard-float/libmodem.a b/nrf_modem/lib/cellular/nrf9120/hard-float/libmodem.a index 332eec1559..831c6b9a7e 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 4c73c0c1df..af6b469714 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 f562833982..0bda02fb68 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 4e718e449c..aed7d2802c 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 332eec1559..831c6b9a7e 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 4c73c0c1df..af6b469714 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 f562833982..0bda02fb68 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 4e718e449c..aed7d2802c 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 02e2920da3..f6bc049b9b 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 43d12a5eaa..620146da9f 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 49c5a815b0..a0425ce89f 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 2738be575b..269cfdffff 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 3d3f39a560..7969ed89eb 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 75d1025569..bfc37883c5 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 7f2427af75..5f05f1998f 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 509c8ab305..0ce57265cc 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