fem_al: replace gain with FEM type-specific tx_power_control

The MPSL FEM public API is changed. The `mpsl_fem_pa_gain_set`
has been replaced by `mpsl_fem_pa_power_control_set`. There is no more
possibility of setting "gain". The real gain of FEM depends on
many factors including but not limited to input power of the FEM,
frequency, temperature, supply voltage and the way the FEM
is controlled.

The fem_al API is changed so that the concept of generic "gain"
of the front-end module is replaced by "tx_power_control" which
is FEM type-specific.

`fem_tx_power_control` type is introduced.
`fem_tx_gain_set` is replaced by `fem_tx_power_control_set`
`fem_default_tx_gain_get` is replaced by
  'fem_default_tx_output_power_get'

`fem_interface_api` is changed to reflect these changes along with
implementations nrf21540.c and generic_fem.c.

Signed-off-by: Andrzej Kuros <andrzej.kuros@nordicsemi.no>

Author: ankuns

doc/nrf/releases_and_maturity/migration/migration_guide_2.7.rst

@@ -56,7 +56,14 @@ Libraries
 
 This section describes the changes related to libraries.
 
-|no_changes_yet_note|
+FEM abstraction layer
+---------------------
+
+.. toggle::
+
+  * For applications using :ref:`fem_al_lib`:
+    The function :c:func:`fem_tx_power_control_set` replaces the function :c:func:`fem_tx_gain_set`.
+    The function :c:func:`fem_default_tx_output_power_get` replaces the function :c:func:`fem_default_tx_gain_get`.
 
 Recommended changes
 *******************

include/fem_al/fem_al.h

@@ -34,6 +34,12 @@ enum fem_antenna {
 	FEM_ANTENNA_2
 };
 
+/**@brief Type holding Tx power control to be applied to front-end module.
+ *
+ * @note The value stored in this type is specific to the FEM type in use.
+ */
+typedef uint8_t fem_tx_power_control;
+
 /**@brief Initialize the front-end module.
  *
  * @param[in] timer_instance Pointer to a 1-us resolution timer instance.
@@ -68,17 +74,18 @@ int fem_power_up(void);
  */
 int fem_power_down(void);
 
-/**@brief Configure Tx gain of the front-end module in arbitrary units.
+/**@brief Configure Tx power control of the front-end module.
  *
- * @param[in] gain Tx gain in arbitrary units specific for used front-end module implementation.
+ * @param[in] tx_power_control Tx power control specific to the front-end module implementation.
  *                 For nRF21540 GPIO/SPI, this is a register value.
  *                 For nRF21540 GPIO, this is MODE pin value.
- *                 Check your front-end module product specification for gain value range.
+ *                 Check your front-end module product specification for Tx power control value
+ *                 range.
  *
  * @retval 0 If the operation was successful.
  *           Otherwise, a (negative) error code is returned.
  */
-int fem_tx_gain_set(uint32_t gain);
+int fem_tx_power_control_set(fem_tx_power_control tx_power_control);
 
 /**@brief Get the default radio ramp-up time for reception or transmission with a given data rate
  *        and modulation.
@@ -145,11 +152,11 @@ uint32_t fem_radio_tx_ramp_up_delay_get(bool fast, nrf_radio_mode_t mode);
  */
 uint32_t fem_radio_rx_ramp_up_delay_get(bool fast, nrf_radio_mode_t mode);
 
-/**@brief Set the front-end module gain and returns output power to be set on the radio peripheral
- *        to get requested output power.
+/**@brief Set the front-end module Tx power control and returns output power
+ *        to be set on the radio peripheral to get requested output power.
  *
  * This function calculates power value for RADIO peripheral register and
- * sets front-end module gain value.
+ * sets front-end module Tx power control value.
  *
  * @note If the exact value of @p power cannot be achieved, this function attempts to use less
  *       power to not exceed the limits.
@@ -204,11 +211,11 @@ static inline int8_t fem_tx_output_power_max_get(uint16_t freq_mhz)
 	return fem_tx_output_power_check(INT8_MAX, freq_mhz, true);
 }
 
-/**@brief Get the front-end module default Tx gain.
+/**@brief Get the front-end module default Tx output power.
  *
- * @return The front-end module default Tx gain value.
+ * @return The front-end module default Tx output power value.
  */
-uint32_t fem_default_tx_gain_get(void);
+int8_t fem_default_tx_output_power_get(void);
 
 /**@brief Apply the workaround for the Errata 254, 255, 256, 257 when appropriate.
  *

lib/fem_al/fem_al.c

@@ -198,37 +198,26 @@ int fem_rx_configure(uint32_t ramp_up_time)
 	return 0;
 }
 
-int fem_tx_gain_set(uint32_t gain)
+int fem_tx_power_control_set(fem_tx_power_control tx_power_control)
 {
 	int32_t err;
-	mpsl_fem_gain_t fem_gain = { 0 };
+	mpsl_fem_pa_power_control_t fem_pa_power_control = 0;
 
 	/* Fallback to FEM specific function. It can be used for checking the valid output power
 	 * range.
 	 */
-	if (fem_api->tx_gain_validate) {
-		err = fem_api->tx_gain_validate(gain);
+	if (fem_api->tx_power_control_validate) {
+		err = fem_api->tx_power_control_validate(tx_power_control);
 		if (err) {
 			return err;
 		}
 	}
 
-	if (!fem_api->tx_default_gain_get) {
-		/* Should not happen. */
-		__ASSERT(false, "Missing FEM specific function for getting default Tx gain");
-		return -EFAULT;
-	}
-
-	/* We need to pass valid gain db value for given front-end module to have possibility to set
-	 * gain value directly in arbitrary value defined in your front-end module
-	 * product specification. In this case the default Tx gain value will be used.
-	 */
-	fem_gain.gain_db = fem_api->tx_default_gain_get();
-	fem_gain.private_setting = gain;
+	fem_pa_power_control = tx_power_control;
 
-	err = mpsl_fem_pa_gain_set(&fem_gain);
+	err = mpsl_fem_pa_power_control_set(fem_pa_power_control);
 	if (err) {
-		printk("Failed to set front-end module gain (err %d)\n", err);
+		printk("Failed to set front-end module Tx power control (err %d)\n", err);
 		return -EINVAL;
 	}
 
@@ -268,10 +257,10 @@ int8_t fem_tx_output_power_prepare(int8_t power, int8_t *radio_tx_power, uint16_
 
 	*radio_tx_power = power_split.radio_tx_power;
 
-	err = mpsl_fem_pa_gain_set(&power_split.fem);
+	err = mpsl_fem_pa_power_control_set(power_split.fem_pa_power_control);
 	if (err) {
 		/* Should not happen */
-		printk("Failed to set front-end module gain (err %d)\n", err);
+		printk("Failed to set front-end module Tx power control (err %d)\n", err);
 		__ASSERT_NO_MSG(false);
 	}
 
@@ -285,10 +274,10 @@ int8_t fem_tx_output_power_check(int8_t power, uint16_t freq_mhz, bool tx_power_
 	return mpsl_fem_tx_power_split(power, &power_split, freq_mhz, tx_power_ceiling);
 }
 
-uint32_t fem_default_tx_gain_get(void)
+int8_t fem_default_tx_output_power_get(void)
 {
-	if (fem_api->tx_default_gain_get) {
-		return fem_api->tx_default_gain_get();
+	if (fem_api->default_tx_output_power_get) {
+		return fem_api->default_tx_output_power_get();
 	}
 
 	return 0;

lib/fem_al/fem_interface.h

@@ -28,8 +28,8 @@ extern "C" {
 struct fem_interface_api {
 	int (*power_up)(void);
 	int (*power_down)(void);
-	int (*tx_gain_validate)(uint32_t gain);
-	uint32_t (*tx_default_gain_get)(void);
+	int (*tx_power_control_validate)(fem_tx_power_control tx_power_control);
+	int8_t (*default_tx_output_power_get)(void);
 	uint32_t (*default_active_delay_calculate)(bool rx, nrf_radio_mode_t mode);
 	int (*antenna_select)(enum fem_antenna ant);
 };

lib/fem_al/generic_fem.c

@@ -148,7 +148,7 @@ static int generic_fem_power_down(void)
 	return err;
 }
 
-static uint32_t tx_default_gain_get(void)
+static int8_t default_tx_output_power_get(void)
 {
 	return DT_PROP(DT_NODELABEL(nrf_radio_fem), tx_gain_db);
 }
@@ -188,7 +188,7 @@ static const struct fem_interface_api generic_fem_api = {
 	.power_up = generic_fem_power_up,
 	.power_down = generic_fem_power_down,
 	.antenna_select = generic_fem_antenna_select,
-	.tx_default_gain_get = tx_default_gain_get,
+	.default_tx_output_power_get = default_tx_output_power_get,
 };
 
 static int generic_fem_setup(void)

lib/fem_al/nrf21540.c

@@ -64,16 +64,16 @@ static int nrf21540_init(void)
 	return 0;
 }
 
-static int tx_gain_validate(uint32_t gain)
+static int tx_power_control_validate(fem_tx_power_control tx_power_control)
 {
 	if (IS_ENABLED(CONFIG_MPSL_FEM_NRF21540_GPIO_SPI)) {
-		return (gain > NRF21540_TX_GAIN_MAX) ? -EINVAL : 0;
+		return (tx_power_control > NRF21540_TX_GAIN_MAX) ? -EINVAL : 0;
 	} else {
-		return ((gain == 0) || (gain == 1)) ? 0 : -EINVAL;
+		return ((tx_power_control == 0) || (tx_power_control == 1)) ? 0 : -EINVAL;
 	}
 }
 
-static uint32_t tx_default_gain_get(void)
+static int8_t default_tx_output_power_get(void)
 {
 	return CONFIG_MPSL_FEM_NRF21540_TX_GAIN_DB;
 }
@@ -108,8 +108,8 @@ static int nrf21540_antenna_select(enum fem_antenna ant)
 #endif /* DT_NODE_HAS_PROP(NRF21540_NODE, ant_sel_gpios) */
 
 static const struct fem_interface_api nrf21540_api = {
-	.tx_gain_validate = tx_gain_validate,
-	.tx_default_gain_get = tx_default_gain_get,
+	.tx_power_control_validate = tx_power_control_validate,
+	.default_tx_output_power_get = default_tx_output_power_get,
 	.antenna_select = nrf21540_antenna_select
 };