1 /***************************************************************************//**
2  * @file
3  * @brief This file contains the type definitions for RAIL structures, enums,
4  *   and other types.
5  *******************************************************************************
6  * # License
7  * <b>Copyright 2020 Silicon Laboratories Inc. www.silabs.com</b>
8  *******************************************************************************
9  *
10  * SPDX-License-Identifier: Zlib
11  *
12  * The licensor of this software is Silicon Laboratories Inc.
13  *
14  * This software is provided 'as-is', without any express or implied
15  * warranty. In no event will the authors be held liable for any damages
16  * arising from the use of this software.
17  *
18  * Permission is granted to anyone to use this software for any purpose,
19  * including commercial applications, and to alter it and redistribute it
20  * freely, subject to the following restrictions:
21  *
22  * 1. The origin of this software must not be misrepresented; you must not
23  *    claim that you wrote the original software. If you use this software
24  *    in a product, an acknowledgment in the product documentation would be
25  *    appreciated but is not required.
26  * 2. Altered source versions must be plainly marked as such, and must not be
27  *    misrepresented as being the original software.
28  * 3. This notice may not be removed or altered from any source distribution.
29  *
30  ******************************************************************************/
31 
32 #ifndef __RAIL_TYPES_H__
33 #define __RAIL_TYPES_H__
34 
35 // Include standard type headers to help define structures
36 #include <stdint.h>
37 #include <stdbool.h>
38 #include <stddef.h>
39 
40 #ifdef __cplusplus
41 extern "C" {
42 #endif
43 
44 #ifdef DOXYGEN_SHOULD_SKIP_THIS
45 /// The RAIL library does not use enumerations because the ARM EABI leaves their
46 /// size ambiguous, which causes problems if the application is built
47 /// with different flags than the library. Instead, uint8_t typedefs
48 /// are used in compiled code for all enumerations. For documentation purposes, this is
49 /// converted to an actual enumeration since it's much easier to read in Doxygen.
50 #define RAIL_ENUM(name) enum name
51 /// This macro is a more generic version of the \ref RAIL_ENUM() macro that
52 /// allows the size of the type to be overridden instead of forcing the use of
53 /// a uint8_t. See \ref RAIL_ENUM() for more information.
54 #define RAIL_ENUM_GENERIC(name, type) enum name
55 #else
56 /// Define used for the RAIL library, which sets each enumeration to a uint8_t
57 /// typedef and creates a named enumeration structure for the enumeration values.
58 #define RAIL_ENUM(name) typedef uint8_t name; enum name##_enum
59 #define RAIL_ENUM_GENERIC(name, type) typedef type name; enum name##_enum
60 // For debugging, use the following define to turn this back into a proper enumeration
61 // #define RAIL_ENUM(name) typedef enum name##_enum name; enum name##_enum
62 #endif
63 
64 /**
65  * @addtogroup RAIL_API
66  * @{
67  */
68 
69 /******************************************************************************
70  * General Structures
71  *****************************************************************************/
72 /**
73  * @addtogroup General
74  * @{
75  */
76 
77 /**
78  * @struct RAIL_Version_t
79  * @brief Contains RAIL Library Version Information.
80  *   It is filled in by RAIL_GetVersion().
81  */
82 typedef struct RAIL_Version {
83   uint32_t hash;      /**< Git hash */
84   uint8_t  major;     /**< Major number    */
85   uint8_t  minor;     /**< Minor number    */
86   uint8_t  rev;       /**< Revision number */
87   uint8_t  build;     /**< Build number */
88   uint8_t  flags;     /**< Build flags */
89   /** Boolean to indicate whether this is a multiprotocol library or not. */
90   bool     multiprotocol;
91 } RAIL_Version_t;
92 
93 /**
94  * @typedef RAIL_Handle_t
95  * @brief A generic handle to a particular radio (e.g. RAIL_EFR32_HANDLE),
96  *   or a real handle of a RAIL instance, as returned from RAIL_Init().
97  *
98  * Generic handles should be used for certain RAIL APIs that are called
99  * prior to RAIL initialization. However, once RAIL has been initialized,
100  * the real handle returned by RAIL_Init() should be used instead.
101  */
102 typedef void *RAIL_Handle_t;
103 
104 /**
105  * @enum RAIL_Status_t
106  * @brief A status returned by many RAIL API calls indicating their success or
107  *   failure.
108  */
RAIL_ENUM(RAIL_Status_t)109 RAIL_ENUM(RAIL_Status_t) {
110   RAIL_STATUS_NO_ERROR, /**< RAIL function reports no error. */
111   RAIL_STATUS_INVALID_PARAMETER, /**< Call to RAIL function threw an error
112                                       because of an invalid parameter. */
113   RAIL_STATUS_INVALID_STATE, /**< Call to RAIL function threw an error
114                                   because it was called during an invalid
115                                   radio state. */
116   RAIL_STATUS_INVALID_CALL, /**< RAIL function is called in an invalid order. */
117   RAIL_STATUS_SUSPENDED, /**< RAIL function did not finish in the allotted
118                               time. */
119   RAIL_STATUS_SCHED_ERROR, /**< RAIL function could not be scheduled
120                                 by the Radio scheduler. Only issued when
121                                 using a Multiprotocol application. */
122 };
123 
124 #ifndef DOXYGEN_SHOULD_SKIP_THIS
125 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
126 #define RAIL_STATUS_NO_ERROR          ((RAIL_Status_t) RAIL_STATUS_NO_ERROR)
127 #define RAIL_STATUS_INVALID_PARAMETER ((RAIL_Status_t) RAIL_STATUS_INVALID_PARAMETER)
128 #define RAIL_STATUS_INVALID_STATE     ((RAIL_Status_t) RAIL_STATUS_INVALID_STATE)
129 #define RAIL_STATUS_INVALID_CALL      ((RAIL_Status_t) RAIL_STATUS_INVALID_CALL)
130 #define RAIL_STATUS_SUSPENDED         ((RAIL_Status_t) RAIL_STATUS_SUSPENDED)
131 #define RAIL_STATUS_SCHED_ERROR       ((RAIL_Status_t) RAIL_STATUS_SCHED_ERROR)
132 #endif//DOXYGEN_SHOULD_SKIP_THIS
133 
134 /**
135  * A pointer to init complete callback function
136  *
137  * @param[in] railHandle The initialized RAIL instance handle.
138  *
139  */
140 typedef void (*RAIL_InitCompleteCallbackPtr_t)(RAIL_Handle_t railHandle);
141 
142 /** A value to signal that RAIL should not use DMA. */
143 #define RAIL_DMA_INVALID (0xFFU)
144 
145 #ifndef DOXYGEN_SHOULD_SKIP_THIS
146 
147 /**
148  * A linked list structure for RAIL state buffers which \ref RAIL_Init()
149  * utilizes for managing internal RAIL state.
150  */
151 typedef struct RAIL_StateBufferEntry {
152   struct RAIL_StateBufferEntry *next; /**< pointer to next buffer in linked list */
153   uint32_t bufferBytes;               /**< size of the buffer */
154   uint64_t *buffer;                   /**< pointer to the buffer in RAM */
155 } RAIL_StateBufferEntry_t;
156 
157 #endif//DOXYGEN_SHOULD_SKIP_THIS
158 
159 /** @} */ // end of group General
160 
161 /******************************************************************************
162  * System Timing Structures
163  *****************************************************************************/
164 /**
165  * @addtogroup System_Timing
166  * @{
167  */
168 
169 /**
170  * @typedef RAIL_Time_t
171  * @brief Time in microseconds
172  */
173 typedef uint32_t RAIL_Time_t;
174 
175 #ifndef DOXYGEN_SHOULD_SKIP_THIS
176 /**
177  * @typedef RAIL_TimerTick_t
178  * @brief Internal RAIL hardware timer tick that drives the RAIL timebase.
179  *
180  * @note \ref RAIL_TimerTick_t does not use the full 32-bit range since we also
181  *   account for fractional error drift on timebase overflow. This counts up
182  *   to ~17 minutes before wrapping.
183  *
184  * @note \ref RAIL_TimerTicksToUs() can be used to convert the delta between
185  *   two \ref RAIL_TimerTick_t values to microseconds.
186  */
187 typedef uint32_t RAIL_TimerTick_t;
188 #endif//DOXYGEN_SHOULD_SKIP_THIS
189 
190 /**
191  * A pointer to the callback called when the RAIL timer expires.
192  *
193  * @param[in] cbArg The argument passed to the callback.
194  */
195 typedef void (*RAIL_TimerCallback_t)(RAIL_Handle_t cbArg);
196 
197 /**
198  * @enum RAIL_TimeMode_t
199  * @brief Specify a time offset in RAIL APIs.
200  *
201  * Different APIs use the same constants and may provide more specifics about
202  * how they're used but the general use for each is described below.
203  */
RAIL_ENUM(RAIL_TimeMode_t)204 RAIL_ENUM(RAIL_TimeMode_t) {
205   /**
206    * The time specified is an exact time in the RAIL timebase. The given
207    * event should happen at exactly that time. If this time is already in the
208    * past, an error is returned. Because the RAIL timebase wraps at 32
209    * bits, there is no real 'past'. Instead, any event greater than
210    * 3/4 of the way into the future is considered to be in the past.
211    */
212   RAIL_TIME_ABSOLUTE,
213   /**
214    * The time specified is relative to the current time. The event should occur
215    * that many ticks in the future. Delays are only guaranteed at least as long
216    * as the value specified. An overhead may occur between the time when the
217    * API is called and when the delay starts. As a result, using this for
218    * operations that must happen at an exact given time is not recommended.
219    * For that, you must use \ref RAIL_TIME_ABSOLUTE delays.
220    *
221    * Note that, if you specify a delay 0, that event is triggered as soon as
222    * possible. This is different than specifying an absolute time of now which
223    * would return an error unless it was possible.
224    */
225   RAIL_TIME_DELAY,
226   /**
227    * The specified time is invalid and should be ignored. For some APIs this
228    * can also indicate that any previously stored delay should be invalidated
229    * and disabled.
230    */
231   RAIL_TIME_DISABLED,
232 };
233 
234 #ifndef DOXYGEN_SHOULD_SKIP_THIS
235 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
236 #define RAIL_TIME_ABSOLUTE ((RAIL_TimeMode_t) RAIL_TIME_ABSOLUTE)
237 #define RAIL_TIME_DELAY    ((RAIL_TimeMode_t) RAIL_TIME_DELAY)
238 #define RAIL_TIME_DISABLED ((RAIL_TimeMode_t) RAIL_TIME_DISABLED)
239 #endif//DOXYGEN_SHOULD_SKIP_THIS
240 
241 /// Forward declaration of RAIL_MultiTimer
242 struct RAIL_MultiTimer;
243 
244 /**
245  * @typedef RAIL_MultiTimerCallback_t
246  * @brief Callback fired when timer expires.
247  *
248  * @param[in] tmr A pointer to an expired timer.
249  * @param[in] expectedTimeOfEvent An absolute time event fired.
250  * @param[in] cbArg A user-supplied callback argument.
251  */
252 typedef void (*RAIL_MultiTimerCallback_t)(struct RAIL_MultiTimer *tmr,
253                                           RAIL_Time_t expectedTimeOfEvent,
254                                           void *cbArg);
255 
256 /**
257  * @struct RAIL_MultiTimer_t
258  * @brief RAIL timer state structure
259  *
260  * This structure is filled out and maintained internally only.
261  * The user/application should not alter any elements of this structure.
262  */
263 typedef struct RAIL_MultiTimer {
264   RAIL_Time_t       absOffset;        /**< Absolute time before the next event. */
265   RAIL_Time_t       relPeriodic;      /**< Relative, periodic time between events; 0 = timer is oneshot. */
266   RAIL_MultiTimerCallback_t callback; /**< A user callback. */
267   void                *cbArg;          /**< A user callback argument. */
268   struct RAIL_MultiTimer   *next;          /**< A pointer to the next soft timer structure. */
269   uint8_t             priority;       /**< A priority of the callback; 0 = highest priority; 255 = lowest. */
270   bool                isRunning;      /**< Indicates the timer is currently running. */
271   bool                doCallback;     /**< Indicates the callback needs to run. */
272 } RAIL_MultiTimer_t;
273 
274 /**
275  * @enum RAIL_PacketTimePosition_t
276  * @brief The available packet timestamp position choices
277  */
RAIL_ENUM(RAIL_PacketTimePosition_t)278 RAIL_ENUM(RAIL_PacketTimePosition_t) {
279   /**
280    * Indicate that a timestamp is not to be or was not provided.
281    * It is useful if the application doesn't care about packet timestamps
282    * and doesn't want RAIL to spend time calculating one.
283    */
284   RAIL_PACKET_TIME_INVALID = 0,
285   /**
286    * Request the choice most expedient for RAIL to calculate,
287    * which may depend on the radio and/or its configuration.
288    * The actual choice would always be reflected in the timePosition
289    * field of \ref RAIL_RxPacketDetails_t or \ref RAIL_TxPacketDetails_t
290    * returned and would never be one of the _USED_TOTAL values.
291    */
292   RAIL_PACKET_TIME_DEFAULT = 1,
293   /**
294    * Request the timestamp corresponding to the first preamble bit
295    * sent or received.
296    * Indicate that timestamp did not require using totalPacketBytes.
297    */
298   RAIL_PACKET_TIME_AT_PREAMBLE_START = 2,
299   /**
300    * Request the timestamp corresponding to the first preamble bit
301    * sent or received.
302    * Indicate that timestamp did require using totalPacketBytes.
303    */
304   RAIL_PACKET_TIME_AT_PREAMBLE_START_USED_TOTAL = 3,
305   /**
306    * Request the timestamp corresponding to right after its last
307    * SYNC word bit has been sent or received.
308    * Indicate that timestamp did not require using totalPacketBytes.
309    */
310   RAIL_PACKET_TIME_AT_SYNC_END = 4,
311   /**
312    * Request the timestamp corresponding to right after its last
313    * SYNC word bit has been sent or received.
314    * Indicate that timestamp did require using totalPacketBytes.
315    */
316   RAIL_PACKET_TIME_AT_SYNC_END_USED_TOTAL = 5,
317   /**
318    * Request the timestamp corresponding to right after its last
319    * bit has been sent or received.
320    * Indicate that timestamp did not require using totalPacketBytes.
321    */
322   RAIL_PACKET_TIME_AT_PACKET_END = 6,
323   /**
324    * Request the timestamp corresponding to right after its last
325    * bit has been sent or received.
326    * Indicate that timestamp did require using totalPacketBytes.
327    */
328   RAIL_PACKET_TIME_AT_PACKET_END_USED_TOTAL = 7,
329   RAIL_PACKET_TIME_COUNT /**< A count of the choices in this enumeration. */
330 };
331 
332 #ifndef DOXYGEN_SHOULD_SKIP_THIS
333 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
334 #define RAIL_PACKET_TIME_INVALID                      ((RAIL_PacketTimePosition_t) RAIL_PACKET_TIME_INVALID)
335 #define RAIL_PACKET_TIME_DEFAULT                      ((RAIL_PacketTimePosition_t) RAIL_PACKET_TIME_DEFAULT)
336 #define RAIL_PACKET_TIME_AT_PREAMBLE_START            ((RAIL_PacketTimePosition_t) RAIL_PACKET_TIME_AT_PREAMBLE_START)
337 #define RAIL_PACKET_TIME_AT_PREAMBLE_START_USED_TOTAL ((RAIL_PacketTimePosition_t) RAIL_PACKET_TIME_AT_PREAMBLE_START_USED_TOTAL)
338 #define RAIL_PACKET_TIME_AT_SYNC_END                  ((RAIL_PacketTimePosition_t) RAIL_PACKET_TIME_AT_SYNC_END)
339 #define RAIL_PACKET_TIME_AT_SYNC_END_USED_TOTAL       ((RAIL_PacketTimePosition_t) RAIL_PACKET_TIME_AT_SYNC_END_USED_TOTAL)
340 #define RAIL_PACKET_TIME_AT_PACKET_END                ((RAIL_PacketTimePosition_t) RAIL_PACKET_TIME_AT_PACKET_END)
341 #define RAIL_PACKET_TIME_AT_PACKET_END_USED_TOTAL     ((RAIL_PacketTimePosition_t) RAIL_PACKET_TIME_AT_PACKET_END_USED_TOTAL)
342 #define RAIL_PACKET_TIME_COUNT                        ((RAIL_PacketTimePosition_t) RAIL_PACKET_TIME_COUNT)
343 #endif//DOXYGEN_SHOULD_SKIP_THIS
344 
345 /**
346  * @struct RAIL_PacketTimeStamp_t
347  * @brief Information for calculating and representing a packet timestamp.
348  */
349 typedef struct RAIL_PacketTimeStamp {
350   /**
351    * Timestamp of the packet in the RAIL timebase.
352    */
353   RAIL_Time_t packetTime;
354   /**
355    * A value specifying the total length in bytes of the packet
356    * used when calculating the packetTime requested by the timePosition
357    * field. This should account for all bytes sent over the air after
358    * the Preamble and Sync word(s) including CRC bytes.
359    */
360   uint16_t totalPacketBytes;
361   /**
362    * A RAIL_PacketTimePosition_t value specifying the packet position
363    * to return in the packetTime field.
364    * If this is \ref RAIL_PACKET_TIME_DEFAULT, this field will be
365    * updated with the actual position corresponding to the packetTime
366    * value filled in by a call using this structure.
367    */
368   RAIL_PacketTimePosition_t timePosition;
369   /**
370    * A value specifying the on-air duration of the data packet,
371    * starting with the first bit of the PHR (i.e. end of sync word).
372    * Preamble and sync word duration are hence excluded.
373    * Only valid for receive packets at the present time on EFR32xG25 only.
374    */
375   RAIL_Time_t packetDurationUs;
376 } RAIL_PacketTimeStamp_t;
377 
378 /** @} */ // end of group System_Timing
379 
380 /**
381  * @addtogroup Sleep
382  * @{
383  */
384 
385 /**
386  * @enum RAIL_SleepConfig_t
387  * @brief The configuration
388  */
RAIL_ENUM(RAIL_SleepConfig_t)389 RAIL_ENUM(RAIL_SleepConfig_t) {
390   RAIL_SLEEP_CONFIG_TIMERSYNC_DISABLED, /**< Disable timer sync before and after sleep. */
391   RAIL_SLEEP_CONFIG_TIMERSYNC_ENABLED, /**< Enable timer sync before and after sleep. */
392 };
393 
394 #ifndef DOXYGEN_SHOULD_SKIP_THIS
395 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
396 #define RAIL_SLEEP_CONFIG_TIMERSYNC_DISABLED ((RAIL_SleepConfig_t) RAIL_SLEEP_CONFIG_TIMERSYNC_DISABLED)
397 #define RAIL_SLEEP_CONFIG_TIMERSYNC_ENABLED  ((RAIL_SleepConfig_t) RAIL_SLEEP_CONFIG_TIMERSYNC_ENABLED)
398 #endif//DOXYGEN_SHOULD_SKIP_THIS
399 
400 /**
401  * @struct RAIL_TimerSyncConfig_t
402  * @brief Channel values used to perform timer sync before and after sleep.
403  *
404  * The default value of this structure is provided in the
405  * \ref RAIL_TIMER_SYNC_DEFAULT macro.
406  */
407 typedef struct RAIL_TimerSyncConfig {
408   /**
409    * PRS Channel used for timer sync operations.
410    */
411   uint8_t prsChannel;
412   /**
413    * RTCC Channel used for timer sync operations
414    */
415   uint8_t rtccChannel;
416   /**
417    * Whether to sync the timer before and after sleeping
418    */
419   RAIL_SleepConfig_t sleep;
420 } RAIL_TimerSyncConfig_t;
421 
422 /** @} */ // end of group Sleep
423 
424 /******************************************************************************
425  * Multiprotocol Structures
426  *****************************************************************************/
427 /**
428  * @addtogroup Multiprotocol
429  * @{
430  */
431 
432 /**
433  * @struct RAIL_SchedulerInfo_t
434  * @brief A structure to hold information used by the scheduler.
435  *
436  * For multiprotocol versions of RAIL, this can be used to control how a receive
437  * or transmit operation is run. It's not necessary in single-protocol applications.
438  */
439 typedef struct RAIL_SchedulerInfo {
440   /**
441    * The scheduler priority to use for this operation. This priority is used to
442    * preempt a long running lower-priority task to ensure higher-priority
443    * operations complete in time. A lower numerical value represents a higher
444    * logical priority meaning 0 is the highest priority and 255 is the lowest.
445    */
446   uint8_t priority;
447   /**
448    * The amount of time in us that this operation can slip by into the future
449    * and still be run. This time is relative to the start time which may be
450    * the current time for relative transmits. If the scheduler can't start the
451    * operation by this time, it will be considered a failure.
452    */
453   RAIL_Time_t slipTime;
454   /**
455    * The transaction time in us for this operation. Since transaction times may
456    * not be known exactly, use a minimum or an expected
457    * guess for this time. The scheduler will use the value entered here to look
458    * for overlaps between low-priority and high-priority tasks and attempt to
459    * find a schedule where all tasks get to run.
460    */
461   RAIL_Time_t transactionTime;
462 } RAIL_SchedulerInfo_t;
463 
464 /** Radio Scheduler Status mask*/
465 #define RAIL_SCHEDULER_STATUS_MASK       0x0FU
466 /** Radio Scheduler Status shift*/
467 #define RAIL_SCHEDULER_STATUS_SHIFT      0
468 
469 /** Radio Scheduler Task mask*/
470 #define RAIL_SCHEDULER_TASK_MASK         0xF0U
471 /** Radio Scheduler Task shift*/
472 #define RAIL_SCHEDULER_TASK_SHIFT        4
473 /**
474  * @enum RAIL_SchedulerStatus_t
475  * @brief Multiprotocol scheduler status returned by RAIL_GetSchedulerStatus().
476  *
477  * \ref Multiprotocol scheduler status is a combination of the upper 4 bits which
478  * constitute the type of scheduler task and the lower 4 bits which constitute
479  * the type of scheduler error.
480  */
RAIL_ENUM(RAIL_SchedulerStatus_t)481 RAIL_ENUM(RAIL_SchedulerStatus_t) {
482   /** Lower 4 bits of uint8_t capture the different Radio Scheduler errors */
483   /** Multiprotocol scheduler reports no error. */
484   RAIL_SCHEDULER_STATUS_NO_ERROR = (0U << RAIL_SCHEDULER_STATUS_SHIFT),
485   /**
486    * The scheduler is disabled or the requested scheduler operation is
487    * unsupported.
488    */
489   RAIL_SCHEDULER_STATUS_UNSUPPORTED = (1U << RAIL_SCHEDULER_STATUS_SHIFT),
490   /**
491    * The scheduled task was started but was interrupted by a higher-priority
492    * event before it could be completed.
493    */
494   RAIL_SCHEDULER_STATUS_EVENT_INTERRUPTED = (2U << RAIL_SCHEDULER_STATUS_SHIFT),
495   /**
496    * Scheduled task could not be scheduled given its priority and the other
497    * tasks running on the system.
498    */
499   RAIL_SCHEDULER_STATUS_SCHEDULE_FAIL = (3U << RAIL_SCHEDULER_STATUS_SHIFT),
500   /**
501    * Calling the RAIL API associated with the Radio scheduler task returned
502    * an error code. See \ref RAIL_GetSchedulerStatus or \ref RAIL_GetSchedulerStatusAlt
503    * for more information about \ref RAIL_Status_t status.
504    */
505   RAIL_SCHEDULER_STATUS_TASK_FAIL = (4U << RAIL_SCHEDULER_STATUS_SHIFT),
506   /**
507    * An internal error occurred in scheduler data structures, which should
508    * not happen and indicates a problem.
509    */
510   RAIL_SCHEDULER_STATUS_INTERNAL_ERROR = (5U << RAIL_SCHEDULER_STATUS_SHIFT),
511 
512   /** Upper 4 bits of uint8_t capture the different Radio Scheduler tasks */
513   RAIL_SCHEDULER_TASK_EMPTY = (0U << RAIL_SCHEDULER_TASK_SHIFT),
514   /** Radio scheduler calls \ref RAIL_ScheduleRx(). */
515   RAIL_SCHEDULER_TASK_SCHEDULED_RX = (1U << RAIL_SCHEDULER_TASK_SHIFT),
516   /** Radio scheduler calls \ref RAIL_StartScheduledTx(). */
517   RAIL_SCHEDULER_TASK_SCHEDULED_TX = (2U << RAIL_SCHEDULER_TASK_SHIFT),
518   /** Radio scheduler calls \ref RAIL_StartTx(). */
519   RAIL_SCHEDULER_TASK_SINGLE_TX = (3U << RAIL_SCHEDULER_TASK_SHIFT),
520   /** Radio scheduler calls \ref RAIL_StartCcaCsmaTx(). */
521   RAIL_SCHEDULER_TASK_SINGLE_CCA_CSMA_TX = (4U << RAIL_SCHEDULER_TASK_SHIFT),
522   /** Radio scheduler calls \ref RAIL_StartCcaLbtTx(). */
523   RAIL_SCHEDULER_TASK_SINGLE_CCA_LBT_TX = (5U << RAIL_SCHEDULER_TASK_SHIFT),
524   /** Radio scheduler calls \ref RAIL_StartScheduledCcaCsmaTx(). */
525   RAIL_SCHEDULER_TASK_SCHEDULED_CCA_CSMA_TX = (6U << RAIL_SCHEDULER_TASK_SHIFT),
526   /** Radio scheduler calls \ref RAIL_StartScheduledCcaLbtTx(). */
527   RAIL_SCHEDULER_TASK_SCHEDULED_CCA_LBT_TX = (7U << RAIL_SCHEDULER_TASK_SHIFT),
528   /** Radio scheduler calls \ref RAIL_StartTxStream(). */
529   RAIL_SCHEDULER_TASK_TX_STREAM = (8U << RAIL_SCHEDULER_TASK_SHIFT),
530   /** Radio scheduler calls \ref RAIL_StartAverageRssi(). */
531   RAIL_SCHEDULER_TASK_AVERAGE_RSSI = (9U << RAIL_SCHEDULER_TASK_SHIFT),
532 
533   /** \ref RAIL_StartScheduledTx() returned error status. */
534   RAIL_SCHEDULER_STATUS_SCHEDULED_TX_FAIL = (RAIL_SCHEDULER_TASK_SCHEDULED_TX
535                                              | RAIL_SCHEDULER_STATUS_TASK_FAIL),
536   /** \ref RAIL_StartTx() returned error status. */
537   RAIL_SCHEDULER_STATUS_SINGLE_TX_FAIL = (RAIL_SCHEDULER_TASK_SINGLE_TX
538                                           | RAIL_SCHEDULER_STATUS_TASK_FAIL),
539   /** \ref RAIL_StartCcaCsmaTx() returned error status. */
540   RAIL_SCHEDULER_STATUS_CCA_CSMA_TX_FAIL = (RAIL_SCHEDULER_TASK_SINGLE_CCA_CSMA_TX
541                                             | RAIL_SCHEDULER_STATUS_TASK_FAIL),
542   /** \ref RAIL_StartCcaLbtTx() returned error status. */
543   RAIL_SCHEDULER_STATUS_CCA_LBT_TX_FAIL = (RAIL_SCHEDULER_TASK_SINGLE_CCA_LBT_TX
544                                            | RAIL_SCHEDULER_STATUS_TASK_FAIL),
545   /** \ref RAIL_ScheduleRx() returned error status. */
546   RAIL_SCHEDULER_STATUS_SCHEDULED_RX_FAIL = (RAIL_SCHEDULER_TASK_SCHEDULED_RX
547                                              | RAIL_SCHEDULER_STATUS_TASK_FAIL),
548   /** \ref RAIL_StartTxStream() returned error status. */
549   RAIL_SCHEDULER_STATUS_TX_STREAM_FAIL = (RAIL_SCHEDULER_TASK_TX_STREAM
550                                           | RAIL_SCHEDULER_STATUS_TASK_FAIL),
551   /** \ref RAIL_StartAverageRssi() returned error status. */
552   RAIL_SCHEDULER_STATUS_AVERAGE_RSSI_FAIL = (RAIL_SCHEDULER_TASK_AVERAGE_RSSI
553                                              | RAIL_SCHEDULER_STATUS_TASK_FAIL),
554 
555   /** Multiprotocol scheduled receive function internal error. */
556   RAIL_SCHEDULER_SCHEDULED_RX_INTERNAL_ERROR = (RAIL_SCHEDULER_TASK_SCHEDULED_RX
557                                                 | RAIL_SCHEDULER_STATUS_INTERNAL_ERROR),
558   /** Multiprotocol scheduled receive scheduling error. */
559   RAIL_SCHEDULER_SCHEDULED_RX_SCHEDULING_ERROR = (RAIL_SCHEDULER_TASK_SCHEDULED_RX
560                                                   | RAIL_SCHEDULER_STATUS_SCHEDULE_FAIL),
561   /** \ref RAIL_ScheduleRx() operation interrupted */
562   RAIL_SCHEDULER_SCHEDULED_RX_INTERRUPTED = (RAIL_SCHEDULER_TASK_SCHEDULED_RX
563                                              | RAIL_SCHEDULER_STATUS_EVENT_INTERRUPTED),
564 
565   /** Multiprotocol scheduled TX internal error. */
566   RAIL_SCHEDULER_SCHEDULED_TX_INTERNAL_ERROR = (RAIL_SCHEDULER_TASK_SCHEDULED_TX
567                                                 | RAIL_SCHEDULER_STATUS_INTERNAL_ERROR),
568   /** Multiprotocol scheduled TX scheduling error. */
569   RAIL_SCHEDULER_SCHEDULED_TX_SCHEDULING_ERROR = (RAIL_SCHEDULER_TASK_SCHEDULED_TX
570                                                   | RAIL_SCHEDULER_STATUS_SCHEDULE_FAIL),
571   /** \ref RAIL_StartScheduledTx() operation interrupted */
572   RAIL_SCHEDULER_SCHEDULED_TX_INTERRUPTED = (RAIL_SCHEDULER_TASK_SCHEDULED_TX
573                                              | RAIL_SCHEDULER_STATUS_EVENT_INTERRUPTED),
574 
575   /** Multiprotocol instantaneous TX internal error. */
576   RAIL_SCHEDULER_SINGLE_TX_INTERNAL_ERROR = (RAIL_SCHEDULER_TASK_SINGLE_TX
577                                              | RAIL_SCHEDULER_STATUS_INTERNAL_ERROR),
578   /** Multiprotocol instantaneous TX scheduling error. */
579   RAIL_SCHEDULER_SINGLE_TX_SCHEDULING_ERROR = (RAIL_SCHEDULER_TASK_SINGLE_TX
580                                                | RAIL_SCHEDULER_STATUS_SCHEDULE_FAIL),
581   /** \ref RAIL_StartTx() operation interrupted */
582   RAIL_SCHEDULER_SINGLE_TX_INTERRUPTED = (RAIL_SCHEDULER_TASK_SINGLE_TX
583                                           | RAIL_SCHEDULER_STATUS_EVENT_INTERRUPTED),
584 
585   /** Multiprotocol single CSMA transmit function internal error. */
586   RAIL_SCHEDULER_SINGLE_CCA_CSMA_TX_INTERNAL_ERROR = (RAIL_SCHEDULER_TASK_SINGLE_CCA_CSMA_TX
587                                                       | RAIL_SCHEDULER_STATUS_INTERNAL_ERROR),
588   /** Multiprotocol single CSMA transmit scheduling error. */
589   RAIL_SCHEDULER_SINGLE_CCA_CSMA_TX_SCHEDULING_ERROR = (RAIL_SCHEDULER_TASK_SINGLE_CCA_CSMA_TX
590                                                         | RAIL_SCHEDULER_STATUS_SCHEDULE_FAIL),
591   /** \ref RAIL_StartCcaCsmaTx() operation interrupted */
592   RAIL_SCHEDULER_SINGLE_CCA_CSMA_TX_INTERRUPTED = (RAIL_SCHEDULER_TASK_SINGLE_CCA_CSMA_TX
593                                                    | RAIL_SCHEDULER_STATUS_EVENT_INTERRUPTED),
594 
595   /** Multiprotocol single LBT transmit function internal error. */
596   RAIL_SCHEDULER_SINGLE_CCA_LBT_TX_INTERNAL_ERROR = (RAIL_SCHEDULER_TASK_SINGLE_CCA_LBT_TX
597                                                      | RAIL_SCHEDULER_STATUS_INTERNAL_ERROR),
598   /** Multiprotocol single LBT transmit scheduling error. */
599   RAIL_SCHEDULER_SINGLE_CCA_LBT_TX_SCHEDULING_ERROR = (RAIL_SCHEDULER_TASK_SINGLE_CCA_LBT_TX
600                                                        | RAIL_SCHEDULER_STATUS_SCHEDULE_FAIL),
601   /** \ref RAIL_StartCcaLbtTx() operation interrupted */
602   RAIL_SCHEDULER_SINGLE_CCA_LBT_TX_INTERRUPTED = (RAIL_SCHEDULER_TASK_SINGLE_CCA_LBT_TX
603                                                   | RAIL_SCHEDULER_STATUS_EVENT_INTERRUPTED),
604 
605   /** Multiprotocol scheduled CSMA transmit function internal error. */
606   RAIL_SCHEDULER_SCHEDULED_CCA_CSMA_TX_INTERNAL_ERROR = (RAIL_SCHEDULER_TASK_SCHEDULED_CCA_CSMA_TX
607                                                          | RAIL_SCHEDULER_STATUS_INTERNAL_ERROR),
608   /** \ref RAIL_StartScheduledCcaCsmaTx() returned error status. */
609   RAIL_SCHEDULER_SCHEDULED_CCA_CSMA_TX_FAIL = (RAIL_SCHEDULER_TASK_SCHEDULED_CCA_CSMA_TX
610                                                | RAIL_SCHEDULER_STATUS_TASK_FAIL),
611   /** Multiprotocol scheduled CSMA transmit scheduling error. */
612   RAIL_SCHEDULER_SCHEDULED_CCA_CSMA_TX_SCHEDULING_ERROR = (RAIL_SCHEDULER_TASK_SCHEDULED_CCA_CSMA_TX
613                                                            | RAIL_SCHEDULER_STATUS_SCHEDULE_FAIL),
614   /** \ref RAIL_StartScheduledCcaCsmaTx() operation interrupted */
615   RAIL_SCHEDULER_SCHEDULED_CCA_CSMA_TX_INTERRUPTED = (RAIL_SCHEDULER_TASK_SCHEDULED_CCA_CSMA_TX
616                                                       | RAIL_SCHEDULER_STATUS_EVENT_INTERRUPTED),
617 
618   /** Multiprotocol scheduled LBT transmit function internal error. */
619   RAIL_SCHEDULER_SCHEDULED_CCA_LBT_TX_INTERNAL_ERROR = (RAIL_SCHEDULER_TASK_SCHEDULED_CCA_LBT_TX
620                                                         | RAIL_SCHEDULER_STATUS_INTERNAL_ERROR),
621   /** \ref RAIL_StartScheduledCcaLbtTx() returned error status. */
622   RAIL_SCHEDULER_SCHEDULED_CCA_LBT_TX_FAIL = (RAIL_SCHEDULER_TASK_SCHEDULED_CCA_LBT_TX
623                                               | RAIL_SCHEDULER_STATUS_TASK_FAIL),
624   /** Multiprotocol scheduled LBT transmit scheduling error. */
625   RAIL_SCHEDULER_SCHEDULED_CCA_LBT_TX_SCHEDULING_ERROR = (RAIL_SCHEDULER_TASK_SCHEDULED_CCA_LBT_TX
626                                                           | RAIL_SCHEDULER_STATUS_SCHEDULE_FAIL),
627   /** \ref RAIL_StartScheduledCcaLbtTx() operation interrupted */
628   RAIL_SCHEDULER_SCHEDULED_CCA_LBT_TX_INTERRUPTED = (RAIL_SCHEDULER_TASK_SCHEDULED_CCA_LBT_TX
629                                                      | RAIL_SCHEDULER_STATUS_EVENT_INTERRUPTED),
630 
631   /** Multiprotocol stream transmit function internal error. */
632   RAIL_SCHEDULER_TX_STREAM_INTERNAL_ERROR = (RAIL_SCHEDULER_TASK_TX_STREAM
633                                              | RAIL_SCHEDULER_STATUS_INTERNAL_ERROR),
634   /** Multiprotocol stream transmit scheduling error. */
635   RAIL_SCHEDULER_TX_STREAM_SCHEDULING_ERROR = (RAIL_SCHEDULER_TASK_TX_STREAM
636                                                | RAIL_SCHEDULER_STATUS_SCHEDULE_FAIL),
637   /** \ref RAIL_StartTxStream() operation interrupted */
638   RAIL_SCHEDULER_TX_STREAM_INTERRUPTED = (RAIL_SCHEDULER_TASK_TX_STREAM
639                                           | RAIL_SCHEDULER_STATUS_EVENT_INTERRUPTED),
640 
641   /** Multiprotocol RSSI averaging function internal error. */
642   RAIL_SCHEDULER_AVERAGE_RSSI_INTERNAL_ERROR = (RAIL_SCHEDULER_TASK_AVERAGE_RSSI
643                                                 | RAIL_SCHEDULER_STATUS_INTERNAL_ERROR),
644   /** Multiprotocol RSSI average scheduling error. */
645   RAIL_SCHEDULER_AVERAGE_RSSI_SCHEDULING_ERROR = (RAIL_SCHEDULER_TASK_AVERAGE_RSSI
646                                                   | RAIL_SCHEDULER_STATUS_SCHEDULE_FAIL),
647   /** \ref RAIL_StartAverageRssi() operation interrupted */
648   RAIL_SCHEDULER_AVERAGE_RSSI_INTERRUPTED = (RAIL_SCHEDULER_TASK_AVERAGE_RSSI
649                                              | RAIL_SCHEDULER_STATUS_EVENT_INTERRUPTED),
650 };
651 
652 #ifndef DOXYGEN_SHOULD_SKIP_THIS
653 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
654 #define RAIL_SCHEDULER_STATUS_NO_ERROR                               ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_STATUS_NO_ERROR)
655 #define RAIL_SCHEDULER_STATUS_UNSUPPORTED                            ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_STATUS_UNSUPPORTED)
656 #define RAIL_SCHEDULER_STATUS_EVENT_INTERRUPTED                      ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_STATUS_EVENT_INTERRUPTED)
657 #define RAIL_SCHEDULER_STATUS_SCHEDULE_FAIL                          ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_STATUS_SCHEDULE_FAIL)
658 #define RAIL_SCHEDULER_STATUS_SCHEDULED_TX_FAIL                      ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_STATUS_SCHEDULED_TX_FAIL)
659 #define RAIL_SCHEDULER_STATUS_SINGLE_TX_FAIL                         ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_STATUS_SINGLE_TX_FAIL)
660 #define RAIL_SCHEDULER_STATUS_CCA_CSMA_TX_FAIL                       ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_STATUS_CCA_CSMA_TX_FAIL)
661 #define RAIL_SCHEDULER_STATUS_CCA_LBT_TX_FAIL                        ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_STATUS_CCA_LBT_TX_FAIL)
662 #define RAIL_SCHEDULER_STATUS_SCHEDULED_RX_FAIL                      ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_STATUS_SCHEDULED_RX_FAIL)
663 #define RAIL_SCHEDULER_STATUS_TX_STREAM_FAIL                         ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_STATUS_TX_STREAM_FAIL)
664 #define RAIL_SCHEDULER_STATUS_AVERAGE_RSSI_FAIL                      ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_STATUS_AVERAGE_RSSI_FAIL)
665 #define RAIL_SCHEDULER_STATUS_INTERNAL_ERROR                         ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_STATUS_INTERNAL_ERROR)
666 
667 #define RAIL_SCHEDULER_TASK_EMPTY                                    ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_TASK_EMPTY)
668 #define RAIL_SCHEDULER_TASK_SCHEDULED_RX                             ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_TASK_SCHEDULED_RX)
669 #define RAIL_SCHEDULER_TASK_SCHEDULED_TX                             ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_SCHEDULED_TX)
670 #define RAIL_SCHEDULER_TASK_SINGLE_TX                                ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_TASK_SINGLE_TX)
671 #define RAIL_SCHEDULER_TASK_SINGLE_CCA_CSMA_TX                       ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_TASK_SINGLE_CCA_CSMA_TX)
672 #define RAIL_SCHEDULER_TASK_SINGLE_CCA_LBT_TX                        ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_TASK_SINGLE_CCA_LBT_TX)
673 #define RAIL_SCHEDULER_TASK_SCHEDULED_CCA_CSMA_TX                    ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_TASK_SCHEDULED_CCA_CSMA_TX)
674 #define RAIL_SCHEDULER_TASK_SCHEDULED_CCA_LBT_TX                     ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_TASK_SCHEDULED_CCA_LBT_TX)
675 #define RAIL_SCHEDULER_TASK_TX_STREAM                                ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_TASK_TX_STREAM)
676 #define RAIL_SCHEDULER_TASK_AVERAGE_RSSI                             ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_TASK_AVERAGE_RSSI)
677 
678 #define RAIL_SCHEDULER_SCHEDULED_RX_INTERNAL_ERROR                   ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_SCHEDULED_RX_INTERNAL_ERROR)
679 #define RAIL_SCHEDULER_SCHEDULED_RX_SCHEDULING_ERROR                 ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_SCHEDULED_RX_SCHEDULING_ERROR)
680 #define RAIL_SCHEDULER_SCHEDULED_RX_INTERRUPTED                      ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_SCHEDULED_RX_INTERRUPTED)
681 #define RAIL_SCHEDULER_SCHEDULED_TX_INTERNAL_ERROR                   ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_SCHEDULED_TX_INTERNAL_ERROR)
682 #define RAIL_SCHEDULER_SCHEDULED_TX_SCHEDULING_ERROR                 ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_SCHEDULED_TX_SCHEDULING_ERROR)
683 #define RAIL_SCHEDULER_SCHEDULED_TX_INTERRUPTED                      ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_SCHEDULED_TX_INTERRUPTED)
684 #define RAIL_SCHEDULER_SINGLE_TX_INTERNAL_ERROR                      ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_SINGLE_TX_INTERNAL_ERROR)
685 #define RAIL_SCHEDULER_SINGLE_TX_SCHEDULING_ERROR                    ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_SINGLE_TX_SCHEDULING_ERROR)
686 #define RAIL_SCHEDULER_SINGLE_TX_INTERRUPTED                         ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_SINGLE_TX_INTERRUPTED)
687 #define RAIL_SCHEDULER_CCA_CSMA_TX_INTERNAL_ERROR                    ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_CCA_CSMA_TX_INTERNAL_ERROR)
688 #define RAIL_SCHEDULER_CCA_CSMA_TX_SCHEDULING_ERROR                  ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_CCA_CSMA_TX_SCHEDULING_ERROR)
689 #define RAIL_SCHEDULER_CCA_CSMA_TX_INTERRUPTED                       ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_CCA_CSMA_TX_INTERRUPTED)
690 #define RAIL_SCHEDULER_CCA_LBT_TX_INTERNAL_ERROR                     ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_CCA_LBT_TX_INTERNAL_ERROR)
691 #define RAIL_SCHEDULER_CCA_LBT_TX_SCHEDULING_ERROR                   ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_CCA_LBT_TX_SCHEDULING_ERROR)
692 #define RAIL_SCHEDULER_CCA_LBT_TX_INTERRUPTED                        ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_CCA_LBT_TX_INTERRUPTED)
693 #define RAIL_SCHEDULER_SCHEDULED_CCA_CSMA_TX_INTERNAL_ERROR          ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_SCHEDULED_CCA_CSMA_TX_INTERNAL_ERROR)
694 #define RAIL_SCHEDULER_SCHEDULED_CCA_CSMA_TX_FAIL                    ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_SCHEDULED_CCA_CSMA_TX_FAIL)
695 #define RAIL_SCHEDULER_SCHEDULED_CCA_CSMA_TX_SCHEDULING_ERROR        ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_SCHEDULED_CCA_CSMA_TX_SCHEDULING_ERROR)
696 #define RAIL_SCHEDULER_SCHEDULED_CCA_CSMA_TX_INTERRUPTED             ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_SCHEDULED_CCA_CSMA_TX_INTERRUPTED)
697 #define RAIL_SCHEDULER_SCHEDULED_CCA_LBT_TX_INTERNAL_ERROR           ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_SCHEDULED_CCA_LBT_TX_INTERNAL_ERROR)
698 #define RAIL_SCHEDULER_SCHEDULED_CCA_LBT_TX_FAIL                     ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_SCHEDULED_CCA_LBT_TX_FAIL)
699 #define RAIL_SCHEDULER_SCHEDULED_CCA_LBT_TX_SCHEDULING_ERROR         ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_SCHEDULED_CCA_LBT_TX_SCHEDULING_ERROR)
700 #define RAIL_SCHEDULER_SCHEDULED_CCA_LBT_TX_INTERRUPTED              ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_SCHEDULED_CCA_LBT_TX_INTERRUPTED)
701 #define RAIL_SCHEDULER_TX_STREAM_INTERNAL_ERROR                      ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_TX_STREAM_INTERNAL_ERROR)
702 #define RAIL_SCHEDULER_TX_STREAM_SCHEDULING_ERROR                    ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_TX_STREAM_SCHEDULING_ERROR)
703 #define RAIL_SCHEDULER_TX_STREAM_INTERRUPTED                         ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_TX_STREAM_INTERRUPTED)
704 #define RAIL_SCHEDULER_AVERAGE_RSSI_INTERNAL_ERROR                   ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_AVERAGE_RSSI_INTERNAL_ERROR)
705 #define RAIL_SCHEDULER_AVERAGE_RSSI_SCHEDULING_ERROR                 ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_AVERAGE_RSSI_SCHEDULING_ERROR)
706 #define RAIL_SCHEDULER_AVERAGE_RSSI_INTERRUPTED                      ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_AVERAGE_RSSI_INTERRUPTED)
707 #endif//DOXYGEN_SHOULD_SKIP_THIS
708 
709 /**
710  * @enum RAIL_TaskType_t
711  * @brief Multiprotocol radio operation task types, used with
712  *        RAIL_SetTaskPriority.
713  */
RAIL_ENUM(RAIL_TaskType_t)714 RAIL_ENUM(RAIL_TaskType_t) {
715   /** Indicate a task started using RAIL_StartRx */
716   RAIL_TASK_TYPE_START_RX,
717   /** Indicate a task started functions other than RAIL_StartRx */
718   RAIL_TASK_TYPE_OTHER,
719 };
720 
721 #ifndef DOXYGEN_SHOULD_SKIP_THIS
722 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
723 #define RAIL_TASK_TYPE_START_RX ((RAIL_TaskType_t) RAIL_TASK_TYPE_START_RX)
724 #define RAIL_TASK_TYPE_OTHER    ((RAIL_TaskType_t) RAIL_TASK_TYPE_OTHER)
725 #endif//DOXYGEN_SHOULD_SKIP_THIS
726 
727 /** @} */ // end of group Multiprotocol
728 
729 /******************************************************************************
730  * Event Structures
731  *****************************************************************************/
732 /**
733  * @addtogroup Events
734  * @{
735  */
736 
737 /**
738  * @enum RAIL_Events_t
739  * @brief RAIL events passed to the event callback. More than one event may be
740  *   indicated due to interrupt latency.
741  */
RAIL_ENUM_GENERIC(RAIL_Events_t,uint64_t)742 RAIL_ENUM_GENERIC(RAIL_Events_t, uint64_t) {
743   // RX Event Bit Shifts
744 
745   /** Shift position of \ref RAIL_EVENT_RSSI_AVERAGE_DONE bit */
746   RAIL_EVENT_RSSI_AVERAGE_DONE_SHIFT = 0,
747   /** Shift position of \ref RAIL_EVENT_RX_ACK_TIMEOUT bit */
748   RAIL_EVENT_RX_ACK_TIMEOUT_SHIFT,
749   /** Shift position of \ref RAIL_EVENT_RX_FIFO_ALMOST_FULL bit */
750   RAIL_EVENT_RX_FIFO_ALMOST_FULL_SHIFT,
751   /** Shift position of \ref RAIL_EVENT_RX_PACKET_RECEIVED bit */
752   RAIL_EVENT_RX_PACKET_RECEIVED_SHIFT,
753   /** Shift position of \ref RAIL_EVENT_RX_PREAMBLE_LOST bit */
754   RAIL_EVENT_RX_PREAMBLE_LOST_SHIFT,
755   /** Shift position of \ref RAIL_EVENT_RX_PREAMBLE_DETECT bit */
756   RAIL_EVENT_RX_PREAMBLE_DETECT_SHIFT,
757   /** Shift position of \ref RAIL_EVENT_RX_SYNC1_DETECT bit */
758   RAIL_EVENT_RX_SYNC1_DETECT_SHIFT,
759   /** Shift position of \ref RAIL_EVENT_RX_SYNC2_DETECT bit */
760   RAIL_EVENT_RX_SYNC2_DETECT_SHIFT,
761   /** Shift position of \ref RAIL_EVENT_RX_FRAME_ERROR bit */
762   RAIL_EVENT_RX_FRAME_ERROR_SHIFT,
763   /** Shift position of \ref RAIL_EVENT_RX_FIFO_FULL bit */
764   RAIL_EVENT_RX_FIFO_FULL_SHIFT,
765   /** Shift position of \ref RAIL_EVENT_RX_FIFO_OVERFLOW bit */
766   RAIL_EVENT_RX_FIFO_OVERFLOW_SHIFT,
767   /** Shift position of \ref RAIL_EVENT_RX_ADDRESS_FILTERED bit */
768   RAIL_EVENT_RX_ADDRESS_FILTERED_SHIFT,
769   /** Shift position of \ref RAIL_EVENT_RX_TIMEOUT bit */
770   RAIL_EVENT_RX_TIMEOUT_SHIFT,
771   /** Shift position of \ref RAIL_EVENT_SCHEDULED_RX_STARTED bit */
772   RAIL_EVENT_SCHEDULED_RX_STARTED_SHIFT,
773   /** Shift position of \ref  RAIL_EVENT_RX_SCHEDULED_RX_END bit */
774   RAIL_EVENT_RX_SCHEDULED_RX_END_SHIFT,
775   /** Shift position of \ref  RAIL_EVENT_RX_SCHEDULED_RX_MISSED bit */
776   RAIL_EVENT_RX_SCHEDULED_RX_MISSED_SHIFT,
777   /** Shift position of \ref RAIL_EVENT_RX_PACKET_ABORTED bit */
778   RAIL_EVENT_RX_PACKET_ABORTED_SHIFT,
779   /** Shift position of \ref RAIL_EVENT_RX_FILTER_PASSED bit */
780   RAIL_EVENT_RX_FILTER_PASSED_SHIFT,
781   /** Shift position of \ref RAIL_EVENT_RX_TIMING_LOST bit */
782   RAIL_EVENT_RX_TIMING_LOST_SHIFT,
783   /** Shift position of \ref RAIL_EVENT_RX_TIMING_DETECT bit */
784   RAIL_EVENT_RX_TIMING_DETECT_SHIFT,
785   /** Shift position of \ref RAIL_EVENT_RX_CHANNEL_HOPPING_COMPLETE bit */
786   RAIL_EVENT_RX_CHANNEL_HOPPING_COMPLETE_SHIFT,
787   /** Shift position of \ref RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND bit */
788   RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND_SHIFT,
789 
790 // TX Event Bit Shifts
791 
792   /** Shift position of \ref RAIL_EVENT_ZWAVE_BEAM bit */
793   RAIL_EVENT_ZWAVE_BEAM_SHIFT,
794   /** Shift position of \ref RAIL_EVENT_TX_FIFO_ALMOST_EMPTY bit */
795   RAIL_EVENT_TX_FIFO_ALMOST_EMPTY_SHIFT,
796   /** Shift position of \ref RAIL_EVENT_TX_PACKET_SENT bit */
797   RAIL_EVENT_TX_PACKET_SENT_SHIFT,
798   /** Shift position of \ref RAIL_EVENT_TXACK_PACKET_SENT bit */
799   RAIL_EVENT_TXACK_PACKET_SENT_SHIFT,
800   /** Shift position of \ref RAIL_EVENT_TX_ABORTED bit */
801   RAIL_EVENT_TX_ABORTED_SHIFT,
802   /** Shift position of \ref RAIL_EVENT_TXACK_ABORTED bit */
803   RAIL_EVENT_TXACK_ABORTED_SHIFT,
804   /** Shift position of \ref RAIL_EVENT_TX_BLOCKED bit */
805   RAIL_EVENT_TX_BLOCKED_SHIFT,
806   /** Shift position of \ref RAIL_EVENT_TXACK_BLOCKED bit */
807   RAIL_EVENT_TXACK_BLOCKED_SHIFT,
808   /** Shift position of \ref RAIL_EVENT_TX_UNDERFLOW bit */
809   RAIL_EVENT_TX_UNDERFLOW_SHIFT,
810   /** Shift position of \ref RAIL_EVENT_TXACK_UNDERFLOW bit */
811   RAIL_EVENT_TXACK_UNDERFLOW_SHIFT,
812   /** Shift position of \ref RAIL_EVENT_TX_CHANNEL_CLEAR bit */
813   RAIL_EVENT_TX_CHANNEL_CLEAR_SHIFT,
814   /** Shift position of \ref RAIL_EVENT_TX_CHANNEL_BUSY bit */
815   RAIL_EVENT_TX_CHANNEL_BUSY_SHIFT,
816   /** Shift position of \ref RAIL_EVENT_TX_CCA_RETRY bit */
817   RAIL_EVENT_TX_CCA_RETRY_SHIFT,
818   /** Shift position of \ref RAIL_EVENT_TX_START_CCA bit */
819   RAIL_EVENT_TX_START_CCA_SHIFT,
820   /** Shift position of \ref RAIL_EVENT_TX_STARTED bit */
821   RAIL_EVENT_TX_STARTED_SHIFT,
822   /** Shift position of \ref  RAIL_EVENT_TX_SCHEDULED_TX_MISSED bit */
823   RAIL_EVENT_TX_SCHEDULED_TX_MISSED_SHIFT,
824 
825   // Scheduler Event Bit Shifts
826 
827   /** Shift position of \ref RAIL_EVENT_CONFIG_UNSCHEDULED bit */
828   RAIL_EVENT_CONFIG_UNSCHEDULED_SHIFT,
829   /** Shift position of \ref RAIL_EVENT_CONFIG_SCHEDULED bit */
830   RAIL_EVENT_CONFIG_SCHEDULED_SHIFT,
831   /** Shift position of \ref RAIL_EVENT_SCHEDULER_STATUS bit */
832   RAIL_EVENT_SCHEDULER_STATUS_SHIFT,
833 
834   // Other Event Bit Shifts
835 
836   /** Shift position of \ref RAIL_EVENT_CAL_NEEDED bit */
837   RAIL_EVENT_CAL_NEEDED_SHIFT,
838   /** Shift position of \ref RAIL_EVENT_RF_SENSED bit */
839   RAIL_EVENT_RF_SENSED_SHIFT,
840   /** Shift position of \ref RAIL_EVENT_PA_PROTECTION bit */
841   RAIL_EVENT_PA_PROTECTION_SHIFT,
842   /** Shift position of \ref RAIL_EVENT_SIGNAL_DETECTED bit */
843   RAIL_EVENT_SIGNAL_DETECTED_SHIFT,
844   /** Shift position of \ref RAIL_EVENT_IEEE802154_MODESWITCH_START bit */
845   RAIL_EVENT_IEEE802154_MODESWITCH_START_SHIFT,
846   /** Shift position of \ref RAIL_EVENT_IEEE802154_MODESWITCH_END bit */
847   RAIL_EVENT_IEEE802154_MODESWITCH_END_SHIFT,
848   /** Shift position of \ref RAIL_EVENT_DETECT_RSSI_THRESHOLD bit */
849   RAIL_EVENT_DETECT_RSSI_THRESHOLD_SHIFT,
850   /** Shift position of \ref RAIL_EVENT_THERMISTOR_DONE bit */
851   RAIL_EVENT_THERMISTOR_DONE_SHIFT,
852   /** Shift position of \ref RAIL_EVENT_TX_BLOCKED_TOO_HOT bit */
853   RAIL_EVENT_TX_BLOCKED_TOO_HOT_SHIFT,
854   /** Shift position of \ref RAIL_EVENT_TEMPERATURE_TOO_HOT bit */
855   RAIL_EVENT_TEMPERATURE_TOO_HOT_SHIFT,
856   /** Shift position of \ref RAIL_EVENT_TEMPERATURE_COOL_DOWN bit */
857   RAIL_EVENT_TEMPERATURE_COOL_DOWN_SHIFT,
858 };
859 
860 /** Shift position of \ref RAIL_EVENT_SCHEDULED_TX_STARTED bit */
861 #define RAIL_EVENT_SCHEDULED_TX_STARTED_SHIFT         RAIL_EVENT_SCHEDULED_RX_STARTED_SHIFT
862 /** Shift position of \ref RAIL_EVENT_RX_DUTY_CYCLE_RX_END bit */
863 #define RAIL_EVENT_RX_DUTY_CYCLE_RX_END_SHIFT         RAIL_EVENT_RX_CHANNEL_HOPPING_COMPLETE_SHIFT
864 /** Shift position of \ref RAIL_EVENT_ZWAVE_LR_ACK_REQUEST_COMMAND_SHIFT bit */
865 #define RAIL_EVENT_ZWAVE_LR_ACK_REQUEST_COMMAND_SHIFT RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND_SHIFT
866 /** Shift position of \ref RAIL_EVENT_MFM_TX_BUFFER_DONE bit */
867 #define RAIL_EVENT_MFM_TX_BUFFER_DONE_SHIFT           RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND_SHIFT
868 
869 // RAIL_Event_t bitmasks
870 
871 /** A value representing no events */
872 #define RAIL_EVENTS_NONE 0ULL
873 
874 /**
875  * Occurs when the hardware-averaged RSSI is done in response to
876  * RAIL_StartAverageRssi() to indicate that the hardware has completed
877  * averaging.
878  *
879  * Call RAIL_GetAverageRssi() to get the result.
880  */
881 #define RAIL_EVENT_RSSI_AVERAGE_DONE (1ULL << RAIL_EVENT_RSSI_AVERAGE_DONE_SHIFT)
882 
883 /**
884  * Occurs when the ACK timeout expires while waiting to receive the
885  * sync word of an expected ACK. If the timeout occurs within packet
886  * reception, this event won't be signaled until after packet
887  * completion has determined the packet wasn't the expected ACK.
888  * See \ref RAIL_RxPacketDetails_t::isAck for the definition of an
889  * expected ACK.
890  *
891  * This event only occurs after calling RAIL_ConfigAutoAck() and after
892  * transmitting a packet with \ref RAIL_TX_OPTION_WAIT_FOR_ACK set.
893  */
894 #define RAIL_EVENT_RX_ACK_TIMEOUT (1ULL << RAIL_EVENT_RX_ACK_TIMEOUT_SHIFT)
895 
896 /**
897  * Occurs when the number of bytes in the receive FIFO exceeds the configured
898  * threshold value.
899  *
900  * Call RAIL_GetRxFifoBytesAvailable() to get the number of
901  * bytes available. When using this event, the threshold should be set via
902  * RAIL_SetRxFifoThreshold().
903  */
904 #define RAIL_EVENT_RX_FIFO_ALMOST_FULL (1ULL << RAIL_EVENT_RX_FIFO_ALMOST_FULL_SHIFT)
905 
906 /**
907  * Occurs whenever a packet is received with \ref RAIL_RX_PACKET_READY_SUCCESS
908  * or \ref RAIL_RX_PACKET_READY_CRC_ERROR.
909  *
910  * Call RAIL_GetRxPacketInfo() to get
911  * basic information about the packet along with a handle to this packet for
912  * subsequent use with RAIL_PeekRxPacket(), RAIL_GetRxPacketDetails(),
913  * RAIL_HoldRxPacket(), and RAIL_ReleaseRxPacket() as needed.
914  */
915 #define RAIL_EVENT_RX_PACKET_RECEIVED (1ULL << RAIL_EVENT_RX_PACKET_RECEIVED_SHIFT)
916 
917 /**
918  * Occurs when the radio has lost a preamble.
919  *
920  * This event can occur multiple
921  * times while searching for a packet and is generally used for diagnostic
922  * purposes. It can only occur after a
923  * \ref RAIL_EVENT_RX_PREAMBLE_DETECT event has already occurred.
924  */
925 #define RAIL_EVENT_RX_PREAMBLE_LOST (1ULL << RAIL_EVENT_RX_PREAMBLE_LOST_SHIFT)
926 
927 /**
928  * Occurs when the radio has detected a preamble.
929  *
930  * This event can occur multiple
931  * times while searching for a packet and is generally used for diagnostic
932  * purposes. It can only occur after a \ref RAIL_EVENT_RX_TIMING_DETECT
933  * event has already occurred.
934  */
935 #define RAIL_EVENT_RX_PREAMBLE_DETECT (1ULL << RAIL_EVENT_RX_PREAMBLE_DETECT_SHIFT)
936 
937 /**
938  * Occurs when the first sync word is detected.
939  *
940  * After this event occurs, one of
941  * the events in the \ref RAIL_EVENTS_RX_COMPLETION mask will occur.
942  */
943 #define RAIL_EVENT_RX_SYNC1_DETECT (1ULL << RAIL_EVENT_RX_SYNC1_DETECT_SHIFT)
944 
945 /**
946  * Occurs when the second sync word is detected.
947  *
948  * After this event occurs, one of
949  * the events in the \ref RAIL_EVENTS_RX_COMPLETION mask will occur.
950  */
951 #define RAIL_EVENT_RX_SYNC2_DETECT (1ULL << RAIL_EVENT_RX_SYNC2_DETECT_SHIFT)
952 
953 /**
954  * Occurs when a receive is aborted with \ref RAIL_RX_PACKET_ABORT_CRC_ERROR
955  * which only happens after any filtering has passed.
956  *
957  * For EFR32 parts, this event includes CRC errors, block decoding errors,
958  * and illegal frame length -- when detected after filtering. (When such
959  * errors are detected during filtering, they're signaled as \ref
960  * RAIL_EVENT_RX_PACKET_ABORTED instead.)
961  *
962  * If \ref RAIL_RX_OPTION_IGNORE_CRC_ERRORS is set, this event will not
963  * occur for CRC errors, but could still occur for the other errors.
964  */
965 #define RAIL_EVENT_RX_FRAME_ERROR (1ULL << RAIL_EVENT_RX_FRAME_ERROR_SHIFT)
966 
967 /**
968  * When using \ref RAIL_RxDataSource_t::RX_PACKET_DATA this event
969  * occurs coincident to a receive packet completion event in which the
970  * receive FIFO or any supplemental packet metadata FIFO (see \ref
971  * Data_Management) are full and further packet reception is jeopardized.
972  *
973  * It signals that an overflow is imminent (and may already have occurred)
974  * telling the application it should release the oldest packet(s) as soon
975  * as possible. This event may may be posted multiple times with subsequent
976  * receive completion events if the FIFO(s) remain full, and should also
977  * occur coincident with \ref RAIL_EVENT_RX_FIFO_OVERFLOW.
978  *
979  * When not using \ref RAIL_RxDataSource_t::RX_PACKET_DATA this event
980  * is not tied to packet completion and will occur coincident with
981  * \ref RAIL_EVENT_RX_FIFO_OVERFLOW when the receive FIFO has filled and
982  * overflowed. The application should consume receive FIFO data via
983  * \ref RAIL_ReadRxFifo() as soon as possible to minimize lost raw data.
984  */
985 #define RAIL_EVENT_RX_FIFO_FULL (1ULL << RAIL_EVENT_RX_FIFO_FULL_SHIFT)
986 
987 /**
988  * When using \ref RAIL_RxDataSource_t::RX_PACKET_DATA this event
989  * occurs when a receive is aborted with \ref RAIL_RX_PACKET_ABORT_OVERFLOW
990  * due to overflowing the receive FIFO or any supplemental packet metadata
991  * FIFO (see \ref Data_Management).
992  *
993  * The radio suspends receiving packets until this event is posted and
994  * the receive FIFO(s) have been fully processed (drained and released
995  * or reset). It is not guaranteed that a \ref RAIL_EVENT_RX_FIFO_FULL
996  * will precede this event, but both events should be coincident.
997  *
998  * When not using \ref RAIL_RxDataSource_t::RX_PACKET_DATA this event
999  * is not tied to packet completion and will occur coincident with
1000  * \ref RAIL_EVENT_RX_FIFO_FULL when the receive FIFO has filled and
1001  * overflowed. The application should consume receive FIFO data via
1002  * \ref RAIL_ReadRxFifo() as soon as possible to minimize lost raw data.
1003  */
1004 #define RAIL_EVENT_RX_FIFO_OVERFLOW (1ULL << RAIL_EVENT_RX_FIFO_OVERFLOW_SHIFT)
1005 
1006 /**
1007  * Occurs when a receive is aborted with \ref RAIL_RX_PACKET_ABORT_FILTERED
1008  * because its address does not match the filtering settings.
1009  *
1010  * This event can only occur after calling RAIL_EnableAddressFilter().
1011  */
1012 #define RAIL_EVENT_RX_ADDRESS_FILTERED (1ULL << RAIL_EVENT_RX_ADDRESS_FILTERED_SHIFT)
1013 
1014 /**
1015  * Occurs when an RX event times out.
1016  *
1017  * This event can only occur if the
1018  * RAIL_StateTiming_t::rxSearchTimeout passed to RAIL_SetStateTiming() is
1019  * not zero.
1020  */
1021 #define RAIL_EVENT_RX_TIMEOUT (1ULL << RAIL_EVENT_RX_TIMEOUT_SHIFT)
1022 
1023 /**
1024  * Occurs when a scheduled RX begins turning on the transmitter.
1025  * This event has the same numerical value as RAIL_EVENT_SCHEDULED_TX_STARTED
1026  * because one cannot schedule both RX and TX simultaneously.
1027  */
1028 #define RAIL_EVENT_SCHEDULED_RX_STARTED (1ULL << RAIL_EVENT_SCHEDULED_RX_STARTED_SHIFT)
1029 
1030 /**
1031  * Occurs when a scheduled TX begins turning on the transmitter.
1032  * This event has the same numerical value as RAIL_EVENT_SCHEDULED_RX_STARTED
1033  * because one cannot schedule both RX and TX simultaneously.
1034  */
1035 #define RAIL_EVENT_SCHEDULED_TX_STARTED (1ULL << RAIL_EVENT_SCHEDULED_TX_STARTED_SHIFT)
1036 
1037 /**
1038  * Occurs when the scheduled RX window ends.
1039  *
1040  * This event only occurs in response
1041  * to a scheduled receive timeout after calling RAIL_ScheduleRx(). If
1042  * RAIL_ScheduleRxConfig_t::rxTransitionEndSchedule was passed as false,
1043  * this event will occur unless the receive is aborted (due to a call to
1044  * RAIL_Idle() or a scheduler preemption, for instance). If
1045  * RAIL_ScheduleRxConfig_t::rxTransitionEndSchedule was passed as true,
1046  * any of the \ref RAIL_EVENTS_RX_COMPLETION events occurring will also cause
1047  * this event not to occur, since the scheduled receive will end with the
1048  * transition at the end of the packet. However, if the application has not
1049  * enabled the specific \ref RAIL_EVENTS_RX_COMPLETION event which implicitly
1050  * ended the scheduled receive, this event will be posted instead.
1051  */
1052 #define RAIL_EVENT_RX_SCHEDULED_RX_END (1ULL << RAIL_EVENT_RX_SCHEDULED_RX_END_SHIFT)
1053 
1054 /**
1055  * Occurs when start of a scheduled receive is missed
1056  *
1057  * This can occur if the radio is put to sleep and not woken up with enough time
1058  * to configure the scheduled receive event.
1059  */
1060 #define RAIL_EVENT_RX_SCHEDULED_RX_MISSED (1ULL << RAIL_EVENT_RX_SCHEDULED_RX_MISSED_SHIFT)
1061 
1062 /**
1063  * Occurs when a receive is aborted during filtering with
1064  * \ref RAIL_RX_PACKET_ABORT_FORMAT or after filtering with
1065  * \ref RAIL_RX_PACKET_ABORT_ABORTED for reasons other than address
1066  * filtering mismatch (which triggers \ref RAIL_EVENT_RX_ADDRESS_FILTERED
1067  * instead).
1068  *
1069  * For EFR32 parts, this event includes CRC errors, block decoding errors,
1070  * illegal frame length, and other RAIL built-in protocol-specific packet
1071  * content errors -- when detected during filtering. (When such errors
1072  * are detected after filtering, they're signaled as \ref
1073  * RAIL_EVENT_RX_FRAME_ERROR instead.) It also includes application or
1074  * multiprotocol scheduler aborting a receive after filtering has passed.
1075  */
1076 #define RAIL_EVENT_RX_PACKET_ABORTED (1ULL << RAIL_EVENT_RX_PACKET_ABORTED_SHIFT)
1077 
1078 /**
1079  * Occurs when the packet has passed any configured address and frame
1080  * filtering options.
1081  *
1082  * This event will only occur between the start of the
1083  * packet, indicated by \ref RAIL_EVENT_RX_SYNC1_DETECT or
1084  * \ref RAIL_EVENT_RX_SYNC2_DETECT and one of the events in the
1085  * \ref RAIL_EVENTS_RX_COMPLETION mask. It will always occur before or
1086  * concurrently with \ref RAIL_EVENT_RX_PACKET_RECEIVED. If IEEE 802.15.4 frame
1087  * and address filtering are enabled, this event will occur immediately after
1088  * destination address filtering.
1089  */
1090 #define RAIL_EVENT_RX_FILTER_PASSED (1ULL << RAIL_EVENT_RX_FILTER_PASSED_SHIFT)
1091 
1092 /**
1093  * Occurs when the modem timing is lost.
1094  *
1095  * This event can occur multiple times
1096  * while searching for a packet and is generally used for diagnostic purposes.
1097  * It can only occur after a \ref RAIL_EVENT_RX_TIMING_DETECT event has
1098  * already occurred.
1099  */
1100 #define RAIL_EVENT_RX_TIMING_LOST (1ULL << RAIL_EVENT_RX_TIMING_LOST_SHIFT)
1101 
1102 /**
1103  * Occurs when the modem timing is detected.
1104  *
1105  * This event can occur multiple times
1106  * while searching for a packet and is generally used for diagnostic purposes.
1107  */
1108 #define RAIL_EVENT_RX_TIMING_DETECT (1ULL << RAIL_EVENT_RX_TIMING_DETECT_SHIFT)
1109 
1110 /**
1111  * Occurs when RX Channel Hopping is enabled and channel hopping finishes
1112  * receiving on the last channel in its sequence.
1113  *
1114  * The intent behind this event
1115  * is to allow the user to keep the radio on for as short a time as possible.
1116  * That is, once the channel sequence is complete, the application will receive
1117  * this event and can trigger a sleep/idle until it is necessary to cycle
1118  * through the channels again. If this event is left on indefinitely and not
1119  * handled it will likely be a fairly noisy event, as it continues to fire
1120  * each time the hopping algorithm cycles through the channel sequence.
1121  */
1122 #define RAIL_EVENT_RX_CHANNEL_HOPPING_COMPLETE (1ULL << RAIL_EVENT_RX_CHANNEL_HOPPING_COMPLETE_SHIFT)
1123 
1124 /**
1125  * Occurs during RX duty cycle mode when the radio finishes its time in
1126  * receive mode.
1127  *
1128  * The application can then trigger a sleep/idle until it
1129  * needs to listen again.
1130  */
1131 #define RAIL_EVENT_RX_DUTY_CYCLE_RX_END (1ULL << RAIL_EVENT_RX_DUTY_CYCLE_RX_END_SHIFT)
1132 
1133 /**
1134  * Indicate a Data Request is received when using IEEE 802.15.4
1135  * functionality.
1136  *
1137  * It occurs when the command byte of an incoming ACK-requesting MAC Control
1138  * frame is for a data request. This callback is called before
1139  * the packet is fully received to allow the node to have more time to decide
1140  * whether to indicate a frame is pending in the outgoing ACK. This event only
1141  * occurs if the RAIL IEEE 802.15.4 functionality is enabled, but will never
1142  * occur if promiscuous mode is enabled via
1143  * RAIL_IEEE802154_SetPromiscuousMode().
1144  *
1145  * Call RAIL_IEEE802154_GetAddress() to get the source address of the packet.
1146  */
1147 #define RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND (1ULL << RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND_SHIFT)
1148 
1149 /**
1150  * Indicate a Z-Wave Beam Request relevant to the node was received.
1151  *
1152  * This event only occurs if the RAIL Z-Wave functionality is enabled
1153  * and its \ref RAIL_ZWAVE_OPTION_DETECT_BEAM_FRAMES is enabled.
1154  * This event is used in lieu of \ref RAIL_EVENT_RX_PACKET_RECEIVED,
1155  * which is reserved for Z-Wave packets other than Beams.
1156  *
1157  * Call RAIL_ZWAVE_GetBeamNodeId() to get the NodeId to which the Beam was
1158  * targeted, which would be either the broadcast id 0xFF or the node's own
1159  * single-cast id.
1160  *
1161  * @note All Z-Wave Beam requests are generally discarded, triggering
1162  *   \ref RAIL_EVENT_RX_PACKET_ABORTED.
1163  */
1164 #define RAIL_EVENT_ZWAVE_BEAM (1ULL << RAIL_EVENT_ZWAVE_BEAM_SHIFT)
1165 
1166 /**
1167  * Indicate a MFM buffer has completely transmitted.
1168  *
1169  * This event only occurs if the RAIL MFM functionality is enabled
1170  * and a MFM buffer has completely transmitted.
1171  *
1172  * Following this event, the application can update the MFM buffer
1173  * that has transmitted to be used for the next transmission.
1174  */
1175 #define RAIL_EVENT_MFM_TX_BUFFER_DONE (1ULL << RAIL_EVENT_MFM_TX_BUFFER_DONE_SHIFT)
1176 
1177 /**
1178  * Indicate a request for populating Z-Wave LR ACK packet.
1179  * This event only occurs if the RAIL Z-Wave functionality is enabled.
1180  *
1181  * Following this event, the application must call \ref RAIL_ZWAVE_SetLrAckData()
1182  * to populate noise floor, TX power and receive RSSI fields of the Z-Wave
1183  * Long Range ACK packet.
1184  */
1185 #define RAIL_EVENT_ZWAVE_LR_ACK_REQUEST_COMMAND (1ULL << RAIL_EVENT_ZWAVE_LR_ACK_REQUEST_COMMAND_SHIFT)
1186 
1187 /**
1188  * The mask representing all events that determine the end of a received
1189  * packet.
1190  *
1191  * After a \ref RAIL_EVENT_RX_SYNC1_DETECT or a
1192  * \ref RAIL_EVENT_RX_SYNC2_DETECT,
1193  * exactly one of the following events will occur. When one of these events
1194  * occurs, a state transition will take place based on the parameter passed to
1195  * RAIL_SetRxTransitions(). The RAIL_StateTransitions_t::success transition
1196  * will be followed only if the \ref RAIL_EVENT_RX_PACKET_RECEIVED event occurs.
1197  * Any of the other events will trigger the RAIL_StateTransitions_t::error
1198  * transition.
1199  */
1200 #define RAIL_EVENTS_RX_COMPLETION (RAIL_EVENT_RX_PACKET_RECEIVED    \
1201                                    | RAIL_EVENT_RX_PACKET_ABORTED   \
1202                                    | RAIL_EVENT_RX_FRAME_ERROR      \
1203                                    | RAIL_EVENT_RX_FIFO_OVERFLOW    \
1204                                    | RAIL_EVENT_RX_ADDRESS_FILTERED \
1205                                    | RAIL_EVENT_RX_SCHEDULED_RX_MISSED)
1206 
1207 // TX Event Bitmasks
1208 
1209 /**
1210  * Occurs when the number of bytes in the transmit FIFO falls below the
1211  * configured threshold value.
1212  *
1213  * This event does not occur on initialization or after resetting the transmit
1214  * FIFO with RAIL_ResetFifo().
1215  *
1216  * Call RAIL_GetTxFifoSpaceAvailable() to get the
1217  * number of bytes available in the transmit FIFO at the time of the callback
1218  * dispatch. When using this event, the threshold should be set via
1219  * RAIL_SetTxFifoThreshold().
1220  */
1221 #define RAIL_EVENT_TX_FIFO_ALMOST_EMPTY (1ULL << RAIL_EVENT_TX_FIFO_ALMOST_EMPTY_SHIFT)
1222 
1223 /**
1224  * Occurs after a packet has been transmitted.
1225  *
1226  * Call RAIL_GetTxPacketDetails()
1227  * to get information about the packet that was transmitted.
1228  * @note RAIL_GetTxPacketDetails() is only valid to call during the time frame
1229  *   of the RAIL_Config_t::eventsCallback.
1230  */
1231 #define RAIL_EVENT_TX_PACKET_SENT (1ULL << RAIL_EVENT_TX_PACKET_SENT_SHIFT)
1232 
1233 /**
1234  * Occurs after an ACK packet has been transmitted.
1235  *
1236  * Call RAIL_GetTxPacketDetails()
1237  * to get information about the packet that was transmitted. This event can only occur
1238  * after calling RAIL_ConfigAutoAck().
1239  * @note RAIL_GetTxPacketDetails() is only valid to call during the time frame
1240  *   of the RAIL_Config_t::eventsCallback.
1241  */
1242 #define RAIL_EVENT_TXACK_PACKET_SENT (1ULL << RAIL_EVENT_TXACK_PACKET_SENT_SHIFT)
1243 
1244 /**
1245  * Occurs when a transmit is aborted by the user.
1246  *
1247  * This can happen due to calling RAIL_Idle() or due to a scheduler
1248  * preemption.
1249  *
1250  * @note The Transmit FIFO is left in an indeterminate state and should be
1251  *    reset prior to reuse for sending a new packet. Contrast this
1252  *    with \ref RAIL_EVENT_TX_BLOCKED.
1253  */
1254 #define RAIL_EVENT_TX_ABORTED (1ULL << RAIL_EVENT_TX_ABORTED_SHIFT)
1255 
1256 /**
1257  * Occurs when an ACK transmit is aborted by the user.
1258  *
1259  * This event can only
1260  * occur after calling RAIL_ConfigAutoAck(), which can happen due to calling
1261  * RAIL_Idle() or due to a scheduler preemption.
1262  */
1263 #define RAIL_EVENT_TXACK_ABORTED (1ULL << RAIL_EVENT_TXACK_ABORTED_SHIFT)
1264 
1265 /**
1266  * Occurs when a transmit is blocked from occurring because
1267  * RAIL_EnableTxHoldOff() was called.
1268  *
1269  * @note Since the transmit never started, the Transmit FIFO remains intact
1270  *   after this event -- no packet data was consumed from it. Contrast this
1271  *   with \ref RAIL_EVENT_TX_ABORTED.
1272  */
1273 #define RAIL_EVENT_TX_BLOCKED (1ULL << RAIL_EVENT_TX_BLOCKED_SHIFT)
1274 
1275 /**
1276  * Occurs when an ACK transmit is blocked from occurring because
1277  * RAIL_EnableTxHoldOff() was called.
1278  *
1279  * This event can only occur after calling RAIL_ConfigAutoAck().
1280  */
1281 #define RAIL_EVENT_TXACK_BLOCKED (1ULL << RAIL_EVENT_TXACK_BLOCKED_SHIFT)
1282 
1283 /**
1284  * Occurs when the transmit buffer underflows.
1285  *
1286  * This can happen due to the
1287  * transmitted packet specifying an unintended length based on the current
1288  * radio configuration or due to RAIL_WriteTxFifo() calls not keeping up with
1289  * the transmit rate if the entire packet isn't loaded at once.
1290  *
1291  * @note The Transmit FIFO is left in an indeterminate state and should be
1292  *    reset prior to reuse for sending a new packet. Contrast this
1293  *    with \ref RAIL_EVENT_TX_BLOCKED.
1294  */
1295 #define RAIL_EVENT_TX_UNDERFLOW (1ULL << RAIL_EVENT_TX_UNDERFLOW_SHIFT)
1296 
1297 /**
1298  * Occurs when the ACK transmit buffer underflows.
1299  *
1300  * This can happen due to the
1301  * transmitted packet specifying an unintended length based on the current
1302  * radio configuration or due to RAIL_WriteAutoAckFifo() not being called at
1303  * all before an ACK transmit.
1304  *
1305  * This event can only occur after calling RAIL_ConfigAutoAck().
1306  */
1307 #define RAIL_EVENT_TXACK_UNDERFLOW (1ULL << RAIL_EVENT_TXACK_UNDERFLOW_SHIFT)
1308 
1309 /**
1310  * Occurs when Carrier Sense Multiple Access (CSMA) or Listen Before Talk (LBT)
1311  * succeeds.
1312  *
1313  * This event can only happen after calling RAIL_StartCcaCsmaTx() or
1314  * RAIL_StartCcaLbtTx().
1315  */
1316 #define RAIL_EVENT_TX_CHANNEL_CLEAR (1ULL << RAIL_EVENT_TX_CHANNEL_CLEAR_SHIFT)
1317 
1318 /**
1319  * Occurs when Carrier Sense Multiple Access (CSMA) or Listen Before Talk (LBT)
1320  * fails.
1321  *
1322  * This event can only happen after calling RAIL_StartCcaCsmaTx() or
1323  * RAIL_StartCcaLbtTx().
1324  *
1325  * @note Since the transmit never started, the Transmit FIFO remains intact
1326  *   after this event -- no packet data was consumed from it.
1327  */
1328 #define RAIL_EVENT_TX_CHANNEL_BUSY (1ULL << RAIL_EVENT_TX_CHANNEL_BUSY_SHIFT)
1329 
1330 /**
1331  * Occurs during CSMA or LBT when an individual Clear Channel Assessment (CCA)
1332  * check fails, but there are more tries needed before the overall operation
1333  * completes.
1334  *
1335  * This event can occur multiple times based on the configuration
1336  * of the ongoing CSMA or LBT transmission. It can only happen after
1337  * calling RAIL_StartCcaCsmaTx() or RAIL_StartCcaLbtTx().
1338  */
1339 #define RAIL_EVENT_TX_CCA_RETRY (1ULL << RAIL_EVENT_TX_CCA_RETRY_SHIFT)
1340 
1341 /**
1342  * Occurs when the receiver is activated to perform a Clear Channel Assessment
1343  * (CCA) check.
1344  *
1345  * This event generally precedes the actual start of a CCA check by roughly
1346  * the \ref RAIL_StateTiming_t::idleToRx time (subject to
1347  * \ref RAIL_MINIMUM_TRANSITION_US).  It can
1348  * occur multiple times based on the configuration of the ongoing CSMA or LBT
1349  * transmission. It can only happen after calling RAIL_StartCcaCsmaTx()
1350  * or RAIL_StartCcaLbtTx().
1351  */
1352 #define RAIL_EVENT_TX_START_CCA (1ULL << RAIL_EVENT_TX_START_CCA_SHIFT)
1353 
1354 /**
1355  * Occurs when the radio starts transmitting a normal packet on the air.
1356  *
1357  * A start-of-transmit timestamp is captured for this event. It can be
1358  * retrieved by calling \ref RAIL_GetTxTimePreambleStart() passing \ref
1359  * RAIL_TX_STARTED_BYTES for its totalPacketBytes parameter.
1360  *
1361  * @note This event does not apply to ACK transmits. Currently there
1362  *   is no equivalent event or timestamp captured for the start of an
1363  *   ACK transmit.
1364  */
1365 #define RAIL_EVENT_TX_STARTED (1ULL << RAIL_EVENT_TX_STARTED_SHIFT)
1366 
1367 /**
1368  * A value to pass as \ref RAIL_GetTxTimePreambleStart() totalPacketBytes
1369  * parameter to retrieve the \ref RAIL_EVENT_TX_STARTED timestamp.
1370  */
1371 #define RAIL_TX_STARTED_BYTES 0U
1372 
1373 /**
1374  * Occurs when the start of a scheduled transmit is missed
1375  *
1376  * This can occur if the radio is put to sleep and not woken up with enough time
1377  * to configure the scheduled transmit event.
1378  *
1379  * @note Since the transmit never started, the Transmit FIFO remains intact
1380  *   after this event -- no packet data was consumed from it.
1381  */
1382 #define RAIL_EVENT_TX_SCHEDULED_TX_MISSED (1ULL << RAIL_EVENT_TX_SCHEDULED_TX_MISSED_SHIFT)
1383 
1384 /**
1385  * A mask representing all events that determine the end of a transmitted
1386  * packet. After a \ref RAIL_STATUS_NO_ERROR return value
1387  * from one of the transmit functions, exactly one of the following
1388  * events will occur. When one of these events occurs, a state transition
1389  * takes place based on the parameter passed to RAIL_SetTxTransitions().
1390  * The RAIL_StateTransitions_t::success transition will be followed only
1391  * if the \ref RAIL_EVENT_TX_PACKET_SENT event occurs. Any of the other
1392  * events will trigger the RAIL_StateTransitions_t::error transition.
1393  */
1394 #define RAIL_EVENTS_TX_COMPLETION (RAIL_EVENT_TX_PACKET_SENT    \
1395                                    | RAIL_EVENT_TX_ABORTED      \
1396                                    | RAIL_EVENT_TX_BLOCKED      \
1397                                    | RAIL_EVENT_TX_UNDERFLOW    \
1398                                    | RAIL_EVENT_TX_CHANNEL_BUSY \
1399                                    | RAIL_EVENT_TX_SCHEDULED_TX_MISSED)
1400 
1401 /**
1402  * A mask representing all events that determine the end of a transmitted
1403  * ACK packet. After an ACK-requesting receive, exactly one of the
1404  * following events will occur. When one of these events occurs, a state
1405  * transition takes place based on the RAIL_AutoAckConfig_t::rxTransitions
1406  * passed to RAIL_ConfigAutoAck(). The receive transitions are used because the
1407  * transmitted ACK packet is considered a part of the ACK-requesting received
1408  * packet. The RAIL_StateTransitions_t::success transition will be followed
1409  * only if the \ref RAIL_EVENT_TXACK_PACKET_SENT event occurs. Any of the other
1410  * events will trigger the RAIL_StateTransitions_t::error transition.
1411  */
1412 #define RAIL_EVENTS_TXACK_COMPLETION (RAIL_EVENT_TXACK_PACKET_SENT \
1413                                       | RAIL_EVENT_TXACK_ABORTED   \
1414                                       | RAIL_EVENT_TXACK_BLOCKED   \
1415                                       | RAIL_EVENT_TXACK_UNDERFLOW)
1416 
1417 // Scheduler Event Bitmasks
1418 
1419 /**
1420  * Occurs when the scheduler switches away from this configuration.
1421  *
1422  * This event will occur in dynamic multiprotocol scenarios each
1423  * time a protocol is shutting down. When it does occur, it will be
1424  * the only event passed to RAIL_Config_t::eventsCallback. Therefore,
1425  * to optimize protocol switch time, this event should be handled
1426  * among the first in that callback, and then the application can return
1427  * immediately.
1428  *
1429  * @note: To minimize protocol switch time, Silicon Labs recommends this event
1430  *        event being turned off unless it is used.
1431  */
1432 #define RAIL_EVENT_CONFIG_UNSCHEDULED (1ULL << RAIL_EVENT_CONFIG_UNSCHEDULED_SHIFT)
1433 
1434 /**
1435  * Occurs when the scheduler switches to this configuration.
1436  *
1437  * This event will occur in dynamic multiprotocol scenarios each time
1438  * a protocol is starting up. When it does occur, it will
1439  * be the only event passed to RAIL_Config_t::eventsCallback. Therefore, in
1440  * order to optimize protocol switch time, this event should be handled among
1441  * the first in that callback, and then the application can return immediately.
1442  *
1443  * @note: To minimize protocol switch time, Silicon Labs recommends this event
1444  *        event being turned off unless it is used.
1445  */
1446 #define RAIL_EVENT_CONFIG_SCHEDULED (1ULL << RAIL_EVENT_CONFIG_SCHEDULED_SHIFT)
1447 
1448 /**
1449  * Occurs when the scheduler has a status to report.
1450  *
1451  * The exact status can be found with RAIL_GetSchedulerStatus().
1452  * See \ref RAIL_SchedulerStatus_t for more details. When this event
1453  * does occur, it will be the only event passed to RAIL_Config_t::eventsCallback.
1454  * Therefore, to optimize protocol switch time, this event should
1455  * be handled among the first in that callback, and then the application
1456  * can return immediately.
1457  *
1458  * @note RAIL_GetSchedulerStatus() is only valid to call during the time frame
1459  *   of the RAIL_Config_t::eventsCallback.
1460  *
1461  * @note: To minimize protocol switch time, Silicon Labs recommends this event
1462  *        event being turned off unless it is used.
1463  */
1464 #define RAIL_EVENT_SCHEDULER_STATUS (1ULL << RAIL_EVENT_SCHEDULER_STATUS_SHIFT)
1465 
1466 // Other Event Bitmasks
1467 
1468 /**
1469  * Occurs when the application needs to run a calibration, as
1470  * determined by the RAIL library.
1471  *
1472  * The application determines the opportune time to call RAIL_Calibrate().
1473  */
1474 #define RAIL_EVENT_CAL_NEEDED (1ULL << RAIL_EVENT_CAL_NEEDED_SHIFT)
1475 
1476 /**
1477  * Occurs when RF energy is sensed from the radio. This event can be used as
1478  * an alternative to the callback passed as \ref RAIL_RfSense_CallbackPtr_t.
1479  *
1480  * Alternatively, the application can poll using \ref RAIL_IsRfSensed().
1481  *
1482  * @note This event will not occur when waking up from EM4. Prefer
1483  *   \ref RAIL_IsRfSensed() when waking from EM4.
1484  */
1485 #define RAIL_EVENT_RF_SENSED (1ULL << RAIL_EVENT_RF_SENSED_SHIFT)
1486 
1487 /**
1488  * Occurs when PA protection circuit kicks in.
1489  */
1490 #define RAIL_EVENT_PA_PROTECTION (1ULL << RAIL_EVENT_PA_PROTECTION_SHIFT)
1491 
1492 /**
1493  * Occurs after enabling the signal detection using \ref RAIL_BLE_EnableSignalDetection
1494  * or \ref RAIL_IEEE802154_EnableSignalDetection when a signal is detected.
1495  * This is only used on platforms that support signal identifier, where
1496  * \ref RAIL_BLE_SUPPORTS_SIGNAL_IDENTIFIER or
1497  * \ref RAIL_IEEE802154_SUPPORTS_SIGNAL_IDENTIFIER is true.
1498  */
1499 #define RAIL_EVENT_SIGNAL_DETECTED (1ULL << RAIL_EVENT_SIGNAL_DETECTED_SHIFT)
1500 
1501 /**
1502  * Occurs when a Wi-SUN mode switch packet has been received, after switching to the new PHY.
1503  *
1504  * It doesn't occur when a mode switch packet is transmitted.
1505  *
1506  * IEEE 802.15.4 option \ref RAIL_IEEE802154_G_OPTION_WISUN_MODESWITCH must be enabled for this event to occur.
1507  *
1508  * Only available on platforms where \ref RAIL_IEEE802154_SUPPORTS_G_MODESWITCH is true.
1509  */
1510 #define RAIL_EVENT_IEEE802154_MODESWITCH_START (1ULL << RAIL_EVENT_IEEE802154_MODESWITCH_START_SHIFT)
1511 
1512 /**
1513  * Occurs when switching back to the original base PHY in effect prior to the Wi-SUN mode switch reception.
1514  *
1515  * This typically occurs if no packet is seen within some timeframe after the mode switch packet was received
1516  * or if the first packet received in the new PHY is aborted, filtered, or fails CRC.
1517  *
1518  * IEEE 802.15.4 option \ref RAIL_IEEE802154_G_OPTION_WISUN_MODESWITCH must be enabled for this event to occur.
1519  *
1520  * Only available on platforms where \ref RAIL_IEEE802154_SUPPORTS_G_MODESWITCH is true.
1521  */
1522 #define RAIL_EVENT_IEEE802154_MODESWITCH_END (1ULL << RAIL_EVENT_IEEE802154_MODESWITCH_END_SHIFT)
1523 
1524 /**
1525  * Occurs when the sampled RSSI is above the threshold set by
1526  * \ref RAIL_SetRssiDetectThreshold().
1527  */
1528 #define RAIL_EVENT_DETECT_RSSI_THRESHOLD (1ULL << RAIL_EVENT_DETECT_RSSI_THRESHOLD_SHIFT)
1529 
1530 /**
1531  * Occurs when the thermistor has finished its measurement in response to
1532  * \ref RAIL_StartThermistorMeasurement().
1533  */
1534 #define RAIL_EVENT_THERMISTOR_DONE (1ULL << RAIL_EVENT_THERMISTOR_DONE_SHIFT)
1535 
1536 /**
1537  * Occurs when a Tx has been blocked because of temperature exceeding
1538  * the safety threshold.
1539  *
1540  * Only occurs on platforms where \ref RAIL_SUPPORTS_EFF is true.
1541  */
1542 #define RAIL_EVENT_TX_BLOCKED_TOO_HOT (1ULL << RAIL_EVENT_TX_BLOCKED_TOO_HOT_SHIFT)
1543 
1544 /**
1545  * Occurs when die internal temperature exceeds the temperature threshold subtracted
1546  * by the cool down parameter from \ref RAIL_ChipTempConfig_t.
1547  * Transmits are blocked until temperature has cooled enough, indicated by
1548  * \ref RAIL_EVENT_TEMPERATURE_COOL_DOWN.
1549  *
1550  * Only occurs on platforms where \ref RAIL_SUPPORTS_THERMAL_PROTECTION is true.
1551  */
1552 #define RAIL_EVENT_TEMPERATURE_TOO_HOT (1ULL << RAIL_EVENT_TEMPERATURE_TOO_HOT_SHIFT)
1553 
1554 /**
1555  * Occurs when die internal temperature falls below the temperature threshold subtracted
1556  * by the cool down parameter from \ref RAIL_ChipTempConfig_t.
1557  * Transmits are no longer blocked by temperature limitation, indicated by
1558  * \ref RAIL_EVENT_TEMPERATURE_TOO_HOT.
1559  *
1560  * Only occurs on platforms where \ref RAIL_SUPPORTS_THERMAL_PROTECTION is true.
1561  */
1562 #define RAIL_EVENT_TEMPERATURE_COOL_DOWN (1ULL << RAIL_EVENT_TEMPERATURE_COOL_DOWN_SHIFT)
1563 
1564 /** A value representing all possible events */
1565 #define RAIL_EVENTS_ALL 0xFFFFFFFFFFFFFFFFULL
1566 
1567 /** @} */ // end of group Events
1568 
1569 /**
1570  * @addtogroup PA Power Amplifier (PA)
1571  * @ingroup Transmit
1572  * @{
1573  */
1574 
1575 /**
1576  * The transmit power in deci-dBm units (e.g., 4.5 dBm -> 45 deci-dBm). These
1577  * values are used by the conversion functions to convert a \ref
1578  * RAIL_TxPowerLevel_t to deci-dBm for the application consumption. On EFR32,
1579  * they can range from \ref RAIL_TX_POWER_MIN to \ref RAIL_TX_POWER_MAX.
1580  */
1581 typedef int16_t RAIL_TxPower_t;
1582 
1583 /** The maximum valid value for a \ref RAIL_TxPower_t. */
1584 #define RAIL_TX_POWER_MAX ((RAIL_TxPower_t)0x7FFF)
1585 /** The minimum valid value for a \ref RAIL_TxPower_t. */
1586 #define RAIL_TX_POWER_MIN ((RAIL_TxPower_t)0x8000)
1587 
1588 /** The maximum power in deci-dBm the curve supports */
1589 #define RAIL_TX_POWER_CURVE_DEFAULT_MAX ((RAIL_TxPower_t)200)
1590 /** The increment step in deci-dBm for calculating power level*/
1591 #define RAIL_TX_POWER_CURVE_DEFAULT_INCREMENT ((RAIL_TxPower_t)40)
1592 
1593 /// mV are used for all TX power voltage values.
1594 /// TX power voltages take and return voltages multiplied by this factor.
1595 #define RAIL_TX_POWER_VOLTAGE_SCALING_FACTOR 1000
1596 
1597 /// deci-dBm are used for all TX power dBm values.
1598 /// All dBm inputs to TX power functions take dBm power times this factor.
1599 #define RAIL_TX_POWER_DBM_SCALING_FACTOR 10
1600 
1601 /** @} */ // PA Power Amplifier (PA)
1602 
1603 /******************************************************************************
1604  * Radio Configuration Structures
1605  *****************************************************************************/
1606 /**
1607  * @addtogroup Radio_Configuration
1608  * @{
1609  */
1610 
1611 /**
1612  * @struct RAIL_FrameType_t
1613  * @brief Configures if there is a frame type in your frame and the lengths of
1614  * each frame. The number of bits set in the mask determines the number of
1615  * elements in frameLen. A maximum of 8 different frame types may be specified.
1616  */
1617 typedef struct RAIL_FrameType {
1618   /**
1619    * A pointer to an array of frame lengths for each frame type. The length of this
1620    * array should be equal to the number of frame types. The array that
1621    * frameLen points to should not change location or be modified.
1622    */
1623   uint16_t *frameLen;
1624   /**
1625    * Zero-indexed location of the byte containing the frame type field.
1626    */
1627   uint8_t offset;
1628   /**
1629    * A bitmask of the frame type field, which determines a number of frames expected
1630    * based on the number of bits set. No more than 3 bits can be set in the mask and
1631    * they must be contiguous ones. For example, if the highest three bits of the byte
1632    * specified by offset constitute the frame type, then mask should be 0xE0,
1633    * which has 3 bits set, indicating 8 possible frame types.
1634    */
1635   uint8_t mask;
1636   /**
1637    * A bitmask that marks if each frame is valid or should be filtered. Frame type
1638    * 0 corresponds to the lowest bit in isValid. If the frame is filtered, a
1639    * RAIL_EVENT_RX_PACKET_ABORTED will be raised.
1640    */
1641   uint8_t isValid;
1642   /**
1643    * A bitmask that marks if each frame should have the address filter applied.
1644    * Frame type 0 corresponds to the least significant bit in addressFilter.
1645    */
1646   uint8_t addressFilter;
1647 } RAIL_FrameType_t;
1648 
1649 /**
1650  * @def RAIL_SETFIXEDLENGTH_INVALID
1651  * @brief An invalid return value when calling RAIL_SetFixedLength().
1652  *
1653  * An invalid return value when calling RAIL_SetFixedLength() while the radio is
1654  * not in fixed-length mode.
1655  */
1656 #define RAIL_SETFIXEDLENGTH_INVALID (0xFFFFU)
1657 
1658 /**
1659  * @struct RAIL_ChannelConfigEntryAttr_t
1660  * @brief A channel configuration entry attribute structure. Items listed
1661  *  are designed to be altered and updated during run-time.
1662  */
1663 typedef struct RAIL_ChannelConfigEntryAttr RAIL_ChannelConfigEntryAttr_t;
1664 
1665 /**
1666  * @enum RAIL_ChannelConfigEntryType_t
1667  * @brief Define if the channel support using concurrent PHY during channel
1668  * hopping. RAIL_RX_CHANNEL_HOPPING_MODE_CONC and RAIL_RX_CHANNEL_HOPPING_MODE_VT
1669  * can only be used if the channel supports it.
1670  */
RAIL_ENUM(RAIL_ChannelConfigEntryType_t)1671 RAIL_ENUM(RAIL_ChannelConfigEntryType_t) {
1672   RAIL_CH_TYPE_NORMAL, /**< Not a concurrent PHY. */
1673   RAIL_CH_TYPE_CONC_BASE, /**< Base concurrent PHY. */
1674   RAIL_CH_TYPE_CONC_VIRTUAL, /**< Virtual concurrent PHY. */
1675 };
1676 
1677 #ifndef DOXYGEN_SHOULD_SKIP_THIS
1678 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
1679 #define RAIL_CH_TYPE_NORMAL       ((RAIL_ChannelConfigEntryType_t) RAIL_CH_TYPE_NORMAL)
1680 #define RAIL_CH_TYPE_CONC_BASE    ((RAIL_ChannelConfigEntryType_t) RAIL_CH_TYPE_CONC_BASE)
1681 #define RAIL_CH_TYPE_CONC_VIRTUAL ((RAIL_ChannelConfigEntryType_t) RAIL_CH_TYPE_CONC_VIRTUAL)
1682 #endif//DOXYGEN_SHOULD_SKIP_THIS
1683 
1684 /**
1685  * @def RADIO_CONFIG_ENABLE_CONC_PHY
1686  * @brief Indicates this version of RAIL supports concurrent PHY information in
1687  * radio configurator output. Needed for backwards compatibility.
1688  */
1689 #define RADIO_CONFIG_ENABLE_CONC_PHY 1
1690 
1691 /**
1692  * @def RADIO_CONFIG_ENABLE_STACK_INFO
1693  * @brief Indicates this version of RAIL supports stack info feature in
1694  * radio configurator output. Needed for backwards compatibility.
1695  */
1696 #define RADIO_CONFIG_ENABLE_STACK_INFO
1697 
1698 /**
1699  * @struct RAIL_AlternatePhy_t
1700  * @brief Alternate PHY configuration entry structure, which gathers some info
1701  *   on the alternate PHY in the context of concurrent mode.
1702  */
1703 typedef struct RAIL_AlternatePhy {
1704   uint32_t baseFrequency; /**< A base frequency in Hz of this channel set. */
1705   uint32_t channelSpacing; /**< A channel spacing in Hz of this channel set. */
1706   uint16_t numberOfChannels; /**< The number of channels (and not the channel number !) */
1707   uint16_t minIf_kHz; /**< minimum IF for the alternate PHY in kHz. */
1708   uint16_t minBaseIf_kHz; /**< minimum IF for the base PHY in kHz. */
1709   bool isOfdmModem; /**< Indicates that OFDM modem is used by this alternate PHY. */
1710 } RAIL_AlternatePhy_t;
1711 
1712 /**
1713  * @struct RAIL_ChannelConfigEntry_t
1714  * @brief A channel configuration entry structure, which defines a channel range
1715  *   and parameters across which a corresponding radio configuration is valid.
1716  *
1717  * operating frequency = baseFrequency
1718  *   + channelSpacing * (channel - physicalChannelOffset);
1719  */
1720 typedef struct RAIL_ChannelConfigEntry {
1721   const uint32_t *phyConfigDeltaAdd; /**< The minimum radio configuration to apply to the base
1722                                           configuration for this channel set. */
1723   uint32_t baseFrequency; /**< A base frequency in Hz of this channel set. */
1724   uint32_t channelSpacing; /**< A channel spacing in Hz of this channel set. */
1725   uint16_t physicalChannelOffset; /**< The offset to subtract from the logical
1726                                        channel to align them with the zero
1727                                        based physical channels which are
1728                                        relative to baseFrequency.
1729                                        (i.e., By default ch 0 = base freq, but
1730                                        if offset = 11, ch 11 = base freq.) */
1731   uint16_t channelNumberStart; /**< The first valid RAIL channel number for this
1732                                     channel set. */
1733   uint16_t channelNumberEnd; /**< The last valid RAIL channel number for this
1734                                   channel set. */
1735   RAIL_TxPower_t maxPower; /**< The maximum power allowed in this channel set. */
1736   RAIL_ChannelConfigEntryAttr_t *attr; /**< A pointer to a structure containing
1737                                             attributes specific to this
1738                                             channel set. */
1739   RAIL_ChannelConfigEntryType_t entryType; /**< Indicates channel config type. */
1740   uint8_t reserved[3]; /**< to align to 32-bit boundary. */
1741   const uint8_t *stackInfo; /**< Array containing information according to the protocolId value,
1742                                  first byte of this array.
1743                                  The first 2 fields are common to all protocols and accessible by RAIL,
1744                                  others are ignored by RAIL and only used by the application.
1745                                  Common fields are listed in RAIL_StackInfoCommon_t. */
1746   RAIL_AlternatePhy_t *alternatePhy; /**< Pointer to alternate PHY. */
1747 } RAIL_ChannelConfigEntry_t;
1748 
1749 /// @struct RAIL_ChannelConfig_t
1750 /// @brief A channel configuration structure, which defines the channel meaning
1751 ///   when a channel number is passed into a RAIL function, e.g., RAIL_StartTx()
1752 ///   and RAIL_StartRx().
1753 ///
1754 /// A RAIL_ChannelConfig_t structure defines the channel scheme that an
1755 /// application uses when registered in RAIL_ConfigChannels().
1756 ///
1757 /// These are a few examples of different channel configurations:
1758 /// @code{.c}
1759 /// // 21 channels starting at 2.45 GHz with channel spacing of 1 MHz
1760 /// // ... generated by Simplicity Studio (i.e., rail_config.c) ...
1761 /// const uint32_t generated[] = { ... };
1762 /// RAIL_ChannelConfigEntryAttr_t generated_entryAttr = { ... };
1763 /// const RAIL_ChannelConfigEntry_t generated_channels[] = {
1764 ///   {
1765 ///     .phyConfigDeltaAdd = NULL, // Add this to default configuration for this entry
1766 ///     .baseFrequency = 2450000000,
1767 ///     .channelSpacing = 1000000,
1768 ///     .physicalChannelOffset = 0,
1769 ///     .channelNumberStart = 0,
1770 ///     .channelNumberEnd = 20,
1771 ///     .maxPower = RAIL_TX_POWER_MAX,
1772 ///     .attr = &generated_entryAttr
1773 ///   },
1774 /// };
1775 /// const RAIL_ChannelConfig_t generated_channelConfig = {
1776 ///   .phyConfigBase = generated, // Default radio configuration for all entries
1777 ///   .phyConfigDeltaSubtract = NULL, // Subtract this to restore the default configuration
1778 ///   .configs = generated_channels,
1779 ///   .length = 1 // There are this many channel configuration entries
1780 /// };
1781 /// const RAIL_ChannelConfig_t *channelConfigs[] = {
1782 ///   &generated_channelConfig,
1783 ///   NULL
1784 /// };
1785 /// // ... in main code ...
1786 /// // Associate a specific channel configuration with a particular RAIL instance.
1787 /// RAIL_ConfigChannels(railHandle, channelConfigs[0]);
1788 ///
1789 /// // 4 nonlinear channels
1790 /// // ... in rail_config.c ...
1791 /// const uint32_t generated[] = { ... };
1792 /// RAIL_ChannelConfigEntryAttr_t generated_entryAttr = { ... };
1793 /// const RAIL_ChannelConfigEntry_t generated_channels[] = {
1794 ///   {
1795 ///     .phyConfigDeltaAdd = NULL, // Add this to default configuration for this entry
1796 ///     .baseFrequency = 910123456,
1797 ///     .channelSpacing = 0,
1798 ///     .physicalChannelOffset = 0,
1799 ///     .channelNumberStart = 0,
1800 ///     .channelNumberEnd = 0,
1801 ///     .maxPower = RAIL_TX_POWER_MAX,
1802 ///     .attr = &generated_entryAttr
1803 ///   },
1804 ///   {
1805 ///     .phyConfigDeltaAdd = NULL,
1806 ///     .baseFrequency = 911654789,
1807 ///     .channelSpacing = 0,
1808 ///     .physicalChannelOffset = 0, // Since ch spacing = 0, offset can be 0
1809 ///     .channelNumberStart = 1,
1810 ///     .channelNumberEnd = 1,
1811 ///     .maxPower = RAIL_TX_POWER_MAX,
1812 ///     .attr = &generated_entryAttr
1813 ///   },
1814 ///   {
1815 ///     .phyConfigDeltaAdd = NULL,
1816 ///     .baseFrequency = 912321456,
1817 ///     .channelSpacing = 100000,
1818 ///     .physicalChannelOffset = 2, // Since ch spacing != 0, offset = 2
1819 ///     .channelNumberStart = 2, // ch 2 = baseFrequency
1820 ///     .channelNumberEnd = 2,
1821 ///     .maxPower = RAIL_TX_POWER_MAX,
1822 ///     .attr = &generated_entryAttr
1823 ///   },
1824 ///   {
1825 ///     .phyConfigDeltaAdd = NULL,
1826 ///     .baseFrequency = 913147852,
1827 ///     .channelSpacing = 0,
1828 ///     .physicalChannelOffset = 0,
1829 ///     .channelNumberStart = 3,
1830 ///     .channelNumberEnd = 3,
1831 ///     .maxPower = RAIL_TX_POWER_MAX,
1832 ///     .attr = &generated_entryAttr
1833 ///   },
1834 /// };
1835 /// const RAIL_ChannelConfig_t generated_channelConfig = {
1836 ///   .phyConfigBase = generated, // Default radio configuration for all entries
1837 ///   .phyConfigDeltaSubtract = NULL, // Subtract this to restore the default configuration
1838 ///   .configs = generated_channels,
1839 ///   .length = 4 // There are this many channel configuration entries
1840 /// };
1841 /// const RAIL_ChannelConfig_t *channelConfigs[] = {
1842 ///   &generated_channelConfig,
1843 ///   NULL
1844 /// };
1845 /// // ... in main code ...
1846 /// // Associate a specific channel configuration with a particular RAIL instance.
1847 /// RAIL_ConfigChannels(railHandle, channelConfigs[0]);
1848 ///
1849 /// // Multiple radio configurations
1850 /// // ... in rail_config.c ...
1851 /// const uint32_t generated0[] = { ... };
1852 /// RAIL_ChannelConfigEntryAttr_t generated0_entryAttr = { ... };
1853 /// const RAIL_ChannelConfigEntry_t generated0_channels[] = {
1854 ///   {
1855 ///     .phyConfigDeltaAdd = NULL, // Add this to the default configuration for this entry
1856 ///     .baseFrequency = 2450000000,
1857 ///     .channelSpacing = 1000000,
1858 ///     .physicalChannelOffset = 0,
1859 ///     .channelNumberStart = 0,
1860 ///     .channelNumberEnd = 20,
1861 ///     .maxPower = RAIL_TX_POWER_MAX,
1862 ///     .attr = &generated0_entryAttr
1863 ///   },
1864 /// };
1865 /// const RAIL_ChannelConfig_t generated0_channelConfig = {
1866 ///   .phyConfigBase = generated0, // Default radio configuration for all entries
1867 ///   .phyConfigDeltaSubtract = NULL, // Subtract this to restore default configuration
1868 ///   .configs = generated0_channels,
1869 ///   .length = 1 // There are this many channel configuration entries
1870 /// };
1871 /// const uint32_t generated1[] = { ... };
1872 /// RAIL_ChannelConfigEntryAttr_t generated1_entryAttr = { ... };
1873 /// const RAIL_ChannelConfigEntry_t generated1_channels[] = {
1874 ///   {
1875 ///     .phyConfigDeltaAdd = NULL,
1876 ///     .baseFrequency = 2450000000,
1877 ///     .channelSpacing = 1000000,
1878 ///     .physicalChannelOffset = 0,
1879 ///     .channelNumberStart = 0,
1880 ///     .channelNumberEnd = 20,
1881 ///     .maxPower = -100, // Use this entry when TX power <= -10dBm
1882 ///     .attr = &generated1_entryAttr
1883 ///   },
1884 ///   {
1885 ///     .phyConfigDeltaAdd = NULL,
1886 ///     .baseFrequency = 2450000000,
1887 ///     .channelSpacing = 1000000,
1888 ///     .physicalChannelOffset = 0,
1889 ///     .channelNumberStart = 0,
1890 ///     .channelNumberEnd = 20,
1891 ///     .maxPower = 15, // Use this entry when TX power > -10dBm
1892 ///                     // and TX power <= 1.5dBm
1893 ///     .attr = &generated1_entryAttr
1894 ///   },
1895 ///   {
1896 ///     .phyConfigDeltaAdd = NULL,
1897 ///     .baseFrequency = 2450000000,
1898 ///     .channelSpacing = 1000000,
1899 ///     .physicalChannelOffset = 0,
1900 ///     .channelNumberStart = 0,
1901 ///     .channelNumberEnd = 20,
1902 ///     .maxPower = RAIL_TX_POWER_MAX, // Use this entry when TX power > 1.5dBm
1903 ///     .attr = &generated1_entryAttr
1904 ///   },
1905 /// };
1906 /// const RAIL_ChannelConfig_t generated1_channelConfig = {
1907 ///   .phyConfigBase = generated1,
1908 ///   .phyConfigDeltaSubtract = NULL,
1909 ///   .configs = generated1_channels,
1910 ///   .length = 3
1911 /// };
1912 /// const uint32_t generated2[] = { ... };
1913 /// RAIL_ChannelConfigEntryAttr_t generated2_entryAttr = { ... };
1914 /// const RAIL_ChannelConfigEntry_t generated2_channels[] = {
1915 ///   {
1916 ///     .phyConfigDeltaAdd = NULL,
1917 ///     .baseFrequency = 2450000000,
1918 ///     .channelSpacing = 1000000,
1919 ///     .physicalChannelOffset = 0,
1920 ///     .channelNumberStart = 0,
1921 ///     .channelNumberEnd = 20,
1922 ///     .maxPower = RAIL_TX_POWER_MAX,
1923 ///     .attr = &generated2_entryAttr
1924 ///   },
1925 /// };
1926 /// const RAIL_ChannelConfig_t generated2_channelConfig = {
1927 ///   .phyConfigBase = generated2,
1928 ///   .phyConfigDeltaSubtract = NULL,
1929 ///   .configs = generated2_channels,
1930 ///   .length = 1
1931 /// };
1932 /// const RAIL_ChannelConfig_t *channelConfigs[] = {
1933 ///   &generated0_channelConfig,
1934 ///   &generated1_channelConfig,
1935 ///   &generated2_channelConfig,
1936 ///   NULL
1937 /// };
1938 /// // ... in main code ...
1939 /// // Create a unique RAIL handle for each unique channel configuration.
1940 /// railHandle0 = RAIL_Init(&railCfg0, &RAILCb_RfReady0);
1941 /// railHandle1 = RAIL_Init(&railCfg1, &RAILCb_RfReady1);
1942 /// railHandle2 = RAIL_Init(&railCfg2, &RAILCb_RfReady2);
1943 /// // Associate each channel configuration with its corresponding RAIL handle.
1944 /// RAIL_ConfigChannels(railHandle0, channelConfigs[0]);
1945 /// RAIL_ConfigChannels(railHandle1, channelConfigs[1]);
1946 /// RAIL_ConfigChannels(railHandle2, channelConfigs[2]);
1947 /// // Use a RAIL handle and channel to access the desired channel configuration entry.
1948 /// RAIL_SetTxPowerDbm(railHandle1, 100); // set 10.0 dBm TX power
1949 /// RAIL_StartRx(railHandle1, 0, &schedInfo); // RX using generated1_channels[2]
1950 /// RAIL_SetTxPowerDbm(railHandle1, 0); // set 0 dBm TX power
1951 /// RAIL_StartRx(railHandle1, 0, &schedInfo); // RX using generated1_channels[1]
1952 /// RAIL_StartRx(railHandle2, 0, &schedInfo); // RX using generated2_channels[0]
1953 /// @endcode
1954 
1955 typedef struct RAIL_ChannelConfig {
1956   const uint32_t *phyConfigBase; /**< Base radio configuration for the corresponding
1957                                       channel configuration entries. */
1958   const uint32_t *phyConfigDeltaSubtract; /**< Minimum radio configuration to restore
1959                                                channel entries back to base
1960                                                configuration. */
1961   const RAIL_ChannelConfigEntry_t *configs; /**< Pointer to an array of
1962                                                  RAIL_ChannelConfigEntry_t
1963                                                  entries. */
1964   uint32_t length; /**< Number of RAIL_ChannelConfigEntry_t entries. */
1965   uint32_t signature; /**< Signature for this structure. Only used on modules. */
1966 } RAIL_ChannelConfig_t;
1967 
1968 /**
1969  * @struct RAIL_ChannelMetadata_t
1970  * @brief Container for individual channel metadata.
1971  */
1972 typedef struct RAIL_ChannelMetadata {
1973   uint16_t channel; /**< Channel number */
1974   uint16_t reserved; /**< Word alignment */
1975   uint32_t frequency; /**< Channel frequency, in Hz */
1976 } RAIL_ChannelMetadata_t;
1977 
1978 /**
1979  * @struct RAIL_StackInfoCommon_t
1980  * @brief StackInfo fields common to all protocols.
1981  */
1982 typedef struct RAIL_StackInfoCommon {
1983   uint8_t protocolId; /**< Same as RAIL_PtiProtocol_t */
1984   uint8_t phyId;  /**< PHY Id depending on the protocol_id value */
1985 } RAIL_StackInfoCommon_t;
1986 
1987 /**
1988  * @typedef RAIL_RadioConfigChangedCallback_t
1989  * @brief A pointer to a function called whenever a radio configuration change occurs.
1990  *
1991  * @param[in] railHandle A handle for RAIL instance.
1992  * @param[in] entry The radio configuration entry being changed to.
1993  */
1994 typedef void (*RAIL_RadioConfigChangedCallback_t)(RAIL_Handle_t railHandle,
1995                                                   const RAIL_ChannelConfigEntry_t *entry);
1996 
1997 /** @} */ // end of group Radio_Configuration
1998 
1999 /******************************************************************************
2000  * Packet Trace Interface (PTI) Structures
2001  *****************************************************************************/
2002 /**
2003  * @addtogroup PTI
2004  * @{
2005  */
2006 
2007 /**
2008  * @enum RAIL_PtiProtocol_t
2009  * @brief The protocol that RAIL outputs via the Packet Trace Interface (PTI).
2010  */
RAIL_ENUM(RAIL_PtiProtocol_t)2011 RAIL_ENUM(RAIL_PtiProtocol_t) {
2012   RAIL_PTI_PROTOCOL_CUSTOM = 0, /**< PTI output for a custom protocol. */
2013   RAIL_PTI_PROTOCOL_THREAD = 2, /**< PTI output for the Thread protocol. */
2014   RAIL_PTI_PROTOCOL_BLE = 3, /**< PTI output for the Bluetooth Smart protocol. */
2015   RAIL_PTI_PROTOCOL_CONNECT = 4, /**< PTI output for the Connect protocol. */
2016   RAIL_PTI_PROTOCOL_ZIGBEE = 5, /**< PTI output for the Zigbee protocol. */
2017   RAIL_PTI_PROTOCOL_ZWAVE = 6, /**< PTI output for the Z-Wave protocol. */
2018   RAIL_PTI_PROTOCOL_WISUN = 7, /**< PTI output for the Wi-SUN protocol. */
2019   RAIL_PTI_PROTOCOL_802154 = 8, /**< PTI output for a custom protocol using a built-in 802.15.4 radio config. */
2020 };
2021 
2022 #ifndef DOXYGEN_SHOULD_SKIP_THIS
2023 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
2024 #define RAIL_PTI_PROTOCOL_CUSTOM  ((RAIL_PtiProtocol_t) RAIL_PTI_PROTOCOL_CUSTOM)
2025 #define RAIL_PTI_PROTOCOL_THREAD  ((RAIL_PtiProtocol_t) RAIL_PTI_PROTOCOL_THREAD)
2026 #define RAIL_PTI_PROTOCOL_BLE     ((RAIL_PtiProtocol_t) RAIL_PTI_PROTOCOL_BLE)
2027 #define RAIL_PTI_PROTOCOL_CONNECT ((RAIL_PtiProtocol_t) RAIL_PTI_PROTOCOL_CONNECT)
2028 #define RAIL_PTI_PROTOCOL_ZIGBEE  ((RAIL_PtiProtocol_t) RAIL_PTI_PROTOCOL_ZIGBEE)
2029 #define RAIL_PTI_PROTOCOL_ZWAVE   ((RAIL_PtiProtocol_t) RAIL_PTI_PROTOCOL_ZWAVE)
2030 #define RAIL_PTI_PROTOCOL_802154  ((RAIL_PtiProtocol_t) RAIL_PTI_PROTOCOL_802154)
2031 #endif//DOXYGEN_SHOULD_SKIP_THIS
2032 
2033 /** @} */ // end of group PTI
2034 
2035 /******************************************************************************
2036  * Data Management Structures
2037  *****************************************************************************/
2038 /**
2039  * @addtogroup Data_Management
2040  * @{
2041  */
2042 
2043 /**
2044  * @enum RAIL_TxDataSource_t
2045  * @brief Transmit data sources supported by RAIL.
2046  */
RAIL_ENUM(RAIL_TxDataSource_t)2047 RAIL_ENUM(RAIL_TxDataSource_t) {
2048   TX_PACKET_DATA, /**< Uses the frame hardware to packetize data. */
2049   /** Uses the multi-level frequency modulation data.
2050    * @note This is only supported on devices where \ref RAIL_SUPPORTS_MFM
2051    *   or \ref RAIL_SupportsMfm() are true.
2052    * @note This feature cannot be used with built-in protocols (802.15.4, BLE,
2053    *   Z-Wave).
2054    */
2055   TX_MFM_DATA,
2056   /** A count of the choices in this enumeration. */
2057   RAIL_TX_DATA_SOURCE_COUNT // Must be last
2058 };
2059 
2060 #ifndef DOXYGEN_SHOULD_SKIP_THIS
2061 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
2062 #define TX_PACKET_DATA            ((RAIL_TxDataSource_t) TX_PACKET_DATA)
2063 #define TX_MFM_DATA               ((RAIL_TxDataSource_t) TX_MFM_DATA)
2064 #define RAIL_TX_DATA_SOURCE_COUNT ((RAIL_TxDataSource_t) RAIL_TX_DATA_SOURCE_COUNT)
2065 #endif//DOXYGEN_SHOULD_SKIP_THIS
2066 
2067 /**
2068  * @enum RAIL_RxDataSource_t
2069  * @brief Receive data sources supported by RAIL.
2070  *
2071  * @note Data sources other than \ref RX_PACKET_DATA require use of
2072  *   \ref RAIL_DataMethod_t::FIFO_MODE.
2073  */
RAIL_ENUM(RAIL_RxDataSource_t)2074 RAIL_ENUM(RAIL_RxDataSource_t) {
2075   RX_PACKET_DATA, /**< Uses the frame hardware to packetize data. */
2076   RX_DEMOD_DATA, /**< Gets 8-bit data output from the demodulator. */
2077   RX_IQDATA_FILTLSB, /**< Gets lower 16 bits of I/Q data provided to the
2078                           demodulator. */
2079   RX_IQDATA_FILTMSB, /**< Gets highest 16 bits of I/Q data provided to the
2080                          demodulator. */
2081   RX_DIRECT_MODE_DATA, /**< Gets RX direct mode data output from the demodulator.
2082                             Only supported if
2083                             \ref RAIL_SUPPORTS_RX_DIRECT_MODE_DATA_TO_FIFO
2084                             is true. */
2085   /** A count of the choices in this enumeration. */
2086   RAIL_RX_DATA_SOURCE_COUNT // Must be last
2087 };
2088 
2089 #ifndef DOXYGEN_SHOULD_SKIP_THIS
2090 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
2091 #define RX_PACKET_DATA            ((RAIL_RxDataSource_t) RX_PACKET_DATA)
2092 #define RX_DEMOD_DATA             ((RAIL_RxDataSource_t) RX_DEMOD_DATA)
2093 #define RX_IQDATA_FILTLSB         ((RAIL_RxDataSource_t) RX_IQDATA_FILTLSB)
2094 #define RX_IQDATA_FILTMSB         ((RAIL_RxDataSource_t) RX_IQDATA_FILTMSB)
2095 #define RX_DIRECT_MODE_DATA       ((RAIL_RxDataSource_t) RX_DIRECT_MODE_DATA)
2096 #define RAIL_RX_DATA_SOURCE_COUNT ((RAIL_RxDataSource_t) RAIL_RX_DATA_SOURCE_COUNT)
2097 #endif//DOXYGEN_SHOULD_SKIP_THIS
2098 
2099 /**
2100  * @enum RAIL_DataMethod_t
2101  * @brief Methods for the application to provide and retrieve data from RAIL.
2102  *
2103  * For Transmit the distinction between \ref RAIL_DataMethod_t::PACKET_MODE
2104  * and \ref RAIL_DataMethod_t::FIFO_MODE has become more cosmetic than
2105  * functional, as the RAIL_WriteTxFifo() and RAIL_SetTxFifoThreshold() APIs
2106  * and related \ref RAIL_EVENT_TX_FIFO_ALMOST_EMPTY event can be used in
2107  * either mode. For Receive the distinction is functionally important because
2108  * in \ref RAIL_DataMethod_t::PACKET_MODE rollback occurs automatically for
2109  * unsuccessfully-received packets (\ref RAIL_RxPacketStatus_t ABORT statuses),
2110  * flushing their data. In \ref RAIL_DataMethod_t::FIFO_MODE rollback is
2111  * prevented, leaving the data from unsuccessfully-received packets in the
2112  * receive FIFO for the application to deal with. This allows for packets
2113  * larger than the receive FIFO size where automatic rollback would corrupt
2114  * the receive FIFO.
2115  */
RAIL_ENUM(RAIL_DataMethod_t)2116 RAIL_ENUM(RAIL_DataMethod_t) {
2117   PACKET_MODE, /**< Packet-based data method. */
2118   FIFO_MODE, /**< FIFO-based data method. */
2119   /** A count of the choices in this enumeration. */
2120   RAIL_DATA_METHOD_COUNT // Must be last
2121 };
2122 
2123 #ifndef DOXYGEN_SHOULD_SKIP_THIS
2124 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
2125 #define PACKET_MODE            ((RAIL_DataMethod_t) PACKET_MODE)
2126 #define FIFO_MODE              ((RAIL_DataMethod_t) FIFO_MODE)
2127 #define RAIL_DATA_METHOD_COUNT ((RAIL_DataMethod_t) RAIL_DATA_METHOD_COUNT)
2128 #endif//DOXYGEN_SHOULD_SKIP_THIS
2129 
2130 /**
2131  * @def RAIL_FIFO_THRESHOLD_DISABLED
2132  * @brief A FIFO threshold value that disables the threshold.
2133  */
2134 #define RAIL_FIFO_THRESHOLD_DISABLED 0xFFFFU
2135 
2136 /**
2137  * @struct RAIL_DataConfig_t
2138  * @brief RAIL data configuration structure
2139  *
2140  * Select the transmit/receive data sources and the
2141  * method the application uses to provide/retrieve data from RAIL.
2142  */
2143 typedef struct {
2144   RAIL_TxDataSource_t txSource; /**< Source of TX Data. */
2145   RAIL_RxDataSource_t rxSource; /**< Source of RX Data. */
2146   RAIL_DataMethod_t txMethod; /**< Method of providing transmit data. */
2147   RAIL_DataMethod_t rxMethod; /**< Method of retrieving receive data. */
2148 } RAIL_DataConfig_t;
2149 
2150 /** @} */ // end of group Data Management
2151 
2152 /******************************************************************************
2153  * State Transitions
2154  *****************************************************************************/
2155 /**
2156  * @addtogroup State_Transitions
2157  * @{
2158  */
2159 
2160 /**
2161  * @enum RAIL_RadioState_t
2162  * @brief The state of the radio.
2163  */
RAIL_ENUM(RAIL_RadioState_t)2164 RAIL_ENUM(RAIL_RadioState_t) {
2165   RAIL_RF_STATE_INACTIVE = 0u,       /**< Radio is inactive. */
2166   RAIL_RF_STATE_ACTIVE = (1u << 0),  /**< Radio is either idle or,
2167                                           in combination with the RX and TX states,
2168                                           receiving or transmitting a frame.*/
2169   RAIL_RF_STATE_RX = (1u << 1),      /**< Radio is in receive. */
2170   RAIL_RF_STATE_TX = (1u << 2),      /**< Radio is in transmit. */
2171   RAIL_RF_STATE_IDLE = (RAIL_RF_STATE_ACTIVE),  /**< Radio is idle. */
2172   /** Radio is actively receiving a frame. */
2173   RAIL_RF_STATE_RX_ACTIVE = (RAIL_RF_STATE_RX | RAIL_RF_STATE_ACTIVE),
2174   /** Radio is actively transmitting a frame. */
2175   RAIL_RF_STATE_TX_ACTIVE = (RAIL_RF_STATE_TX | RAIL_RF_STATE_ACTIVE)
2176 };
2177 
2178 #ifndef DOXYGEN_SHOULD_SKIP_THIS
2179 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
2180 #define RAIL_RF_STATE_INACTIVE  ((RAIL_RadioState_t) RAIL_RF_STATE_INACTIVE)
2181 #define RAIL_RF_STATE_ACTIVE    ((RAIL_RadioState_t) RAIL_RF_STATE_ACTIVE)
2182 #define RAIL_RF_STATE_RX        ((RAIL_RadioState_t) RAIL_RF_STATE_RX)
2183 #define RAIL_RF_STATE_TX        ((RAIL_RadioState_t) RAIL_RF_STATE_TX)
2184 #define RAIL_RF_STATE_IDLE      ((RAIL_RadioState_t) RAIL_RF_STATE_IDLE)
2185 #define RAIL_RF_STATE_RX_ACTIVE ((RAIL_RadioState_t) RAIL_RF_STATE_RX_ACTIVE)
2186 #define RAIL_RF_STATE_TX_ACTIVE ((RAIL_RadioState_t) RAIL_RF_STATE_TX_ACTIVE)
2187 #endif//DOXYGEN_SHOULD_SKIP_THIS
2188 
2189 /**
2190  * @struct RAIL_StateTransitions_t
2191  * @brief Used to specify radio states to transition to on success or failure.
2192  */
2193 typedef struct RAIL_StateTransitions {
2194   /**
2195    * Indicate the state the radio should return to after a successful action.
2196    */
2197   RAIL_RadioState_t success;
2198   /**
2199    * Indicate the state the radio should return to after an error.
2200    */
2201   RAIL_RadioState_t error;
2202 } RAIL_StateTransitions_t;
2203 
2204 /**
2205  * @enum RAIL_RadioStateDetail_t
2206  * @brief The detailed state of the radio.
2207  *
2208  * The three radio state bits \ref RAIL_RF_STATE_DETAIL_IDLE_STATE, \ref
2209  * RAIL_RF_STATE_DETAIL_RX_STATE, and \ref RAIL_RF_STATE_DETAIL_TX_STATE
2210  * comprise a set of mutually exclusive core radio states. Only one (or none)
2211  * of these bits can be set at a time. Otherwise, the value is invalid.
2212  *
2213  * The precise meaning of each of these three core bits, when set, depends on
2214  * the value of the two bits \ref RAIL_RF_STATE_DETAIL_TRANSITION and \ref
2215  * RAIL_RF_STATE_DETAIL_ACTIVE. When \ref RAIL_RF_STATE_DETAIL_TRANSITION is
2216  * set, the radio is transitioning into the core radio state corresponding
2217  * to the set state bit. When it is clear, the radio is already in the core
2218  * radio state that corresponds to the set state bit. When \ref
2219  * RAIL_RF_STATE_DETAIL_ACTIVE is set, the radio is actively transmitting or
2220  * receiving. When it is clear, the radio is not actively transmitting or receiving.
2221  * This bit will always be clear when \ref RAIL_RF_STATE_DETAIL_IDLE_STATE is
2222  * set, and will always be set when \ref RAIL_RF_STATE_DETAIL_TX_STATE is set.
2223  * Otherwise, the value is invalid.
2224  *
2225  * The bit \ref RAIL_RF_STATE_DETAIL_NO_FRAMES is set if the radio is currently
2226  * operating with frame detection disabled, and clear otherwise. The bit \ref
2227  * RAIL_RF_STATE_DETAIL_LBT_SHIFT is set if an LBT/CSMA operation
2228  * (e.g., performing CCA) is currently ongoing, and clear otherwise.
2229  */
RAIL_ENUM(RAIL_RadioStateDetail_t)2230 RAIL_ENUM(RAIL_RadioStateDetail_t) {
2231   /** Shift position of \ref RAIL_RF_STATE_DETAIL_IDLE_STATE bit */
2232   RAIL_RF_STATE_DETAIL_IDLE_STATE_SHIFT = 0u,
2233   /** Shift position of \ref RAIL_RF_STATE_DETAIL_RX_STATE bit */
2234   RAIL_RF_STATE_DETAIL_RX_STATE_SHIFT,
2235   /** Shift position of \ref RAIL_RF_STATE_DETAIL_TX_STATE bit */
2236   RAIL_RF_STATE_DETAIL_TX_STATE_SHIFT,
2237   /** Shift position of \ref RAIL_RF_STATE_DETAIL_TRANSITION bit */
2238   RAIL_RF_STATE_DETAIL_TRANSITION_SHIFT,
2239   /** Shift position of \ref RAIL_RF_STATE_DETAIL_ACTIVE bit */
2240   RAIL_RF_STATE_DETAIL_ACTIVE_SHIFT,
2241   /** Shift position of \ref RAIL_RF_STATE_DETAIL_NO_FRAMES bit */
2242   RAIL_RF_STATE_DETAIL_NO_FRAMES_SHIFT,
2243   /** Shift position of \ref RAIL_RF_STATE_DETAIL_LBT bit */
2244   RAIL_RF_STATE_DETAIL_LBT_SHIFT,
2245 };
2246 
2247 /** Radio is inactive. */
2248 #define RAIL_RF_STATE_DETAIL_INACTIVE (0U)
2249 /** Radio is in or headed to the idle state. */
2250 #define RAIL_RF_STATE_DETAIL_IDLE_STATE (1U << RAIL_RF_STATE_DETAIL_IDLE_STATE_SHIFT)
2251 /** Radio is in or headed to the receive state. */
2252 #define RAIL_RF_STATE_DETAIL_RX_STATE (1U << RAIL_RF_STATE_DETAIL_RX_STATE_SHIFT)
2253 /** Radio is in or headed to the transmit state. */
2254 #define RAIL_RF_STATE_DETAIL_TX_STATE (1U << RAIL_RF_STATE_DETAIL_TX_STATE_SHIFT)
2255 /** Radio is headed to the idle, receive, or transmit state. */
2256 #define RAIL_RF_STATE_DETAIL_TRANSITION (1U << RAIL_RF_STATE_DETAIL_TRANSITION_SHIFT)
2257 /** Radio is actively transmitting or receiving. */
2258 #define RAIL_RF_STATE_DETAIL_ACTIVE (1U << RAIL_RF_STATE_DETAIL_ACTIVE_SHIFT)
2259 /** Radio has frame detect disabled. */
2260 #define RAIL_RF_STATE_DETAIL_NO_FRAMES (1U << RAIL_RF_STATE_DETAIL_NO_FRAMES_SHIFT)
2261 /** LBT/CSMA operation is currently ongoing. */
2262 #define RAIL_RF_STATE_DETAIL_LBT (1U << RAIL_RF_STATE_DETAIL_LBT_SHIFT)
2263 /** Mask for core radio state bits. */
2264 #define RAIL_RF_STATE_DETAIL_CORE_STATE_MASK (RAIL_RF_STATE_DETAIL_IDLE_STATE \
2265                                               | RAIL_RF_STATE_DETAIL_RX_STATE \
2266                                               | RAIL_RF_STATE_DETAIL_TX_STATE)
2267 
2268 /**
2269  * @enum RAIL_IdleMode_t
2270  * @brief An enumeration for the different types of supported idle modes. These
2271  *   vary how quickly and destructively they put the radio into idle.
2272  */
RAIL_ENUM(RAIL_IdleMode_t)2273 RAIL_ENUM(RAIL_IdleMode_t) {
2274   /**
2275    * Idle the radio by turning off receive and canceling any future scheduled
2276    * receive or transmit operations. It does not abort a receive or
2277    * transmit in progress.
2278    */
2279   RAIL_IDLE,
2280   /**
2281    * Idle the radio by turning off receive and any scheduled events. It
2282    * also aborts any receive, transmit, or scheduled events in progress.
2283    */
2284   RAIL_IDLE_ABORT,
2285   /**
2286    * Force the radio into a shutdown mode by stopping whatever state is in
2287    * progress. This is a more destructive shutdown than \ref RAIL_IDLE or
2288    * \ref RAIL_IDLE_ABORT and can be useful in certain situations when directed
2289    * by the support team or for debugging. Note that this method may corrupt
2290    * receive and transmit buffers so it requires a more thorough cleanup
2291    * and any held packets will be lost.
2292    */
2293   RAIL_IDLE_FORCE_SHUTDOWN,
2294   /**
2295    * Similar to the \ref RAIL_IDLE_FORCE_SHUTDOWN command, however, it will also
2296    * clear any pending RAIL events related to receive and transmit.
2297    */
2298   RAIL_IDLE_FORCE_SHUTDOWN_CLEAR_FLAGS,
2299 };
2300 
2301 #ifndef DOXYGEN_SHOULD_SKIP_THIS
2302 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
2303 #define RAIL_IDLE                            ((RAIL_IdleMode_t) RAIL_IDLE)
2304 #define RAIL_IDLE_ABORT                      ((RAIL_IdleMode_t) RAIL_IDLE_ABORT)
2305 #define RAIL_IDLE_FORCE_SHUTDOWN             ((RAIL_IdleMode_t) RAIL_IDLE_FORCE_SHUTDOWN)
2306 #define RAIL_IDLE_FORCE_SHUTDOWN_CLEAR_FLAGS ((RAIL_IdleMode_t) RAIL_IDLE_FORCE_SHUTDOWN_CLEAR_FLAGS)
2307 #endif//DOXYGEN_SHOULD_SKIP_THIS
2308 
2309 /** @} */ // end of group State_Transitions
2310 
2311 /******************************************************************************
2312  * TX Channel Hopping
2313  *****************************************************************************/
2314 /**
2315  * @addtogroup Tx_Channel_Hopping TX Channel Hopping
2316  * @{
2317  */
2318 
2319 /**
2320  * @struct RAIL_TxChannelHoppingConfigEntry_t
2321  * @brief Structure that represents one of the channels that is part of a
2322  *   \ref RAIL_TxChannelHoppingConfig_t sequence of channels used in
2323  *   channel hopping.
2324  */
2325 typedef struct RAIL_TxChannelHoppingConfigEntry {
2326   /**
2327    * The channel number to be used for this entry in the channel hopping
2328    * sequence. If this is an invalid channel for the current PHY, the
2329    * call to \ref RAIL_SetNextTxRepeat() will fail.
2330    */
2331   uint16_t channel;
2332   /**
2333    * Pad bytes reserved for future use and currently ignored.
2334    */
2335   uint8_t reserved[2];
2336   /**
2337    * Idle time in microseconds to wait before transmitting on the channel
2338    * indicated by this entry.
2339    */
2340   uint32_t delay;
2341 } RAIL_TxChannelHoppingConfigEntry_t;
2342 
2343 /**
2344  * @struct RAIL_TxChannelHoppingConfig_t
2345  * @brief Wrapper struct that will contain the sequence of
2346  *   \ref RAIL_TxChannelHoppingConfigEntry_t that represents the channel
2347  *   sequence to use during TX Channel Hopping.
2348  */
2349 typedef struct RAIL_TxChannelHoppingConfig {
2350   /**
2351    * Pointer to contiguous global read-write memory that will be used
2352    * by RAIL to store channel hopping information throughout its operation.
2353    * It need not be initialized and applications should never write
2354    * data anywhere in this buffer.
2355    *
2356    * @note the size of this buffer must be at least as large as
2357    * 3 + 30 * numberOfChannels, plus the sum of the sizes of the
2358    * radioConfigDeltaAdd's of the required channels, plus the size of the
2359    * radioConfigDeltaSubtract. In the case that one channel
2360    * appears two or more times in your channel sequence
2361    * (e.g., 1, 2, 3, 2), you must account for the radio configuration
2362    * size that number of times (i.e., need to count channel 2's
2363    * radio configuration size twice for the given example). The overall
2364    * 3 words and 30 words per channel needed in this buffer are
2365    * for internal use to the library.
2366    */
2367   uint32_t *buffer;
2368   /**
2369    * This parameter must be set to the length of the buffer array. This way,
2370    * during configuration, the software can confirm it's writing within the
2371    * range of the buffer. The configuration API will return an error
2372    * if bufferLength is insufficient.
2373    */
2374   uint16_t bufferLength;
2375   /**
2376    * The number of channels in the channel hopping sequence, which is the
2377    * number of elements in the array that entries points to.
2378    */
2379   uint8_t numberOfChannels;
2380   /**
2381    * Pad byte reserved for future use and currently ignored.
2382    */
2383   uint8_t reserved;
2384   /**
2385    * A pointer to the first element of an array of \ref
2386    * RAIL_TxChannelHoppingConfigEntry_t that represents the channels
2387    * used during channel hopping. The length of this array must be
2388    * numberOfChannels.
2389    */
2390   RAIL_TxChannelHoppingConfigEntry_t *entries;
2391 } RAIL_TxChannelHoppingConfig_t;
2392 
2393 /** @} */ // end of group Tx_Channel_Hopping
2394 
2395 /******************************************************************************
2396  * TX/RX Configuration Structures
2397  *****************************************************************************/
2398 /**
2399  * @addtogroup Transmit
2400  * @{
2401  */
2402 
2403 /**
2404  * @enum RAIL_StopMode_t
2405  * @brief Stop radio operation options bit mask
2406  */
RAIL_ENUM(RAIL_StopMode_t)2407 RAIL_ENUM(RAIL_StopMode_t) {
2408   /** Shift position of \ref RAIL_STOP_MODE_ACTIVE bit */
2409   RAIL_STOP_MODE_ACTIVE_SHIFT = 0,
2410   /** Shift position of \ref RAIL_STOP_MODE_PENDING bit */
2411   RAIL_STOP_MODE_PENDING_SHIFT = 1
2412 };
2413 
2414 /** Do not stop any radio operations */
2415 #define RAIL_STOP_MODES_NONE   (0U)
2416 /** Stop active radio operations only */
2417 #define RAIL_STOP_MODE_ACTIVE (1U << RAIL_STOP_MODE_ACTIVE_SHIFT)
2418 /** Stop pending radio operations */
2419 #define RAIL_STOP_MODE_PENDING (1U << RAIL_STOP_MODE_PENDING_SHIFT)
2420 /** Stop all radio operations */
2421 #define RAIL_STOP_MODES_ALL (0xFFU)
2422 
2423 /**
2424  * @enum RAIL_TxOptions_t
2425  * @brief Transmit options, in reality a bitmask.
2426  */
RAIL_ENUM_GENERIC(RAIL_TxOptions_t,uint32_t)2427 RAIL_ENUM_GENERIC(RAIL_TxOptions_t, uint32_t) {
2428   /** Shift position of \ref RAIL_TX_OPTION_WAIT_FOR_ACK bit */
2429   RAIL_TX_OPTION_WAIT_FOR_ACK_SHIFT = 0,
2430   /** Shift position of \ref RAIL_TX_OPTION_REMOVE_CRC bit */
2431   RAIL_TX_OPTION_REMOVE_CRC_SHIFT,
2432   /** Shift position of \ref RAIL_TX_OPTION_SYNC_WORD_ID bit */
2433   RAIL_TX_OPTION_SYNC_WORD_ID_SHIFT,
2434   /** Shift position of \ref RAIL_TX_OPTION_ANTENNA0 bit */
2435   RAIL_TX_OPTION_ANTENNA0_SHIFT,
2436   /** Shift position of \ref RAIL_TX_OPTION_ANTENNA1 bit */
2437   RAIL_TX_OPTION_ANTENNA1_SHIFT,
2438   /** Shift position of \ref RAIL_TX_OPTION_ALT_PREAMBLE_LEN bit */
2439   RAIL_TX_OPTION_ALT_PREAMBLE_LEN_SHIFT,
2440   /** Shift position of \ref RAIL_TX_OPTION_CCA_PEAK_RSSI bit */
2441   RAIL_TX_OPTION_CCA_PEAK_RSSI_SHIFT,
2442   /** Shift position of \ref RAIL_TX_OPTION_CCA_ONLY bit */
2443   RAIL_TX_OPTION_CCA_ONLY_SHIFT,
2444   /** Shift position of \ref RAIL_TX_OPTION_RESEND bit */
2445   RAIL_TX_OPTION_RESEND_SHIFT,
2446   /** Shift position of \ref RAIL_TX_OPTION_CONCURRENT_PHY_ID bit */
2447   RAIL_TX_OPTION_CONCURRENT_PHY_ID_SHIFT,
2448   /** A count of the choices in this enumeration. */
2449   RAIL_TX_OPTIONS_COUNT // Must be last
2450 };
2451 
2452 /** A value representing no options enabled. */
2453 #define RAIL_TX_OPTIONS_NONE 0UL
2454 /** All options disabled by default. This is the fastest TX option to apply. */
2455 #define RAIL_TX_OPTIONS_DEFAULT RAIL_TX_OPTIONS_NONE
2456 /**
2457  * An option to configure whether or not the TXing node will listen for an ACK.
2458  * If this is false, the isAck flag in RAIL_RxPacketDetails_t of a received
2459  * packet will always be false.
2460  */
2461 #define RAIL_TX_OPTION_WAIT_FOR_ACK (1UL << RAIL_TX_OPTION_WAIT_FOR_ACK_SHIFT)
2462 /**
2463  * An option to remove CRC bytes from TX packets. To receive packets when the
2464  * sender has this option set true, set \ref RAIL_RX_OPTION_IGNORE_CRC_ERRORS
2465  * on the receive side.
2466  */
2467 #define RAIL_TX_OPTION_REMOVE_CRC (1UL << RAIL_TX_OPTION_REMOVE_CRC_SHIFT)
2468 /**
2469  * An option to select which sync word is used during the transmission.
2470  * When two sync words are configured by the PHY or \ref RAIL_ConfigSyncWords()
2471  * enabling this option selects SYNC2 rather than SYNC1 for the upcoming transmit.
2472  *
2473  * This option should not be used when only one sync word has been configured.
2474  *
2475  * @note There are a few special radio configurations (e.g. BLE Viterbi) that do
2476  * not support transmitting different sync words.
2477  */
2478 #define RAIL_TX_OPTION_SYNC_WORD_ID (1UL << RAIL_TX_OPTION_SYNC_WORD_ID_SHIFT)
2479 /**
2480  * An option to select antenna 0 for transmission. If the antenna selection
2481  * option is not set or if both antenna options are set, then the transmit
2482  * will occur on either antenna depending on the last receive or transmit
2483  * selection. This option is only valid on platforms that support
2484  * \ref Antenna_Control and have been configured via RAIL_ConfigAntenna().
2485  *
2486  * @note These TX antenna options do not control the antenna used for
2487  *   \ref Auto_Ack transmissions, which always occur on the same antenna
2488  *   used to receive the packet being acknowledged.
2489  */
2490 #define RAIL_TX_OPTION_ANTENNA0 (1UL << RAIL_TX_OPTION_ANTENNA0_SHIFT)
2491 /**
2492  * An option to select antenna 1 for transmission. If the antenna selection
2493  * option is not set or if both antenna options are set, then the transmit
2494  * will occur on either antenna depending on the last receive or transmit
2495  * selection. This option is only valid on platforms that support
2496  * \ref Antenna_Control and have been configured via RAIL_ConfigAntenna().
2497  *
2498  * @note These TX antenna options do not control the antenna used for
2499  *   \ref Auto_Ack transmissions, which always occur on the same antenna
2500  *   used to receive the packet being acknowledged.
2501  */
2502 #define RAIL_TX_OPTION_ANTENNA1 (1UL << RAIL_TX_OPTION_ANTENNA1_SHIFT)
2503 /**
2504  * An option to dynamically set an alternate preamble length for the
2505  * transmission. If this option is not set, the pre-configured
2506  * channel preamble length will be used.
2507  */
2508 #define RAIL_TX_OPTION_ALT_PREAMBLE_LEN (1UL << RAIL_TX_OPTION_ALT_PREAMBLE_LEN_SHIFT)
2509 /**
2510  * An option to use peak rather than average RSSI energy detected during
2511  * CSMA's RAIL_CsmaConfig_t::ccaDuration or LBT's
2512  * RAIL_LbtConfig_t::lbtDuration to determine whether the channel is clear
2513  * or busy. This option is only valid when calling one of the CCA transmit
2514  * routines: \ref RAIL_StartCcaCsmaTx, \ref RAIL_StartCcaLbtTx, \ref
2515  * RAIL_StartScheduledCcaCsmaTx, or \ref RAIL_StartScheduledCcaLbtTx.
2516  *
2517  * @note This option does nothing on platforms like EFR32XG1 that lack
2518  * support for capturing peak RSSI energy.
2519  */
2520 #define RAIL_TX_OPTION_CCA_PEAK_RSSI (1UL << RAIL_TX_OPTION_CCA_PEAK_RSSI_SHIFT)
2521 /**
2522  * An option to only perform the CCA (CSMA/LBT) operation but *not*
2523  * automatically transmit if the channel is clear. This option is only valid
2524  * when calling one of the CCA transmit routines: \ref RAIL_StartCcaCsmaTx,
2525  * \ref RAIL_StartCcaLbtTx, \ref RAIL_StartScheduledCcaCsmaTx, or \ref
2526  * RAIL_StartScheduledCcaLbtTx.
2527  *
2528  * Application can then use the \ref RAIL_EVENT_TX_CHANNEL_CLEAR to
2529  * initiate transmit manually, e.g., giving it the opportunity to adjust
2530  * outgoing packet data before the packet goes out.
2531  *
2532  * @note Configured state transitions to Rx or Idle are suspended during
2533  * this CSMA/LBT operation. If packet reception occurs, the radio will
2534  * return to the state it was in just prior to the CSMA/LBT operation
2535  * when that reception (including any AutoACK response) is complete.
2536  */
2537 #define RAIL_TX_OPTION_CCA_ONLY (1UL << RAIL_TX_OPTION_CCA_ONLY_SHIFT)
2538 
2539 /**
2540  * An option to resend packet at the beginning of the Transmit FIFO.
2541  *
2542  * The packet to be resent must have been previously provided by
2543  * \ref RAIL_SetTxFifo() or \ref RAIL_WriteTxFifo() passing true for
2544  * the latter's reset parameter. It works by setting the
2545  * transmit FIFO's read offset to the beginning of the FIFO while
2546  * leaving its write offset intact. For this to work,
2547  * \ref RAIL_DataConfig_t::txMethod must be RAIL_DataMethod_t::PACKET_MODE
2548  * (i.e., the packet can't exceed the Transmit FIFO's size), otherwise
2549  * undefined behavior will result.
2550  *
2551  * This option can also be used with \ref RAIL_SetNextTxRepeat() to cause
2552  * the repeated packet(s) to all be the same as the first.
2553  */
2554 #define RAIL_TX_OPTION_RESEND (1UL << RAIL_TX_OPTION_RESEND_SHIFT)
2555 
2556 /**
2557  * An option to specify which PHY is used to transmit in the case of concurrent mode.
2558  * Concurrent mode is only allowed on EFR32xG25 for some predefined combinations of Wi-SUN PHYs.
2559  * When set/unset, the alternate/base PHY is used to transmit.
2560  */
2561 #define RAIL_TX_OPTION_CONCURRENT_PHY_ID (1UL << RAIL_TX_OPTION_CONCURRENT_PHY_ID_SHIFT)
2562 
2563 /** A value representing all possible options. */
2564 #define RAIL_TX_OPTIONS_ALL 0xFFFFFFFFUL
2565 
2566 /**
2567  * @struct RAIL_TxPacketDetails_t
2568  * @brief Detailed information requested about the packet that was just,
2569  *   or is currently being, transmitted.
2570  */
2571 typedef struct RAIL_TxPacketDetails {
2572   /**
2573    * The timestamp of the transmitted packet in the RAIL timebase,
2574    * filled in by RAIL_GetTxPacketDetails().
2575    */
2576   RAIL_PacketTimeStamp_t timeSent;
2577   /**
2578    * Indicate whether the transmitted packet was an automatic ACK. In a generic
2579    * sense, an automatic ACK is defined as a packet sent in response to a
2580    * received ACK-requesting frame when auto-ACK is enabled. In a protocol
2581    * specific sense this definition may be more or less restrictive to match the
2582    * specification and you should refer to that protocol's documentation.
2583    */
2584   bool isAck;
2585 } RAIL_TxPacketDetails_t;
2586 
2587 /**
2588  * @enum RAIL_ScheduledTxDuringRx_t
2589  * @brief Enumerates the possible outcomes of what will occur if a
2590  *   scheduled TX ends up firing during RX. Because RX and TX can't
2591  *   happen at the same time, it is up to the user how the TX should be
2592  *   handled. This enumeration is passed into RAIL_StartScheduledTx()
2593  *   as part of \ref RAIL_ScheduleTxConfig_t.
2594  */
RAIL_ENUM(RAIL_ScheduledTxDuringRx_t)2595 RAIL_ENUM(RAIL_ScheduledTxDuringRx_t) {
2596   /**
2597    * The scheduled TX will be postponed until RX completes and then sent.
2598    */
2599   RAIL_SCHEDULED_TX_DURING_RX_POSTPONE_TX,
2600   /**
2601    * The scheduled TX will be aborted and a
2602    * \ref RAIL_EVENT_TX_BLOCKED event will fire.
2603    */
2604   RAIL_SCHEDULED_TX_DURING_RX_ABORT_TX,
2605 };
2606 
2607 #ifndef DOXYGEN_SHOULD_SKIP_THIS
2608 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
2609 #define RAIL_SCHEDULED_TX_DURING_RX_POSTPONE_TX ((RAIL_ScheduledTxDuringRx_t) RAIL_SCHEDULED_TX_DURING_RX_POSTPONE_TX)
2610 #define RAIL_SCHEDULED_TX_DURING_RX_ABORT_TX    ((RAIL_ScheduledTxDuringRx_t) RAIL_SCHEDULED_TX_DURING_RX_ABORT_TX)
2611 #endif//DOXYGEN_SHOULD_SKIP_THIS
2612 
2613 /**
2614  * @struct RAIL_ScheduleTxConfig_t
2615  * @brief A configuration structure for a scheduled transmit.
2616  */
2617 typedef struct RAIL_ScheduleTxConfig {
2618   /**
2619    * The time when to transmit this packet. The exact interpretation of
2620    * this value depends on the mode specified below.
2621    */
2622   RAIL_Time_t when;
2623   /**
2624    * The type of delay. See the \ref RAIL_TimeMode_t documentation for
2625    * more information. Be sure to use \ref RAIL_TIME_ABSOLUTE delays for
2626    * time-critical protocols.
2627    */
2628   RAIL_TimeMode_t mode;
2629   /**
2630    * Indicate which action to take with a scheduled TX if it occurs during RX.
2631    * See \ref RAIL_ScheduledTxDuringRx_t structure for more information on
2632    * potential options.
2633    */
2634   RAIL_ScheduledTxDuringRx_t txDuringRx;
2635 } RAIL_ScheduleTxConfig_t;
2636 
2637 /**
2638  * @def RAIL_MAX_LBT_TRIES
2639  * @brief The maximum number of LBT/CSMA retries supported.
2640  */
2641 #define RAIL_MAX_LBT_TRIES      (15U)
2642 
2643 /**
2644  * @def RAIL_MAX_CSMA_EXPONENT
2645  * @brief The maximum power-of-2 exponent for CSMA backoffs.
2646  */
2647 #define RAIL_MAX_CSMA_EXPONENT  (8U)
2648 
2649 ///
2650 /// @struct RAIL_CsmaConfig_t
2651 /// @brief A configuration structure for the CSMA transmit algorithm.
2652 ///
2653 /// One of RAIL's schemes for polite spectrum access is an implementation of
2654 /// a Carrier-Sense Multiple Access (CSMA) algorithm based on IEEE 802.15.4
2655 /// (unslotted).
2656 /// \n In pseudo-code it works like this, showing relevant event notifications:
2657 /// @code{.c}
2658 /// // Return true to transmit packet, false to not transmit packet.
2659 /// bool performCsma(const RAIL_CsmaConfig_t *csmaConfig)
2660 /// {
2661 ///   bool isFixedBackoff = ((csmaConfig->csmaMinBoExp == 0)
2662 ///                          && (csmaConfig->csmaMaxBoExp == 0));
2663 ///   int backoffExp = csmaConfig->csmaMinBoExp; // Initial backoff exponent
2664 ///   int backoffMultiplier = 1; // Assume fixed backoff
2665 ///   int try;
2666 ///
2667 ///   // Special-case tries == 0 to transmit immediately without backoff+CCA
2668 ///   if (csmaConfig->csmaTries == 0) {
2669 ///     return true;
2670 ///   }
2671 ///
2672 ///   // Start overall timeout if specified:
2673 ///   if (csmaConfig->csmaTimeout > 0) {
2674 ///     StartAbortTimer(csmaConfig->csmaTimeout, RAIL_EVENT_TX_CHANNEL_BUSY);
2675 ///     // If timeout occurs, abort and signal the indicated event.
2676 ///   }
2677 ///
2678 ///   for (try = 0; try < csmaConfig->csmaTries; try++) {
2679 ///     if (try > 0) {
2680 ///       signalEvent(RAIL_EVENT_TX_CCA_RETRY);
2681 ///     }
2682 ///     // Determine the backoff multipler for this try:
2683 ///     if (isFixedBackoff) {
2684 ///       // backoffMultiplier already set to 1 for fixed backoff
2685 ///     } else {
2686 ///       // Start with the backoff exponent for this try:
2687 ///       if (try > 0) {
2688 ///         backoffExp++;
2689 ///         if (backoffExp > csmaConfig->csmaMaxBoExp) {
2690 ///           backoffExp = csmaConfig->csmaMaxBoExp;
2691 ///         }
2692 ///       }
2693 ///       // Pick random multiplier between 0 and 2^backoffExp - 1 inclusive:
2694 ///       backoffMultiplier = pickRandomInteger(0, (1 << backoffExp) - 1);
2695 ///     }
2696 ///     // Perform the backoff:
2697 ///     delayMicroseconds(backoffMultiplier * csmaConfig->ccaBackoff);
2698 ///     // Perform the Clear-Channel Assessment (CCA):
2699 ///     // Channel is considered busy if radio is actively receiving or
2700 ///     // transmitting, or the average energy detected across duration
2701 ///     // is above the threshold.
2702 ///     signalEvent(RAIL_EVENT_TX_START_CCA);
2703 ///     if (performCca(csmaConfig->ccaDuration, csmaConfig->ccaThreshold)) {
2704 ///       // CCA (and CSMA) success: Transmit after RX-to-TX turnaround
2705 ///       StopAbortTimer();
2706 ///       signalEvent(RAIL_EVENT_TX_CHANNEL_CLEAR);
2707 ///       return true;
2708 ///     } else {
2709 ///       // CCA failed: loop to try again, or exit if out of tries
2710 ///     }
2711 ///   }
2712 ///   // Overall CSMA failure: Don't transmit
2713 ///   StopAbortTimer();
2714 ///   signalEvent(RAIL_EVENT_TX_CHANNEL_BUSY);
2715 ///   return false;
2716 /// }
2717 /// @endcode
2718 ///
2719 typedef struct RAIL_CsmaConfig {
2720   /**
2721    * The minimum (starting) exponent for CSMA random backoff (2^exp - 1).
2722    * It can range from 0 to \ref RAIL_MAX_CSMA_EXPONENT.
2723    *
2724    * @warning On EFR32, due to a hardware limitation, this can only be 0
2725    *   if \ref csmaMaxBoExp is also 0 specifying a non-random fixed backoff.
2726    *   \ref RAIL_STATUS_INVALID_PARAMETER will result otherwise.
2727    *   If you really want CSMA's first iteration to have no backoff prior to
2728    *   CCA, with subsequent iterations having random backoff as the exponent
2729    *   is increased, you must do a fixed backoff of 0 operation first
2730    *   (\ref csmaMinBoExp = 0, \ref csmaMaxBoExp = 0, \ref ccaBackoff = 0,
2731    *   \ref csmaTries = 1), and if that fails (\ref RAIL_EVENT_TX_CHANNEL_BUSY),
2732    *   follow up with a random backoff operation starting at \ref csmaMinBoExp
2733    *   = 1 for the remaining iterations.
2734    */
2735   uint8_t  csmaMinBoExp;
2736   /**
2737    * The maximum exponent for CSMA random backoff (2^exp - 1).
2738    * It can range from 0 to \ref RAIL_MAX_CSMA_EXPONENT and must be greater
2739    * than or equal to \ref csmaMinBoExp.
2740    * \n If both exponents are 0, a non-random fixed backoff of \ref ccaBackoff
2741    * duration results.
2742    */
2743   uint8_t  csmaMaxBoExp;
2744   /**
2745    * The number of backoff-then-CCA iterations that can fail before reporting
2746    * \ref RAIL_EVENT_TX_CHANNEL_BUSY. Typically ranges from 1 to \ref
2747    * RAIL_MAX_LBT_TRIES; higher values are disallowed. A value 0 always
2748    * transmits immediately without performing CSMA, similar to calling
2749    * RAIL_StartTx().
2750    */
2751   uint8_t  csmaTries;
2752   /**
2753    * The CCA RSSI threshold, in dBm, above which the channel is
2754    * considered 'busy'.
2755    */
2756   int8_t   ccaThreshold;
2757   /**
2758    * The backoff unit period in RAIL's microsecond time base. It is
2759    * multiplied by the random backoff exponential controlled by \ref
2760    * csmaMinBoExp and \ref csmaMaxBoExp to determine the overall backoff
2761    * period. For random backoffs, any value above 511 microseconds will
2762    * be truncated. For fixed backoffs it can go up to 65535 microseconds.
2763    */
2764   uint16_t ccaBackoff;
2765   /**
2766    * The minimum desired CCA check duration in microseconds. The RSSI is
2767    * averaged over this duration by default but can be set to use the peak RSSI,
2768    * on supported platforms, using the \ref RAIL_TX_OPTION_CCA_PEAK_RSSI option.
2769    *
2770    * @note Depending on the radio configuration, due to hardware constraints,
2771    *   the actual duration may be longer. Also, if the requested duration
2772    *   is too large for the radio to accommodate, RAIL_StartCcaCsmaTx()
2773    *   will fail returning \ref RAIL_STATUS_INVALID_PARAMETER.
2774    */
2775   uint16_t ccaDuration;
2776   /**
2777    * An overall timeout, in RAIL's microsecond time base, for the operation.
2778    * If the transmission doesn't start before this timeout expires, the
2779    * transmission will fail with \ref RAIL_EVENT_TX_CHANNEL_BUSY.
2780    * A value 0 means no timeout is imposed.
2781    */
2782   RAIL_Time_t csmaTimeout;
2783 } RAIL_CsmaConfig_t;
2784 
2785 /**
2786  * @def RAIL_CSMA_CONFIG_802_15_4_2003_2p4_GHz_OQPSK_CSMA
2787  * @brief RAIL_CsmaConfig_t initializer configuring CSMA per IEEE 802.15.4-2003
2788  *   on 2.4 GHz OSPSK, commonly used by ZigBee.
2789  */
2790 #define RAIL_CSMA_CONFIG_802_15_4_2003_2p4_GHz_OQPSK_CSMA {                    \
2791     /* CSMA per 802.15.4-2003 on 2.4 GHz OSPSK, commonly used by ZigBee     */ \
2792     /* csmaMinBoExp */ 3,   /* 2^3-1 for 0..7 backoffs on 1st try           */ \
2793     /* csmaMaxBoExp */ 5,   /* 2^5-1 for 0..31 backoffs on 3rd+ tries       */ \
2794     /* csmaTries    */ 5,   /* 5 tries overall (4 re-tries)                 */ \
2795     /* ccaThreshold */ -75, /* 10 dB above sensitivity                      */ \
2796     /* ccaBackoff   */ 320, /* 20 symbols at 16 us/symbol                   */ \
2797     /* ccaDuration  */ 128, /* 8 symbols at 16 us/symbol                    */ \
2798     /* csmaTimeout  */ 0,   /* No timeout                                   */ \
2799 }
2800 
2801 /**
2802  * @def RAIL_CSMA_CONFIG_SINGLE_CCA
2803  * @brief RAIL_CsmaConfig_t initializer configuring a single CCA prior to TX.
2804  *   It can be used to as a basis for implementing other channel access schemes
2805  *   with custom backoff delays. Users can override ccaBackoff with a fixed
2806  *   delay on each use.
2807  */
2808 #define RAIL_CSMA_CONFIG_SINGLE_CCA {                                          \
2809     /* Perform a single CCA after 'fixed' delay                             */ \
2810     /* csmaMinBoExp */ 0,   /* Used for fixed backoff                       */ \
2811     /* csmaMaxBoExp */ 0,   /* Used for fixed backoff                       */ \
2812     /* csmaTries    */ 1,   /* Single try                                   */ \
2813     /* ccaThreshold */ -75, /* Override if not desired choice               */ \
2814     /* ccaBackoff   */ 0,   /* No backoff (override with fixed value)       */ \
2815     /* ccaDuration  */ 128, /* Override if not desired length               */ \
2816     /* csmaTimeout  */ 0,   /* no timeout                                   */ \
2817 }
2818 
2819 ///
2820 /// @struct RAIL_LbtConfig_t
2821 /// @brief A configuration structure for the LBT transmit algorithm.
2822 ///
2823 /// One of RAIL's schemes for polite spectrum access is an implementation of
2824 /// a Listen-Before-Talk (LBT) algorithm, loosely based on ETSI 300 220-1.
2825 /// \n Currently, however, it is constrained by the EFR32's CSMA-oriented hardware
2826 /// so is turned into an equivalent \ref RAIL_CsmaConfig_t configuration and
2827 /// passed to the CSMA engine:
2828 /// @code{.c}
2829 /// if (lbtMaxBoRand == lbtMinBoRand) {
2830 ///   // Fixed backoff
2831 ///   csmaMinBoExp = csmaMaxBoExp = 0;
2832 ///   if (lbtMinBoRand == 0) {
2833 ///     ccaBackoff = lbtBackoff;
2834 ///   } else {
2835 ///     ccaBackoff = lbtMinBoRand * lbtBackoff;
2836 ///   }
2837 ///   ccaDuration = lbtDuration;
2838 /// } else {
2839 ///   // Random backoff: map to random range 0 .. (lbtMaxBoRand - lbtMinBoRand)
2840 ///   csmaMinBoExp = csmaMaxBoExp = ceiling(log2(lbtMaxBoRand - lbtMinBoRand));
2841 ///   ccaBackoff = round((lbtBackoff * (lbtMaxBoRand - lbtMinBoRand))
2842 ///                      / (1 << csmaMinBoExp));
2843 ///   ccaDuration = lbtDuration + (lbtMinBoRand * lbtBackoff);
2844 /// }
2845 /// csmaTries    = lbtTries;
2846 /// ccaThreshold = lbtThreshold;
2847 /// csmaTimeout  = lbtTimeout;
2848 /// @endcode
2849 ///
2850 typedef struct RAIL_LbtConfig {
2851   /**
2852    * The minimum backoff random multiplier.
2853    */
2854   uint8_t  lbtMinBoRand;
2855   /**
2856    * The maximum backoff random multiplier.
2857    * It must be greater than or equal to \ref lbtMinBoRand.
2858    * \n If both backoff multipliers are identical, a non-random fixed backoff
2859    * of \ref lbtBackoff times the multiplier (minimum 1) duration results.
2860    */
2861   uint8_t  lbtMaxBoRand;
2862   /**
2863    * The number of LBT iterations that can fail before reporting
2864    * \ref RAIL_EVENT_TX_CHANNEL_BUSY. Typically ranges from 1 to \ref
2865    * RAIL_MAX_LBT_TRIES; higher values are disallowed. A value 0 always
2866    * transmits immediately without performing LBT, similar to calling
2867    * RAIL_StartTx().
2868    */
2869   uint8_t  lbtTries;
2870   /**
2871    * The LBT RSSI threshold, in dBm, above which the channel is
2872    * considered 'busy'.
2873    */
2874   int8_t   lbtThreshold;
2875   /**
2876    * The backoff unit period, in RAIL's microsecond time base. It is
2877    * multiplied by the random backoff multiplier controlled by \ref
2878    * lbtMinBoRand and \ref lbtMaxBoRand to determine the overall backoff
2879    * period. For random backoffs, any value above 511 microseconds will
2880    * be truncated. For fixed backoffs, it can go up to 65535 microseconds.
2881    */
2882   uint16_t lbtBackoff;
2883   /**
2884    * The minimum desired LBT check duration in microseconds.
2885    *
2886    * @note Depending on the radio configuration, due to hardware constraints,
2887    *   the actual duration may be longer. Also, if the requested duration
2888    *   is too large for the radio to accommodate, RAIL_StartCcaLbtTx()
2889    *   will fail returning \ref RAIL_STATUS_INVALID_PARAMETER.
2890    */
2891   uint16_t lbtDuration;
2892   /**
2893    * An overall timeout, in RAIL's microsecond time base, for the operation.
2894    * If the transmission doesn't start before this timeout expires, the
2895    * transmission will fail with \ref RAIL_EVENT_TX_CHANNEL_BUSY.
2896    * This is important for limiting LBT due to LBT's unbounded requirement
2897    * that if the channel is busy, the next try must wait for the channel to
2898    * clear. A value 0 means no timeout is imposed.
2899    */
2900   RAIL_Time_t lbtTimeout;
2901 } RAIL_LbtConfig_t;
2902 
2903 /**
2904  * @def RAIL_LBT_CONFIG_ETSI_EN_300_220_1_V2_4_1
2905  * @brief RAIL_LbtConfig_t initializer configuring LBT per ETSI 300 220-1
2906  *   V2.4.1 for a typical Sub-GHz band. To be practical, users should override
2907  *   lbtTries and/or lbtTimeout so channel access failure will be reported in a
2908  *   reasonable time frame rather than the unbounded time frame ETSI defined.
2909  */
2910 #define RAIL_LBT_CONFIG_ETSI_EN_300_220_1_V2_4_1 {                                \
2911     /* LBT per ETSI 300 220-1 V2.4.1                                        */    \
2912     /* LBT time = random backoff of 0-5 ms in .5 ms increments plus 5 ms fixed */ \
2913     /* lbtMinBoRand */ 0,    /*                                             */    \
2914     /* lbtMaxBoRand */ 10,   /*                                             */    \
2915     /* lbtTries     */ RAIL_MAX_LBT_TRIES, /* the maximum supported         */    \
2916     /* lbtThreshold */ -87,  /*                                             */    \
2917     /* lbtBackoff   */ 500,  /* 0.5 ms                                      */    \
2918     /* lbtDuration  */ 5000, /* 5 ms                                        */    \
2919     /* lbtTimeout   */ 0,    /* No timeout (recommend user override)        */    \
2920 }
2921 
2922 /**
2923  * @struct RAIL_SyncWordConfig_t
2924  * @brief RAIL sync words and length configuration.
2925  *
2926  */
2927 typedef struct RAIL_SyncWordConfig {
2928   /** Sync word length in bits, between 2 and 32, inclusive.*/
2929   uint8_t syncWordBits;
2930   /**
2931    *  Sync Word1
2932    *  @note Only @ref syncWordBits number of LS bits are used, which are sent or received on air LSB first.
2933    */
2934   uint32_t syncWord1;
2935   /**
2936    *  Sync Word2
2937    *  @note Only @ref syncWordBits number of LS bits are used, which are sent or received on air LSB first.
2938    */
2939   uint32_t syncWord2;
2940 } RAIL_SyncWordConfig_t;
2941 
2942 /** @} */ // end of group Transmit
2943 
2944 /**
2945  * @addtogroup Receive
2946  * @{
2947  */
2948 
2949 /**
2950  * @addtogroup Address_Filtering
2951  * @{
2952  */
2953 
2954 /// A default address filtering match table for configurations that use only one
2955 /// address field. The truth table for address matching is shown below.
2956 ///
2957 /// |                | No Match | Address 0 | Address 1 | Address 2 | Address 3 |
2958 /// |----------------|----------|-----------|-----------|-----------|-----------|
2959 /// | __No Match__   |    0     |     1     |     1     |     1     |     1     |
2960 /// | __Address 0__  |    1     |     1     |     1     |     1     |     1     |
2961 /// | __Address 1__  |    1     |     1     |     1     |     1     |     1     |
2962 /// | __Address 2__  |    1     |     1     |     1     |     1     |     1     |
2963 /// | __Address 3__  |    1     |     1     |     1     |     1     |     1     |
2964 ///
2965 #define ADDRCONFIG_MATCH_TABLE_SINGLE_FIELD (0x1FFFFFE)
2966 /// A default address filtering match table for configurations that use two
2967 /// address fields and want to match the same index in each. The truth
2968 /// table for address matching is shown below.
2969 ///
2970 /// |                | No Match | Address 0 | Address 1 | Address 2 | Address 3 |
2971 /// |----------------|----------|-----------|-----------|-----------|-----------|
2972 /// | __No Match__   |    0     |    0      |    0      |    0      |    0      |
2973 /// | __Address 0__  |    0     |    1      |    0      |    0      |    0      |
2974 /// | __Address 1__  |    0     |    0      |    1      |    0      |    0      |
2975 /// | __Address 2__  |    0     |    0      |    0      |    1      |    0      |
2976 /// | __Address 3__  |    0     |    0      |    0      |    0      |    1      |
2977 #define ADDRCONFIG_MATCH_TABLE_DOUBLE_FIELD (0x1041040)
2978 
2979 /// The maximum number of address fields that can be used by the address
2980 /// filtering logic.
2981 #define ADDRCONFIG_MAX_ADDRESS_FIELDS (2)
2982 
2983 /**
2984  * @struct RAIL_AddrConfig_t
2985  * @brief A structure to configure the address filtering functionality in RAIL.
2986  */
2987 typedef struct RAIL_AddrConfig {
2988   /**
2989    * A list of the start offsets for each field.
2990    *
2991    * These offsets are specified relative to the previous field's end.
2992    * For the first field, it is relative to either the beginning of the packet
2993    * or the end of the frame type byte if frame type decoding is enabled. If a
2994    * field is unused, it's offset should be set to 0.
2995    */
2996   uint8_t offsets[ADDRCONFIG_MAX_ADDRESS_FIELDS];
2997 
2998   /**
2999    * A list of the address field sizes.
3000    *
3001    * These sizes are specified in bytes from 0 to 8. If you choose a
3002    * size of 0, this field is effectively disabled.
3003    */
3004   uint8_t sizes[ADDRCONFIG_MAX_ADDRESS_FIELDS];
3005 
3006   /**
3007    * The truth table to determine how the two fields combine to create a match.
3008    *
3009    * For detailed information about how this truth table is formed, see the
3010    * detailed description of \ref Address_Filtering.
3011    *
3012    * For simple predefined configurations use the following defines.
3013    *  - ADDRCONFIG_MATCH_TABLE_SINGLE_FIELD
3014    *    - For filtering that only uses a single address field.
3015    *  - ADDRCONFIG_MATCH_TABLE_DOUBLE_FIELD for two field filtering where you
3016    *    - For filtering that uses two address fields in a configurations where
3017    *      you want the following logic `((Field0, Index0) && (Field1, Index0))
3018    *      || ((Field0, Index1) && (Field1, Index1)) || ...`
3019    */
3020   uint32_t matchTable;
3021 } RAIL_AddrConfig_t;
3022 
3023 /**
3024  * @brief A bitmask representation of which 4 filters passed for each
3025  *   \ref ADDRCONFIG_MAX_ADDRESS_FIELDS when filtering has completed
3026  *   successfully.
3027  *
3028  * It's layout is:
3029  * |  Bit 7 |  Bit 6 |  Bit 5 |  Bit 4 |  Bit 3 |  Bit 2 |  Bit 1 |  Bit 0 |
3030  * |--------+--------+--------+--------+--------+--------+--------+--------|
3031  * |   Second Address Field Nibble     |     First Address Field Nibble    |
3032  * | Addr 3 | Addr 2 | Addr 1 | Addr 0 | Addr 3 | Addr 2 | Addr 1 | Addr 0 |
3033  * |  match |  match |  match |  match |  match |  match |  match |  match |
3034  * |--------+--------+--------+--------+--------+--------+--------+--------|
3035  *
3036  * @note This information is valid in \ref RAIL_IEEE802154_Address_t on all
3037  *   platforms, but is only valid in \ref RAIL_RxPacketInfo_t on platforms
3038  *   where \ref RAIL_SUPPORTS_ADDR_FILTER_MASK is true.
3039  */
3040 typedef uint8_t RAIL_AddrFilterMask_t;
3041 
3042 /** @} */ // end of group Address_Filtering
3043 
3044 /**
3045  * @enum RAIL_RxOptions_t
3046  * @brief Receive options, in reality a bitmask.
3047  */
RAIL_ENUM_GENERIC(RAIL_RxOptions_t,uint32_t)3048 RAIL_ENUM_GENERIC(RAIL_RxOptions_t, uint32_t) {
3049   /** Shift position of \ref RAIL_RX_OPTION_STORE_CRC bit. */
3050   RAIL_RX_OPTION_STORE_CRC_SHIFT = 0,
3051   /** Shift position of \ref RAIL_RX_OPTION_IGNORE_CRC_ERRORS bit. */
3052   RAIL_RX_OPTION_IGNORE_CRC_ERRORS_SHIFT,
3053   /** Shift position of \ref RAIL_RX_OPTION_ENABLE_DUALSYNC bit. */
3054   RAIL_RX_OPTION_ENABLE_DUALSYNC_SHIFT,
3055   /** Shift position of \ref RAIL_RX_OPTION_TRACK_ABORTED_FRAMES bit. */
3056   RAIL_RX_OPTION_TRACK_ABORTED_FRAMES_SHIFT,
3057   /** Shift position of \ref RAIL_RX_OPTION_REMOVE_APPENDED_INFO bit. */
3058   RAIL_RX_OPTION_REMOVE_APPENDED_INFO_SHIFT,
3059   /** Shift position of \ref RAIL_RX_OPTION_ANTENNA0 bit. */
3060   RAIL_RX_OPTION_ANTENNA0_SHIFT,
3061   /** Shift position of \ref RAIL_RX_OPTION_ANTENNA1 bit. */
3062   RAIL_RX_OPTION_ANTENNA1_SHIFT,
3063   /** Shift position of \ref RAIL_RX_OPTION_DISABLE_FRAME_DETECTION bit. */
3064   RAIL_RX_OPTION_DISABLE_FRAME_DETECTION_SHIFT,
3065   #ifndef DOXYGEN_SHOULD_SKIP_THIS
3066   /** Shift position of \ref RAIL_RX_OPTION_SKIP_DC_CAL bit. */
3067   RAIL_RX_OPTION_SKIP_DC_CAL_SHIFT,
3068   /** Shift position of \ref RAIL_RX_OPTION_SKIP_SYNTH_CAL bit. */
3069   RAIL_RX_OPTION_SKIP_SYNTH_CAL_SHIFT,
3070   #endif //DOXYGEN_SHOULD_SKIP_THIS
3071   /** Shift position of \ref RAIL_RX_OPTION_CHANNEL_SWITCHING bit. */
3072   RAIL_RX_OPTION_CHANNEL_SWITCHING_SHIFT,
3073 };
3074 
3075 /** A value representing no options enabled. */
3076 #define RAIL_RX_OPTIONS_NONE 0
3077 /** All options are disabled by default. */
3078 #define RAIL_RX_OPTIONS_DEFAULT RAIL_RX_OPTIONS_NONE
3079 
3080 /**
3081  * An option to configure whether the CRC portion of the packet is included in
3082  * the packet payload exposed to the app on packet reception.
3083  * Defaults to false.
3084  */
3085 #define RAIL_RX_OPTION_STORE_CRC (1UL << RAIL_RX_OPTION_STORE_CRC_SHIFT)
3086 /**
3087  * An option to configure whether CRC errors will be ignored.
3088  * If this is set, RX will still be successful, even if
3089  * the CRC does not pass the check. Defaults to false.
3090  *
3091  * @note An expected ACK that fails CRC with this option set
3092  *   will still be considered the expected ACK, terminating
3093  *   the RAIL_AutoAckConfig_t::ackTimeout period.
3094  */
3095 #define RAIL_RX_OPTION_IGNORE_CRC_ERRORS (1UL << RAIL_RX_OPTION_IGNORE_CRC_ERRORS_SHIFT)
3096 
3097 /**
3098  * An option to control which sync words will be accepted. Setting it to
3099  * 0 (default) will cause the receiver to listen for SYNC1 only. Setting it to
3100  * 1 causes the receiver to listen for either SYNC1 or SYNC2. RX appended info
3101  * will contain which sync word was detected. Note, this only affects which
3102  * sync word(s) are received, but not what each of the sync words actually are.
3103  * This feature may not be available on some combinations of chips, PHYs, and
3104  * protocols. Use the compile time symbol RAIL_SUPPORTS_DUAL_SYNC_WORDS or
3105  * the runtime call RAIL_SupportsDualSyncWords() to check whether the
3106  * platform supports this feature. Also, DUALSYNC may be incompatible
3107  * with certain radio configurations. In these cases, setting this bit will
3108  * be ignored. See the data sheet or support team for more details.
3109  */
3110 #define RAIL_RX_OPTION_ENABLE_DUALSYNC (1UL << RAIL_RX_OPTION_ENABLE_DUALSYNC_SHIFT)
3111 
3112 /**
3113  * An option to configure whether frames which are aborted during reception
3114  * should continue to be tracked. Setting this option allows viewing Packet
3115  * Trace information for frames which get discarded. Defaults to false.
3116  *
3117  * This option is ignored when doing a \ref RAIL_IDLE_FORCE_SHUTDOWN or
3118  * \ref RAIL_IDLE_FORCE_SHUTDOWN_CLEAR_FLAGS.
3119  *
3120  * @note This option should not be used with coded PHYs since packet data
3121  *   received after the abort will not be decoded properly.
3122  */
3123 #define RAIL_RX_OPTION_TRACK_ABORTED_FRAMES (1UL << RAIL_RX_OPTION_TRACK_ABORTED_FRAMES_SHIFT)
3124 
3125 /**
3126  * An option to suppress capturing the appended information after
3127  * received frames. Defaults to false. When suppressed, certain
3128  * \ref RAIL_RxPacketDetails_t details will not be available for received
3129  * packets whose \ref RAIL_RxPacketStatus_t is among the RAIL_RX_PACKET_READY_
3130  * set.
3131  *
3132  * @warning This option should be changed only when the radio is idle
3133  *   and the receive FIFO is empty or has been reset,
3134  *   otherwise \ref RAIL_GetRxPacketInfo() and \ref RAIL_GetRxPacketDetails()
3135  *   may think appended info is packet data or vice-versa.
3136  */
3137 #define RAIL_RX_OPTION_REMOVE_APPENDED_INFO (1UL << RAIL_RX_OPTION_REMOVE_APPENDED_INFO_SHIFT)
3138 
3139 /**
3140  * An option to select the use of antenna 0 during receive (including
3141  * \ref Auto_Ack receive). If no antenna option is selected, the packet
3142  * will be received on the last antenna used for receive or transmit.
3143  * Defaults to false. This option is only valid on platforms that support
3144  * \ref Antenna_Control and have been configured via RAIL_ConfigAntenna().
3145  */
3146 #define RAIL_RX_OPTION_ANTENNA0 (1UL << RAIL_RX_OPTION_ANTENNA0_SHIFT)
3147 
3148 /**
3149  * An option to select the use of antenna 1 during receive (including
3150  * \ref Auto_Ack receive). If no antenna option is selected, the packet
3151  * will be received on the last antenna used for receive or transmit.
3152  * Defaults to false. This option is only valid on platforms that support
3153  * \ref Antenna_Control and have been configured via RAIL_ConfigAntenna().
3154  */
3155 #define RAIL_RX_OPTION_ANTENNA1 (1UL << RAIL_RX_OPTION_ANTENNA1_SHIFT)
3156 
3157 /**
3158  * An option combination to automatically choose an antenna during receive
3159  * (including \ref Auto_Ack receive). If both antenna 0 and antenna 1
3160  * options are set, the radio will dynamically switch between antennas
3161  * during packet detection and choose the best one for completing the
3162  * reception. This option is only valid when the antenna diversity
3163  * field is properly configured via Simplicity Studio.
3164  * This option is only valid on platforms that support
3165  * \ref Antenna_Control and have been configured via RAIL_ConfigAntenna().
3166  */
3167 #define RAIL_RX_OPTION_ANTENNA_AUTO (RAIL_RX_OPTION_ANTENNA0 | RAIL_RX_OPTION_ANTENNA1)
3168 
3169 /**
3170  * An option to disable frame detection. This can be useful for doing energy
3171  * detection without risking packet reception. Enabling this will abort any
3172  * frame currently being received in addition to preventing further frames
3173  * from being received. Defaults to false.
3174  */
3175 #define RAIL_RX_OPTION_DISABLE_FRAME_DETECTION (1UL << RAIL_RX_OPTION_DISABLE_FRAME_DETECTION_SHIFT)
3176 
3177 #ifndef DOXYGEN_SHOULD_SKIP_THIS
3178 /**
3179  * An option to skip DC calibration when transitioning from RX to RX. This can be
3180  * useful for reducing the state transition time, but risks impacting
3181  * receive capability. Enabling this bypasses DC calibration (like
3182  * \ref RAIL_RX_CHANNEL_HOPPING_OPTION_SKIP_DC_CAL)
3183  * Defaults to false.
3184  */
3185 #define RAIL_RX_OPTION_SKIP_DC_CAL (1UL << RAIL_RX_OPTION_SKIP_DC_CAL_SHIFT)
3186 
3187 /**
3188  * An option to skip synth calibration when transitioning from RX to RX. This can
3189  * be useful for reducing the state transition time, but risks impacting receive
3190  * capability. Enabling this bypasses synth calibration (like
3191  * \ref RAIL_RX_CHANNEL_HOPPING_OPTION_SKIP_SYNTH_CAL)
3192  * Defaults to false.
3193  */
3194 #define RAIL_RX_OPTION_SKIP_SYNTH_CAL (1U << RAIL_RX_OPTION_SKIP_SYNTH_CAL_SHIFT)
3195 #endif //DOXYGEN_SHOULD_SKIP_THIS
3196 
3197 /**
3198  * An option to enable IEEE 802.15.4 RX channel switching.
3199  * \ref RAIL_IEEE802154_ConfigRxChannelSwitching() must be called to configure the
3200  * feature before enabling it via this option.
3201  * Defaults to false.
3202  *
3203  * @note This option is only supported on specific chips where
3204  *   \ref RAIL_IEEE802154_SUPPORTS_RX_CHANNEL_SWITCHING is true.
3205  *
3206  * @note This option overrides \ref RAIL_RX_OPTION_ANTENNA0,
3207  *   \ref RAIL_RX_OPTION_ANTENNA1 and \ref RAIL_RX_OPTION_ANTENNA_AUTO antenna
3208  *   selection options.
3209  */
3210 #define RAIL_RX_OPTION_CHANNEL_SWITCHING (1U << RAIL_RX_OPTION_CHANNEL_SWITCHING_SHIFT)
3211 
3212 /** A value representing all possible options. */
3213 #define RAIL_RX_OPTIONS_ALL 0xFFFFFFFFUL
3214 
3215 /** The value returned by RAIL for an invalid RSSI, in dBm. */
3216 #define RAIL_RSSI_INVALID_DBM     (-128)
3217 /** The value returned by RAIL for an invalid RSSI: in quarter dBm. */
3218 #define RAIL_RSSI_INVALID         ((int16_t)(RAIL_RSSI_INVALID_DBM * 4))
3219 /** The lowest RSSI value returned by RAIL: in quarter dBm. */
3220 #define RAIL_RSSI_LOWEST          ((int16_t)(RAIL_RSSI_INVALID + 1))
3221 
3222 /** Maximum absolute value for RSSI offset */
3223 #define RAIL_RSSI_OFFSET_MAX      35
3224 
3225 /** A sentinel value to indicate waiting for a valid RSSI without a timeout. */
3226 #define RAIL_GET_RSSI_WAIT_WITHOUT_TIMEOUT ((RAIL_Time_t)0xFFFFFFFFU)
3227 /** A sentinel value to indicate no waiting for a valid RSSI. */
3228 #define RAIL_GET_RSSI_NO_WAIT ((RAIL_Time_t)0U)
3229 
3230 /**
3231  * @struct RAIL_ScheduleRxConfig_t
3232  * @brief Configures the scheduled RX algorithm.
3233  *
3234  * Defines the start and end times of the receive window created
3235  * for a scheduled receive. If either start or end times are disabled, they
3236  * will be ignored.
3237  */
3238 typedef struct RAIL_ScheduleRxConfig {
3239   /**
3240    * The time to start receive. See startMode for more information about the
3241    * types of start times that you can specify.
3242    */
3243   RAIL_Time_t start;
3244   /**
3245    * How to interpret the time value specified in the start parameter. See the
3246    * \ref RAIL_TimeMode_t documentation for more information. Use
3247    * \ref RAIL_TIME_ABSOLUTE for absolute times, \ref RAIL_TIME_DELAY for times
3248    * relative to the current time and \ref RAIL_TIME_DISABLED to ignore the
3249    * start time.
3250    */
3251   RAIL_TimeMode_t startMode;
3252   /**
3253    * The time to end receive. See endMode for more information about the types
3254    * of end times you can specify.
3255    */
3256   RAIL_Time_t end;
3257   /**
3258    * How to interpret the time value specified in the end parameter. See the
3259    * \ref RAIL_TimeMode_t documentation for more information. Note that, in
3260    * this API, if you specify a \ref RAIL_TIME_DELAY, it is relative to the
3261    * start time if given and relative to now if none is specified. Also, using
3262    * \ref RAIL_TIME_DISABLED means that this window will not end unless you
3263    * explicitly call \ref RAIL_Idle() or add an end event through a future
3264    * update to this configuration.
3265    */
3266   RAIL_TimeMode_t endMode;
3267   /**
3268    * While in scheduled RX, you can still control the radio state via
3269    * state transitions. This option configures whether a transition
3270    * to RX goes back to scheduled RX or to the normal RX state. Once in the
3271    * normal RX state, you will effectively end the scheduled RX window and can
3272    * continue to receive indefinitely depending on the state transitions. Set
3273    * to 1 to transition to normal RX and 0 to stay in the scheduled RX.
3274    *
3275    * This setting also influences the posting of
3276    * \ref RAIL_EVENT_RX_SCHEDULED_RX_END when the scheduled Rx window is
3277    * implicitly ended by a packet receive (any of the
3278    * \ref RAIL_EVENTS_RX_COMPLETION events). See that event for details.
3279    *
3280    * @note An Rx transition to Idle state will always terminate the
3281    * scheduled Rx window, regardless of this setting. This can be used
3282    * to ensure Scheduled RX terminates on the first packet received
3283    * (or first successful packet if the RX error transition is to Rx
3284    * while the Rx success transition is to Idle).
3285    */
3286   uint8_t rxTransitionEndSchedule;
3287   /**
3288    * This setting tells RAIL what to do with a packet being received
3289    * when the window end event occurs. If set to 0, such a packet
3290    * will be allowed to complete. Any other setting will cause that
3291    * packet to be aborted. In either situation, any posting of
3292    * \ref RAIL_EVENT_RX_SCHEDULED_RX_END is deferred briefly to when
3293    * the packet's corresponding \ref RAIL_EVENTS_RX_COMPLETION occurs.
3294    */
3295   uint8_t hardWindowEnd;
3296 } RAIL_ScheduleRxConfig_t;
3297 
3298 /**
3299  * @enum RAIL_RxPacketStatus_t
3300  * @brief The packet status code associated with a packet received or
3301  *   currently being received.
3302  *
3303  * @note RECEIVING implies some packet data may be available, but
3304  *   is untrustworthy (not CRC-verified) and might disappear if the packet
3305  *   is rolled back on error. No packet details are yet available.
3306  * @note In RX \ref RAIL_DataMethod_t::FIFO_MODE, ABORT statuses imply some
3307  *   packet data may be available, but it's incomplete and not trustworthy.
3308  */
RAIL_ENUM(RAIL_RxPacketStatus_t)3309 RAIL_ENUM(RAIL_RxPacketStatus_t) {
3310   /**
3311    * The radio is idle or searching for a packet.
3312    */
3313   RAIL_RX_PACKET_NONE = 0,
3314   /**
3315    * The packet was aborted during filtering because of illegal frame length,
3316    * CRC or block decoding errors, other RAIL built-in protocol-specific
3317    * packet content errors, or by the application or multiprotocol scheduler
3318    * idling the radio with \ref RAIL_IDLE_ABORT or higher.
3319    *
3320    * Corresponding \ref RAIL_EVENT_RX_PACKET_ABORTED is triggered.
3321    */
3322   RAIL_RX_PACKET_ABORT_FORMAT,
3323   /**
3324    * The packet failed address filtering.
3325    *
3326    * Corresponding \ref RAIL_EVENT_RX_ADDRESS_FILTERED is triggered.
3327    */
3328   RAIL_RX_PACKET_ABORT_FILTERED,
3329   /**
3330    * The packet passed any filtering but was aborted by the application
3331    * or multiprotocol scheduler idling the radio with \ref RAIL_IDLE_ABORT
3332    * or higher.
3333    *
3334    * Corresponding \ref RAIL_EVENT_RX_PACKET_ABORTED is triggered.
3335    */
3336   RAIL_RX_PACKET_ABORT_ABORTED,
3337   /**
3338    * The packet overflowed the receive buffer.
3339    *
3340    * Corresponding \ref RAIL_EVENT_RX_FIFO_OVERFLOW is triggered.
3341    */
3342   RAIL_RX_PACKET_ABORT_OVERFLOW,
3343   /**
3344    * The packet passed any filtering but subsequently failed CRC check(s)
3345    * block decoding, or illegal frame length, and was aborted.
3346    *
3347    * Corresponding \ref RAIL_EVENT_RX_FRAME_ERROR is triggered.
3348    */
3349   RAIL_RX_PACKET_ABORT_CRC_ERROR,
3350   /**
3351    * The packet passed any filtering but subsequently failed CRC check(s)
3352    * with \ref RAIL_RX_OPTION_IGNORE_CRC_ERRORS in effect. Can also occur
3353    * when the packet prematurely ended successfully during filtering,
3354    * and either the \ref RAIL_EVENT_RX_PACKET_ABORTED or
3355    * \ref RAIL_EVENT_RX_ADDRESS_FILTERED events had been enabled
3356    * requesting notification of such packets.
3357    *
3358    * Corresponding \ref RAIL_EVENT_RX_PACKET_RECEIVED is triggered.
3359    */
3360   RAIL_RX_PACKET_READY_CRC_ERROR,
3361   /**
3362    * The packet was successfully received, passing CRC check(s).
3363    *
3364    * Corresponding \ref RAIL_EVENT_RX_PACKET_RECEIVED is triggered.
3365    */
3366   RAIL_RX_PACKET_READY_SUCCESS,
3367   /**
3368    * A packet is being received and is not yet complete.
3369    */
3370   RAIL_RX_PACKET_RECEIVING,
3371 };
3372 
3373 #ifndef DOXYGEN_SHOULD_SKIP_THIS
3374 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
3375 #define RAIL_RX_PACKET_NONE            ((RAIL_RxPacketStatus_t) RAIL_RX_PACKET_NONE)
3376 #define RAIL_RX_PACKET_ABORT_FORMAT    ((RAIL_RxPacketStatus_t) RAIL_RX_PACKET_ABORT_FORMAT)
3377 #define RAIL_RX_PACKET_ABORT_FILTERED  ((RAIL_RxPacketStatus_t) RAIL_RX_PACKET_ABORT_FILTERED)
3378 #define RAIL_RX_PACKET_ABORT_ABORTED   ((RAIL_RxPacketStatus_t) RAIL_RX_PACKET_ABORT_ABORTED)
3379 #define RAIL_RX_PACKET_ABORT_OVERFLOW  ((RAIL_RxPacketStatus_t) RAIL_RX_PACKET_ABORT_OVERFLOW)
3380 #define RAIL_RX_PACKET_ABORT_CRC_ERROR ((RAIL_RxPacketStatus_t) RAIL_RX_PACKET_ABORT_CRC_ERROR)
3381 #define RAIL_RX_PACKET_READY_CRC_ERROR ((RAIL_RxPacketStatus_t) RAIL_RX_PACKET_READY_CRC_ERROR)
3382 #define RAIL_RX_PACKET_READY_SUCCESS   ((RAIL_RxPacketStatus_t) RAIL_RX_PACKET_READY_SUCCESS)
3383 #define RAIL_RX_PACKET_RECEIVING       ((RAIL_RxPacketStatus_t) RAIL_RX_PACKET_RECEIVING)
3384 #endif//DOXYGEN_SHOULD_SKIP_THIS
3385 
3386 /**
3387  * @typedef RAIL_RxPacketHandle_t
3388  * @brief A handle used to reference a packet during reception processing.
3389  *   There are several sentinel handle values that pertain to certain
3390  *   circumstances: \ref RAIL_RX_PACKET_HANDLE_INVALID, \ref
3391  *   RAIL_RX_PACKET_HANDLE_OLDEST, \ref RAIL_RX_PACKET_HANDLE_OLDEST_COMPLETE
3392  *   and \ref RAIL_RX_PACKET_HANDLE_NEWEST.
3393  */
3394 typedef const void *RAIL_RxPacketHandle_t;
3395 
3396 /** An invalid RX packet handle value. */
3397 #define RAIL_RX_PACKET_HANDLE_INVALID  (NULL)
3398 
3399 /** A special RX packet handle to refer to the oldest unreleased packet.
3400  * This includes the newest unread packet which is possibly incomplete or not
3401  * yet started.
3402  * This handle is used implicitly by \ref RAIL_ReadRxFifo().
3403  */
3404 #define RAIL_RX_PACKET_HANDLE_OLDEST   ((RAIL_RxPacketHandle_t) 1)
3405 
3406 /** A special RX packet handle to refer to the oldest unreleased
3407  *  complete packet. This never includes incomplete or unstarted packets.
3408  *  (Using \ref RAIL_RX_PACKET_HANDLE_OLDEST is inappropriate for this
3409  *  purpose because it can refer to an unstarted, incomplete, or
3410  *  unheld packet which are inappropriate to be consumed by the application.)
3411  */
3412 #define RAIL_RX_PACKET_HANDLE_OLDEST_COMPLETE   ((RAIL_RxPacketHandle_t) 2)
3413 
3414 /** A special RX packet handle to refer to the newest unreleased packet
3415  *  when in callback context. For a callback involving a completed
3416  *  receive event, this refers to the packet just completed. For
3417  *  other callback events, this refers to the next packet to be
3418  *  completed, which might be in-progress or might not have even
3419  *  started yet.
3420  */
3421 #define RAIL_RX_PACKET_HANDLE_NEWEST   ((RAIL_RxPacketHandle_t) 3)
3422 
3423 /**
3424  * @struct RAIL_RxPacketInfo_t
3425  * @brief Basic information about a packet being received or already
3426  *   completed and awaiting processing, including memory pointers to
3427  *   its data in the circular receive FIFO buffer. This packet information
3428  *   refers to remaining packet data that has not already been consumed
3429  *   by RAIL_ReadRxFifo().
3430  * @note Because the receive FIFO buffer is circular, a packet might start
3431  *   near the end of the buffer and wrap around to the beginning of
3432  *   the buffer to finish, hence the distinction between the first
3433  *   and last portions. Packets that fit without wrapping only have
3434  *   a first portion (firstPortionBytes == packetBytes and lastPortionData
3435  *   will be NULL).
3436  */
3437 typedef struct RAIL_RxPacketInfo {
3438   RAIL_RxPacketStatus_t packetStatus; /**< The packet status of this packet. */
3439   uint16_t packetBytes;               /**< The number of packet data bytes
3440                                            available to read in this packet. */
3441   uint16_t firstPortionBytes;         /**< The number of bytes in the first portion. */
3442   uint8_t *firstPortionData;          /**< The pointer to the first portion of packet
3443                                            data containing firstPortionBytes
3444                                            number of bytes. */
3445   uint8_t *lastPortionData;           /**< The pointer to the last portion of a
3446                                            packet, if any; NULL otherwise. The
3447                                            number of bytes in this portion is
3448                                            packetBytes - firstPortionBytes. */
3449   RAIL_AddrFilterMask_t filterMask;   /**< A bitmask representing which address
3450                                            filter(s) this packet has passed.
3451                                            Will be 0 when not filtering or if
3452                                            packet info is retrieved before
3453                                            filtering has completed. It's
3454                                            undefined on platforms lacking \ref
3455                                            RAIL_SUPPORTS_ADDR_FILTER_MASK */
3456 } RAIL_RxPacketInfo_t;
3457 
3458 /**
3459  * @struct RAIL_RxPacketDetails_t
3460  * @brief Received packet details obtained via RAIL_GetRxPacketDetails()
3461  *   or RAIL_GetRxPacketDetailsAlt().
3462  *
3463  * @note Certain details are always available, while others are only available
3464  *   if the \ref RAIL_RxOptions_t \ref RAIL_RX_OPTION_REMOVE_APPENDED_INFO
3465  *   option is not in effect and the received packet's
3466  *   \ref RAIL_RxPacketStatus_t is among the RAIL_RX_PACKET_READY_ set.
3467  *   Each detail's description indicates its availability.
3468  *
3469  */
3470 typedef struct RAIL_RxPacketDetails {
3471   /**
3472    * The timestamp of the received packet in the RAIL timebase.
3473    *
3474    * When not available it will be \ref RAIL_PACKET_TIME_INVALID.
3475    */
3476   RAIL_PacketTimeStamp_t timeReceived;
3477   /**
3478    * Indicates whether the CRC passed or failed for the received packet.
3479    * It is true for \ref RAIL_RX_PACKET_READY_SUCCESS packets and false
3480    * for all others.
3481    *
3482    * It is always available.
3483    */
3484   bool crcPassed;
3485   /**
3486    * Indicate whether the received packet was the expected ACK.
3487    * It is true for the expected ACK and false otherwise.
3488    *
3489    * It is always available.
3490    *
3491    * An expected ACK is defined as a protocol-correct ACK packet
3492    * successfully-received (\ref RAIL_RX_PACKET_READY_SUCCESS or
3493    * \ref RAIL_RX_PACKET_READY_CRC_ERROR) and whose sync word was
3494    * detected within the
3495    * RAIL_AutoAckConfig_t::ackTimeout period following a transmit
3496    * which specified \ref RAIL_TX_OPTION_WAIT_FOR_ACK, requested
3497    * an ACK, and auto-ACK is enabled. When true, the ackTimeout
3498    * period was terminated so no \ref RAIL_EVENT_RX_ACK_TIMEOUT
3499    * will be subsequently posted for the transmit.
3500    *
3501    * A "protocol-correct ACK" applies to the 802.15.4 or Z-Wave
3502    * protocols for which RAIL can discern the frame type and match
3503    * the ACK's sequence number with that of the transmitted frame.
3504    * For other protocols, the first packet successfully-received
3505    * whose sync word was detected within the ackTimeout period is
3506    * considered the expected ACK; upper layers are responsible for
3507    * confirming this.
3508    */
3509   bool isAck;
3510   /**
3511    * RSSI of the received packet in integer dBm. This RSSI measurement is
3512    * started as soon as the sync word is detected. The duration of the
3513    * measurement is PHY-specific.
3514    *
3515    * When not available it will be \ref RAIL_RSSI_INVALID_DBM.
3516    */
3517   int8_t rssi;
3518   /**
3519    * The link quality indicator of the received packet. A zero would
3520    * indicate a very low quality packet while a 255 would indicate a very
3521    * high quality packet.
3522    *
3523    * When not available it will be 0.
3524    */
3525   uint8_t lqi;
3526   /**
3527    * For radios and PHY configurations that support multiple sync words, this
3528    * number is the ID of the sync word that was used for this packet.
3529    *
3530    * It is always available.
3531    */
3532   uint8_t syncWordId;
3533   /**
3534    * In configurations where the radio has the option of receiving a given
3535    * packet in multiple ways, indicates which of the sub-PHY options
3536    * was used to receive the packet. Most radio configurations do not have
3537    * this ability and the subPhyId is set to 0.
3538    *
3539    * Currently, this field is used by the BLE Coded PHY, the BLE Simulscan PHY
3540    * and the SUN OFDM PHYs.
3541    * In BLE cases, a value of 0 marks a 500 kbps packet, a value of 1 marks a 125
3542    * kbps packet, and a value of 2 marks a 1 Mbps packet.
3543    * Also, see \ref RAIL_BLE_ConfigPhyCoded and \ref RAIL_BLE_ConfigPhySimulscan.
3544    *
3545    * In SUN OFDM cases, the value corresponds to the numerical value of the
3546    * Modulation and Coding Scheme (MCS) level of the last received packet.
3547    * The packet bitrate depends on the MCS value, as well as the OFDM option.
3548    * Packets bitrates for SUN OFDM PHYs can be found in 802.15.4-2020 specification,
3549    * chapter 20.3, table 20-10.
3550    * Ex: Packet bitrate for OFDM option 1 MCS0 is 100kb/s and 2400kb/s for MCS6.
3551    *
3552    * It is always available.
3553    */
3554   uint8_t subPhyId;
3555   /**
3556    * For \ref Antenna_Control configurations where the device has multiple
3557    * antennas, this indicates which antenna received the packet. When there
3558    * is only one antenna, this will be set to the default of 0.
3559    *
3560    * It is always available.
3561    */
3562   uint8_t antennaId;
3563   /**
3564    * When channel hopping is enabled, this field will contain the index
3565    * of the channel in \ref RAIL_RxChannelHoppingConfig_t::entries on which
3566    * this packet was received, or a sentinel value. On EFR32XG1 parts,
3567    * on which channel hopping is not supported, this value is still part
3568    * of the structure, but will be a meaningless value.
3569    *
3570    * It is always available.
3571    */
3572   uint8_t channelHoppingChannelIndex;
3573   /**
3574    * The channel on which the packet was received.
3575    *
3576    * It is always available.
3577    *
3578    * @note It is best to fully process (empty or clear) the receive FIFO
3579    *   before changing channel configurations (\ref RAIL_ConfigChannels()
3580    *   or a built-in configuration) as unprocessed packets' channel
3581    *   could reflect the wrong configuration. On EFR32xG1 only this
3582    *   advice also applies when changing channels for receive or transmit
3583    *   where unprocessed packets' channel could reflect the new channel.
3584    */
3585   uint16_t channel;
3586 } RAIL_RxPacketDetails_t;
3587 
3588 /** @} */ // end of group Receive
3589 
3590 /**
3591  * @addtogroup Auto_Ack
3592  * @{
3593  */
3594 /**
3595  * @struct RAIL_AutoAckConfig_t
3596  * @brief Enable/disable the auto-ACK algorithm, based on "enable".
3597  *
3598  * The structure provides a default state (the "success" of tx/rxTransitions
3599  * when ACKing is enabled) for the radio to return to after an ACK
3600  * operation occurs (transmitting or attempting to receive an ACK), or normal
3601  * state transitions to return to in the case ACKing is
3602  * disabled. Regardless whether the ACK operation was successful, the
3603  * radio returns to the specified success state.
3604  *
3605  * ackTimeout specifies how long to stay in receive and wait for an ACK
3606  * to start (sync detected) before issuing a RAIL_EVENT_RX_ACK_TIMEOUT
3607  * event and return to the default state.
3608  */
3609 typedef struct RAIL_AutoAckConfig {
3610   /**
3611    * Indicate whether auto-ACKing should be enabled or disabled.
3612    */
3613   bool enable;
3614   /**
3615    * Define the RX ACK timeout duration in microseconds up to 65535
3616    * microseconds maximum. Only applied when auto-ACKing is enabled.
3617    * The ACK timeout timer starts at the completion of a \ref
3618    * RAIL_TX_OPTION_WAIT_FOR_ACK transmit and expires only while waiting
3619    * for a packet (prior to SYNC detect), triggering \ref
3620    * RAIL_EVENT_RX_ACK_TIMEOUT. During packet reception that event is
3621    * held off until packet completion and suppressed entirely if the
3622    * received packet is the expected ACK.
3623    */
3624   uint16_t ackTimeout;
3625   /**
3626    * State transitions to do after receiving a packet. When auto-ACKing is
3627    * enabled, the "error" transition is always ignored and the radio will
3628    * return to the "success" state after any ACKing sequence
3629    * (\ref RAIL_RF_STATE_RX or \ref RAIL_RF_STATE_IDLE).
3630    * See \ref RAIL_ConfigAutoAck for more details on this.
3631    */
3632   RAIL_StateTransitions_t rxTransitions;
3633   /**
3634    * State transitions to do after transmitting a packet. When auto-ACKing is
3635    * enabled, the "error" transition is always ignored and the radio will
3636    * return to the "success" state after any ACKing sequence
3637    * (\ref RAIL_RF_STATE_RX or \ref RAIL_RF_STATE_IDLE).
3638    * See \ref RAIL_ConfigAutoAck for more details on this.
3639    */
3640   RAIL_StateTransitions_t txTransitions;
3641 } RAIL_AutoAckConfig_t;
3642 
3643 /// Acknowledgment packets cannot be longer than 64 bytes.
3644 #define RAIL_AUTOACK_MAX_LENGTH (64U)
3645 
3646 /** @} */ // end of group Auto_Ack
3647 
3648 /******************************************************************************
3649  * External_Thermistor Structures
3650  *****************************************************************************/
3651 /**
3652  * @addtogroup External_Thermistor
3653  * @{
3654  */
3655 
3656 /// A sentinel value to indicate an invalid thermistor measurement value.
3657 #define RAIL_INVALID_THERMISTOR_VALUE (0xFFFFFFFFU)
3658 /// A sentinel value to indicate an invalid PPM calculation value.
3659 #define RAIL_INVALID_PPM_VALUE   (-128)
3660 
3661 /**
3662  * @struct RAIL_HFXOThermistorConfig_t
3663  * @brief Configure the port and pin of the thermistor.
3664  * @note This configuration is OPN dependent.
3665  */
3666 typedef struct RAIL_HFXOThermistorConfig {
3667   /**
3668    * The GPIO port to access the thermistor.
3669    */
3670   uint8_t port;
3671   /**
3672    * The GPIO pin to set the thermistor.
3673    */
3674   uint8_t pin;
3675 } RAIL_HFXOThermistorConfig_t;
3676 
3677 /**
3678  * @struct RAIL_HFXOCompensationConfig_t
3679  * @brief Set compensation spepcific parameters
3680  */
3681 typedef struct RAIL_HFXOCompensationConfig {
3682   /**
3683    * Indicates whether the HFXO compensation in temperature is activated.
3684    */
3685   bool enableCompensation;
3686   /**
3687    * The temperature reference delimiting the nominal zone from the critical one.
3688    * This field is relevant if enableCompensation is set to true.
3689    */
3690   int8_t zoneTemperatureC;
3691   /**
3692    * The temperature shift used to start a new compensation, in the nominal zone.
3693    * This field is relevant if enableCompensation is set to true.
3694    */
3695   uint8_t deltaNominal;
3696   /**
3697    * The temperature shift used to start a new compensation, in the critical zone.
3698    * This field is relevant if enableCompensation is set to true.
3699    */
3700   uint8_t deltaCritical;
3701 } RAIL_HFXOCompensationConfig_t;
3702 /** @} */ // end of group External_Thermistor
3703 
3704 /******************************************************************************
3705  * Calibration Structures
3706  *****************************************************************************/
3707 /**
3708  * @addtogroup Calibration
3709  * @{
3710  */
3711 
3712 /**
3713  * @typedef RAIL_CalMask_t
3714  * @brief A calibration mask type
3715  *
3716  * This type is a bitmask of different RAIL calibration values. The exact
3717  * meaning of these bits depends on what a particular chip supports.
3718  */
3719 typedef uint32_t RAIL_CalMask_t;
3720 
3721 /** @} */ // end of group Calibration
3722 
3723 /******************************************************************************
3724  * LQI Structures
3725  *****************************************************************************/
3726 /**
3727  * @addtogroup Receive
3728  * @{
3729  */
3730 
3731 /**
3732  * @typedef RAIL_ConvertLqiCallback_t
3733  * @brief A pointer to a function called before LQI is copied into the
3734  *   \ref RAIL_RxPacketDetails_t structure.
3735  *
3736  * @param[in] lqi The LQI value obtained by hardware and being readied for
3737  *   application consumption. This LQI value is in integral units ranging from
3738  *   0 to 255.
3739  * @param[in] rssi The RSSI value corresponding to the packet from which the
3740  *   hardware LQI value was obtained. This RSSI value is in integral dBm units.
3741  * @return uint8_t The converted LQI value that will be loaded into the
3742  *   \ref RAIL_RxPacketDetails_t structure in preparation for application
3743  *   consumption. This value should likewise be in integral units ranging from
3744  *   0 to 255.
3745  */
3746 typedef uint8_t (*RAIL_ConvertLqiCallback_t)(uint8_t lqi,
3747                                              int8_t rssi);
3748 
3749 /** @} */ // end of group Receive
3750 
3751 /******************************************************************************
3752  * RF Sense Structures
3753  *****************************************************************************/
3754 /**
3755  * @addtogroup Rf_Sense
3756  * @{
3757  */
3758 
3759 /**
3760  * A pointer to an RF Sense callback function.
3761  *
3762  * Consider using the event \ref RAIL_EVENT_RF_SENSED as an alternative.
3763  */
3764 typedef void (*RAIL_RfSense_CallbackPtr_t)(void);
3765 
3766 /**
3767  * RF Sense low sensitivity offset.
3768  */
3769 #define RAIL_RFSENSE_LOW_SENSITIVITY_OFFSET   (0x20U)
3770 
3771 /**
3772  * @enum RAIL_RfSenseBand_t
3773  * @brief An enumeration for specifying the RF Sense frequency band.
3774  */
RAIL_ENUM(RAIL_RfSenseBand_t)3775 RAIL_ENUM(RAIL_RfSenseBand_t) {
3776   RAIL_RFSENSE_OFF,    /**< RF Sense is disabled. */
3777   RAIL_RFSENSE_2_4GHZ, /**< RF Sense is in 2.4 G band. */
3778   RAIL_RFSENSE_SUBGHZ, /**< RF Sense is in subgig band. */
3779   RAIL_RFSENSE_ANY,    /**< RF Sense is in both bands. */
3780   RAIL_RFSENSE_MAX,    // Must be last before sensitivity options.
3781   RAIL_RFSENSE_2_4GHZ_LOW_SENSITIVITY = RAIL_RFSENSE_LOW_SENSITIVITY_OFFSET + RAIL_RFSENSE_2_4GHZ,  /**< RF Sense is in low sensitivity 2.4 G band */
3782   RAIL_RFSENSE_SUBGHZ_LOW_SENSITIVITY = RAIL_RFSENSE_LOW_SENSITIVITY_OFFSET + RAIL_RFSENSE_SUBGHZ,  /**< RF Sense is in low sensitivity subgig band */
3783   RAIL_RFENSE_ANY_LOW_SENSITIVITY = RAIL_RFSENSE_LOW_SENSITIVITY_OFFSET + RAIL_RFSENSE_ANY          /**< RF Sense is in low sensitivity for both bands. */
3784 };
3785 
3786 #ifndef DOXYGEN_SHOULD_SKIP_THIS
3787 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
3788 #define RAIL_RFSENSE_OFF                    ((RAIL_RfSenseBand_t) RAIL_RFSENSE_OFF)
3789 #define RAIL_RFSENSE_2_4GHZ                 ((RAIL_RfSenseBand_t) RAIL_RFSENSE_2_4GHZ)
3790 #define RAIL_RFSENSE_SUBGHZ                 ((RAIL_RfSenseBand_t) RAIL_RFSENSE_SUBGHZ)
3791 #define RAIL_RFSENSE_ANY                    ((RAIL_RfSenseBand_t) RAIL_RFSENSE_ANY)
3792 #define RAIL_RFSENSE_MAX                    ((RAIL_RfSenseBand_t) RAIL_RFSENSE_MAX)
3793 #define RAIL_RFSENSE_2_4GHZ_LOW_SENSITIVITY ((RAIL_RfSenseBand_t) RAIL_RFSENSE_2_4GHZ_LOW_SENSITIVITY)
3794 #define RAIL_RFSENSE_SUBGHZ_LOW_SENSITIVITY ((RAIL_RfSenseBand_t) RAIL_RFSENSE_SUBGHZ_LOW_SENSITIVITY)
3795 #define RAIL_RFENSE_ANY_LOW_SENSITIVITY     ((RAIL_RfSenseBand_t) RAIL_RFENSE_ANY_LOW_SENSITIVITY)
3796 #endif//DOXYGEN_SHOULD_SKIP_THIS
3797 
3798 /**
3799  * Use the MODEM default sync word.
3800  */
3801 #define RAIL_RFSENSE_USE_HW_SYNCWORD    (0U)
3802 
3803 /**
3804  * @struct RAIL_RfSenseSelectiveOokConfig_t
3805  * @brief Structure to configure RFSENSE Selective(OOK) mode.
3806  */
3807 typedef struct RAIL_RfSenseSelectiveOokConfig {
3808   /**
3809    * The frequency band(s) on which to sense the
3810    * RF energy. To stop RF Sense, specify \ref RAIL_RFSENSE_OFF.
3811    */
3812   RAIL_RfSenseBand_t band;
3813   /**
3814    * Syncword Length in bytes, 1-4 bytes.
3815    * @note When \ref syncWord is set to use \ref RAIL_RFSENSE_USE_HW_SYNCWORD,
3816    * the \ref syncWordNumBytes value will be ignored since we rely on the
3817    * HW default settings for sync word.
3818    */
3819   uint8_t syncWordNumBytes;
3820   /**
3821    * Sync Word Value.
3822    * To use HW default sync word, set to \ref RAIL_RFSENSE_USE_HW_SYNCWORD.
3823    */
3824   uint32_t syncWord;
3825   /**
3826    * The callback function, called when RF is sensed.
3827    */
3828   RAIL_RfSense_CallbackPtr_t cb;
3829 } RAIL_RfSenseSelectiveOokConfig_t;
3830 
3831 /** @} */ // end of group Rf_Sense
3832 
3833 /******************************************************************************
3834  * RX Channel Hopping
3835  *****************************************************************************/
3836 /**
3837  * @addtogroup Rx_Channel_Hopping RX Channel Hopping
3838  * @{
3839  */
3840 
3841 /**
3842  * @enum RAIL_RxChannelHoppingMode_t
3843  * @brief Modes by which RAIL can determine when to proceed to the next
3844  * channel during channel hopping
3845  */
RAIL_ENUM(RAIL_RxChannelHoppingMode_t)3846 RAIL_ENUM(RAIL_RxChannelHoppingMode_t) {
3847   /**
3848    * Switch to the next channel each time the radio enters RX.
3849    */
3850   RAIL_RX_CHANNEL_HOPPING_MODE_MANUAL,
3851   /**
3852    * Switch to the next channel after a certain amount of time passes.
3853    * The time should be specified in microseconds in \ref
3854    * RAIL_RxChannelHoppingConfigEntry_t::parameter, and must be less
3855    * than \ref RAIL_RX_CHANNEL_HOPPING_MAX_SENSE_TIME_US.
3856    */
3857   RAIL_RX_CHANNEL_HOPPING_MODE_TIMEOUT,
3858   /**
3859    * Listen in receive RX for at least a specified timeout. If,
3860    * by the end of the timeout, the radio has packet timing,
3861    * remain in the current channel until the radio loses it. The
3862    * timeout should be specified in microseconds in \ref
3863    * RAIL_RxChannelHoppingConfigEntry_t::parameter, and must be less
3864    * than \ref RAIL_RX_CHANNEL_HOPPING_MAX_SENSE_TIME_US.
3865    */
3866   RAIL_RX_CHANNEL_HOPPING_MODE_TIMING_SENSE,
3867   /**
3868    * Listen in receive RX for at least a specified timeout. If,
3869    * by the end of the timeout, the radio has a packet preamble,
3870    * remain in the current channel until the radio loses it. The
3871    * timeout should be specified in microseconds in \ref
3872    * RAIL_RxChannelHoppingConfigEntry_t::parameter, and must be less
3873    * than \ref RAIL_RX_CHANNEL_HOPPING_MAX_SENSE_TIME_US.
3874    */
3875   RAIL_RX_CHANNEL_HOPPING_MODE_PREAMBLE_SENSE,
3876   /**
3877    * Placeholder for a reserved hopping mode that is not supported.
3878    */
3879   RAIL_RX_CHANNEL_HOPPING_MODE_RESERVED1,
3880   /**
3881    * A mode that combines modes TIMING_SENSE, PREAMBLE_SENSE, and
3882    * TIMEOUT (sync detect) all running in parallel. Refer to \ref
3883    * RAIL_RxChannelHoppingConfigMultiMode_t for further details.
3884    * A pointer to that structure, allocated in global read-write
3885    * memory and initialized to the desired configuration values, is
3886    * specified as the \ref RAIL_RxChannelHoppingConfigEntry_t::parameter
3887    * or \ref RAIL_RxDutyCycleConfig_t::parameter, cast appropriately:
3888    * @code{.c}
3889    *   .parameter = (uint32_t)(void *)&hoppingConfigMultiMode,
3890    * @endcode
3891    *
3892    * @note RAIL will overwrite the contents of the \ref
3893    * RAIL_RxChannelHoppingConfigMultiMode_t during operation so it
3894    * must be reinitialized with the desired configuration prior to
3895    * every call to \ref RAIL_ConfigRxChannelHopping() or
3896    * \ref RAIL_ConfigRxDutyCycle().
3897    *
3898    * @note Multiple \ref RAIL_RxChannelHoppingConfigEntry_t entries may
3899    * share the same \ref RAIL_RxChannelHoppingConfigMultiMode_t if their
3900    * settings are identical, otherwise a separate \ref
3901    * RAIL_RxChannelHoppingConfigMultiMode_t is needed for each
3902    * \ref RAIL_RxChannelHoppingConfigEntry_t that uses this mode.
3903    */
3904   RAIL_RX_CHANNEL_HOPPING_MODE_MULTI_SENSE,
3905   /**
3906    * Switch to the next channel based on the demodulation settings in the PHY
3907    * config. This mode is PHY and chip dependent. The
3908    * \ref RAIL_RxChannelHoppingConfigEntry_t::parameter is ignored, and should
3909    * be set to 0 for future compatibility.
3910    */
3911   RAIL_RX_CHANNEL_HOPPING_MODE_SQ,
3912   /**
3913    * Marks that the channel is concurrent with another channel, and otherwise
3914    * behaves identically to \ref RAIL_RX_CHANNEL_HOPPING_MODE_SQ.
3915    */
3916   RAIL_RX_CHANNEL_HOPPING_MODE_CONC,
3917   /**
3918    * Indicates that this channel is a virtual channel that is concurrently
3919    * detected with the channel indicated by the
3920    * \ref RAIL_RxChannelHoppingConfigEntry_t::parameter. Otherwise behaves
3921    * identically to \ref RAIL_RX_CHANNEL_HOPPING_MODE_SQ.
3922    */
3923   RAIL_RX_CHANNEL_HOPPING_MODE_VT,
3924   /**
3925    * This is the transmit channel used for auto-ACK if the regular channel,
3926    * specified in RAIL_RxChannelHoppingConfigEntry::parameter, is
3927    * optimized for RX which may degrade some TX performance
3928    */
3929   RAIL_RX_CHANNEL_HOPPING_MODE_TX,
3930   /**
3931    * A count of the basic choices in this enumeration.
3932    */
3933   RAIL_RX_CHANNEL_HOPPING_MODES_COUNT, // Must be last before _WITH_OPTIONS twins
3934 
3935   /**
3936    * The start of equivalent modes requiring non-default \ref
3937    * RAIL_RxDutyCycleConfig_t::options, needed for backwards-compatibility
3938    * with earlier \ref RAIL_RxDutyCycleConfig_t format. Non-default options
3939    * are supported with \ref RAIL_RxChannelHoppingConfigEntry_t in all modes.
3940    */
3941   RAIL_RX_CHANNEL_HOPPING_MODES_WITH_OPTIONS_BASE = 0x80,
3942   /** Variant of \ref RAIL_RX_CHANNEL_HOPPING_MODE_MANUAL with options. */
3943   RAIL_RX_CHANNEL_HOPPING_MODE_MANUAL_WITH_OPTIONS
3944     = RAIL_RX_CHANNEL_HOPPING_MODES_WITH_OPTIONS_BASE,
3945   /** Variant of \ref RAIL_RX_CHANNEL_HOPPING_MODE_TIMEOUT with options. */
3946   RAIL_RX_CHANNEL_HOPPING_MODE_TIMEOUT_WITH_OPTIONS,
3947   /** Variant of \ref RAIL_RX_CHANNEL_HOPPING_MODE_TIMING_SENSE with options. */
3948   RAIL_RX_CHANNEL_HOPPING_MODE_TIMING_SENSE_WITH_OPTIONS,
3949   /** Variant of \ref RAIL_RX_CHANNEL_HOPPING_MODE_PREAMBLE_SENSE with options. */
3950   RAIL_RX_CHANNEL_HOPPING_MODE_PREAMBLE_SENSE_WITH_OPTIONS,
3951   /** Variant of \ref RAIL_RX_CHANNEL_HOPPING_MODE_RESERVED1 with options. */
3952   RAIL_RX_CHANNEL_HOPPING_MODE_RESERVED1_WITH_OPTIONS,
3953   /** Variant of \ref RAIL_RX_CHANNEL_HOPPING_MODE_MULTI_SENSE with options. */
3954   RAIL_RX_CHANNEL_HOPPING_MODE_MULTI_SENSE_WITH_OPTIONS,
3955   /** Variant of \ref RAIL_RX_CHANNEL_HOPPING_MODE_SQ with options. */
3956   RAIL_RX_CHANNEL_HOPPING_MODE_SQ_WITH_OPTIONS,
3957   /** Variant of \ref RAIL_RX_CHANNEL_HOPPING_MODE_CONC with options. */
3958   RAIL_RX_CHANNEL_HOPPING_MODE_CONC_WITH_OPTIONS,
3959   /** Variant of \ref RAIL_RX_CHANNEL_HOPPING_MODE_VT with options. */
3960   RAIL_RX_CHANNEL_HOPPING_MODE_VT_WITH_OPTIONS,
3961   /** Variant of \ref RAIL_RX_CHANNEL_HOPPING_MODE_TX with options. */
3962   RAIL_RX_CHANNEL_HOPPING_MODE_TX_WITH_OPTIONS,
3963 };
3964 
3965 #ifndef DOXYGEN_SHOULD_SKIP_THIS
3966 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
3967 #define RAIL_RX_CHANNEL_HOPPING_MODE_MANUAL                      ((RAIL_RxChannelHoppingMode_t) RAIL_RX_CHANNEL_HOPPING_MODE_MANUAL)
3968 #define RAIL_RX_CHANNEL_HOPPING_MODE_TIMEOUT                     ((RAIL_RxChannelHoppingMode_t) RAIL_RX_CHANNEL_HOPPING_MODE_TIMEOUT)
3969 #define RAIL_RX_CHANNEL_HOPPING_MODE_TIMING_SENSE                ((RAIL_RxChannelHoppingMode_t) RAIL_RX_CHANNEL_HOPPING_MODE_TIMING_SENSE)
3970 #define RAIL_RX_CHANNEL_HOPPING_MODE_PREAMBLE_SENSE              ((RAIL_RxChannelHoppingMode_t) RAIL_RX_CHANNEL_HOPPING_MODE_PREAMBLE_SENSE)
3971 #define RAIL_RX_CHANNEL_HOPPING_MODE_RESERVED1                   ((RAIL_RxChannelHoppingMode_t) RAIL_RX_CHANNEL_HOPPING_MODE_RESERVED1)
3972 #define RAIL_RX_CHANNEL_HOPPING_MODE_MULTI_SENSE                 ((RAIL_RxChannelHoppingMode_t) RAIL_RX_CHANNEL_HOPPING_MODE_MULTI_SENSE)
3973 #define RAIL_RX_CHANNEL_HOPPING_MODE_SQ                          ((RAIL_RxChannelHoppingMode_t) RAIL_RX_CHANNEL_HOPPING_MODE_SQ)
3974 #define RAIL_RX_CHANNEL_HOPPING_MODE_CONC                        ((RAIL_RxChannelHoppingMode_t) RAIL_RX_CHANNEL_HOPPING_MODE_CONC)
3975 #define RAIL_RX_CHANNEL_HOPPING_MODE_VT                          ((RAIL_RxChannelHoppingMode_t) RAIL_RX_CHANNEL_HOPPING_MODE_VT)
3976 #define RAIL_RX_CHANNEL_HOPPING_MODE_TX                          ((RAIL_RxChannelHoppingMode_t) RAIL_RX_CHANNEL_HOPPING_MODE_TX)
3977 #define RAIL_RX_CHANNEL_HOPPING_MODES_WITH_OPTIONS_BASE          ((RAIL_RxChannelHoppingMode_t) RAIL_RX_CHANNEL_HOPPING_MODES_WITH_OPTIONS_BASE)
3978 #define RAIL_RX_CHANNEL_HOPPING_MODE_MANUAL_WITH_OPTIONS         ((RAIL_RxChannelHoppingMode_t) RAIL_RX_CHANNEL_HOPPING_MODE_MANUAL_WITH_OPTIONS)
3979 #define RAIL_RX_CHANNEL_HOPPING_MODE_TIMEOUT_WITH_OPTIONS        ((RAIL_RxChannelHoppingMode_t) RAIL_RX_CHANNEL_HOPPING_MODE_TIMEOUT_WITH_OPTIONS)
3980 #define RAIL_RX_CHANNEL_HOPPING_MODE_TIMING_SENSE_WITH_OPTIONS   ((RAIL_RxChannelHoppingMode_t) RAIL_RX_CHANNEL_HOPPING_MODE_TIMING_SENSE_WITH_OPTIONS)
3981 #define RAIL_RX_CHANNEL_HOPPING_MODE_PREAMBLE_SENSE_WITH_OPTIONS ((RAIL_RxChannelHoppingMode_t) RAIL_RX_CHANNEL_HOPPING_MODE_PREAMBLE_SENSE_WITH_OPTIONS)
3982 #define RAIL_RX_CHANNEL_HOPPING_MODE_RESERVED1_WITH_OPTIONS      ((RAIL_RxChannelHoppingMode_t) RAIL_RX_CHANNEL_HOPPING_MODE_RESERVED1_WITH_OPTIONS)
3983 #define RAIL_RX_CHANNEL_HOPPING_MODE_MULTI_SENSE_WITH_OPTIONS    ((RAIL_RxChannelHoppingMode_t) RAIL_RX_CHANNEL_HOPPING_MODE_MULTI_SENSE_WITH_OPTIONS)
3984 #define RAIL_RX_CHANNEL_HOPPING_MODE_SQ_WITH_OPTIONS             ((RAIL_RxChannelHoppingMode_t) RAIL_RX_CHANNEL_HOPPING_MODE_SQ_WITH_OPTIONS)
3985 #define RAIL_RX_CHANNEL_HOPPING_MODE_CONC_WITH_OPTIONS           ((RAIL_RxChannelHoppingMode_t) RAIL_RX_CHANNEL_HOPPING_MODE_CONC_WITH_OPTIONS)
3986 #define RAIL_RX_CHANNEL_HOPPING_MODE_VT_WITH_OPTIONS             ((RAIL_RxChannelHoppingMode_t) RAIL_RX_CHANNEL_HOPPING_MODE_VT_WITH_OPTIONS)
3987 #define RAIL_RX_CHANNEL_HOPPING_MODE_TX_WITH_OPTIONS             ((RAIL_RxChannelHoppingMode_t) RAIL_RX_CHANNEL_HOPPING_MODE_TX_WITH_OPTIONS)
3988 #endif//DOXYGEN_SHOULD_SKIP_THIS
3989 
3990 /**
3991  * The maximum sense time supported for those \ref RAIL_RxChannelHoppingMode_t
3992  * modes whose parameter(s) specify a sensing time.
3993  */
3994 #define RAIL_RX_CHANNEL_HOPPING_MAX_SENSE_TIME_US 0x08000000UL
3995 
3996 /**
3997  * @enum RAIL_RxChannelHoppingDelayMode_t
3998  * @deprecated Set only to RAIL_RX_CHANNEL_DELAY_MODE_STATIC
3999  */
RAIL_ENUM(RAIL_RxChannelHoppingDelayMode_t)4000 RAIL_ENUM(RAIL_RxChannelHoppingDelayMode_t) {
4001   /**
4002    * Always delay for exactly the amount of time specified
4003    * in the delay parameter, regardless of how other channel
4004    * hopping channels were extended via preamble sense or other means.
4005    */
4006   RAIL_RX_CHANNEL_HOPPING_DELAY_MODE_STATIC,
4007 };
4008 
4009 /**
4010  * @typedef RAIL_RxChannelHoppingParameter_t
4011  * @brief Rx channel hopping on-channel time
4012  */
4013 typedef uint32_t RAIL_RxChannelHoppingParameter_t;
4014 
4015 #ifndef DOXYGEN_SHOULD_SKIP_THIS
4016 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
4017 #define RAIL_RX_CHANNEL_HOPPING_DELAY_MODE_STATIC ((RAIL_RxChannelHoppingDelayMode_t) RAIL_RX_CHANNEL_HOPPING_DELAY_MODE_STATIC)
4018 #endif//DOXYGEN_SHOULD_SKIP_THIS
4019 
4020 /**
4021  * @enum RAIL_RxChannelHoppingOptions_t
4022  * @brief Options that can customize channel hopping behavior
4023  * on a per-hop basis.
4024  */
RAIL_ENUM(RAIL_RxChannelHoppingOptions_t)4025 RAIL_ENUM(RAIL_RxChannelHoppingOptions_t) {
4026   /** Shift position of \ref RAIL_RX_CHANNEL_HOPPING_OPTION_SKIP_SYNTH_CAL bit */
4027   RAIL_RX_CHANNEL_HOPPING_OPTION_SKIP_SYNTH_CAL_SHIFT,
4028   /** Shift position of \ref RAIL_RX_CHANNEL_HOPPING_OPTION_SKIP_DC_CAL bit */
4029   RAIL_RX_CHANNEL_HOPPING_OPTION_SKIP_DC_CAL_SHIFT,
4030   /** Shift position of \ref RAIL_RX_CHANNEL_HOPPING_OPTION_RSSI_THRESHOLD bit */
4031   RAIL_RX_CHANNEL_HOPPING_OPTION_RSSI_THRESHOLD_SHIFT,
4032   /** Stop hopping on this hop. */
4033   RAIL_RX_CHANNEL_HOPPING_OPTION_STOP_SHIFT,
4034   /** A count of the choices in this enumeration. */
4035   RAIL_RX_CHANNEL_HOPPING_OPTIONS_COUNT // Must be last
4036 };
4037 
4038 /** A value representing no options enabled. */
4039 #define RAIL_RX_CHANNEL_HOPPING_OPTIONS_NONE 0U
4040 /**
4041  * All options disabled by default.
4042  * Channel hopping will behave as described by other
4043  * parameters as it did in RAIL 2.7 and earlier.
4044  */
4045 #define RAIL_RX_CHANNEL_HOPPING_OPTIONS_DEFAULT RAIL_RX_CHANNEL_HOPPING_OPTIONS_NONE
4046 /**
4047  * @deprecated Please use \ref RAIL_RX_CHANNEL_HOPPING_OPTIONS_DEFAULT instead.
4048  */
4049 #define RAIL_RX_CHANNEL_HOPPING_OPTION_DEFAULT RAIL_RX_CHANNEL_HOPPING_OPTIONS_DEFAULT
4050 /**
4051  * An option to skip synth calibration while *hopping into* the channel
4052  * specified in the current entry.
4053  */
4054 #define RAIL_RX_CHANNEL_HOPPING_OPTION_SKIP_SYNTH_CAL (1U << RAIL_RX_CHANNEL_HOPPING_OPTION_SKIP_SYNTH_CAL_SHIFT)
4055 /**
4056  * An option to skip DC calibration while *hopping into* the channel
4057  * specified in the current entry.
4058  */
4059 #define RAIL_RX_CHANNEL_HOPPING_OPTION_SKIP_DC_CAL (1U << RAIL_RX_CHANNEL_HOPPING_OPTION_SKIP_DC_CAL_SHIFT)
4060 /**
4061  * An option to check RSSI after *hopping into* the channel specified
4062  * in the current entry and hop if that RSSI is below the threshold
4063  * specified in \ref RAIL_RxChannelHoppingConfigEntry_t::rssiThresholdDbm.
4064  * This check runs in parallel with the \ref RAIL_RxChannelHoppingMode_t
4065  * specified and may cause a hop sooner than that mode otherwise would.
4066  */
4067 #define RAIL_RX_CHANNEL_HOPPING_OPTION_RSSI_THRESHOLD (1U << RAIL_RX_CHANNEL_HOPPING_OPTION_RSSI_THRESHOLD_SHIFT)
4068 /**
4069  * An option to stop the hopping sequence at this entry in the hop
4070  * table.
4071  */
4072 #define RAIL_RX_CHANNEL_HOPPING_OPTION_STOP (1U << RAIL_RX_CHANNEL_HOPPING_OPTION_STOP_SHIFT)
4073 
4074 /// @struct RAIL_RxChannelHoppingConfigMultiMode_t
4075 /// @brief Structure that parameterizes \ref
4076 ///   RAIL_RX_CHANNEL_HOPPING_MODE_MULTI_SENSE.
4077 ///
4078 /// Every \ref RAIL_RxChannelHoppingConfigEntry_t or
4079 /// \ref RAIL_RxDutyCycleConfig_t that uses \ref
4080 /// RAIL_RX_CHANNEL_HOPPING_MODE_MULTI_SENSE must allocate one of these
4081 /// structures in global read-write memory to provide the settings
4082 /// for this mode and for RAIL to use during hopping or duty cycling.
4083 /// A pointer to this structure, cast appropriately, is what is passed
4084 /// in the corresponding \ref RAIL_RxChannelHoppingConfigEntry_t::parameter
4085 /// or \ref RAIL_RxDutyCycleConfig_t::parameter.
4086 ///
4087 /// The contents of this structure must be initialized prior to each
4088 /// \ref RAIL_ConfigRxChannelHopping() or \ref RAIL_ConfigRxDutyCycle()
4089 /// call and must not be touched thereafter until the next such call.
4090 /// RAIL may change these contents during configuration or operation.
4091 ///
4092 /// This mode of operation functions algorithmically like this pseudocode:
4093 /// @code{.c}
4094 /// extern bool channelHopping; // true if channel hopping, false if duty cycling
4095 /// extern RAIL_RxChannelHoppingConfigEntry_t *hopConfigEntry; // current channel
4096 ///
4097 /// static RAIL_RxChannelHoppingConfigMultiMode_t *multiParams;
4098 /// static RAIL_Time_t rxStartTime;
4099 /// static bool preambleSensed;
4100 ///
4101 /// static void hopOrSuspendRx(uint32_t delay)
4102 /// {
4103 ///   disableDemodEvents();
4104 ///   disableTimerEvents();
4105 ///   stopTimer();
4106 ///   if (channelHopping) {
4107 ///     hopToNextChannel(delay, &hopConfigEntry); // updates hopConfigEntry
4108 ///   } else {
4109 ///     suspendRx(delay);
4110 ///   }
4111 ///   onStartRx(); // resume receive after delay (on new channel if hopping)
4112 /// }
4113 ///
4114 /// void onStartRx(void) // called upon entry to receive
4115 /// {
4116 ///   rxStartTime = RAIL_GetTime();
4117 ///   multiParams = (RAIL_RxChannelHoppingConfigMultiMode_t *)
4118 ///                 (void *)hopConfigEntry->parameter;
4119 ///   startTimer(rxStartTime + multiParams->timingSense);
4120 ///   preambleSensed = false;
4121 ///   enableTimerEvents(); // timer will trigger onTimerEvent() handler
4122 ///   enableDemodEvents(); // demod will trigger onDemodEvent() handler
4123 /// }
4124 ///
4125 /// void onTimerEvent(void) // called when timer expires
4126 /// {
4127 ///   hopOrSuspendRx(hopConfigEntry->delay);
4128 /// }
4129 ///
4130 /// void onDemodEvent(void) // called when demodulator state changes
4131 /// {
4132 ///   if (DEMOD_TIMING_SENSED) {
4133 ///     stopTimer();
4134 ///     startTimer(rxStartTime + multiParams->syncDetect);
4135 ///   }
4136 ///   if (DEMOD_TIMING_LOST) {
4137 ///     stopTimer();
4138 ///     uint32_t newTimeout = RAIL_GetTime() + multiParams->timingReSense;
4139 ///     uint32_t limitTimeout;
4140 ///     if (preambleSensed) {
4141 ///       limitTimeout = rxStartTime + multiParams->syncDetect;
4142 ///     } else {
4143 ///       limitTimeout = rxStartTime + multiParams->preambleSense;
4144 ///     }
4145 ///     if (newTimeout > limitTimeout) {
4146 ///       newTimeout = limitTimeout;
4147 ///     }
4148 ///     if (newTimeout > RAIL_GetTime()) {
4149 ///       startTimer(newTimeout);
4150 ///     } else {
4151 ///       hopOrSuspendRx(hopConfigEntry->delay);
4152 ///     }
4153 ///   }
4154 ///   if (DEMOD_PREAMBLE_SENSED) {
4155 ///     preambleSensed = true;
4156 ///   }
4157 ///   if (DEMOD_PREAMBLE_LOST) {
4158 ///     preambleSensed = false;
4159 ///   }
4160 ///   if (DEMOD_SYNC_DETECTED) {
4161 ///     disableDemodEvents();
4162 ///     disableTimerEvents();
4163 ///     stopTimer();
4164 ///     receivePacket(); // stay on channel to receive frame
4165 ///     hopOrSuspendRx(0); // continue RX per state transitions with no delay
4166 ///   }
4167 /// }
4168 /// @endcode
4169 
4170 typedef struct RAIL_RxChannelHoppingConfigMultiMode {
4171   /**
4172    * Switch to the next channel if sync is not detected before
4173    * this time, in microseconds, measured from entry to Rx.
4174    * This must be greater than preambleSense and less than
4175    * \ref RAIL_RX_CHANNEL_HOPPING_MAX_SENSE_TIME_US.
4176    */
4177   uint32_t syncDetect;
4178   /**
4179    * Switch to the next channel if timing was sensed but then
4180    * lost after this time, in microseconds, measured from entry
4181    * to Rx -- unless preamble had been sensed in which case any
4182    * switching is deferred to timingReSense and, if timing is
4183    * regained, to syncDetect.  This must be greater than timingSense
4184    * and less than \ref RAIL_RX_CHANNEL_HOPPING_MAX_SENSE_TIME_US.
4185    */
4186   uint32_t preambleSense;
4187   /**
4188    * Switch to the next channel if timing is not sensed before
4189    * this time, in microseconds, measured from entry to Rx. This
4190    * must be greater than 2 and less than
4191    * \ref RAIL_RX_CHANNEL_HOPPING_MAX_SENSE_TIME_US.
4192    */
4193   uint32_t timingSense;
4194   /**
4195    * Switch to the next channel if timing was sensed but then
4196    * lost and not regained before this time, in microseconds,
4197    * measured from when timing was lost. This must be less than
4198    * \ref RAIL_RX_CHANNEL_HOPPING_MAX_SENSE_TIME_US.
4199    */
4200   uint32_t timingReSense;
4201   /**
4202    * Set this to 0. This field, along with the others, may be
4203    * used internally by RAIL during configuration or operation.
4204    */
4205   uint32_t status;
4206 } RAIL_RxChannelHoppingConfigMultiMode_t;
4207 
4208 /**
4209  * @struct RAIL_RxChannelHoppingConfigEntry_t
4210  * @brief Structure that represents one of the channels that is part of a
4211  *   \ref RAIL_RxChannelHoppingConfig_t sequence of channels used in
4212  *   channel hopping.
4213  */
4214 typedef struct RAIL_RxChannelHoppingConfigEntry {
4215   /**
4216    * The channel number to be used for this entry in the channel hopping
4217    * sequence. If this is an invalid channel for the current PHY, the
4218    * call to \ref RAIL_ConfigRxChannelHopping() will fail.
4219    */
4220   uint16_t channel;
4221   /** The mode by which RAIL determines when to hop to the next channel. */
4222   RAIL_RxChannelHoppingMode_t mode;
4223   // Unnamed 'uint8_t reserved1[1]' pad byte field here.
4224   /**
4225    * Depending on the 'mode' parameter that was specified, this member
4226    * is used to parameterize that mode. See the comments on each value of
4227    * \ref RAIL_RxChannelHoppingMode_t to learn what to specify here.
4228    */
4229   RAIL_RxChannelHoppingParameter_t parameter;
4230   /**
4231    * Idle time in microseconds to wait before hopping into the
4232    * channel indicated by this entry.
4233    */
4234   uint32_t delay;
4235   /** @deprecated Set delayMode to RAIL_RX_CHANNEL_HOPPING_DELAY_MODE_STATIC. */
4236   RAIL_RxChannelHoppingDelayMode_t delayMode;
4237   /**
4238    * Bitmask of various options that can be applied to the current
4239    * channel hop.
4240    */
4241   RAIL_RxChannelHoppingOptions_t options;
4242   /**
4243    * The RSSI threshold (in dBm) below which a hop will occur in
4244    * any mode when \ref RAIL_RX_CHANNEL_HOPPING_OPTION_RSSI_THRESHOLD is
4245    * specified.
4246    */
4247   int8_t rssiThresholdDbm;
4248   /**
4249    * Pad bytes reserved for future use and currently ignored.
4250    */
4251   uint8_t reserved2[1];
4252 } RAIL_RxChannelHoppingConfigEntry_t;
4253 
4254 /**
4255  * @struct RAIL_RxChannelHoppingConfig_t
4256  * @brief Wrapper struct that will contain the sequence of
4257  *   \ref RAIL_RxChannelHoppingConfigEntry_t that represents the channel
4258  *   sequence to use during RX Channel Hopping.
4259  */
4260 typedef struct RAIL_RxChannelHoppingConfig {
4261   /**
4262    * Pointer to contiguous global read-write memory that will be used
4263    * by RAIL to store channel hopping information throughout its operation.
4264    * It need not be initialized and applications should never write
4265    * data anywhere in this buffer.
4266    *
4267    * @note the size of this buffer must be at least as large as
4268    * 3 + 30 * numberOfChannels, plus the sum of the sizes of the
4269    * radioConfigDeltaAdd's of the required channels, plus the size of the
4270    * radioConfigDeltaSubtract. In the case that one channel
4271    * appears two or more times in your channel sequence
4272    * (e.g., 1, 2, 1, 3), you must account for the radio configuration
4273    * size that number of times (i.e., need to count channel 1's
4274    * radio configuration size twice for the given example). The overall
4275    * 3 words and 30 words per channel needed in this buffer are
4276    * for internal use to the library.
4277    */
4278   uint32_t *buffer;
4279   /**
4280    * This parameter must be set to the length of the buffer array, in 32 bit
4281    * words. This way, during configuration, the software can confirm it's
4282    * writing within the range of the buffer. The configuration API will return
4283    * an error if bufferLength is insufficient.
4284    */
4285   uint16_t bufferLength;
4286   /**
4287    * The number of channels in the channel hopping sequence, which is the
4288    * number of elements in the array that entries points to.
4289    */
4290   uint8_t numberOfChannels;
4291   /**
4292    * A pointer to the first element of an array of \ref
4293    * RAIL_RxChannelHoppingConfigEntry_t that represents the channels
4294    * used during channel hopping. The length of this array must be
4295    * numberOfChannels.
4296    */
4297   RAIL_RxChannelHoppingConfigEntry_t *entries;
4298 } RAIL_RxChannelHoppingConfig_t;
4299 
4300 /**
4301  * @struct RAIL_RxDutyCycleConfig_t
4302  * @brief Structure to configure duty cycled receive mode.
4303  */
4304 typedef struct RAIL_RxDutyCycleConfig {
4305   /** The mode by which RAIL determines when to exit RX. */
4306   RAIL_RxChannelHoppingMode_t mode;
4307   /**
4308    * Depending on the 'mode' parameter that was specified, this member
4309    * is used to parameterize that mode. See the comments on each value of
4310    * \ref RAIL_RxChannelHoppingMode_t to learn what to specify here.
4311    */
4312   // Unnamed 'uint8_t reserved[3]' pad byte field here.
4313   RAIL_RxChannelHoppingParameter_t parameter;
4314   /**
4315    * Idle time in microseconds to wait before re-entering RX.
4316    */
4317   uint32_t delay;
4318   /**
4319    * Indicate how the timing specified in 'delay' should be applied.
4320    */
4321   RAIL_RxChannelHoppingDelayMode_t delayMode;
4322   /**
4323    * Bitmask of various options that can be applied to the current
4324    * duty cycle operation when the mode is >= \ref
4325    * RAIL_RX_CHANNEL_HOPPING_MODE_MANUAL_WITH_OPTIONS (ignored otherwise).
4326    */
4327   RAIL_RxChannelHoppingOptions_t options;
4328   /**
4329    * The RSSI threshold (in dBm) below which Rx will end in
4330    * any mode when \ref RAIL_RX_CHANNEL_HOPPING_OPTION_RSSI_THRESHOLD
4331    * is specified.
4332    */
4333   int8_t rssiThresholdDbm;
4334   /**
4335    * Pad bytes reserved for future use and currently ignored.
4336    */
4337   uint8_t reserved2[1];
4338 } RAIL_RxDutyCycleConfig_t;
4339 
4340 /// A sentinel value to flag an invalid channel hopping index.
4341 #define RAIL_CHANNEL_HOPPING_INVALID_INDEX (0xFEU)
4342 
4343 /** @} */ // end of group Rx_Channel_Hopping
4344 
4345 /******************************************************************************
4346  * Diagnostic Structures
4347  *****************************************************************************/
4348 /**
4349  * @addtogroup Diagnostic
4350  * @{
4351  */
4352 
4353 /**
4354  * @enum RAIL_StreamMode_t
4355  * @brief Possible stream output modes.
4356  */
RAIL_ENUM(RAIL_StreamMode_t)4357 RAIL_ENUM(RAIL_StreamMode_t) {
4358   RAIL_STREAM_CARRIER_WAVE = 0, /**< An unmodulated carrier wave. */
4359   RAIL_STREAM_PN9_STREAM = 1,   /**< PN9 byte sequence. */
4360   RAIL_STREAM_10_STREAM = 2, /**< 101010 sequence. */
4361   RAIL_STREAM_CARRIER_WAVE_PHASENOISE = 3, /**< An unmodulated carrier wave with no change to PLL BW. For series-2, same as RAIL_STREAM_CARRIER_WAVE */
4362   RAIL_STREAM_RAMP_STREAM = 4, /**< ramp sequence starting at a different offset for consecutive packets. Only available for some modulations. Fall back to RAIL_STREAM_PN9_STREAM if not available. */
4363   RAIL_STREAM_CARRIER_WAVE_SHIFTED = 5, /**< An unmodulated carrier wave not centered on DC but shifted roughly by channel_bandwidth/6 allowing an easy check of the residual DC. Only available for OFDM PA. Fall back to RAIL_STREAM_CARRIER_WAVE_PHASENOISE if not available. */
4364   RAIL_STREAM_MODES_COUNT   /**< A count of the choices in this enumeration. Must be last. */
4365 };
4366 
4367 #ifndef DOXYGEN_SHOULD_SKIP_THIS
4368 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
4369 #define RAIL_STREAM_CARRIER_WAVE ((RAIL_StreamMode_t) RAIL_STREAM_CARRIER_WAVE)
4370 #define RAIL_STREAM_PN9_STREAM   ((RAIL_StreamMode_t) RAIL_STREAM_PN9_STREAM)
4371 #define RAIL_STREAM_10_STREAM   ((RAIL_StreamMode_t) RAIL_STREAM_10_STREAM)
4372 #define RAIL_STREAM_CARRIER_WAVE_PHASENOISE ((RAIL_StreamMode_t) RAIL_STREAM_CARRIER_WAVE_PHASENOISE)
4373 #define RAIL_STREAM_RAMP_STREAM   ((RAIL_StreamMode_t) RAIL_STREAM_RAMP_STREAM)
4374 #define RAIL_STREAM_CARRIER_WAVE_SHIFTED ((RAIL_StreamMode_t) RAIL_STREAM_CARRIER_WAVE_SHIFTED)
4375 #define RAIL_STREAM_MODES_COUNT   ((RAIL_StreamMode_t) RAIL_STREAM_MODES_COUNT)
4376 #endif//DOXYGEN_SHOULD_SKIP_THIS
4377 
4378 /**
4379  * @def RAIL_VERIFY_DURATION_MAX
4380  * @brief This radio state verification duration indicates to RAIL that
4381  *   all memory contents should be verified by RAIL before returning to the
4382  *   application.
4383  */
4384 #define RAIL_VERIFY_DURATION_MAX 0xFFFFFFFFUL
4385 
4386 /**
4387  * A pointer to a verification callback function. This will be called by the
4388  * radio state verification feature built into RAIL when a verified memory
4389  * value is different from its reference value.
4390  *
4391  * @param[in] address The address of the data in question.
4392  * @param[in] expectedValue The expected value of the data in question.
4393  * @param[in] actualValue The actual value of the data in question.
4394  * @return bool True indicates a data value difference is acceptable. False
4395  *   indicates a data value difference in unacceptable.
4396  *
4397  * @note This callback will be issued when an address' value is different from
4398  *   its reference value and either of the following conditions are met:
4399  *   1) The default radio configuration provided by the radio configurator is used
4400  *      for verification purposes (i.e., a custom radio configuration is not supplied
4401  *      as an input to \ref RAIL_ConfigVerification()), and the radio
4402  *      configurator has flagged the address under question as being verifiable.
4403  *   2) A custom radio configuration is provided to the verification API (i.e.,
4404  *      a custom radio configuration is supplied as an input to \ref
4405  *      RAIL_ConfigVerification()). When providing a custom radio configuration for
4406  *      verification purposes, all addresses in that configuration will be verified,
4407  *      regardless of whether or not the addresses are flagged as verifiable.
4408  */
4409 typedef bool (*RAIL_VerifyCallbackPtr_t)(uint32_t address,
4410                                          uint32_t expectedValue,
4411                                          uint32_t actualValue);
4412 
4413 /**
4414  * @struct RAIL_VerifyConfig_t
4415  * @brief The configuration array provided to RAIL for use by the radio state
4416  *   verification feature. This structure will be populated with appropriate
4417  *   values by calling \ref RAIL_ConfigVerification(). The application should
4418  *   not set or alter any of these structure elements.
4419  */
4420 typedef struct RAIL_VerifyConfig {
4421   /** Internal verification tracking information. */
4422   RAIL_Handle_t correspondingHandle;
4423   /** Internal verification tracking information. */
4424   uint32_t nextIndexToVerify;
4425   /** Internal verification tracking information. */
4426   const uint32_t *override;
4427   /** Internal verification tracking information. */
4428   RAIL_VerifyCallbackPtr_t cb;
4429 } RAIL_VerifyConfig_t;
4430 
4431 /** @} */ // end of group Diagnostic
4432 
4433 /******************************************************************************
4434  * Energy Friendly Front End Module (EFF)
4435  *****************************************************************************/
4436 /**
4437  * @addtogroup EFF
4438  * @{
4439  */
4440 
4441 /**
4442  * @enum RAIL_EffDevice_t
4443  * @brief EFF part numbers.
4444  *
4445  * The part number of the attached EFF device is passed to
4446  * \ref RAIL_ConfigEff() as \ref RAIL_EffConfig_t.device.
4447  * The \ref rail_util_eff configures and controls
4448  * the EFF based on the capabilities of the attached EFF.
4449  */
RAIL_ENUM(RAIL_EffDevice_t)4450 RAIL_ENUM(RAIL_EffDevice_t) {
4451   RAIL_EFF_DEVICE_NONE = 0, /**< No EFF device attached. */
4452   RAIL_EFF_DEVICE_EFF01A11NMFA0, /**< +30 dBm,   LNA, QFN24, +105C max ambient */
4453   RAIL_EFF_DEVICE_EFF01B11NMFA0, /**< PA Bypass, LNA, QFN24, +105C max ambient */
4454   RAIL_EFF_DEVICE_EFF01A11IMFB0, /**< +30 dBm,   LNA, QFN24, +125C max ambient */
4455   RAIL_EFF_DEVICE_EFF01B11IMFB0, /**< PA Bypass, LNA, QFN24, +125C max ambient */
4456   RAIL_EFF_DEVICE_COUNT,    /**< A count of the choices in this enumeration. */
4457 };
4458 
4459 #ifndef DOXYGEN_SHOULD_SKIP_THIS
4460 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
4461 #define RAIL_EFF_DEVICE_NONE ((RAIL_EffDevice_t) RAIL_EFF_DEVICE_NONE)
4462 #define RAIL_EFF_DEVICE_EFF01A11NMFA0 ((RAIL_EffDevice_t) RAIL_EFF_DEVICE_EFF01A11NMFA0)
4463 #define RAIL_EFF_DEVICE_EFF01B11NMFA0 ((RAIL_EffDevice_t) RAIL_EFF_DEVICE_EFF01B11NMFA0)
4464 #define RAIL_EFF_DEVICE_EFF01A11IMFB0 ((RAIL_EffDevice_t) RAIL_EFF_DEVICE_EFF01A11IMFB0)
4465 #define RAIL_EFF_DEVICE_EFF01B11IMFB0 ((RAIL_EffDevice_t) RAIL_EFF_DEVICE_EFF01B11IMFB0)
4466 #define RAIL_EFF_DEVICE_COUNT ((RAIL_EffDevice_t) RAIL_EFF_DEVICE_COUNT)
4467 #endif//DOXYGEN_SHOULD_SKIP_THIS
4468 
4469 /**
4470  * @def RAIL_EFF_SUPPORTS_TRANSMIT(x)
4471  * @brief A macro that checks for EFFxx devices that support high power transmit
4472  */
4473 #define RAIL_EFF_SUPPORTS_TRANSMIT(x) ( ((x) == RAIL_EFF_DEVICE_EFF01A11NMFA0)    \
4474                                         || ((x) == RAIL_EFF_DEVICE_EFF01A11IMFB0) \
4475                                         )
4476 /**
4477  * @def RAIL_EFF_SUPPORTS_RECEIVE(x)
4478  * @brief A macro that checks for EFFxx devices that support receive
4479  */
4480 #define RAIL_EFF_SUPPORTS_RECEIVE(x) ( ((x) == RAIL_EFF_DEVICE_EFF01A11NMFA0)    \
4481                                        || ((x) == RAIL_EFF_DEVICE_EFF01B11NMFA0) \
4482                                        || ((x) == RAIL_EFF_DEVICE_EFF01A11IMFB0) \
4483                                        || ((x) == RAIL_EFF_DEVICE_EFF01B11IMFB0) \
4484                                        )
4485 
4486 /** Maximum EFF internal temperature in Kelvin, allowing transmissions when
4487  * \ref RAIL_SUPPORTS_EFF is enabled.
4488  */
4489 #define RAIL_EFF_TEMP_THRESHOLD_MAX  (383U)
4490 
4491 /**
4492  * @enum RAIL_EffLnaMode_t
4493  * @brief EFF LNA Modes.
4494  *
4495  * The enabled EFF LNA modes are passed to\ref RAIL_ConfigEff() as the
4496  * \ref RAIL_EffConfig_t.enabledLnaModes.
4497  * The \ref rail_util_eff dynamically transitions between enabled LNA modes to
4498  * maximize receive performance.
4499  */
RAIL_ENUM(RAIL_EffLnaMode_t)4500 RAIL_ENUM(RAIL_EffLnaMode_t) {
4501   RAIL_EFF_LNA_MODE_RURAL   = (0x01U << 0), /**< Rural LNA Mode. */
4502   RAIL_EFF_LNA_MODE_URBAN   = (0x01U << 1), /**< Urban LNA Mode. */
4503   RAIL_EFF_LNA_MODE_BYPASS  = (0x01U << 2), /**< Bypass LNA Mode. */
4504   RAIL_EFF_LNA_MODE_COUNT   = (0x01U << 3), /**< A count of the choices in this enumeration. */
4505 };
4506 
4507 #ifndef DOXYGEN_SHOULD_SKIP_THIS
4508 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
4509 #define RAIL_EFF_LNA_MODE_RURAL ((RAIL_EffLnaMode_t) RAIL_EFF_LNA_MODE_RURAL)
4510 #define RAIL_EFF_LNA_MODE_URBAN ((RAIL_EffLnaMode_t) RAIL_EFF_LNA_MODE_URBAN)
4511 #define RAIL_EFF_LNA_MODE_BYPASS ((RAIL_EffLnaMode_t) RAIL_EFF_LNA_MODE_BYPASS)
4512 #define RAIL_EFF_LNA_MODE_COUNT ((RAIL_EffLnaMode_t) RAIL_EFF_LNA_MODE_COUNT)
4513 #endif//DOXYGEN_SHOULD_SKIP_THIS
4514 
4515 /**
4516  * @enum RAIL_ClpcEnable_t
4517  * @brief EFF Closed Loop Power Control (CLPC) Enable states.
4518  *
4519  * The EFF CLPC Enable state is passed to \ref RAIL_ConfigEff() as the
4520  * \ref RAIL_EffConfig_t.clpcEnable.
4521  * The \ref rail_util_eff uses advanced power controls to tune EFF output to match
4522  * Surface Acoustic Wave (SAW) filter losses and antenna performance.
4523  */
RAIL_ENUM(RAIL_ClpcEnable_t)4524 RAIL_ENUM(RAIL_ClpcEnable_t) {
4525   RAIL_EFF_CLPC_DISABLED                  = 0,  /**< CLPC actions are completely disabled. EFF will output but CLPC will not change modes, take power measurements or tune power output. Temperature measurements are taken.*/
4526   RAIL_EFF_CLPC_MODE_CHANGE               = 1,  /**< CLPC actions are completely disabled. EFF will output, change modes, and take measurements, but not tune power output. */
4527   RAIL_EFF_CLPC_POWER_SLOW                = 2,  /**< CLPC actions allows Slow Loop. EFF will output, change modes, and take measurements, and tune power output based on slow loop. */
4528   RAIL_EFF_CLPC_POWER_FAST                = 3,  /**< CLPC actions allows Fast Loop. EFF will output, change modes, and take measurements, and tune power output based on fast loop. */
4529   RAIL_EFF_CLPC_POWER_BOTH                = 4,  /**< CLPC actions are completely enabled. EFF will output, change modes, take measurements, and tune power output based on slow and fast loops. Default state. */
4530   RAIL_EFF_CLPC_POWER_SLOW_STOPPED        = 5,  /**< CLPC actions allows Slow Loop. EFF will output, change modes, and take measurements, but not tune power output because requested output power is less than max. Internal only state. */
4531   RAIL_EFF_CLPC_POWER_FAST_STOPPED        = 6,  /**< CLPC actions allows Fast Loop. EFF will output, change modes, and take measurements,  but not tune power output because requested output power is less than max. Internal only state. */
4532   RAIL_EFF_CLPC_POWER_BOTH_STOPPED        = 7,  /**< CLPC actions are completely enabled. EFF will output, change modes, and take measurements, but not tune power output because requested output power is less than max. Internal only state. */
4533   RAIL_EFF_CLPC_COUNT                     = 8   /**< A count of the choices in this enumeration. Must be last. */
4534 };
4535 
4536 #ifndef DOXYGEN_SHOULD_SKIP_THIS
4537 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
4538 #define RAIL_EFF_CLPC_DISABLED ((RAIL_ClpcEnable_t) RAIL_EFF_CLPC_DISABLED)
4539 #define RAIL_EFF_CLPC_MODE_CHANGE ((RAIL_ClpcEnable_t) RAIL_EFF_CLPC_MODE_CHANGE)
4540 #define RAIL_EFF_CLPC_POWER_SLOW ((RAIL_ClpcEnable_t) RAIL_EFF_CLPC_POWER_SLOW)
4541 #define RAIL_EFF_CLPC_POWER_FAST ((RAIL_ClpcEnable_t) RAIL_EFF_CLPC_POWER_FAST)
4542 #define RAIL_EFF_CLPC_POWER_BOTH ((RAIL_ClpcEnable_t) RAIL_EFF_CLPC_POWER_BOTH)
4543 #define RAIL_EFF_CLPC_POWER_SLOW_STOPPED ((RAIL_ClpcEnable_t) RAIL_EFF_CLPC_POWER_SLOW_STOPPED)
4544 #define RAIL_EFF_CLPC_POWER_FAST_STOPPED ((RAIL_ClpcEnable_t) RAIL_EFF_CLPC_POWER_FAST_STOPPED)
4545 #define RAIL_EFF_CLPC_POWER_BOTH_STOPPED ((RAIL_ClpcEnable_t) RAIL_EFF_CLPC_POWER_BOTH_STOPPED)
4546 #define RAIL_EFF_CLPC_COUNT ((RAIL_ClpcEnable_t) RAIL_EFF_CLPC_COUNT)
4547 #endif//DOXYGEN_SHOULD_SKIP_THIS
4548 
4549 /**
4550  * @enum RAIL_EffModeSensor_t
4551  * @brief EFF Closed Loop Power Control (CLPC) Mode Sensor Indices
4552  *
4553  * The mode sensor indices are used to access specific settings with CLPC.
4554  */
RAIL_ENUM(RAIL_EffModeSensor_t)4555 RAIL_ENUM(RAIL_EffModeSensor_t) {
4556   RAIL_EFF_MODE_SENSOR_FSK_ANTV = 0,                      /**< CLPC FSK ANTV Sensor. */
4557   RAIL_EFF_MODE_SENSOR_FSK_SAW2 = 1,                      /**< CLPC FSK SAW2 Sensor. */
4558   RAIL_EFF_MODE_SENSOR_OFDM_ANTV = 2,                     /**< CLPC OFDM ANTV power calibration entry 1. */
4559   RAIL_EFF_MODE_SENSOR_OFDM_SAW2 = 3,                     /**< CLPC OFDM SAW2 power calibration entry 1. */
4560   RAIL_EFF_MODE_SENSOR_COUNT                              /**< A count of the choices in this enumeration. Must be last. */
4561 };
4562 
4563 #ifndef DOXYGEN_SHOULD_SKIP_THIS
4564 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
4565 #define RAIL_EFF_MODE_SENSOR_FSK_ANTV ((RAIL_EffModeSensor_t) RAIL_EFF_MODE_SENSOR_FSK_ANTV)
4566 #define RAIL_EFF_MODE_SENSOR_FSK_SAW2 ((RAIL_EffModeSensor_t) RAIL_EFF_MODE_SENSOR_FSK_SAW2)
4567 #define RAIL_EFF_MODE_SENSOR_OFDM_ANTV ((RAIL_EffModeSensor_t) RAIL_EFF_MODE_SENSOR_OFDM_ANTV)
4568 #define RAIL_EFF_MODE_SENSOR_OFDM_SAW2 ((RAIL_EffModeSensor_t) RAIL_EFF_MODE_SENSOR_OFDM_SAW2)
4569 #define RAIL_EFF_MODE_SENSOR_COUNT ((RAIL_EffModeSensor_t) RAIL_EFF_CAL_COUNT)
4570 #endif//DOXYGEN_SHOULD_SKIP_THIS
4571 
4572 /**
4573  * @def RAIL_EFF_MODE_SENSOR_ENUM_NAMES
4574  * @brief A macro that is string versions of the calibration enums.
4575  */
4576 #define RAIL_EFF_MODE_SENSOR_ENUM_NAMES { \
4577     "RAIL_EFF_MODE_SENSOR_FSK_ANTV",      \
4578     "RAIL_EFF_MODE_SENSOR_FSK_SAW2",      \
4579     "RAIL_EFF_MODE_SENSOR_OFDM_ANTV",     \
4580     "RAIL_EFF_MODE_SENSOR_OFDM_SAW2",     \
4581 }
4582 
4583 /** @struct RAIL_EffCalConfig_t
4584  *
4585  * @brief Calibration data for CLPC in a specific mode.
4586  */
4587 typedef struct RAIL_EffCalConfig {
4588   RAIL_TxPower_t cal1Ddbm;     /**< Measured Output Power for CAL1 (nominally 270 ddBm) */
4589   uint16_t cal1Mv;             /**< Measured Output Voltage using sensor at CAL1 ddBm */
4590   RAIL_TxPower_t cal2Ddbm;     /**< Measured Output Power for CAL2 (nominally at 290 ddBm) */
4591   uint16_t cal2Mv;             /**< Measured Output Voltage using sensor at CAL2 ddBm */
4592 } RAIL_EffCalConfig_t;
4593 
4594 /** @struct RAIL_EffClpcSensorConfig_t
4595  *
4596  * @brief Configuration data for a CLPC sensor.
4597  *
4598  * A structure of type \ref RAIL_EffClpcSensorConfig_t stores curve and calibration information for a CLPC sensor.
4599  */
4600 typedef struct RAIL_EffClpcSensorConfig {
4601   int64_t coefA;                   /**< Coefficient A for Sensor Voltage curve. Multiplied by 1e7. */
4602   int64_t coefB;                   /**< Coefficient B for Sensor Voltage curve. Multiplied by 1e7. */
4603   int64_t coefC;                   /**< Coefficient C for Sensor Voltage curve. Multiplied by 1e7. */
4604   int64_t coefD;                   /**< Coefficient D for Sensor Voltage curve. Multiplied by 1e7. */
4605   RAIL_EffCalConfig_t calData;     /**< Calibration data for Sensor for this mode */
4606   int16_t slope1e1MvPerDdbm;       /**< Calculated slope * 10 for Sensor calibration, measured in mV/ddBm */
4607   int16_t offset290Ddbm;           /**< Calculated effective offset at 290 ddBm for Sensor calibration */
4608 } RAIL_EffClpcSensorConfig_t;
4609 
4610 /** @struct RAIL_EffClpcConfig_t
4611  *
4612  * @brief Configuration data for CLPC in a specific mode.
4613  *
4614  * A structure of type \ref RAIL_EffClpcConfig_t stores calibration information for each sensor in a specific mode.
4615  */
4616 typedef struct RAIL_EffClpcConfig {
4617   RAIL_EffClpcSensorConfig_t antv; /**< ANTV sensor configuration */
4618   RAIL_EffClpcSensorConfig_t saw2; /**< SAW2 sensor configuration */
4619 } RAIL_EffClpcConfig_t;
4620 
4621 /**
4622  * @struct RAIL_EffConfig_t
4623  *
4624  * @brief Configuration data for the attached EFF device.
4625  *
4626  * A structure of type \ref RAIL_EffConfig_t is passed to \ref RAIL_ConfigEff().
4627  */
4628 typedef struct RAIL_EffConfig {
4629   RAIL_EffDevice_t device;            /**< EFF Device Type */
4630   uint8_t testPort;                   /**< TEST output GPIO port */
4631   uint8_t testPin;                    /**< TEST output GPIO pin */
4632   RAIL_EffLnaMode_t enabledLnaModes;  /**< LNA modes enable bitmask **/
4633   uint16_t ruralUrbanMv;              /**< Trip point from rural to urban mode, in millivolts */
4634   uint16_t urbanBypassMv;             /**< Trip point from urban to bypass mode, in millivolts */
4635   uint16_t lnaReserved;               /**< Reserved for future use */
4636   uint32_t urbanDwellTimeMs;          /**< Time to stay in urban mode before transitioning to rural mode, in milliseconds */
4637   uint32_t bypassDwellTimeMs;         /**< Time to stay in bypass mode before transitioning to urban or rural mode, in milliseconds */
4638   RAIL_EffClpcConfig_t fskClpcConfig; /**< Config Structure for FSK CLPC settings */
4639   RAIL_EffClpcConfig_t ofdmClpcConfig;/**< Config Structure for OFDM CLPC settings */
4640   uint8_t  clpcReserved;              /**< Reserved for future use */
4641   RAIL_ClpcEnable_t clpcEnable;       /**< Select CLPC mode */
4642   bool advProtectionEnable;           /**< Indicates whether the advanced thermal protection is enabled */
4643   uint8_t reservedByte;               /**< Word alignment */
4644   uint16_t tempThresholdK;            /**< Temperature of EFF above which transmit
4645                                            is not allowed, in degrees Kelvin */
4646 } RAIL_EffConfig_t;
4647 
4648 /** @} */ // end of group EFF
4649 
4650 /******************************************************************************
4651  * Thermal Protection
4652  *****************************************************************************/
4653 /**
4654  * @addtogroup Thermal_Protection Thermal Protection
4655  * @{
4656  */
4657 
4658 /** Maximum junction temperature in Kelvin. A margin is subtracted before using it when
4659  * \ref RAIL_SUPPORTS_THERMAL_PROTECTION is enabled.
4660  */
4661 #define RAIL_CHIP_TEMP_THRESHOLD_MAX      (398U)
4662 
4663 /**
4664  * Default number of Kelvin degrees below threshold needed to allow transmissions.
4665  */
4666 #define RAIL_CHIP_TEMP_COOLDOWN_DEFAULT   (7U)
4667 
4668 /**
4669  * @struct RAIL_ChipTempConfig_t
4670  *
4671  * @brief Configuration parameters for thermal protection.
4672  */
4673 typedef struct RAIL_ChipTempConfig {
4674   bool enable;          /**< Indicates whether the protection is enabled */
4675   uint8_t coolDownK;    /**< Mandatory temperature cool down when the threshold is exceeded,
4676                              in degrees Kelvin */
4677   uint16_t thresholdK;  /**< Temperature above which transmit is blocked,
4678                              in degrees Kelvin */
4679 } RAIL_ChipTempConfig_t;
4680 
4681 /** Number of temperature values provided for the chip thermal protection */
4682 #define RAIL_CHIP_TEMP_MEASURE_COUNT      (3U)
4683 
4684 /**
4685  * @struct RAIL_ChipTempMetrics_t
4686  *
4687  * @brief Data used for thermal protection.
4688  *
4689  */
4690 typedef struct RAIL_ChipTempMetrics {
4691   uint16_t tempK;             /**< Store chip temperature for metrics */
4692   uint16_t minTempK;          /**< Minimum temperature recorded */
4693   uint16_t maxTempK;          /**< Maximum temperature recorded */
4694   bool resetPending;          /**< Indicates if data should be reset */
4695   uint8_t reservedChipTemp;   /**< Reserved for future use */
4696 } RAIL_ChipTempMetrics_t;
4697 
4698 /** @} */ // end of group Thermal_Protection
4699 
4700 #ifndef DOXYGEN_SHOULD_SKIP_THIS
4701 
4702 /******************************************************************************
4703  * Debug Structures
4704  *****************************************************************************/
4705 /**
4706  * @addtogroup Debug
4707  * @{
4708  */
4709 
4710 /**
4711  * @def RAIL_DEBUG_MODE_FREQ_OVERRIDE
4712  * @brief A bitmask to enable the frequency override debug mode to
4713  *   manually tune to a specified frequency. Note that this should only be used
4714  *   for testing and is not as tuned as frequencies from the calculator.
4715  */
4716 #define RAIL_DEBUG_MODE_FREQ_OVERRIDE  0x00000001UL
4717 
4718 /**
4719  * @def RAIL_DEBUG_MODE_VALID_MASK
4720  * @brief Any debug mode bits outside of this mask are invalid and ignored.
4721  */
4722 #define RAIL_DEBUG_MODE_VALID_MASK     (~(RAIL_DEBUG_MODE_FREQ_OVERRIDE))
4723 
4724 /** @} */ // end of group Debug
4725 
4726 #endif//DOXYGEN_SHOULD_SKIP_THIS
4727 
4728 /** @} */ // end of RAIL_API
4729 
4730 #ifdef __cplusplus
4731 }
4732 #endif
4733 
4734 // Include appropriate chip-specific types and APIs *after* common types, and
4735 // *before* types that require chip-specific abstractions.
4736 #include "rail_chip_specific.h"
4737 
4738 #ifdef __cplusplus
4739 extern "C" {
4740 #endif
4741 
4742 /**
4743  * @addtogroup RAIL_API
4744  * @{
4745  */
4746 
4747 /**
4748  * @addtogroup State_Transitions
4749  * @{
4750  */
4751 
4752 /**
4753  * @def RAIL_TRANSITION_TIME_KEEP
4754  * @brief A value to use in \ref RAIL_StateTiming_t fields when
4755  *   calling \ref RAIL_SetStateTiming() to keep that timing
4756  *   parameter at it current setting.
4757  */
4758 #define RAIL_TRANSITION_TIME_KEEP ((RAIL_TransitionTime_t) -1)
4759 
4760 /**
4761  * @struct RAIL_StateTiming_t
4762  * @brief A timing configuration structure for the RAIL State Machine.
4763  *
4764  * Configure the timings of the radio state transitions for common situations.
4765  * All of the listed timings are in microseconds. Transitions from an active
4766  * radio state to idle are not configurable, and will always happen as fast
4767  * as possible.
4768  * No timing value can exceed \ref RAIL_MAXIMUM_TRANSITION_US.
4769  * Use \ref RAIL_TRANSITION_TIME_KEEP to keep an existing setting.
4770  *
4771  * For idleToRx, idleToTx, rxToTx, txToRx, and txToTx a value of 0 for the
4772  * transition time means that the specified transition should happen as fast
4773  * as possible, even if the timing cannot be as consistent. Otherwise, the
4774  * timing value cannot be below \ref RAIL_MINIMUM_TRANSITION_US.
4775  *
4776  * For idleToTx, rxToTx, and txToTx setting a longer \ref
4777  * RAIL_TxPowerConfig_t::rampTime may result in a larger minimum value.
4778  *
4779  * For rxSearchTimeout and txToRxSearchTimeout, there is no minimum value. A
4780  * value of 0 disables the feature, functioning as an infinite timeout.
4781  */
4782 typedef struct RAIL_StateTiming {
4783   RAIL_TransitionTime_t idleToRx; /**< Transition time from IDLE to RX. */
4784   RAIL_TransitionTime_t txToRx; /**< Transition time from TX to RX. */
4785   RAIL_TransitionTime_t idleToTx; /**< Transition time from IDLE to RX. */
4786   RAIL_TransitionTime_t rxToTx; /**< Transition time from RX packet to TX. */
4787   RAIL_TransitionTime_t rxSearchTimeout; /**< Length of time the radio will search for a
4788                                             packet when coming from idle or RX. */
4789   RAIL_TransitionTime_t txToRxSearchTimeout; /**< Length of time the radio will search for a
4790                                                 packet when coming from TX. */
4791   RAIL_TransitionTime_t txToTx; /**< Transition time from TX packet to TX. */
4792 } RAIL_StateTiming_t;
4793 
4794 /** @} */ // end of group State_Transitions
4795 
4796 /**
4797  * @addtogroup Transmit
4798  * @{
4799  */
4800 
4801 /**
4802  * @enum RAIL_TxRepeatOptions_t
4803  * @brief Transmit repeat options, in reality a bitmask.
4804  */
RAIL_ENUM_GENERIC(RAIL_TxRepeatOptions_t,uint16_t)4805 RAIL_ENUM_GENERIC(RAIL_TxRepeatOptions_t, uint16_t) {
4806   /** Shift position of \ref RAIL_TX_REPEAT_OPTION_HOP bit */
4807   RAIL_TX_REPEAT_OPTION_HOP_SHIFT = 0,
4808 };
4809 
4810 /** A value representing no repeat options enabled. */
4811 #define RAIL_TX_REPEAT_OPTIONS_NONE 0U
4812 /** All repeat options disabled by default. */
4813 #define RAIL_TX_REPEAT_OPTIONS_DEFAULT RAIL_TX_REPEAT_OPTIONS_NONE
4814 /**
4815  * An option to configure whether or not to channel-hop before each
4816  * repeated transmit.
4817  */
4818 #define RAIL_TX_REPEAT_OPTION_HOP (1U << RAIL_TX_REPEAT_OPTION_HOP_SHIFT)
4819 
4820 /// @struct RAIL_TxRepeatConfig_t
4821 /// @brief A configuration structure for repeated transmits
4822 ///
4823 /// @note The PA will always be ramped down and up in between transmits so
4824 /// there will always be some minimum delay between transmits depending on the
4825 /// ramp time configuration.
4826 typedef struct RAIL_TxRepeatConfig {
4827   /**
4828    * The number of repeated transmits to run. A total of (iterations + 1)
4829    * transmits will go on-air in the absence of errors.
4830    */
4831   uint16_t iterations;
4832   /**
4833    * Repeat option(s) to apply.
4834    */
4835   RAIL_TxRepeatOptions_t repeatOptions;
4836   /**
4837    * Per-repeat delay or hopping configuration, depending on repeatOptions.
4838    */
4839   union {
4840     /**
4841      * When \ref RAIL_TX_REPEAT_OPTION_HOP is not set, specifies
4842      * the delay time between each repeated transmit. Specify \ref
4843      * RAIL_TRANSITION_TIME_KEEP to use the current \ref
4844      * RAIL_StateTiming_t::txToTx transition time setting.
4845      */
4846     RAIL_TransitionTime_t delay;
4847     /**
4848      * When \ref RAIL_TX_REPEAT_OPTION_HOP is set, this specifies
4849      * the channel hopping configuration to use when hopping between
4850      * repeated transmits. Per-hop delays are configured within each
4851      * \ref RAIL_TxChannelHoppingConfigEntry_t::delay rather than
4852      * this union's delay field.
4853      */
4854     RAIL_TxChannelHoppingConfig_t channelHopping;
4855   } delayOrHop;
4856 } RAIL_TxRepeatConfig_t;
4857 
4858 /// RAIL_TxRepeatConfig_t::iterations initializer configuring infinite
4859 /// repeated transmissions.
4860 #define RAIL_TX_REPEAT_INFINITE_ITERATIONS (0xFFFFU)
4861 
4862 /** @} */ // end of group Transmit
4863 
4864 /** @} */ // end of RAIL_API
4865 
4866 #ifdef __cplusplus
4867 }
4868 #endif
4869 
4870 #endif  // __RAIL_TYPES_H__
4871