Update MPSL and SoftDevice Controller

mpsl/CHANGELOG.rst

@@ -7,6 +7,19 @@ Changelog
    :local:
    :depth: 2
 
+Main Branch
+***********
+
+Changes
+=======
+
+* New FEM protocol APIs are provided to control the PA power, the previous APIs are deprecated.
+  This change does not affect applications developed in the |NCS| context.
+  :c:func:`mpsl_fem_pa_power_control_set` replaces :c:func:`mpsl_fem_pa_gain_set`.
+  :c:func:`mpsl_fem_caps_get` replaces :c:func:`mpsl_fem_pa_is_configured`.
+  The :c:struct:`mpsl_tx_power_split_t` structure contains the new field ``fem_pa_power_control`` to be used with the :c:func:`mpsl_fem_pa_power_control_set` function.
+  The :c:type:`mpsl_fem_gain_t` type is deprecated, please use :c:type:`mpsl_fem_pa_power_control_t` type instead (KRKNWK-18729).
+
 nRF Connect SDK v2.6.0
 **********************
 

mpsl/fem/common/lib/cortex-m33+nodsp/soft-float/manifest.yaml

@@ -1,3 +1,3 @@
 description: MPSL Front-End Module common
-git_revision: 51ff0516ee8a13885fd297b9099aea4b6fcc8980
-timestamp: '2024-03-19T13:41:40Z'
+git_revision: e2e0ef04f1263d97d751a729e260ddf6a0c7ac8b
+timestamp: '2024-03-29T08:31:17Z'

mpsl/fem/common/lib/cortex-m4/hard-float/manifest.yaml

@@ -1,3 +1,3 @@
 description: MPSL Front-End Module common
-git_revision: 51ff0516ee8a13885fd297b9099aea4b6fcc8980
-timestamp: '2024-03-19T13:38:56Z'
+git_revision: e2e0ef04f1263d97d751a729e260ddf6a0c7ac8b
+timestamp: '2024-03-29T08:30:17Z'

mpsl/fem/common/lib/cortex-m4/soft-float/manifest.yaml

@@ -1,3 +1,3 @@
 description: MPSL Front-End Module common
-git_revision: 51ff0516ee8a13885fd297b9099aea4b6fcc8980
-timestamp: '2024-03-19T13:38:56Z'
+git_revision: e2e0ef04f1263d97d751a729e260ddf6a0c7ac8b
+timestamp: '2024-03-29T08:30:17Z'

mpsl/fem/common/lib/cortex-m4/softfp-float/manifest.yaml

@@ -1,3 +1,3 @@
 description: MPSL Front-End Module common
-git_revision: 51ff0516ee8a13885fd297b9099aea4b6fcc8980
-timestamp: '2024-03-19T13:38:56Z'
+git_revision: e2e0ef04f1263d97d751a729e260ddf6a0c7ac8b
+timestamp: '2024-03-29T08:30:17Z'

mpsl/fem/common/lib/nrf54h20_cpurad/hard-float/manifest.yaml

@@ -1,3 +1,3 @@
 description: MPSL Front-End Module common
-git_revision: 51ff0516ee8a13885fd297b9099aea4b6fcc8980
-timestamp: '2024-03-19T13:48:19Z'
+git_revision: e2e0ef04f1263d97d751a729e260ddf6a0c7ac8b
+timestamp: '2024-03-29T08:34:44Z'

mpsl/fem/common/lib/nrf54h20_cpurad/soft-float/manifest.yaml

@@ -1,3 +1,3 @@
 description: MPSL Front-End Module common
-git_revision: 51ff0516ee8a13885fd297b9099aea4b6fcc8980
-timestamp: '2024-03-19T13:48:19Z'
+git_revision: e2e0ef04f1263d97d751a729e260ddf6a0c7ac8b
+timestamp: '2024-03-29T08:34:44Z'

mpsl/fem/common/lib/nrf54h20_cpurad/softfp-float/manifest.yaml

@@ -1,3 +1,3 @@
 description: MPSL Front-End Module common
-git_revision: 51ff0516ee8a13885fd297b9099aea4b6fcc8980
-timestamp: '2024-03-19T13:48:19Z'
+git_revision: e2e0ef04f1263d97d751a729e260ddf6a0c7ac8b
+timestamp: '2024-03-29T08:34:44Z'

mpsl/fem/common/lib/nrf54l15_cpuapp/hard-float/manifest.yaml

@@ -1,3 +1,3 @@
 description: MPSL Front-End Module common
-git_revision: 51ff0516ee8a13885fd297b9099aea4b6fcc8980
-timestamp: '2024-03-19T13:51:35Z'
+git_revision: e2e0ef04f1263d97d751a729e260ddf6a0c7ac8b
+timestamp: '2024-03-29T08:36:16Z'

mpsl/fem/common/lib/nrf54l15_cpuapp/soft-float/manifest.yaml

@@ -1,3 +1,3 @@
 description: MPSL Front-End Module common
-git_revision: 51ff0516ee8a13885fd297b9099aea4b6fcc8980
-timestamp: '2024-03-19T13:51:35Z'
+git_revision: e2e0ef04f1263d97d751a729e260ddf6a0c7ac8b
+timestamp: '2024-03-29T08:36:16Z'

mpsl/fem/common/lib/nrf54l15_cpuapp/softfp-float/manifest.yaml

@@ -1,3 +1,3 @@
 description: MPSL Front-End Module common
-git_revision: 51ff0516ee8a13885fd297b9099aea4b6fcc8980
-timestamp: '2024-03-19T13:51:35Z'
+git_revision: e2e0ef04f1263d97d751a729e260ddf6a0c7ac8b
+timestamp: '2024-03-29T08:36:16Z'

mpsl/fem/include/mpsl_fem_power_model.h

@@ -37,8 +37,35 @@ typedef struct
     /** SoC power in dBm. When returned by a model, this field is expected to contain value
      *  supported by the SoC that can safely be applied directly to RADIO registers. */
     int8_t          soc_pwr;
-    /** Front-End Module gain. */
+
+#ifdef _MPSL_FEM_POWER_MODEL_FEM_GAIN_API_DEPRECATED
+    /** Front-End Module gain. 
+     * 
+     *  @note This field is deprecated. In implementation of your model please wrap any access to
+     *  this field with @c ifdef @c _MPSL_FEM_POWER_MODEL_FEM_GAIN_API_DEPRECATED
+     *  While @ref _MPSL_FEM_POWER_MODEL_FEM_GAIN_API_DEPRECATED is defined this field should be
+     *  written as before. Please note the @c fem_pa_power_control field.
+     *  The @c fem field will be removed along with @ref _MPSL_FEM_POWER_MODEL_FEM_GAIN_API_DEPRECATED
+     *  macro and only the field @c fem_pa_power_control will be left.
+     */
     mpsl_fem_gain_t fem;
+#endif
+
+    /** PA power control to be applied to the FEM.
+     *
+     * This value is FEM type-dependent. The produced value is to be passed to the
+     * call to @ref mpsl_fem_pa_power_control_set.
+     *
+     * @note During depreciation period while @ref _MPSL_FEM_POWER_MODEL_FEM_GAIN_API_DEPRECATED is defined
+     * this field is expected to contain the same value as @c fem.private_setting . If the implementation
+     * of the model is not aligned yet to the new API and does not write @c fem_pa_power_control field,
+     * then in case of difference between @c fem.private_setting and @c fem_pa_power_control the
+     * @c fem.private_setting is used. After depreciation period only the
+     * @c fem_pa_power_control field will be left and macro @ref _MPSL_FEM_POWER_MODEL_FEM_GAIN_API_DEPRECATED
+     * will be removed.
+     */
+    mpsl_fem_pa_power_control_t fem_pa_power_control;
+
     /** Achieved power on the antenna in dBm. */
     int8_t          achieved_pwr;
 } mpsl_fem_power_model_output_t;

mpsl/fem/include/mpsl_fem_types.h

@@ -22,19 +22,72 @@
 extern "C" {
 #endif
 
+/**@brief Support deprecated parts of MPSL Power Model API. */
+#define _MPSL_FEM_POWER_MODEL_FEM_GAIN_API_DEPRECATED
+
+/** Type for PA power control to be applied to Front-End Module, depending on its type.
+ * 
+ *  The meaning of this type is FEM type-specific. Applicable macros are defined within
+ *  FEM type-specific header files found in @c protocol/mpsl_fem_[type]_protocol_api.h .
+ *  Macros are named according to pattern @c MPSL_FEM_[TYPE]_PA_POWER_CONTROL_* .
+ *  When these macros define just a subset of available bits, treat other bits as
+ *  reserved and set them to 0.
+ */
+typedef uint8_t mpsl_fem_pa_power_control_t;
+
 /**
- * @brief Structure that provides complete information about Front-End Module gain.
+ * @brief Structure that provides transmit control to be applied to a Front-End Module.
+ * 
+ * When this structure is filled as an outcome of @ref mpsl_fem_tx_power_split (recommended) 
+ * you don't need to know what is inside the structure.
+ * 
+ * When you need to construct this struct on your own (not recommended), please note that
+ * the content of this structure depends fully on the Front-End Module type in use.
+ * Please refer to FEM type-specific header files found in @c protocol/mpsl_fem_[type]_protocol_api.h .
  */
 typedef struct
 {
     /** Gain in dB. */
     int8_t  gain_db;
-    /** Private setting to be applied to Front-End Module, depending on its type.
-     *  For nRF21540 GPIO/SPI, this is a register value.
-     *  For nRF21540 GPIO, this is MODE pin value. */
+
+    /** Control parameter to be applied to Front-End Module, depending on its type.
+     * 
+     *  The meaning of this field depends on FEM type. Applicable macros are defined within
+     *  FEM type-specific header files found in @c protocol/mpsl_fem_[type]_protocol_api.h .
+     *  Macros are named according to pattern @c MPSL_FEM_[TYPE]_PA_POWER_CONTROL_* .
+     *  When these macros define just a subset of available bits, treat other bits as
+     *  reserved and set them to 0.
+     */
     uint8_t private_setting;
 } mpsl_fem_gain_t;
 
+/** Type binding gain of the FEM with PA power control value for calibration purposes. */
+typedef struct
+{
+    /** Gain in dB. */
+    int8_t gain_db;
+
+#ifdef _MPSL_FEM_POWER_MODEL_FEM_GAIN_API_DEPRECATED
+    /** Equivalent of mpsl_fem_gain_t::private_setting. 
+     * 
+     *  This field is deprecated and will be removed along with the macro 
+     *  @ref _MPSL_FEM_POWER_MODEL_FEM_GAIN_API_DEPRECATED. Please use the field
+     *  @c fem_pa_power_control instead. It has exactly the same content and meaning.
+     */
+    uint8_t private_setting;
+#endif
+
+    /** Control parameter to be applied to Front-End Module, depending on its type.
+     * 
+     *  The meaning of this field depends on FEM type. Applicable macros are defined within
+     *  FEM type-specific header files found in @c protocol/mpsl_fem_[type]_protocol_api.h .
+     *  Macros are named according to pattern @c MPSL_FEM_[TYPE]_PA_POWER_CONTROL_* .
+     *  When these macros define just a subset of available bits, treat other bits as
+     *  reserved and set them to 0.
+     */
+    mpsl_fem_pa_power_control_t fem_pa_power_control;
+} mpsl_fem_calibration_point_t;
+
 /**
  * @brief Union that provides data for calibrating Front-End Module gain.
  */
@@ -49,15 +102,15 @@ typedef union
     /** Calibration data for nRF21540 GPIO. */
     struct
     {
-        mpsl_fem_gain_t pouta; ///< Gain in dB and relevant MODE pin state for precalibrated POUTA setting.
-        mpsl_fem_gain_t poutb; ///< Gain in dB and relevant MODE pin state for precalibrated POUTB setting.
+        mpsl_fem_calibration_point_t pouta; ///< Gain in dB and relevant MODE pin state for precalibrated POUTA setting.
+        mpsl_fem_calibration_point_t poutb; ///< Gain in dB and relevant MODE pin state for precalibrated POUTB setting.
     } nrf21540_gpio;
 
     /** Calibration data for nRF21540 GPIO/SPI. */
     struct
     {
-        mpsl_fem_gain_t pouta; ///< Gain in dB and relevant register value for precalibrated POUTA setting.
-        mpsl_fem_gain_t poutb; ///< Gain in dB and relevant register value for precalibrated POUTB setting.
+        mpsl_fem_calibration_point_t pouta; ///< Gain in dB and relevant register value for precalibrated POUTA setting.
+        mpsl_fem_calibration_point_t poutb; ///< Gain in dB and relevant register value for precalibrated POUTB setting.
     } nrf21540_gpio_spi;
 
 } mpsl_fem_calibration_data_t;

mpsl/fem/include/protocol/mpsl_fem_protocol_api.h

@@ -116,10 +116,50 @@ typedef struct
     /** TX power to be applied to the RADIO peripheral. */
     mpsl_tx_power_t radio_tx_power;
 
-    /** FEM gain. */
+    /** FEM gain.
+     * 
+     * @note This field is deprecated and will be removed. Please use the
+     * @c fem_pa_power_control field and @ref mpsl_fem_pa_power_control_set function.
+     */
     mpsl_fem_gain_t fem;
+
+    /** FEM PA power control.*/
+    mpsl_fem_pa_power_control_t fem_pa_power_control;
 } mpsl_tx_power_split_t;
 
+/** @brief PA setup is required before starting a transmission.
+ *
+ *  This flag applies to @ref mpsl_fem_caps_t::flags.
+ * 
+ *  If it is set, then @ref mpsl_fem_pa_configuration_set must be called before transmission starts.
+ */
+#define MPSL_FEM_CAPS_FLAG_PA_SETUP_REQUIRED  (1U << 0)
+
+/** @brief LNA setup is required before starting a reception.
+ *
+ *  This flag applies to @ref mpsl_fem_caps_t::flags.
+ * 
+ *  If it is set, then @ref mpsl_fem_lna_configuration_set must be called before reception starts.
+ */
+#define MPSL_FEM_CAPS_FLAG_LNA_SETUP_REQUIRED (1U << 1)
+
+/** @brief Structure representing capabilities and characteristics of the FEM in use. */
+typedef struct
+{
+    /** Flags informing about the FEM in use.
+     *
+     *  The following flags apply:
+     *  @ref MPSL_FEM_CAPS_FLAG_PA_SETUP_REQUIRED, @ref MPSL_FEM_CAPS_FLAG_LNA_SETUP_REQUIRED
+     */
+    uint32_t flags;
+} mpsl_fem_caps_t;
+
+/** @brief Gets the capabilities of the FEM in use.
+ * 
+ *  @param[out] p_caps  Pointer to the capabilities structure to be filled in.
+ */
+void mpsl_fem_caps_get(mpsl_fem_caps_t * p_caps);
+
 /** @brief Disable Front End Module.
  *
  * Some Front End Module devices can be explicitly disabled after PA and LNA activities are
@@ -332,7 +372,34 @@ int8_t mpsl_fem_tx_power_split(const mpsl_tx_power_t         power,
                                uint16_t                      freq_mhz,
                                bool                          tx_power_ceiling);
 
+/** @brief Sets the PA power control.
+ * 
+ * Setting the PA power control informs the FEM implementation how the PA is to be controlled
+ * before the next transmission.
+ * 
+ * The PA power control set by this function is to be applied to control signals or
+ * parameters. What signals and parameters are controlled and how does it happen depends on
+ * implementation of given FEM. The meaning of @p pa_power_control parameter is
+ * fully FEM type-dependent. For FEM type-independent protocol implementation please
+ * use the function @ref mpsl_fem_tx_power_split and provide outcome of this function
+ * returned by the parameter @c p_tx_power_split to the call to @ref mpsl_fem_pa_power_control_set.
+ * For applications intended for testing the FEM itself when @ref mpsl_fem_tx_power_split is not used
+ * you must make the @p pa_power_control parameter on your own.
+ *
+ * @note The PA power control set by this function will be applied to radio transmissions
+ * following the call. If the function is called during radio transmission
+ * or during ramp-up for transmission it is unspecified if the control is applied.
+ *
+ * @param[in] pa_power_control  PA power control to be applied to the FEM.
+ *
+ * @retval   0             PA power control has been applied successfully.
+ * @retval   -NRF_EINVAL   PA power control could not be applied. Provided @p pa_power_control is invalid.
+ */
+int32_t mpsl_fem_pa_power_control_set(mpsl_fem_pa_power_control_t pa_power_control);
+
 /** @brief Sets PA gain.
+ * 
+ * @note This function is deprecated. Please use @ref mpsl_fem_pa_power_control_set .
  *
  * @note The gain set by this function will be applied to radio transmissions
  * following the call. If the function is called during radio transmission
@@ -347,6 +414,8 @@ int32_t mpsl_fem_pa_gain_set(const mpsl_fem_gain_t * p_gain);
 
 /** @brief Checks if the PA signaling is configured and enabled, and gets
  *  the configured gain in dB.
+ * 
+ * @note This function is deprecated. Please use the function @ref mpsl_fem_caps_get instead.
  *
  * @param[out] p_gain The configured gain in dB if PA is configured and enabled.
  *                    If there is no PA present or the PA does not affect

mpsl/fem/nrf21540_gpio/include/protocol/mpsl_fem_nrf21540_gpio_protocol_api.h

@@ -0,0 +1,43 @@
+/*
+ * Copyright (c) Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
+ */
+
+/**
+ * @file mpsl_fem_nrf21540_gpio_protocol_api.h
+ *
+ * @defgroup mpsl_fem_nrf21540_gpio_protocol_api MPSL nRF21540 GPIO Front End Module Protocol API Extension.
+ * @ingroup  mpsl_fem
+ *
+ * @{
+ */
+
+#ifndef MPSL_FEM_NRF21540_GPIO_PROTOCOL_API_H__
+#define MPSL_FEM_NRF21540_GPIO_PROTOCOL_API_H__
+
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** @brief Bit number of @c private_setting holding MODE pin state. */
+#define MPSL_FEM_NRF21540_GPIO_PA_POWER_CONTROL_MODE_BITNO    (0)
+
+/** @brief Bit mask of @c private_setting for holding MODE pin state. */
+#define MPSL_FEM_NRF21540_GPIO_PA_POWER_CONTROL_MODE_MSK      (1U << MPSL_FEM_NRF21540_GPIO_PA_POWER_CONTROL_MODE_BITNO)
+
+/** @brief Bit field value of @c private_setting for controlling MODE pin state to use POUTA power setting. */
+#define MPSL_FEM_NRF21540_GPIO_PA_POWER_CONTROL_MODE_POUTA    (0U << MPSL_FEM_NRF21540_GPIO_PA_POWER_CONTROL_MODE_BITNO)
+
+/** @brief Bit field value of @c private_setting for controlling MODE pin state to use POUTB power setting. */
+#define MPSL_FEM_NRF21540_GPIO_PA_POWER_CONTROL_MODE_POUTB    (1U << MPSL_FEM_NRF21540_GPIO_PA_POWER_CONTROL_MODE_BITNO)
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif // MPSL_FEM_NRF21540_GPIO_PROTOCOL_API_H__
+
+/**@} */

mpsl/fem/nrf21540_gpio/lib/cortex-m33+nodsp/hard-float/manifest.yaml

@@ -0,0 +1,3 @@
+description: MPSL Front-End Module nrf21540_gpio
+git_revision: e2e0ef04f1263d97d751a729e260ddf6a0c7ac8b
+timestamp: '2024-03-29T08:32:53Z'

mpsl/fem/nrf21540_gpio/lib/cortex-m33+nodsp/soft-float/manifest.yaml

@@ -1,3 +1,3 @@
 description: MPSL Front-End Module nrf21540_gpio
-git_revision: 51ff0516ee8a13885fd297b9099aea4b6fcc8980
-timestamp: '2024-03-19T13:41:40Z'
+git_revision: e2e0ef04f1263d97d751a729e260ddf6a0c7ac8b
+timestamp: '2024-03-29T08:31:17Z'

mpsl/fem/nrf21540_gpio/lib/cortex-m33+nodsp/softfp-float/manifest.yaml

@@ -0,0 +1,3 @@
+description: MPSL Front-End Module nrf21540_gpio
+git_revision: e2e0ef04f1263d97d751a729e260ddf6a0c7ac8b
+timestamp: '2024-03-29T08:32:53Z'

mpsl/fem/nrf21540_gpio/lib/cortex-m4/hard-float/manifest.yaml

@@ -1,3 +1,3 @@
 description: MPSL Front-End Module nrf21540_gpio
-git_revision: 51ff0516ee8a13885fd297b9099aea4b6fcc8980
-timestamp: '2024-03-19T13:38:56Z'
+git_revision: e2e0ef04f1263d97d751a729e260ddf6a0c7ac8b
+timestamp: '2024-03-29T08:30:17Z'

mpsl/fem/nrf21540_gpio/lib/cortex-m4/soft-float/manifest.yaml

@@ -1,3 +1,3 @@
 description: MPSL Front-End Module nrf21540_gpio
-git_revision: 51ff0516ee8a13885fd297b9099aea4b6fcc8980
-timestamp: '2024-03-19T13:38:56Z'
+git_revision: e2e0ef04f1263d97d751a729e260ddf6a0c7ac8b
+timestamp: '2024-03-29T08:30:17Z'

mpsl/fem/nrf21540_gpio/lib/cortex-m4/softfp-float/manifest.yaml

@@ -1,3 +1,3 @@
 description: MPSL Front-End Module nrf21540_gpio
-git_revision: 51ff0516ee8a13885fd297b9099aea4b6fcc8980
-timestamp: '2024-03-19T13:38:56Z'
+git_revision: e2e0ef04f1263d97d751a729e260ddf6a0c7ac8b
+timestamp: '2024-03-29T08:30:17Z'