1 /***************************************************************************//**
2 * @file
3 * @brief PA power conversion curve types used by Silicon Labs PA power
4 * conversion functions.
5 * @details This file contains the curve types needed convert PA power levels
6 * to dBm powers.
7 *******************************************************************************
8 * # License
9 * <b>Copyright 2020 Silicon Laboratories Inc. www.silabs.com</b>
10 *******************************************************************************
11 *
12 * SPDX-License-Identifier: Zlib
13 *
14 * The licensor of this software is Silicon Laboratories Inc.
15 *
16 * This software is provided 'as-is', without any express or implied
17 * warranty. In no event will the authors be held liable for any damages
18 * arising from the use of this software.
19 *
20 * Permission is granted to anyone to use this software for any purpose,
21 * including commercial applications, and to alter it and redistribute it
22 * freely, subject to the following restrictions:
23 *
24 * 1. The origin of this software must not be misrepresented; you must not
25 * claim that you wrote the original software. If you use this software
26 * in a product, an acknowledgment in the product documentation would be
27 * appreciated but is not required.
28 * 2. Altered source versions must be plainly marked as such, and must not be
29 * misrepresented as being the original software.
30 * 3. This notice may not be removed or altered from any source distribution.
31 *
32 ******************************************************************************/
33
34 #ifndef PA_CURVE_TYPES_EFR32_H
35 #define PA_CURVE_TYPES_EFR32_H
36
37 #include "rail_types.h"
38
39 #ifdef __cplusplus
40 extern "C" {
41 #endif
42
43 /**
44 * @struct RAIL_TxPowerCurves
45 *
46 * @brief Structure containing data defining each segment of the
47 * power (deci-dBm) to powerLevel mapping curve fits.
48 *
49 * Note, these used in an equation of the form:
50 *
51 * powerLevel * 1000 = slope * power + intercept
52 *
53 * powerLevel is the 0-252/0-248/1-7 values used in the RAIL_Get/SetTxPower
54 * functions, and power is the actual output power of the PA, specified
55 * in deci-dBm.
56 *
57 * @note If the curves are generated with
58 * maxPower and increment other than \ref RAIL_TX_POWER_CURVE_DEFAULT_MAX and
59 * \ref RAIL_TX_POWER_CURVE_DEFAULT_INCREMENT respectively, then the first
60 * \ref RAIL_TxPowerCurveSegment_t has its maxPowerLevel equal to
61 * \ref RAIL_TX_POWER_LEVEL_INVALID and its slope and intercept stores the
62 * maxPower and increment in deci-dBm respectively.
63 */
64 typedef struct RAIL_TxPowerCurveSegment {
65 /** The highest power level that this segment will be used to convert */
66 uint16_t maxPowerLevel;
67 /** slope of the line */
68 int16_t slope;
69 /** y-intercept of the line */
70 int32_t intercept;
71 } RAIL_TxPowerCurveSegment_t;
72
73 /**
74 * @struct RAIL_TxPowerCurves
75 *
76 * @brief Structure containing the min and max values for a given
77 * PA and voltage supply combination (in deci-dBm).
78 */
79 typedef struct RAIL_TxPowerCurves {
80 /** max deci-dBm value */
81 int16_t maxPower;
82 /** min deci-dBm value */
83 int16_t minPower;
84 /**
85 * Pointer to "piecewiseSegments"-length array of
86 * RAIL_TxPowerCurveSegment_t of power (deci-dBm) to
87 * powerLevel conversion fits.
88 */
89 const RAIL_TxPowerCurveSegment_t *powerParams;
90 } RAIL_TxPowerCurves_t;
91
92 /**
93 * @struct RAIL_TxPowerCurvesConfig
94 *
95 * @brief Structure containing curve fit information and other metadata
96 * required to properly use the WEAK versions of RAIL_ConvertRawToDb
97 * and RAIL_ConvertDbmToRaw
98 */
99 typedef struct RAIL_TxPowerCurvesConfig {
100 /**
101 * Pointer a RAIL_TxPowerCurves_t representing the piecewise linear segments
102 * of curves that map power level to power in dBm for the 2.4 GHz high power
103 * PA.
104 *
105 * @note By the default conversion implementation, segments must be specified
106 * in decreasing power order. That is, the 0th entry of this array should be
107 * used to convert the highest power (levels). Segment at position n is valid
108 * from maxPowerLevel+1 from the segment at n+1 (or 0 if n is array length -
109 * 1) to maxPowerLevel of segment n, inclusive.
110 */
111 const RAIL_TxPowerCurves_t *txPower24HpCurves;
112
113 /**
114 * Pointer a RAIL_TxPowerCurves_t representing the piecewise linear segments
115 * of curves that map power level to power in dBm for the subgig PA.
116 *
117 * @note By the default conversion implementation, segments must be specified
118 * in decreasing power order. That is, the 0th entry of this array should be
119 * used to convert the highest power (levels). Segment at position n is valid
120 * from maxPowerLevel+1 from the segment at n+1 (or 0 if n is array length -
121 * 1) to maxPowerLevel of segment n, inclusive.
122 */
123 const RAIL_TxPowerCurves_t *txPowerSgCurves;
124
125 /**
126 * Look up table for each of the power levels of the 2.4GHz low power
127 * amplifier and their equivalent deci-dB value.
128 */
129 const int16_t *txPower24LpCurves;
130 /**
131 * The number of piecewise segments provided to the PA in each of the four
132 * conversion curve fits. The default is 8, but regardless of the number, it
133 * must be the same for all curves.
134 */
135 uint8_t piecewiseSegments;
136 } RAIL_TxPowerCurvesConfig_t;
137
138 /// PA conversion algorithms types for converting between dBm and power levels
RAIL_ENUM(RAIL_PaConversionAlgorithm_t)139 RAIL_ENUM(RAIL_PaConversionAlgorithm_t) {
140 RAIL_PA_ALGORITHM_PIECEWISE_LINEAR, /** Piecewise linear fit */
141 RAIL_PA_ALGORITHM_MAPPING_TABLE, /** Mapping table between quantities */
142 RAIL_PA_ALGORITHM_DBM_POWERSETTING_MAPPING_TABLE, /** Mapping table between pa power settings and dBm values */
143 };
144
145 #ifndef DOXYGEN_SHOULD_SKIP_THIS
146 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
147 #define RAIL_PA_ALGORITHM_PIECEWISE_LINEAR ((RAIL_PaConversionAlgorithm_t) RAIL_PA_ALGORITHM_PIECEWISE_LINEAR)
148 #define RAIL_PA_ALGORITHM_MAPPING_TABLE ((RAIL_PaConversionAlgorithm_t) RAIL_PA_ALGORITHM_MAPPING_TABLE)
149 #define RAIL_PA_ALGORITHM_DBM_POWERSETTING_MAPPING_TABLE ((RAIL_PaConversionAlgorithm_t) RAIL_PA_ALGORITHM_DBM_POWERSETTING_MAPPING_TABLE)
150 #endif//DOXYGEN_SHOULD_SKIP_THIS
151
152 /**
153 * @struct RAIL_TxPowerCurvesAlt
154 *
155 * @brief Structure containing the min and max values for a given
156 * PA and voltage supply combination (in deci-dBm).
157 */
158 typedef struct RAIL_TxPowerCurveAlt {
159 /** max deci-dBm value */
160 int16_t maxPower;
161 /** min deci-dBm value */
162 int16_t minPower;
163 /**
164 * "piecewiseSegments"-length array of RAIL_TxPowerCurveSegment_t
165 * of power (deci-dBm) to powerLevel conversion fits.
166 */
167 //Array does not have a size since it can be various sizes.
168 //No further fields allowed after this one.
169 RAIL_TxPowerCurveSegment_t powerParams[];
170 } RAIL_TxPowerCurveAlt_t;
171
172 typedef union RAIL_PowerConversion {
173 /**
174 * Pointer to a powerCurve containing line segment data for the curves
175 * corresponding to a specific PA.
176 *
177 * @note By the default conversion implementation, segments must be specified
178 * in decreasing power order. That is, the 0th entry of this array should be
179 * used to convert the highest power (levels). Segment at position n is valid
180 * from maxPowerLevel+1 from the segment at n+1 (or 0 if n is array length -
181 * 1) to maxPowerLevel of segment n, inclusive.
182 */
183 const RAIL_TxPowerCurveAlt_t *powerCurve;
184 /**
185 * Lookup table for PA's which use the mapping table algorithm for converting
186 * between deci-dBm and power levels.
187 */
188 #if RAIL_SUPPORTS_DBM_POWERSETTING_MAPPING_TABLE
189 const int32_t *mappingTable;
190 #else
191 const int16_t *mappingTable;
192 #endif
193 } RAIL_PowerConversion_t;
194
195 /// PA descriptor as used in the PA conversion functions
196 typedef struct RAIL_PaDescriptor {
197 /** Algorithm used to map dBm to power levels for this PA */
198 RAIL_PaConversionAlgorithm_t algorithm;
199 /**
200 * The number of piecewise segments provided to the PA in a piecewise linear
201 * curve fit. The default is 8. Should be set to 0 when not using the
202 * piecewise linear algorithm.
203 */
204 uint8_t segments;
205 /** Min power level for this PA */
206 RAIL_TxPowerLevel_t min;
207 /** Max power level for this PA */
208 RAIL_TxPowerLevel_t max;
209 #if RAIL_SUPPORTS_DBM_POWERSETTING_MAPPING_TABLE
210 RAIL_TxPowerLevel_t step; /** step size in deci-dBm between entries in table */
211 uint8_t padding;
212 uint16_t padding2;
213 RAIL_TxPower_t minPowerDbm; /** Min power in deci-dBm for this PA */
214 RAIL_TxPower_t maxPowerDbm; /** Max power in deci-dBm for this PA */
215 #endif
216 /** Union containing a pointer to algorithm-specific conversion data. */
217 RAIL_PowerConversion_t conversion;
218 } RAIL_PaDescriptor_t;
219
220 /**
221 * @typedef RAIL_TxPowerCurvesConfigAlt_t
222 *
223 * @brief More generic structure containing information about
224 * piecewise linear curves and mapping tables, instead of specific PA's.
225 */
226 typedef struct RAIL_TxPowerCurvesConfigAlt {
227 RAIL_PaDescriptor_t curves[RAIL_NUM_PA];
228 uint32_t signature;
229 uint16_t paVoltage;
230 } RAIL_TxPowerCurvesConfigAlt_t;
231
232 #ifdef __cplusplus
233 }
234 #endif
235
236 #endif // PA_CURVE_TYPES_EFR32_H
237
