From 455ed75329a0681d09f86896af443ed0246dc263 Mon Sep 17 00:00:00 2001 From: divya pillai Date: Thu, 23 Jan 2025 13:31:52 +0100 Subject: [PATCH] doc: doc review doc review Signed-off-by: divya pillai --- nrf_modem/doc/CHANGELOG.rst | 12 ++++--- nrf_modem/doc/dectphy.rst | 67 ++++++++++++++++--------------------- 2 files changed, 36 insertions(+), 43 deletions(-) diff --git a/nrf_modem/doc/CHANGELOG.rst b/nrf_modem/doc/CHANGELOG.rst index 07282d7f3c4..06405f4d01e 100644 --- a/nrf_modem/doc/CHANGELOG.rst +++ b/nrf_modem/doc/CHANGELOG.rst @@ -16,20 +16,21 @@ 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 an set ``errno`` to ``NRF_EINVAL``. - If you use a version of this library from v2.3.0 to v2.9.0 outside of |NCS| and are initializing the library by calling the :c:func:`nrf_modem_init()` function, ensure that the lifetime of the :c:func:`nrf_modem_init` parameter is ``static``. + 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 many new features and improvements, notably: +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. +.. 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: @@ -52,7 +53,8 @@ Added support for DECT PHY firmware v1.1.0 with many new features and improvemen * 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_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. diff --git a/nrf_modem/doc/dectphy.rst b/nrf_modem/doc/dectphy.rst index 0cf922139d1..d5d446a721b 100644 --- a/nrf_modem/doc/dectphy.rst +++ b/nrf_modem/doc/dectphy.rst @@ -57,7 +57,7 @@ The DECT NR+ PHY firmware implements only the physical layer of the protocol sta General operation ***************** -The DECT PHY stack has three states: +The DECT PHY stack has the following three states: * deinitialized, deactivated * initialized, deactivated @@ -77,7 +77,8 @@ Initializing the DECT PHY readies the hardware resources for the PHY in the netw 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 network processor. +#. Initialize the Modem library by calling the :c:func:`nrf_modem_init` function. + This also turns on the network processor. #. Register the event handler for DECT PHY operations by calling the :c:func:`nrf_modem_dect_phy_event_handler_set` function. Afterwards, the application can initialize the DECT PHY by calling the :c:func:`nrf_modem_dect_phy_init` function. @@ -104,9 +105,7 @@ Activation ========== 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 in the PHY is in activated state, it's possible to begin receiving and transmitting data. - +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. Radio modes @@ -114,42 +113,36 @@ Radio modes The radio modes have implications on operation latency and power consumption. -The radio can be configured in one of three modes: +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 starting operations immediately, that is, operations whose configured start time is zero. +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 radio entering standby mode when possible. - +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 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. +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. Deactivation ============ 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. Deinitialization ================ The DECT PHY can be deinitialized using the :c:func:`nrf_modem_dect_phy_deinit` function. - The DECT PHY can be de-initialized, which in turn de-initializes the physical layer in the network processor, 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 @@ -161,10 +154,10 @@ This allows the application to track the changes in temperature and adjust furth 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.NRF_MODEM_DECT_PHY_ERR_TEMP_HIGH` error. +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.NRF_MODEM_DECT_PHY_ERR_OP_CANCELED` error in their relative events. +This will cancel all scheduled operations, with the :c:enumerator:`NRF_MODEM_DECT_PHY_ERR_OP_CANCELED` error in their relative events. 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. @@ -180,14 +173,13 @@ 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 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 events for radio operations carry an application-defined handle that can be used to identify the operation. @@ -196,7 +188,7 @@ 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 DECT PHY events provide the value of modem time counter at the moment the event was sent by the modem core to the application core. +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. @@ -211,15 +203,15 @@ Example 1: Immediate execution Pre-conditions: -* The DECT PHY radio mode is :c:enumerator:`NRF_MODEM_DECT_PHY_RADIO_MODE_LOW_LATENCY` -* There are no scheduled or ongoing operations +* The DECT PHY radio mode is :c:enumerator:`NRF_MODEM_DECT_PHY_RADIO_MODE_LOW_LATENCY`. +* There are no scheduled or ongoing operations. Let ``t`` be the current modem time. 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.operation.receive.idle_to_active` -* for TX operations by :c:member:`nrf_modem_dect_phy_latency_info.operation.transmit.idle_to_active` +* 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 actual start time of the operation can be calculated as ``t + startup``. @@ -227,11 +219,11 @@ Stopping the operation also incurs latency, which includes the time to close the The stop latency ``stop`` depends on the operation, and is indicated: -* for an RX operation: :c:member:`nrf_modem_dect_phy_latency_info.operation.receive.active_to_idle_rx` -* for an RSSI operation: :c:member:`nrf_modem_dect_phy_latency_info.operation.receive.active_to_idle_rssi` -* for an RX operation with RSSI measurements: :c:member:`nrf_modem_dect_phy_latency_info.operation.receive.active_to_idle_rx_rssi` -* for a TX operation: :c:member:`nrf_modem_dect_phy_latency_info.operation.transmit.active_to_idle` -* for a TX_RX operation: :c:member:`nrf_modem_dect_phy_latency_info.operation.receive.active_to_idle_rx` +* 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``. @@ -239,29 +231,28 @@ Example 2: Scheduling one operation after another Pre-conditions: -* The DECT PHY is activated -* There are is one scheduled or ongoing operation (operation 1) +* 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.operation.receive.idle_to_active` -* for TX operations by: :c:member:`nrf_modem_dect_phy_latency_info.operation.transmit.idle_to_active` +* 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. -This delay is represented by the value :c:member:`nrf_modem_dect_phy_latency_info.radio_mode.scheduled_operation_startup`, which we will refer to as ``sched_startup``. +This delay is represented by the value :c:member:`nrf_modem_dect_phy_latency_info.scheduled_operation_startup`, which refers to as ``sched_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. -This delay is represented by the value :c:member:`nrf_modem_dect_phy_latency_info.radio_mode.scheduled_operation_transition`, which we will refer to as ``sched_transition``. +This delay is represented by the value :c:member:`nrf_modem_dect_phy_latency_info.scheduled_operation_transition`, which refers to as ``sched_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 **************** @@ -420,6 +411,6 @@ The application can cancel operations using the :c:func:`nrf_modem_dect_phy_canc 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 will carry the error :c:enumerator:`nrf_modem_dect_phy_err.NRF_MODEM_DECT_PHY_ERR_OP_CANCELED`, otherwise it will report a success. +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. -Once the operation is canceled one :c:enumerator:`NRF_MODEM_DECT_PHY_EVT_CANCELED` event is sent to the application to indicate that the cancel operation has completed. +Once the operation is canceled, one :c:enumerator:`NRF_MODEM_DECT_PHY_EVT_CANCELED` event is sent to the application to indicate that the cancellation operation has completed.