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 #include "sl_status.h"
40
41 #ifdef __cplusplus
42 extern "C" {
43 #endif
44
45 #ifdef DOXYGEN_SHOULD_SKIP_THIS
46 /// The RAIL library does not use enumerations because the ARM EABI leaves their
47 /// size ambiguous, which causes problems if the application is built
48 /// with different flags than the library. Instead, uint8_t typedefs
49 /// are used in compiled code for all enumerations. For documentation purposes, this is
50 /// converted to an actual enumeration since it's much easier to read in Doxygen.
51 #define RAIL_ENUM(name) enum name
52 /// This macro is a more generic version of the \ref RAIL_ENUM() macro that
53 /// allows the size of the type to be overridden instead of forcing the use of
54 /// a uint8_t. See \ref RAIL_ENUM() for more information.
55 #define RAIL_ENUM_GENERIC(name, type) enum name
56 #else//!DOXYGEN_SHOULD_SKIP_THIS
57 /// Define used for the RAIL library, which sets each enumeration to a uint8_t
58 /// typedef and creates a named enumeration structure for the enumeration values.
59 /// For debugging, use the following define to turn this back into a proper enumeration
60 /// #define RAIL_ENUM(name) typedef enum name##_enum name; enum name##_enum
61 #define RAIL_ENUM(name) typedef uint8_t name; enum name##_enum
62 #define RAIL_ENUM_GENERIC(name, type) typedef type name; enum name##_enum
63 #endif//DOXYGEN_SHOULD_SKIP_THIS
64
65 /**
66 * @addtogroup RAIL_API
67 * @{
68 */
69
70 /******************************************************************************
71 * General Structures
72 *****************************************************************************/
73 /**
74 * @addtogroup General
75 * @{
76 */
77
78 /**
79 * @struct RAIL_Version_t
80 * @brief Contains RAIL Library Version Information.
81 * It is filled in by \ref RAIL_GetVersion().
82 */
83 typedef struct RAIL_Version {
84 /** Git hash */
85 uint32_t hash;
86 /** Major number */
87 uint8_t major;
88 /** Minor number */
89 uint8_t minor;
90 /** Revision number */
91 uint8_t rev;
92 /** Build number */
93 uint8_t build;
94 /** Build flags */
95 uint8_t flags;
96 /** Boolean to indicate whether this is a multiprotocol library or not. */
97 bool multiprotocol;
98 } RAIL_Version_t;
99
100 /**
101 * @typedef RAIL_Handle_t
102 * @brief A radio-generic handle (e.g., \ref RAIL_EFR32_HANDLE),
103 * or a real RAIL instance handle as returned from \ref RAIL_Init().
104 *
105 * Generic handles should be used for certain RAIL APIs that are called
106 * prior to RAIL initialization. However, once RAIL has been initialized,
107 * the real handle returned by \ref RAIL_Init() should be used instead.
108 */
109 typedef void *RAIL_Handle_t;
110
111 /**
112 * A placeholder for a radio-generic RAIL handle. Using NULL as a RAIL handle
113 * is not recommended. As a result, another value that can't be de-referenced
114 * is used.
115 *
116 * This generic handle can and should be used for RAIL APIs that are called
117 * prior to RAIL initialization.
118 */
119 #define RAIL_EFR32_HANDLE ((RAIL_Handle_t)0xFFFFFFFFUL)
120
121 /**
122 * @typedef RAIL_Status_t
123 * @brief A status returned by many RAIL API calls indicating their success or
124 * failure. It is a subset of sl_status_t.
125 */
126 typedef sl_status_t RAIL_Status_t;
127
128 /** RAIL function reports no error. */
129 #define RAIL_STATUS_NO_ERROR SL_STATUS_OK // 0x0000
130
131 /** Call to RAIL function threw an error because of an invalid parameter. */
132 #define RAIL_STATUS_INVALID_PARAMETER SL_STATUS_INVALID_PARAMETER // 0x0021
133
134 /**
135 * Call to RAIL function threw an error because it was called during
136 * an invalid radio state.
137 */
138 #define RAIL_STATUS_INVALID_STATE SL_STATUS_INVALID_STATE // 0x0002
139
140 /** RAIL function is called in an invalid order. */
141 #define RAIL_STATUS_INVALID_CALL SL_STATUS_NOT_AVAILABLE // 0x000E
142
143 /** RAIL function did not finish in the allotted time. */
144 #define RAIL_STATUS_SUSPENDED SL_STATUS_IN_PROGRESS // 0x0005
145
146 /**
147 * RAIL function could not be scheduled by the Radio scheduler.
148 * Only issued when using a Multiprotocol application.
149 */
150 #define RAIL_STATUS_SCHED_ERROR SL_STATUS_ABORT // 0x0006
151
152 /**
153 * A pointer to an initialization complete callback function.
154 *
155 * @param[in] railHandle The initialized RAIL instance handle.
156 */
157 typedef void (*RAIL_InitCompleteCallbackPtr_t)(RAIL_Handle_t railHandle);
158
159 /** A value to signal that RAIL should not use DMA. */
160 #define RAIL_DMA_INVALID (0xFFU)
161
162 /**
163 * @struct RAILSched_Config_t
164 * @brief Provided for backwards compatibility.
165 */
166 typedef struct RAILSched_Config {
167 /** Dummy buffer no longer used. */
168 uint8_t buffer[1];
169 } RAILSched_Config_t;
170
171 /**
172 * @typedef RAIL_StateBuffer_t
173 * @brief Provided for backwards compatibility.
174 */
175 typedef uint8_t RAIL_StateBuffer_t[1];
176
177 #ifndef DOXYGEN_SHOULD_SKIP_THIS
178
179 /**
180 * A linked list structure for RAIL state buffers which \ref RAIL_Init()
181 * utilizes for managing internal RAIL state.
182 */
183 typedef struct RAIL_StateBufferEntry {
184 /** pointer to next buffer in linked list */
185 struct RAIL_StateBufferEntry *next;
186 /** size of the buffer */
187 uint32_t bufferBytes;
188 /** pointer to the buffer in RAM */
189 uint64_t *buffer;
190 } RAIL_StateBufferEntry_t;
191
192 #endif//DOXYGEN_SHOULD_SKIP_THIS
193
194 /** @} */ // end of group General
195
196 /******************************************************************************
197 * System Timing Structures
198 *****************************************************************************/
199 /**
200 * @addtogroup System_Timing
201 * @{
202 */
203
204 /**
205 * @typedef RAIL_Time_t
206 * @brief Time in microseconds
207 */
208 typedef uint32_t RAIL_Time_t;
209
210 /**
211 * A pointer to the callback called when the RAIL timer expires.
212 *
213 * @param[in] cbArg The argument passed to the callback.
214 */
215 typedef void (*RAIL_TimerCallback_t)(RAIL_Handle_t cbArg);
216
217 /**
218 * @enum RAIL_TimeMode_t
219 * @brief Specify a time offset in RAIL APIs.
220 *
221 * Different APIs use the same constants and may provide more specifics about
222 * how they're used but the general use for each is described below.
223 */
RAIL_ENUM(RAIL_TimeMode_t)224 RAIL_ENUM(RAIL_TimeMode_t) {
225 /**
226 * The time specified is an exact time in the RAIL timebase. The given
227 * event should happen at exactly that time. If this time is already in the
228 * past, an error is returned. Because the RAIL timebase wraps at 32
229 * bits, there is no real 'past'. Instead, any event greater than
230 * 3/4 of the way into the future is considered to be in the past.
231 */
232 RAIL_TIME_ABSOLUTE = 0,
233 /**
234 * The time specified is relative to the current time. The event should occur
235 * that many ticks in the future. Delays are only guaranteed at least as long
236 * as the value specified. An overhead may occur between the time when the
237 * API is called and when the delay starts. As a result, using this for
238 * operations that must happen at an exact given time is not recommended.
239 * For that, you must use \ref RAIL_TIME_ABSOLUTE delays.
240 *
241 * Note that, if you specify a delay 0, that event is triggered as soon as
242 * possible. This is different than specifying an absolute time of now which
243 * would return an error unless it was possible.
244 */
245 RAIL_TIME_DELAY = 1,
246 /**
247 * The specified time is invalid and should be ignored. For some APIs this
248 * can also indicate that any previously stored delay should be invalidated
249 * and disabled.
250 */
251 RAIL_TIME_DISABLED = 2,
252 };
253
254 #ifndef DOXYGEN_SHOULD_SKIP_THIS
255 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
256 #define RAIL_TIME_ABSOLUTE ((RAIL_TimeMode_t) RAIL_TIME_ABSOLUTE)
257 #define RAIL_TIME_DELAY ((RAIL_TimeMode_t) RAIL_TIME_DELAY)
258 #define RAIL_TIME_DISABLED ((RAIL_TimeMode_t) RAIL_TIME_DISABLED)
259 #endif//DOXYGEN_SHOULD_SKIP_THIS
260
261 /// @struct RAIL_MultiTimer
262 /// Forward structure declaration of \ref RAIL_MultiTimer_t.
263 struct RAIL_MultiTimer;
264
265 /**
266 * @typedef RAIL_MultiTimerCallback_t
267 * @brief Callback fired when timer expires.
268 *
269 * @param[in] tmr A pointer to an expired timer.
270 * @param[in] expectedTimeOfEvent An absolute time event fired.
271 * @param[in] cbArg A user-supplied callback argument.
272 */
273 typedef void (*RAIL_MultiTimerCallback_t)(struct RAIL_MultiTimer *tmr,
274 RAIL_Time_t expectedTimeOfEvent,
275 void *cbArg);
276
277 /**
278 * @struct RAIL_MultiTimer_t
279 * @brief RAIL timer state structure.
280 *
281 * This structure is filled out and maintained internally only.
282 * The user/application should not alter any elements of this structure.
283 */
284 typedef struct RAIL_MultiTimer {
285 /** Absolute time before the next event. */
286 RAIL_Time_t absOffset;
287 /** Relative, periodic time between events; 0 = timer is oneshot. */
288 RAIL_Time_t relPeriodic;
289 /** A user callback. */
290 RAIL_MultiTimerCallback_t callback;
291 /** A user callback argument. */
292 void *cbArg;
293 /** A pointer to the next soft timer structure. */
294 struct RAIL_MultiTimer *next;
295 /** A priority of the callback; 0 = highest priority; 255 = lowest. */
296 uint8_t priority;
297 /** Indicates the timer is currently running. */
298 bool isRunning;
299 /** Indicates the callback needs to run. */
300 bool doCallback;
301 } RAIL_MultiTimer_t;
302
303 /**
304 * @enum RAIL_PacketTimePosition_t
305 * @brief The available packet timestamp position choices.
306 */
RAIL_ENUM(RAIL_PacketTimePosition_t)307 RAIL_ENUM(RAIL_PacketTimePosition_t) {
308 /**
309 * Indicate that a timestamp is not to be or was not provided.
310 * It is useful if the application doesn't care about packet timestamps
311 * and doesn't want RAIL to spend time calculating one.
312 */
313 RAIL_PACKET_TIME_INVALID = 0,
314 /**
315 * Request the choice most expedient for RAIL to calculate,
316 * which may depend on the radio and/or its configuration.
317 * The actual choice would always be reflected in the \ref
318 * RAIL_PacketTimeStamp_t::timePosition field of the \ref
319 * RAIL_RxPacketDetails_t::timeReceived or \ref
320 * RAIL_TxPacketDetails_t::timeSent
321 * returned and would never be one of the _USED_TOTAL values.
322 */
323 RAIL_PACKET_TIME_DEFAULT = 1,
324 /**
325 * Request the timestamp corresponding to the first preamble bit
326 * sent or received.
327 * Indicate that timestamp did not require using totalPacketBytes.
328 */
329 RAIL_PACKET_TIME_AT_PREAMBLE_START = 2,
330 /**
331 * Request the timestamp corresponding to the first preamble bit
332 * sent or received.
333 * Indicate that timestamp did require using totalPacketBytes.
334 */
335 RAIL_PACKET_TIME_AT_PREAMBLE_START_USED_TOTAL = 3,
336 /**
337 * Request the timestamp corresponding to right after its last
338 * SYNC word bit has been sent or received.
339 * Indicate that timestamp did not require using totalPacketBytes.
340 */
341 RAIL_PACKET_TIME_AT_SYNC_END = 4,
342 /**
343 * Request the timestamp corresponding to right after its last
344 * SYNC word bit has been sent or received.
345 * Indicate that timestamp did require using totalPacketBytes.
346 */
347 RAIL_PACKET_TIME_AT_SYNC_END_USED_TOTAL = 5,
348 /**
349 * Request the timestamp corresponding to right after its last
350 * bit has been sent or received.
351 * Indicate that timestamp did not require using totalPacketBytes.
352 */
353 RAIL_PACKET_TIME_AT_PACKET_END = 6,
354 /**
355 * Request the timestamp corresponding to right after its last
356 * bit has been sent or received.
357 * Indicate that timestamp did require using totalPacketBytes.
358 */
359 RAIL_PACKET_TIME_AT_PACKET_END_USED_TOTAL = 7,
360 /** A count of the choices in this enumeration. Must be last. */
361 RAIL_PACKET_TIME_COUNT
362 };
363
364 #ifndef DOXYGEN_SHOULD_SKIP_THIS
365 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
366 #define RAIL_PACKET_TIME_INVALID ((RAIL_PacketTimePosition_t) RAIL_PACKET_TIME_INVALID)
367 #define RAIL_PACKET_TIME_DEFAULT ((RAIL_PacketTimePosition_t) RAIL_PACKET_TIME_DEFAULT)
368 #define RAIL_PACKET_TIME_AT_PREAMBLE_START ((RAIL_PacketTimePosition_t) RAIL_PACKET_TIME_AT_PREAMBLE_START)
369 #define RAIL_PACKET_TIME_AT_PREAMBLE_START_USED_TOTAL ((RAIL_PacketTimePosition_t) RAIL_PACKET_TIME_AT_PREAMBLE_START_USED_TOTAL)
370 #define RAIL_PACKET_TIME_AT_SYNC_END ((RAIL_PacketTimePosition_t) RAIL_PACKET_TIME_AT_SYNC_END)
371 #define RAIL_PACKET_TIME_AT_SYNC_END_USED_TOTAL ((RAIL_PacketTimePosition_t) RAIL_PACKET_TIME_AT_SYNC_END_USED_TOTAL)
372 #define RAIL_PACKET_TIME_AT_PACKET_END ((RAIL_PacketTimePosition_t) RAIL_PACKET_TIME_AT_PACKET_END)
373 #define RAIL_PACKET_TIME_AT_PACKET_END_USED_TOTAL ((RAIL_PacketTimePosition_t) RAIL_PACKET_TIME_AT_PACKET_END_USED_TOTAL)
374 #define RAIL_PACKET_TIME_COUNT ((RAIL_PacketTimePosition_t) RAIL_PACKET_TIME_COUNT)
375 #endif//DOXYGEN_SHOULD_SKIP_THIS
376
377 /**
378 * @struct RAIL_PacketTimeStamp_t
379 * @brief Information for calculating and representing a packet timestamp.
380 */
381 typedef struct RAIL_PacketTimeStamp {
382 /**
383 * Timestamp of the packet in the RAIL timebase.
384 */
385 RAIL_Time_t packetTime;
386 /**
387 * A value specifying the total length in bytes of the packet
388 * used when calculating the packetTime requested by the timePosition
389 * field. This should account for all bytes sent over the air after
390 * the Preamble and Sync word(s) including CRC bytes.
391 */
392 uint16_t totalPacketBytes;
393 /**
394 * A \ref RAIL_PacketTimePosition_t value specifying the packet position
395 * to return in the packetTime field.
396 * If this is \ref RAIL_PACKET_TIME_DEFAULT, this field will be
397 * updated with the actual position corresponding to the packetTime
398 * value filled in by a call using this structure.
399 */
400 RAIL_PacketTimePosition_t timePosition;
401 /**
402 * In RX for EFR32xG25 only:
403 * A value specifying the on-air duration of the data packet,
404 * starting with the first bit of the PHR (i.e., end of sync word);
405 * preamble and sync word duration are hence excluded.
406 *
407 * In Tx for all platforms:
408 * A value specifying the on-air duration of the data packet,
409 * starting at the preamble (i.e. includes preamble, sync word, PHR,
410 * payload and FCS). This value can be used to compute duty cycles.
411 * @note This field is currently valid only for normal transmits but
412 * not Auto-Ack transmits which set the field to zero.
413 */
414 RAIL_Time_t packetDurationUs;
415 } RAIL_PacketTimeStamp_t;
416
417 /** @} */ // end of group System_Timing
418
419 /******************************************************************************
420 * Sleep Structures
421 *****************************************************************************/
422 /**
423 * @addtogroup Sleep
424 * @{
425 */
426
427 /**
428 * @enum RAIL_SleepConfig_t
429 * @brief The configuration
430 */
RAIL_ENUM(RAIL_SleepConfig_t)431 RAIL_ENUM(RAIL_SleepConfig_t) {
432 /** Disable timer sync before and after sleep. */
433 RAIL_SLEEP_CONFIG_TIMERSYNC_DISABLED = 0,
434 /** Enable timer sync before and after sleep. */
435 RAIL_SLEEP_CONFIG_TIMERSYNC_ENABLED = 1,
436 };
437
438 #ifndef DOXYGEN_SHOULD_SKIP_THIS
439 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
440 #define RAIL_SLEEP_CONFIG_TIMERSYNC_DISABLED ((RAIL_SleepConfig_t) RAIL_SLEEP_CONFIG_TIMERSYNC_DISABLED)
441 #define RAIL_SLEEP_CONFIG_TIMERSYNC_ENABLED ((RAIL_SleepConfig_t) RAIL_SLEEP_CONFIG_TIMERSYNC_ENABLED)
442 #endif//DOXYGEN_SHOULD_SKIP_THIS
443
444 /**
445 * @struct RAIL_TimerSyncConfig_t
446 * @brief Channel values used to perform timer sync before and after sleep.
447 *
448 * The default value of this structure is provided in the
449 * \ref RAIL_TIMER_SYNC_DEFAULT macro.
450 */
451 typedef struct RAIL_TimerSyncConfig {
452 /**
453 * PRS Channel used for timer sync operations.
454 * Use \ref RAIL_TIMER_SYNC_PRS_CHANNEL_DEFAULT or another suitable one.
455 */
456 uint8_t prsChannel;
457 /**
458 * RTCC Channel used for timer sync operations. Only applies to
459 * platforms where the RTCC used for timer sync has multiple channels.
460 * Use \ref RAIL_TIMER_SYNC_RTCC_CHANNEL_DEFAULT or another suitable one.
461 */
462 uint8_t rtccChannel;
463 /**
464 * Whether to sync the timer before and after sleeping.
465 */
466 RAIL_SleepConfig_t sleep;
467 } RAIL_TimerSyncConfig_t;
468
469 /// Default timer synchronization configuration.
470 #define RAIL_TIMER_SYNC_DEFAULT { \
471 .prsChannel = RAIL_TIMER_SYNC_PRS_CHANNEL_DEFAULT, \
472 .rtccChannel = RAIL_TIMER_SYNC_RTCC_CHANNEL_DEFAULT, \
473 .sleep = RAIL_SLEEP_CONFIG_TIMERSYNC_ENABLED, \
474 }
475
476 /** @} */ // end of group Sleep
477
478 /******************************************************************************
479 * Multiprotocol Structures
480 *****************************************************************************/
481 /**
482 * @addtogroup Multiprotocol
483 * @{
484 */
485
486 /**
487 * @struct RAIL_SchedulerInfo_t
488 * @brief A structure to hold information used by the scheduler.
489 *
490 * For multiprotocol versions of RAIL, this can be used to control how a receive
491 * or transmit operation is run. It's not necessary in single-protocol applications.
492 */
493 typedef struct RAIL_SchedulerInfo {
494 /**
495 * The scheduler priority to use for this operation. This priority is used to
496 * preempt a long running lower-priority task to ensure higher-priority
497 * operations complete in time. A lower numerical value represents a higher
498 * logical priority meaning 0 is the highest priority and 255 is the lowest.
499 */
500 uint8_t priority;
501 /**
502 * The amount of time in microseconds that this operation can slip by into the future
503 * and still be run. This time is relative to the start time which may be
504 * the current time for relative transmits. If the scheduler can't start the
505 * operation by this time, it will be considered a failure.
506 */
507 RAIL_Time_t slipTime;
508 /**
509 * The transaction time in microseconds for this operation. Since transaction times may
510 * not be known exactly, use a minimum or an expected
511 * guess for this time. The scheduler will use the value entered here to look
512 * for overlaps between low-priority and high-priority tasks and attempt to
513 * find a schedule where all tasks get to run.
514 */
515 RAIL_Time_t transactionTime;
516 } RAIL_SchedulerInfo_t;
517
518 /** Radio Scheduler Status mask within \ref RAIL_SchedulerStatus_t values. */
519 #define RAIL_SCHEDULER_STATUS_MASK 0x0FU
520 /** Radio Scheduler Status shift within \ref RAIL_SchedulerStatus_t values. */
521 #define RAIL_SCHEDULER_STATUS_SHIFT 0
522
523 /** Radio Scheduler Task mask within \ref RAIL_SchedulerStatus_t values. */
524 #define RAIL_SCHEDULER_TASK_MASK 0xF0U
525 /** Radio Scheduler Task shift within \ref RAIL_SchedulerStatus_t values. */
526 #define RAIL_SCHEDULER_TASK_SHIFT 4
527
528 /**
529 * @enum RAIL_SchedulerStatus_t
530 * @brief Multiprotocol scheduler status returned by \ref RAIL_GetSchedulerStatus().
531 *
532 * \ref Multiprotocol scheduler status is a combination of the upper 4 bits which
533 * constitute the type of scheduler task and the lower 4 bits which constitute
534 * the type of scheduler error.
535 */
RAIL_ENUM(RAIL_SchedulerStatus_t)536 RAIL_ENUM(RAIL_SchedulerStatus_t) {
537 /** Multiprotocol scheduler reports no error. */
538 RAIL_SCHEDULER_STATUS_NO_ERROR = (0U << RAIL_SCHEDULER_STATUS_SHIFT),
539 /**
540 * The scheduler is disabled or the requested scheduler operation is
541 * unsupported.
542 */
543 RAIL_SCHEDULER_STATUS_UNSUPPORTED = (1U << RAIL_SCHEDULER_STATUS_SHIFT),
544 /**
545 * The scheduled task was started but was interrupted by a higher-priority
546 * event before it could be completed.
547 */
548 RAIL_SCHEDULER_STATUS_EVENT_INTERRUPTED = (2U << RAIL_SCHEDULER_STATUS_SHIFT),
549 /**
550 * Scheduled task could not be scheduled given its priority and the other
551 * tasks running on the system.
552 */
553 RAIL_SCHEDULER_STATUS_SCHEDULE_FAIL = (3U << RAIL_SCHEDULER_STATUS_SHIFT),
554 /**
555 * Calling the RAIL API associated with the Radio scheduler task returned
556 * an error code. See \ref RAIL_GetSchedulerStatus() or \ref RAIL_GetSchedulerStatusAlt()
557 * for more information about \ref RAIL_Status_t status.
558 */
559 RAIL_SCHEDULER_STATUS_TASK_FAIL = (4U << RAIL_SCHEDULER_STATUS_SHIFT),
560 /**
561 * An internal error occurred in scheduler data structures, which should
562 * not happen and indicates a problem.
563 */
564 RAIL_SCHEDULER_STATUS_INTERNAL_ERROR = (5U << RAIL_SCHEDULER_STATUS_SHIFT),
565
566 /** Radio scheduler has no task. */
567 RAIL_SCHEDULER_TASK_EMPTY = (0U << RAIL_SCHEDULER_TASK_SHIFT),
568 /** Radio scheduler calls \ref RAIL_ScheduleRx(). */
569 RAIL_SCHEDULER_TASK_SCHEDULED_RX = (1U << RAIL_SCHEDULER_TASK_SHIFT),
570 /** Radio scheduler calls \ref RAIL_StartScheduledTx(). */
571 RAIL_SCHEDULER_TASK_SCHEDULED_TX = (2U << RAIL_SCHEDULER_TASK_SHIFT),
572 /** Radio scheduler calls \ref RAIL_StartTx(). */
573 RAIL_SCHEDULER_TASK_SINGLE_TX = (3U << RAIL_SCHEDULER_TASK_SHIFT),
574 /** Radio scheduler calls \ref RAIL_StartCcaCsmaTx(). */
575 RAIL_SCHEDULER_TASK_SINGLE_CCA_CSMA_TX = (4U << RAIL_SCHEDULER_TASK_SHIFT),
576 /** Radio scheduler calls \ref RAIL_StartCcaLbtTx(). */
577 RAIL_SCHEDULER_TASK_SINGLE_CCA_LBT_TX = (5U << RAIL_SCHEDULER_TASK_SHIFT),
578 /** Radio scheduler calls \ref RAIL_StartScheduledCcaCsmaTx(). */
579 RAIL_SCHEDULER_TASK_SCHEDULED_CCA_CSMA_TX = (6U << RAIL_SCHEDULER_TASK_SHIFT),
580 /** Radio scheduler calls \ref RAIL_StartScheduledCcaLbtTx(). */
581 RAIL_SCHEDULER_TASK_SCHEDULED_CCA_LBT_TX = (7U << RAIL_SCHEDULER_TASK_SHIFT),
582 /** Radio scheduler calls \ref RAIL_StartTxStream(). */
583 RAIL_SCHEDULER_TASK_TX_STREAM = (8U << RAIL_SCHEDULER_TASK_SHIFT),
584 /** Radio scheduler calls \ref RAIL_StartAverageRssi(). */
585 RAIL_SCHEDULER_TASK_AVERAGE_RSSI = (9U << RAIL_SCHEDULER_TASK_SHIFT),
586
587 /** \ref RAIL_StartScheduledTx() returned error status. */
588 RAIL_SCHEDULER_STATUS_SCHEDULED_TX_FAIL = (RAIL_SCHEDULER_TASK_SCHEDULED_TX
589 | RAIL_SCHEDULER_STATUS_TASK_FAIL),
590 /** \ref RAIL_StartTx() returned error status. */
591 RAIL_SCHEDULER_STATUS_SINGLE_TX_FAIL = (RAIL_SCHEDULER_TASK_SINGLE_TX
592 | RAIL_SCHEDULER_STATUS_TASK_FAIL),
593 /** \ref RAIL_StartCcaCsmaTx() returned error status. */
594 RAIL_SCHEDULER_STATUS_CCA_CSMA_TX_FAIL = (RAIL_SCHEDULER_TASK_SINGLE_CCA_CSMA_TX
595 | RAIL_SCHEDULER_STATUS_TASK_FAIL),
596 /** \ref RAIL_StartCcaLbtTx() returned error status. */
597 RAIL_SCHEDULER_STATUS_CCA_LBT_TX_FAIL = (RAIL_SCHEDULER_TASK_SINGLE_CCA_LBT_TX
598 | RAIL_SCHEDULER_STATUS_TASK_FAIL),
599 /** \ref RAIL_ScheduleRx() returned error status. */
600 RAIL_SCHEDULER_STATUS_SCHEDULED_RX_FAIL = (RAIL_SCHEDULER_TASK_SCHEDULED_RX
601 | RAIL_SCHEDULER_STATUS_TASK_FAIL),
602 /** \ref RAIL_StartTxStream() returned error status. */
603 RAIL_SCHEDULER_STATUS_TX_STREAM_FAIL = (RAIL_SCHEDULER_TASK_TX_STREAM
604 | RAIL_SCHEDULER_STATUS_TASK_FAIL),
605 /** \ref RAIL_StartAverageRssi() returned error status. */
606 RAIL_SCHEDULER_STATUS_AVERAGE_RSSI_FAIL = (RAIL_SCHEDULER_TASK_AVERAGE_RSSI
607 | RAIL_SCHEDULER_STATUS_TASK_FAIL),
608
609 /** Multiprotocol scheduled receive function internal error. */
610 RAIL_SCHEDULER_SCHEDULED_RX_INTERNAL_ERROR = (RAIL_SCHEDULER_TASK_SCHEDULED_RX
611 | RAIL_SCHEDULER_STATUS_INTERNAL_ERROR),
612 /** Multiprotocol scheduled receive scheduling error. */
613 RAIL_SCHEDULER_SCHEDULED_RX_SCHEDULING_ERROR = (RAIL_SCHEDULER_TASK_SCHEDULED_RX
614 | RAIL_SCHEDULER_STATUS_SCHEDULE_FAIL),
615 /** \ref RAIL_ScheduleRx() operation interrupted */
616 RAIL_SCHEDULER_SCHEDULED_RX_INTERRUPTED = (RAIL_SCHEDULER_TASK_SCHEDULED_RX
617 | RAIL_SCHEDULER_STATUS_EVENT_INTERRUPTED),
618
619 /** Multiprotocol scheduled TX internal error. */
620 RAIL_SCHEDULER_SCHEDULED_TX_INTERNAL_ERROR = (RAIL_SCHEDULER_TASK_SCHEDULED_TX
621 | RAIL_SCHEDULER_STATUS_INTERNAL_ERROR),
622 /** Multiprotocol scheduled TX scheduling error. */
623 RAIL_SCHEDULER_SCHEDULED_TX_SCHEDULING_ERROR = (RAIL_SCHEDULER_TASK_SCHEDULED_TX
624 | RAIL_SCHEDULER_STATUS_SCHEDULE_FAIL),
625 /** \ref RAIL_StartScheduledTx() operation interrupted. */
626 RAIL_SCHEDULER_SCHEDULED_TX_INTERRUPTED = (RAIL_SCHEDULER_TASK_SCHEDULED_TX
627 | RAIL_SCHEDULER_STATUS_EVENT_INTERRUPTED),
628
629 /** Multiprotocol instantaneous TX internal error. */
630 RAIL_SCHEDULER_SINGLE_TX_INTERNAL_ERROR = (RAIL_SCHEDULER_TASK_SINGLE_TX
631 | RAIL_SCHEDULER_STATUS_INTERNAL_ERROR),
632 /** Multiprotocol instantaneous TX scheduling error. */
633 RAIL_SCHEDULER_SINGLE_TX_SCHEDULING_ERROR = (RAIL_SCHEDULER_TASK_SINGLE_TX
634 | RAIL_SCHEDULER_STATUS_SCHEDULE_FAIL),
635 /** \ref RAIL_StartTx() operation interrupted. */
636 RAIL_SCHEDULER_SINGLE_TX_INTERRUPTED = (RAIL_SCHEDULER_TASK_SINGLE_TX
637 | RAIL_SCHEDULER_STATUS_EVENT_INTERRUPTED),
638
639 /** Multiprotocol single CSMA transmit function internal error. */
640 RAIL_SCHEDULER_SINGLE_CCA_CSMA_TX_INTERNAL_ERROR = (RAIL_SCHEDULER_TASK_SINGLE_CCA_CSMA_TX
641 | RAIL_SCHEDULER_STATUS_INTERNAL_ERROR),
642 /** Multiprotocol single CSMA transmit scheduling error. */
643 RAIL_SCHEDULER_SINGLE_CCA_CSMA_TX_SCHEDULING_ERROR = (RAIL_SCHEDULER_TASK_SINGLE_CCA_CSMA_TX
644 | RAIL_SCHEDULER_STATUS_SCHEDULE_FAIL),
645 /** \ref RAIL_StartCcaCsmaTx() operation interrupted. */
646 RAIL_SCHEDULER_SINGLE_CCA_CSMA_TX_INTERRUPTED = (RAIL_SCHEDULER_TASK_SINGLE_CCA_CSMA_TX
647 | RAIL_SCHEDULER_STATUS_EVENT_INTERRUPTED),
648
649 /** Multiprotocol single LBT transmit function internal error. */
650 RAIL_SCHEDULER_SINGLE_CCA_LBT_TX_INTERNAL_ERROR = (RAIL_SCHEDULER_TASK_SINGLE_CCA_LBT_TX
651 | RAIL_SCHEDULER_STATUS_INTERNAL_ERROR),
652 /** Multiprotocol single LBT transmit scheduling error. */
653 RAIL_SCHEDULER_SINGLE_CCA_LBT_TX_SCHEDULING_ERROR = (RAIL_SCHEDULER_TASK_SINGLE_CCA_LBT_TX
654 | RAIL_SCHEDULER_STATUS_SCHEDULE_FAIL),
655 /** \ref RAIL_StartCcaLbtTx() operation interrupted. */
656 RAIL_SCHEDULER_SINGLE_CCA_LBT_TX_INTERRUPTED = (RAIL_SCHEDULER_TASK_SINGLE_CCA_LBT_TX
657 | RAIL_SCHEDULER_STATUS_EVENT_INTERRUPTED),
658
659 /** Multiprotocol scheduled CSMA transmit function internal error. */
660 RAIL_SCHEDULER_SCHEDULED_CCA_CSMA_TX_INTERNAL_ERROR = (RAIL_SCHEDULER_TASK_SCHEDULED_CCA_CSMA_TX
661 | RAIL_SCHEDULER_STATUS_INTERNAL_ERROR),
662 /** \ref RAIL_StartScheduledCcaCsmaTx() returned error status. */
663 RAIL_SCHEDULER_SCHEDULED_CCA_CSMA_TX_FAIL = (RAIL_SCHEDULER_TASK_SCHEDULED_CCA_CSMA_TX
664 | RAIL_SCHEDULER_STATUS_TASK_FAIL),
665 /** Multiprotocol scheduled CSMA transmit scheduling error. */
666 RAIL_SCHEDULER_SCHEDULED_CCA_CSMA_TX_SCHEDULING_ERROR = (RAIL_SCHEDULER_TASK_SCHEDULED_CCA_CSMA_TX
667 | RAIL_SCHEDULER_STATUS_SCHEDULE_FAIL),
668 /** \ref RAIL_StartScheduledCcaCsmaTx() operation interrupted. */
669 RAIL_SCHEDULER_SCHEDULED_CCA_CSMA_TX_INTERRUPTED = (RAIL_SCHEDULER_TASK_SCHEDULED_CCA_CSMA_TX
670 | RAIL_SCHEDULER_STATUS_EVENT_INTERRUPTED),
671
672 /** Multiprotocol scheduled LBT transmit function internal error. */
673 RAIL_SCHEDULER_SCHEDULED_CCA_LBT_TX_INTERNAL_ERROR = (RAIL_SCHEDULER_TASK_SCHEDULED_CCA_LBT_TX
674 | RAIL_SCHEDULER_STATUS_INTERNAL_ERROR),
675 /** \ref RAIL_StartScheduledCcaLbtTx() returned error status. */
676 RAIL_SCHEDULER_SCHEDULED_CCA_LBT_TX_FAIL = (RAIL_SCHEDULER_TASK_SCHEDULED_CCA_LBT_TX
677 | RAIL_SCHEDULER_STATUS_TASK_FAIL),
678 /** Multiprotocol scheduled LBT transmit scheduling error. */
679 RAIL_SCHEDULER_SCHEDULED_CCA_LBT_TX_SCHEDULING_ERROR = (RAIL_SCHEDULER_TASK_SCHEDULED_CCA_LBT_TX
680 | RAIL_SCHEDULER_STATUS_SCHEDULE_FAIL),
681 /** \ref RAIL_StartScheduledCcaLbtTx() operation interrupted. */
682 RAIL_SCHEDULER_SCHEDULED_CCA_LBT_TX_INTERRUPTED = (RAIL_SCHEDULER_TASK_SCHEDULED_CCA_LBT_TX
683 | RAIL_SCHEDULER_STATUS_EVENT_INTERRUPTED),
684
685 /** Multiprotocol stream transmit function internal error. */
686 RAIL_SCHEDULER_TX_STREAM_INTERNAL_ERROR = (RAIL_SCHEDULER_TASK_TX_STREAM
687 | RAIL_SCHEDULER_STATUS_INTERNAL_ERROR),
688 /** Multiprotocol stream transmit scheduling error. */
689 RAIL_SCHEDULER_TX_STREAM_SCHEDULING_ERROR = (RAIL_SCHEDULER_TASK_TX_STREAM
690 | RAIL_SCHEDULER_STATUS_SCHEDULE_FAIL),
691 /** \ref RAIL_StartTxStream() operation interrupted. */
692 RAIL_SCHEDULER_TX_STREAM_INTERRUPTED = (RAIL_SCHEDULER_TASK_TX_STREAM
693 | RAIL_SCHEDULER_STATUS_EVENT_INTERRUPTED),
694
695 /** Multiprotocol RSSI averaging function internal error. */
696 RAIL_SCHEDULER_AVERAGE_RSSI_INTERNAL_ERROR = (RAIL_SCHEDULER_TASK_AVERAGE_RSSI
697 | RAIL_SCHEDULER_STATUS_INTERNAL_ERROR),
698 /** Multiprotocol RSSI average scheduling error. */
699 RAIL_SCHEDULER_AVERAGE_RSSI_SCHEDULING_ERROR = (RAIL_SCHEDULER_TASK_AVERAGE_RSSI
700 | RAIL_SCHEDULER_STATUS_SCHEDULE_FAIL),
701 /** \ref RAIL_StartAverageRssi() operation interrupted. */
702 RAIL_SCHEDULER_AVERAGE_RSSI_INTERRUPTED = (RAIL_SCHEDULER_TASK_AVERAGE_RSSI
703 | RAIL_SCHEDULER_STATUS_EVENT_INTERRUPTED),
704 };
705
706 #ifndef DOXYGEN_SHOULD_SKIP_THIS
707 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
708 #define RAIL_SCHEDULER_STATUS_NO_ERROR ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_STATUS_NO_ERROR)
709 #define RAIL_SCHEDULER_STATUS_UNSUPPORTED ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_STATUS_UNSUPPORTED)
710 #define RAIL_SCHEDULER_STATUS_EVENT_INTERRUPTED ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_STATUS_EVENT_INTERRUPTED)
711 #define RAIL_SCHEDULER_STATUS_SCHEDULE_FAIL ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_STATUS_SCHEDULE_FAIL)
712 #define RAIL_SCHEDULER_STATUS_SCHEDULED_TX_FAIL ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_STATUS_SCHEDULED_TX_FAIL)
713 #define RAIL_SCHEDULER_STATUS_SINGLE_TX_FAIL ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_STATUS_SINGLE_TX_FAIL)
714 #define RAIL_SCHEDULER_STATUS_CCA_CSMA_TX_FAIL ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_STATUS_CCA_CSMA_TX_FAIL)
715 #define RAIL_SCHEDULER_STATUS_CCA_LBT_TX_FAIL ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_STATUS_CCA_LBT_TX_FAIL)
716 #define RAIL_SCHEDULER_STATUS_SCHEDULED_RX_FAIL ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_STATUS_SCHEDULED_RX_FAIL)
717 #define RAIL_SCHEDULER_STATUS_TX_STREAM_FAIL ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_STATUS_TX_STREAM_FAIL)
718 #define RAIL_SCHEDULER_STATUS_AVERAGE_RSSI_FAIL ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_STATUS_AVERAGE_RSSI_FAIL)
719 #define RAIL_SCHEDULER_STATUS_INTERNAL_ERROR ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_STATUS_INTERNAL_ERROR)
720
721 #define RAIL_SCHEDULER_TASK_EMPTY ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_TASK_EMPTY)
722 #define RAIL_SCHEDULER_TASK_SCHEDULED_RX ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_TASK_SCHEDULED_RX)
723 #define RAIL_SCHEDULER_TASK_SCHEDULED_TX ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_SCHEDULED_TX)
724 #define RAIL_SCHEDULER_TASK_SINGLE_TX ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_TASK_SINGLE_TX)
725 #define RAIL_SCHEDULER_TASK_SINGLE_CCA_CSMA_TX ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_TASK_SINGLE_CCA_CSMA_TX)
726 #define RAIL_SCHEDULER_TASK_SINGLE_CCA_LBT_TX ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_TASK_SINGLE_CCA_LBT_TX)
727 #define RAIL_SCHEDULER_TASK_SCHEDULED_CCA_CSMA_TX ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_TASK_SCHEDULED_CCA_CSMA_TX)
728 #define RAIL_SCHEDULER_TASK_SCHEDULED_CCA_LBT_TX ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_TASK_SCHEDULED_CCA_LBT_TX)
729 #define RAIL_SCHEDULER_TASK_TX_STREAM ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_TASK_TX_STREAM)
730 #define RAIL_SCHEDULER_TASK_AVERAGE_RSSI ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_TASK_AVERAGE_RSSI)
731
732 #define RAIL_SCHEDULER_SCHEDULED_RX_INTERNAL_ERROR ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_SCHEDULED_RX_INTERNAL_ERROR)
733 #define RAIL_SCHEDULER_SCHEDULED_RX_SCHEDULING_ERROR ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_SCHEDULED_RX_SCHEDULING_ERROR)
734 #define RAIL_SCHEDULER_SCHEDULED_RX_INTERRUPTED ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_SCHEDULED_RX_INTERRUPTED)
735 #define RAIL_SCHEDULER_SCHEDULED_TX_INTERNAL_ERROR ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_SCHEDULED_TX_INTERNAL_ERROR)
736 #define RAIL_SCHEDULER_SCHEDULED_TX_SCHEDULING_ERROR ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_SCHEDULED_TX_SCHEDULING_ERROR)
737 #define RAIL_SCHEDULER_SCHEDULED_TX_INTERRUPTED ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_SCHEDULED_TX_INTERRUPTED)
738 #define RAIL_SCHEDULER_SINGLE_TX_INTERNAL_ERROR ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_SINGLE_TX_INTERNAL_ERROR)
739 #define RAIL_SCHEDULER_SINGLE_TX_SCHEDULING_ERROR ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_SINGLE_TX_SCHEDULING_ERROR)
740 #define RAIL_SCHEDULER_SINGLE_TX_INTERRUPTED ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_SINGLE_TX_INTERRUPTED)
741 #define RAIL_SCHEDULER_CCA_CSMA_TX_INTERNAL_ERROR ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_CCA_CSMA_TX_INTERNAL_ERROR)
742 #define RAIL_SCHEDULER_CCA_CSMA_TX_SCHEDULING_ERROR ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_CCA_CSMA_TX_SCHEDULING_ERROR)
743 #define RAIL_SCHEDULER_CCA_CSMA_TX_INTERRUPTED ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_CCA_CSMA_TX_INTERRUPTED)
744 #define RAIL_SCHEDULER_CCA_LBT_TX_INTERNAL_ERROR ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_CCA_LBT_TX_INTERNAL_ERROR)
745 #define RAIL_SCHEDULER_CCA_LBT_TX_SCHEDULING_ERROR ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_CCA_LBT_TX_SCHEDULING_ERROR)
746 #define RAIL_SCHEDULER_CCA_LBT_TX_INTERRUPTED ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_CCA_LBT_TX_INTERRUPTED)
747 #define RAIL_SCHEDULER_SCHEDULED_CCA_CSMA_TX_INTERNAL_ERROR ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_SCHEDULED_CCA_CSMA_TX_INTERNAL_ERROR)
748 #define RAIL_SCHEDULER_SCHEDULED_CCA_CSMA_TX_FAIL ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_SCHEDULED_CCA_CSMA_TX_FAIL)
749 #define RAIL_SCHEDULER_SCHEDULED_CCA_CSMA_TX_SCHEDULING_ERROR ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_SCHEDULED_CCA_CSMA_TX_SCHEDULING_ERROR)
750 #define RAIL_SCHEDULER_SCHEDULED_CCA_CSMA_TX_INTERRUPTED ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_SCHEDULED_CCA_CSMA_TX_INTERRUPTED)
751 #define RAIL_SCHEDULER_SCHEDULED_CCA_LBT_TX_INTERNAL_ERROR ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_SCHEDULED_CCA_LBT_TX_INTERNAL_ERROR)
752 #define RAIL_SCHEDULER_SCHEDULED_CCA_LBT_TX_FAIL ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_SCHEDULED_CCA_LBT_TX_FAIL)
753 #define RAIL_SCHEDULER_SCHEDULED_CCA_LBT_TX_SCHEDULING_ERROR ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_SCHEDULED_CCA_LBT_TX_SCHEDULING_ERROR)
754 #define RAIL_SCHEDULER_SCHEDULED_CCA_LBT_TX_INTERRUPTED ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_SCHEDULED_CCA_LBT_TX_INTERRUPTED)
755 #define RAIL_SCHEDULER_TX_STREAM_INTERNAL_ERROR ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_TX_STREAM_INTERNAL_ERROR)
756 #define RAIL_SCHEDULER_TX_STREAM_SCHEDULING_ERROR ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_TX_STREAM_SCHEDULING_ERROR)
757 #define RAIL_SCHEDULER_TX_STREAM_INTERRUPTED ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_TX_STREAM_INTERRUPTED)
758 #define RAIL_SCHEDULER_AVERAGE_RSSI_INTERNAL_ERROR ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_AVERAGE_RSSI_INTERNAL_ERROR)
759 #define RAIL_SCHEDULER_AVERAGE_RSSI_SCHEDULING_ERROR ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_AVERAGE_RSSI_SCHEDULING_ERROR)
760 #define RAIL_SCHEDULER_AVERAGE_RSSI_INTERRUPTED ((RAIL_SchedulerStatus_t) RAIL_SCHEDULER_AVERAGE_RSSI_INTERRUPTED)
761 #endif//DOXYGEN_SHOULD_SKIP_THIS
762
763 /**
764 * @enum RAIL_TaskType_t
765 * @brief Multiprotocol radio operation task types, used with
766 * \ref RAIL_SetTaskPriority().
767 */
RAIL_ENUM(RAIL_TaskType_t)768 RAIL_ENUM(RAIL_TaskType_t) {
769 /** Indicate a task started using \ref RAIL_StartRx(). */
770 RAIL_TASK_TYPE_START_RX = 0,
771 /** Indicate a task started functions other than \ref RAIL_StartRx(). */
772 RAIL_TASK_TYPE_OTHER = 1,
773 };
774
775 #ifndef DOXYGEN_SHOULD_SKIP_THIS
776 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
777 #define RAIL_TASK_TYPE_START_RX ((RAIL_TaskType_t) RAIL_TASK_TYPE_START_RX)
778 #define RAIL_TASK_TYPE_OTHER ((RAIL_TaskType_t) RAIL_TASK_TYPE_OTHER)
779 #endif//DOXYGEN_SHOULD_SKIP_THIS
780
781 /** @} */ // end of group Multiprotocol
782
783 /******************************************************************************
784 * Event Structures
785 *****************************************************************************/
786 /**
787 * @addtogroup Events
788 * @{
789 */
790
791 /**
792 * @enum RAIL_Events_t
793 * @brief RAIL events passed to the event callback. More than one event may be
794 * indicated due to interrupt latency.
795 */
RAIL_ENUM_GENERIC(RAIL_Events_t,uint64_t)796 RAIL_ENUM_GENERIC(RAIL_Events_t, uint64_t) {
797 // RX Event Bit Shifts
798
799 /** Shift position of \ref RAIL_EVENT_RSSI_AVERAGE_DONE bit. */
800 RAIL_EVENT_RSSI_AVERAGE_DONE_SHIFT = 0,
801 /** Shift position of \ref RAIL_EVENT_RX_ACK_TIMEOUT bit. */
802 RAIL_EVENT_RX_ACK_TIMEOUT_SHIFT = 1,
803 /** Shift position of \ref RAIL_EVENT_RX_FIFO_ALMOST_FULL bit. */
804 RAIL_EVENT_RX_FIFO_ALMOST_FULL_SHIFT = 2,
805 /** Shift position of \ref RAIL_EVENT_RX_PACKET_RECEIVED bit. */
806 RAIL_EVENT_RX_PACKET_RECEIVED_SHIFT = 3,
807 /** Shift position of \ref RAIL_EVENT_RX_PREAMBLE_LOST bit. */
808 RAIL_EVENT_RX_PREAMBLE_LOST_SHIFT = 4,
809 /** Shift position of \ref RAIL_EVENT_RX_PREAMBLE_DETECT bit. */
810 RAIL_EVENT_RX_PREAMBLE_DETECT_SHIFT = 5,
811 /** Shift position of \ref RAIL_EVENT_RX_SYNC1_DETECT bit. */
812 RAIL_EVENT_RX_SYNC1_DETECT_SHIFT = 6,
813 /** Shift position of \ref RAIL_EVENT_RX_SYNC2_DETECT bit. */
814 RAIL_EVENT_RX_SYNC2_DETECT_SHIFT = 7,
815 /** Shift position of \ref RAIL_EVENT_RX_FRAME_ERROR bit. */
816 RAIL_EVENT_RX_FRAME_ERROR_SHIFT = 8,
817 /** Shift position of \ref RAIL_EVENT_RX_FIFO_FULL bit. */
818 RAIL_EVENT_RX_FIFO_FULL_SHIFT = 9,
819 /** Shift position of \ref RAIL_EVENT_RX_FIFO_OVERFLOW bit. */
820 RAIL_EVENT_RX_FIFO_OVERFLOW_SHIFT = 10,
821 /** Shift position of \ref RAIL_EVENT_RX_ADDRESS_FILTERED bit. */
822 RAIL_EVENT_RX_ADDRESS_FILTERED_SHIFT = 11,
823 /** Shift position of \ref RAIL_EVENT_RX_TIMEOUT bit. */
824 RAIL_EVENT_RX_TIMEOUT_SHIFT = 12,
825 /** Shift position of \ref RAIL_EVENT_SCHEDULED_RX_STARTED bit. */
826 RAIL_EVENT_SCHEDULED_RX_STARTED_SHIFT = 13,
827 /** Shift position of \ref RAIL_EVENT_RX_SCHEDULED_RX_END bit. */
828 RAIL_EVENT_RX_SCHEDULED_RX_END_SHIFT = 14,
829 /** Shift position of \ref RAIL_EVENT_RX_SCHEDULED_RX_MISSED bit. */
830 RAIL_EVENT_RX_SCHEDULED_RX_MISSED_SHIFT = 15,
831 /** Shift position of \ref RAIL_EVENT_RX_PACKET_ABORTED bit. */
832 RAIL_EVENT_RX_PACKET_ABORTED_SHIFT = 16,
833 /** Shift position of \ref RAIL_EVENT_RX_FILTER_PASSED bit. */
834 RAIL_EVENT_RX_FILTER_PASSED_SHIFT = 17,
835 /** Shift position of \ref RAIL_EVENT_RX_TIMING_LOST bit. */
836 RAIL_EVENT_RX_TIMING_LOST_SHIFT = 18,
837 /** Shift position of \ref RAIL_EVENT_RX_TIMING_DETECT bit. */
838 RAIL_EVENT_RX_TIMING_DETECT_SHIFT = 19,
839 /** Shift position of \ref RAIL_EVENT_RX_CHANNEL_HOPPING_COMPLETE bit. */
840 RAIL_EVENT_RX_CHANNEL_HOPPING_COMPLETE_SHIFT = 20,
841 /** Shift position of \ref RAIL_EVENT_RX_DUTY_CYCLE_RX_END bit. */
842 RAIL_EVENT_RX_DUTY_CYCLE_RX_END_SHIFT = RAIL_EVENT_RX_CHANNEL_HOPPING_COMPLETE_SHIFT,
843 /** Shift position of \ref RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND bit. */
844 RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND_SHIFT = 21,
845 /** Shift position of \ref RAIL_EVENT_ZWAVE_LR_ACK_REQUEST_COMMAND_SHIFT bit. */
846 RAIL_EVENT_ZWAVE_LR_ACK_REQUEST_COMMAND_SHIFT = RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND_SHIFT,
847 /** Shift position of \ref RAIL_EVENT_MFM_TX_BUFFER_DONE bit. */
848 RAIL_EVENT_MFM_TX_BUFFER_DONE_SHIFT = RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND_SHIFT,
849
850 // TX Event Bit Shifts
851
852 /** Shift position of \ref RAIL_EVENT_ZWAVE_BEAM bit. */
853 RAIL_EVENT_ZWAVE_BEAM_SHIFT = 22,
854 /** Shift position of \ref RAIL_EVENT_TX_FIFO_ALMOST_EMPTY bit. */
855 RAIL_EVENT_TX_FIFO_ALMOST_EMPTY_SHIFT = 23,
856 /** Shift position of \ref RAIL_EVENT_TX_PACKET_SENT bit. */
857 RAIL_EVENT_TX_PACKET_SENT_SHIFT = 24,
858 /** Shift position of \ref RAIL_EVENT_TXACK_PACKET_SENT bit. */
859 RAIL_EVENT_TXACK_PACKET_SENT_SHIFT = 25,
860 /** Shift position of \ref RAIL_EVENT_TX_ABORTED bit. */
861 RAIL_EVENT_TX_ABORTED_SHIFT = 26,
862 /** Shift position of \ref RAIL_EVENT_TXACK_ABORTED bit. */
863 RAIL_EVENT_TXACK_ABORTED_SHIFT = 27,
864 /** Shift position of \ref RAIL_EVENT_TX_BLOCKED bit. */
865 RAIL_EVENT_TX_BLOCKED_SHIFT = 28,
866 /** Shift position of \ref RAIL_EVENT_TXACK_BLOCKED bit. */
867 RAIL_EVENT_TXACK_BLOCKED_SHIFT = 29,
868 /** Shift position of \ref RAIL_EVENT_TX_UNDERFLOW bit. */
869 RAIL_EVENT_TX_UNDERFLOW_SHIFT = 30,
870 /** Shift position of \ref RAIL_EVENT_TXACK_UNDERFLOW bit. */
871 RAIL_EVENT_TXACK_UNDERFLOW_SHIFT = 31,
872 /** Shift position of \ref RAIL_EVENT_TX_CHANNEL_CLEAR bit. */
873 RAIL_EVENT_TX_CHANNEL_CLEAR_SHIFT = 32,
874 /** Shift position of \ref RAIL_EVENT_TX_CHANNEL_BUSY bit. */
875 RAIL_EVENT_TX_CHANNEL_BUSY_SHIFT = 33,
876 /** Shift position of \ref RAIL_EVENT_TX_CCA_RETRY bit. */
877 RAIL_EVENT_TX_CCA_RETRY_SHIFT = 34,
878 /** Shift position of \ref RAIL_EVENT_TX_START_CCA bit. */
879 RAIL_EVENT_TX_START_CCA_SHIFT = 35,
880 /** Shift position of \ref RAIL_EVENT_TX_STARTED bit. */
881 RAIL_EVENT_TX_STARTED_SHIFT = 36,
882 /** Shift position of \ref RAIL_EVENT_SCHEDULED_TX_STARTED bit. */
883 RAIL_EVENT_SCHEDULED_TX_STARTED_SHIFT = RAIL_EVENT_SCHEDULED_RX_STARTED_SHIFT,
884 /** Shift position of \ref RAIL_EVENT_TX_SCHEDULED_TX_MISSED bit. */
885 RAIL_EVENT_TX_SCHEDULED_TX_MISSED_SHIFT = 37,
886
887 // Scheduler Event Bit Shifts
888
889 /** Shift position of \ref RAIL_EVENT_CONFIG_UNSCHEDULED bit. */
890 RAIL_EVENT_CONFIG_UNSCHEDULED_SHIFT = 38,
891 /** Shift position of \ref RAIL_EVENT_CONFIG_SCHEDULED bit. */
892 RAIL_EVENT_CONFIG_SCHEDULED_SHIFT = 39,
893 /** Shift position of \ref RAIL_EVENT_SCHEDULER_STATUS bit. */
894 RAIL_EVENT_SCHEDULER_STATUS_SHIFT = 40,
895
896 // Other Event Bit Shifts
897
898 /** Shift position of \ref RAIL_EVENT_CAL_NEEDED bit. */
899 RAIL_EVENT_CAL_NEEDED_SHIFT = 41,
900 /** Shift position of \ref RAIL_EVENT_RF_SENSED bit. */
901 RAIL_EVENT_RF_SENSED_SHIFT = 42,
902 /** Shift position of \ref RAIL_EVENT_PA_PROTECTION bit. */
903 RAIL_EVENT_PA_PROTECTION_SHIFT = 43,
904 /** Shift position of \ref RAIL_EVENT_SIGNAL_DETECTED bit. */
905 RAIL_EVENT_SIGNAL_DETECTED_SHIFT = 44,
906 /** Shift position of \ref RAIL_EVENT_IEEE802154_MODESWITCH_START bit. */
907 RAIL_EVENT_IEEE802154_MODESWITCH_START_SHIFT = 45,
908 /** Shift position of \ref RAIL_EVENT_IEEE802154_MODESWITCH_END bit. */
909 RAIL_EVENT_IEEE802154_MODESWITCH_END_SHIFT = 46,
910 /** Shift position of \ref RAIL_EVENT_DETECT_RSSI_THRESHOLD bit. */
911 RAIL_EVENT_DETECT_RSSI_THRESHOLD_SHIFT = 47,
912 /** Shift position of \ref RAIL_EVENT_THERMISTOR_DONE bit. */
913 RAIL_EVENT_THERMISTOR_DONE_SHIFT = 48,
914 /** Shift position of \ref RAIL_EVENT_TX_BLOCKED_TOO_HOT bit. */
915 RAIL_EVENT_TX_BLOCKED_TOO_HOT_SHIFT = 49,
916 /** Shift position of \ref RAIL_EVENT_TEMPERATURE_TOO_HOT bit. */
917 RAIL_EVENT_TEMPERATURE_TOO_HOT_SHIFT = 50,
918 /** Shift position of \ref RAIL_EVENT_TEMPERATURE_COOL_DOWN bit. */
919 RAIL_EVENT_TEMPERATURE_COOL_DOWN_SHIFT = 51,
920 /** Shift position of \ref RAIL_EVENT_USER_MBOX bit. */
921 RAIL_EVENT_USER_MBOX_SHIFT = 52,
922 };
923
924 // RAIL_Event_t bitmasks
925
926 /** A value representing no events. */
927 #define RAIL_EVENTS_NONE 0ULL
928
929 /**
930 * Occurs when the hardware-averaged RSSI is done in response to
931 * \ref RAIL_StartAverageRssi() to indicate that the hardware has completed
932 * averaging.
933 *
934 * Call \ref RAIL_GetAverageRssi() to get the result.
935 */
936 #define RAIL_EVENT_RSSI_AVERAGE_DONE (1ULL << RAIL_EVENT_RSSI_AVERAGE_DONE_SHIFT)
937
938 /**
939 * Occurs when the Ack timeout expires while waiting to receive the
940 * sync word of an expected Ack. If the timeout occurs within packet
941 * reception, this event won't be signaled until after packet
942 * completion has determined the packet wasn't the expected Ack.
943 * See \ref RAIL_RxPacketDetails_t::isAck for the definition of an
944 * expected Ack.
945 *
946 * This event only occurs after calling \ref RAIL_ConfigAutoAck() and after
947 * transmitting a packet with \ref RAIL_TX_OPTION_WAIT_FOR_ACK set.
948 */
949 #define RAIL_EVENT_RX_ACK_TIMEOUT (1ULL << RAIL_EVENT_RX_ACK_TIMEOUT_SHIFT)
950
951 /**
952 * Keeps occurring as long as the number of bytes in the receive FIFO
953 * exceeds the configured threshold value.
954 *
955 * Call \ref RAIL_GetRxFifoBytesAvailable() to get the number of
956 * bytes available. When using this event, the threshold should be set via
957 * \ref RAIL_SetRxFifoThreshold().
958 *
959 * How to avoid sticking in the event handler (even in idle state):
960 * 1. Disable the event (via the config events API or the
961 * \ref RAIL_FIFO_THRESHOLD_DISABLED parameter)
962 * 2. Increase FIFO threshold
963 * 3. Read the FIFO (that's not an option in
964 * \ref RAIL_DataMethod_t::PACKET_MODE) in the event handler
965 */
966 #define RAIL_EVENT_RX_FIFO_ALMOST_FULL (1ULL << RAIL_EVENT_RX_FIFO_ALMOST_FULL_SHIFT)
967
968 /**
969 * Occurs whenever a packet is received with \ref RAIL_RX_PACKET_READY_SUCCESS
970 * or \ref RAIL_RX_PACKET_READY_CRC_ERROR.
971 *
972 * Call \ref RAIL_GetRxPacketInfo() to get
973 * basic information about the packet along with a handle to this packet for
974 * subsequent use with \ref RAIL_PeekRxPacket(), \ref RAIL_GetRxPacketDetails(),
975 * \ref RAIL_HoldRxPacket(), and \ref RAIL_ReleaseRxPacket() as needed.
976 */
977 #define RAIL_EVENT_RX_PACKET_RECEIVED (1ULL << RAIL_EVENT_RX_PACKET_RECEIVED_SHIFT)
978
979 /**
980 * Occurs when the radio has lost a preamble.
981 *
982 * This event can occur multiple
983 * times while searching for a packet and is generally used for diagnostic
984 * purposes. It can only occur after a
985 * \ref RAIL_EVENT_RX_PREAMBLE_DETECT event has already occurred.
986 *
987 * @note See warning for \ref RAIL_EVENT_RX_PREAMBLE_DETECT.
988 */
989 #define RAIL_EVENT_RX_PREAMBLE_LOST (1ULL << RAIL_EVENT_RX_PREAMBLE_LOST_SHIFT)
990
991 /**
992 * Occurs when the radio has detected a preamble.
993 *
994 * This event can occur multiple
995 * times while searching for a packet and is generally used for diagnostic
996 * purposes. It can only occur after a \ref RAIL_EVENT_RX_TIMING_DETECT
997 * event has already occurred.
998 *
999 * @warning This event, along with \ref RAIL_EVENT_RX_PREAMBLE_LOST,
1000 * may not work on some demodulators. Some demodulators usurped the signals
1001 * on which these events are based for another purpose. These demodulators
1002 * in particular are available on the EFR32xG23, EFR32xG25, and the EFR32xG28
1003 * platforms. Enabling these events on these platforms may cause the
1004 * events to fire infinitely and possibly freeze the application.
1005 */
1006 #define RAIL_EVENT_RX_PREAMBLE_DETECT (1ULL << RAIL_EVENT_RX_PREAMBLE_DETECT_SHIFT)
1007
1008 /**
1009 * Occurs when the first sync word is detected.
1010 *
1011 * After this event occurs, one of
1012 * the events in the \ref RAIL_EVENTS_RX_COMPLETION mask will occur.
1013 */
1014 #define RAIL_EVENT_RX_SYNC1_DETECT (1ULL << RAIL_EVENT_RX_SYNC1_DETECT_SHIFT)
1015
1016 /**
1017 * Occurs when the second sync word is detected.
1018 *
1019 * After this event occurs, one of
1020 * the events in the \ref RAIL_EVENTS_RX_COMPLETION mask will occur.
1021 */
1022 #define RAIL_EVENT_RX_SYNC2_DETECT (1ULL << RAIL_EVENT_RX_SYNC2_DETECT_SHIFT)
1023
1024 /**
1025 * Occurs when a receive is aborted with \ref RAIL_RX_PACKET_ABORT_CRC_ERROR
1026 * which only happens after any filtering has passed.
1027 *
1028 * For EFR32 parts, this event includes CRC errors, block decoding errors,
1029 * and illegal frame length -- when detected after filtering. (When such
1030 * errors are detected during filtering, they're signaled as \ref
1031 * RAIL_EVENT_RX_PACKET_ABORTED instead.)
1032 *
1033 * If \ref RAIL_RX_OPTION_IGNORE_CRC_ERRORS is set, this event will not
1034 * occur for CRC errors, but could still occur for the other errors.
1035 */
1036 #define RAIL_EVENT_RX_FRAME_ERROR (1ULL << RAIL_EVENT_RX_FRAME_ERROR_SHIFT)
1037
1038 /**
1039 * When using \ref RAIL_RxDataSource_t::RX_PACKET_DATA this event
1040 * occurs coincident to a receive packet completion event in which the
1041 * receive FIFO or any supplemental packet metadata FIFO (see \ref
1042 * Data_Management) are full and further packet reception is jeopardized.
1043 *
1044 * It signals that an overflow is imminent (and may already have occurred)
1045 * telling the application it should release the oldest packet(s) as soon
1046 * as possible. This event may may be posted multiple times with subsequent
1047 * receive completion events if the FIFO(s) remain full, and should also
1048 * occur coincident with \ref RAIL_EVENT_RX_FIFO_OVERFLOW.
1049 *
1050 * When not using \ref RAIL_RxDataSource_t::RX_PACKET_DATA this event
1051 * is not tied to packet completion and will occur coincident with
1052 * \ref RAIL_EVENT_RX_FIFO_OVERFLOW when the receive FIFO has filled and
1053 * overflowed. The application should consume receive FIFO data via
1054 * \ref RAIL_ReadRxFifo() as soon as possible to minimize lost raw data.
1055 */
1056 #define RAIL_EVENT_RX_FIFO_FULL (1ULL << RAIL_EVENT_RX_FIFO_FULL_SHIFT)
1057
1058 /**
1059 * When using \ref RAIL_RxDataSource_t::RX_PACKET_DATA this event
1060 * occurs when a receive is aborted with \ref RAIL_RX_PACKET_ABORT_OVERFLOW
1061 * due to overflowing the receive FIFO or any supplemental packet metadata
1062 * FIFO (see \ref Data_Management).
1063 *
1064 * The radio suspends receiving packets until this event is posted and
1065 * the receive FIFO(s) have been fully processed (drained and released
1066 * or reset). It is not guaranteed that a \ref RAIL_EVENT_RX_FIFO_FULL
1067 * will precede this event, but both events should be coincident.
1068 *
1069 * When not using \ref RAIL_RxDataSource_t::RX_PACKET_DATA this event
1070 * is not tied to packet completion and will occur coincident with
1071 * \ref RAIL_EVENT_RX_FIFO_FULL when the receive FIFO has filled and
1072 * overflowed. The application should consume receive FIFO data via
1073 * \ref RAIL_ReadRxFifo() as soon as possible to minimize lost raw data.
1074 */
1075 #define RAIL_EVENT_RX_FIFO_OVERFLOW (1ULL << RAIL_EVENT_RX_FIFO_OVERFLOW_SHIFT)
1076
1077 /**
1078 * Occurs when a receive is aborted with \ref RAIL_RX_PACKET_ABORT_FILTERED
1079 * because its address does not match the filtering settings.
1080 *
1081 * This event can only occur after calling \ref RAIL_EnableAddressFilter().
1082 */
1083 #define RAIL_EVENT_RX_ADDRESS_FILTERED (1ULL << RAIL_EVENT_RX_ADDRESS_FILTERED_SHIFT)
1084
1085 /**
1086 * Occurs when an RX event times out.
1087 *
1088 * This event can only occur if the
1089 * RAIL_StateTiming_t::rxSearchTimeout passed to \ref RAIL_SetStateTiming() is
1090 * not zero.
1091 */
1092 #define RAIL_EVENT_RX_TIMEOUT (1ULL << RAIL_EVENT_RX_TIMEOUT_SHIFT)
1093
1094 /**
1095 * Occurs when a scheduled RX begins turning on the receiver.
1096 * This event has the same numerical value as \ref RAIL_EVENT_SCHEDULED_TX_STARTED
1097 * because one cannot schedule both RX and TX simultaneously.
1098 */
1099 #define RAIL_EVENT_SCHEDULED_RX_STARTED (1ULL << RAIL_EVENT_SCHEDULED_RX_STARTED_SHIFT)
1100
1101 /**
1102 * Occurs when the scheduled RX window ends.
1103 *
1104 * This event only occurs in response
1105 * to a scheduled receive timeout after calling \ref RAIL_ScheduleRx(). If
1106 * RAIL_ScheduleRxConfig_t::rxTransitionEndSchedule was passed as false,
1107 * this event will occur unless the receive is aborted (due to a call to
1108 * \ref RAIL_Idle() or a scheduler preemption, for instance). If
1109 * RAIL_ScheduleRxConfig_t::rxTransitionEndSchedule was passed as true,
1110 * any of the \ref RAIL_EVENTS_RX_COMPLETION events occurring will also cause
1111 * this event not to occur, since the scheduled receive will end with the
1112 * transition at the end of the packet. However, if the application has not
1113 * enabled the specific \ref RAIL_EVENTS_RX_COMPLETION event which implicitly
1114 * ended the scheduled receive, this event will be posted instead.
1115 */
1116 #define RAIL_EVENT_RX_SCHEDULED_RX_END (1ULL << RAIL_EVENT_RX_SCHEDULED_RX_END_SHIFT)
1117
1118 /**
1119 * Occurs when start of a scheduled receive is missed.
1120 *
1121 * This can occur if the radio is put to sleep and not woken up with enough time
1122 * to configure the scheduled receive event.
1123 */
1124 #define RAIL_EVENT_RX_SCHEDULED_RX_MISSED (1ULL << RAIL_EVENT_RX_SCHEDULED_RX_MISSED_SHIFT)
1125
1126 /**
1127 * Occurs when a receive is aborted during filtering with
1128 * \ref RAIL_RX_PACKET_ABORT_FORMAT or after filtering with
1129 * \ref RAIL_RX_PACKET_ABORT_ABORTED for reasons other than address
1130 * filtering mismatch (which triggers \ref RAIL_EVENT_RX_ADDRESS_FILTERED
1131 * instead).
1132 *
1133 * For EFR32 parts, this event includes CRC errors, block decoding errors,
1134 * illegal frame length, and other RAIL built-in protocol-specific packet
1135 * content errors -- when detected during filtering. (When such errors
1136 * are detected after filtering, they're signaled as \ref
1137 * RAIL_EVENT_RX_FRAME_ERROR instead.) It also includes application or
1138 * multiprotocol scheduler aborting a receive after filtering has passed.
1139 */
1140 #define RAIL_EVENT_RX_PACKET_ABORTED (1ULL << RAIL_EVENT_RX_PACKET_ABORTED_SHIFT)
1141
1142 /**
1143 * Occurs when the packet has passed any configured address and frame
1144 * filtering options.
1145 *
1146 * This event will only occur between the start of the
1147 * packet, indicated by \ref RAIL_EVENT_RX_SYNC1_DETECT or
1148 * \ref RAIL_EVENT_RX_SYNC2_DETECT and one of the events in the
1149 * \ref RAIL_EVENTS_RX_COMPLETION mask. It will always occur before or
1150 * concurrently with \ref RAIL_EVENT_RX_PACKET_RECEIVED. If IEEE 802.15.4 frame
1151 * and address filtering are enabled, this event will occur immediately after
1152 * destination address filtering.
1153 */
1154 #define RAIL_EVENT_RX_FILTER_PASSED (1ULL << RAIL_EVENT_RX_FILTER_PASSED_SHIFT)
1155
1156 /**
1157 * Occurs when the modem timing is lost.
1158 *
1159 * This event can occur multiple times
1160 * while searching for a packet and is generally used for diagnostic purposes.
1161 * It can only occur after a \ref RAIL_EVENT_RX_TIMING_DETECT event has
1162 * already occurred.
1163 *
1164 * @note See warning for \ref RAIL_EVENT_RX_TIMING_DETECT.
1165 */
1166 #define RAIL_EVENT_RX_TIMING_LOST (1ULL << RAIL_EVENT_RX_TIMING_LOST_SHIFT)
1167
1168 /**
1169 * Occurs when the modem timing is detected.
1170 *
1171 * This event can occur multiple times
1172 * while searching for a packet and is generally used for diagnostic purposes.
1173 *
1174 * @warning This event, along with \ref RAIL_EVENT_RX_TIMING_LOST,
1175 * may not work on some demodulators. Some demodulators usurped the signals
1176 * on which these events are based for another purpose. These demodulators
1177 * in particular are available on the EFR32xG23, EFR32xG25, and the EFR32xG28
1178 * platforms. Enabling these events on these platforms may cause the
1179 * events to fire infinitely and possibly freeze the application.
1180 */
1181 #define RAIL_EVENT_RX_TIMING_DETECT (1ULL << RAIL_EVENT_RX_TIMING_DETECT_SHIFT)
1182
1183 /**
1184 * Occurs when RX Channel Hopping is enabled and channel hopping finishes
1185 * receiving on the last channel in its sequence.
1186 *
1187 * The intent behind this event
1188 * is to allow the user to keep the radio on for as short a time as possible.
1189 * That is, once the channel sequence is complete, the application will receive
1190 * this event and can trigger a sleep/idle until it is necessary to cycle
1191 * through the channels again. If this event is left on indefinitely and not
1192 * handled it will likely be a fairly noisy event, as it continues to fire
1193 * each time the hopping algorithm cycles through the channel sequence.
1194 *
1195 * @warning This event currently does not occur when using \ref
1196 * RAIL_RxChannelHoppingMode_t::RAIL_RX_CHANNEL_HOPPING_MODE_MANUAL.
1197 * As a workaround, an application can monitor the current hop channel
1198 * with \ref RAIL_GetChannelAlt().
1199 */
1200 #define RAIL_EVENT_RX_CHANNEL_HOPPING_COMPLETE (1ULL << RAIL_EVENT_RX_CHANNEL_HOPPING_COMPLETE_SHIFT)
1201
1202 /**
1203 * Occurs during RX duty cycle mode when the radio finishes its time in
1204 * receive mode.
1205 *
1206 * The application can then trigger a sleep/idle until it
1207 * needs to listen again.
1208 */
1209 #define RAIL_EVENT_RX_DUTY_CYCLE_RX_END (1ULL << RAIL_EVENT_RX_DUTY_CYCLE_RX_END_SHIFT)
1210
1211 /**
1212 * Indicate a Data Request is received when using IEEE 802.15.4
1213 * functionality.
1214 *
1215 * It occurs when the command byte of an incoming Ack-requesting MAC Control
1216 * frame is for a data request. This callback is called before
1217 * the packet is fully received to allow the node to have more time to decide
1218 * whether to indicate a frame is pending in the outgoing Ack. This event only
1219 * occurs if the RAIL IEEE 802.15.4 functionality is enabled, but will never
1220 * occur if promiscuous mode is enabled via \ref
1221 * RAIL_IEEE802154_SetPromiscuousMode().
1222 *
1223 * Call \ref RAIL_IEEE802154_GetAddress() to get the source address of the packet.
1224 */
1225 #define RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND (1ULL << RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND_SHIFT)
1226
1227 /**
1228 * Indicate a Z-Wave Beam Request relevant to the node was received.
1229 *
1230 * This event only occurs if the RAIL Z-Wave functionality is enabled
1231 * and its \ref RAIL_ZWAVE_OPTION_DETECT_BEAM_FRAMES is enabled.
1232 * This event is used in lieu of \ref RAIL_EVENT_RX_PACKET_RECEIVED,
1233 * which is reserved for Z-Wave packets other than Beams.
1234 *
1235 * Call \ref RAIL_ZWAVE_GetBeamNodeId() to get the Node Id to which the Beam was
1236 * targeted, which would be either the broadcast id 0xFF or the node's own
1237 * single-cast id.
1238 *
1239 * @note All Z-Wave Beam requests are generally discarded, triggering
1240 * \ref RAIL_EVENT_RX_PACKET_ABORTED.
1241 */
1242 #define RAIL_EVENT_ZWAVE_BEAM (1ULL << RAIL_EVENT_ZWAVE_BEAM_SHIFT)
1243
1244 /**
1245 * Indicate a MFM buffer has completely transmitted.
1246 *
1247 * This event only occurs if the RAIL MFM functionality is enabled
1248 * and a MFM buffer has completely transmitted.
1249 *
1250 * Following this event, the application can update the MFM buffer
1251 * that has transmitted to be used for the next transmission.
1252 */
1253 #define RAIL_EVENT_MFM_TX_BUFFER_DONE (1ULL << RAIL_EVENT_MFM_TX_BUFFER_DONE_SHIFT)
1254
1255 /**
1256 * Indicate a request for populating Z-Wave LR Ack packet.
1257 * This event only occurs if the RAIL Z-Wave functionality is enabled.
1258 *
1259 * Following this event, the application must call \ref RAIL_ZWAVE_SetLrAckData()
1260 * to populate noise floor, TX power and receive RSSI fields of the Z-Wave
1261 * Long Range Ack packet.
1262 */
1263 #define RAIL_EVENT_ZWAVE_LR_ACK_REQUEST_COMMAND (1ULL << RAIL_EVENT_ZWAVE_LR_ACK_REQUEST_COMMAND_SHIFT)
1264
1265 /**
1266 * The mask representing all events that determine the end of a received
1267 * packet.
1268 *
1269 * After a \ref RAIL_EVENT_RX_SYNC1_DETECT or a
1270 * \ref RAIL_EVENT_RX_SYNC2_DETECT,
1271 * exactly one of the following events will occur. When one of these events
1272 * occurs, a state transition will take place based on the parameter passed to
1273 * \ref RAIL_SetRxTransitions(). The \ref RAIL_StateTransitions_t::success transition
1274 * will be followed only if the \ref RAIL_EVENT_RX_PACKET_RECEIVED event occurs.
1275 * Any of the other events will trigger the \ref RAIL_StateTransitions_t::error
1276 * transition.
1277 */
1278 #define RAIL_EVENTS_RX_COMPLETION (RAIL_EVENT_RX_PACKET_RECEIVED \
1279 | RAIL_EVENT_RX_PACKET_ABORTED \
1280 | RAIL_EVENT_RX_FRAME_ERROR \
1281 | RAIL_EVENT_RX_FIFO_OVERFLOW \
1282 | RAIL_EVENT_RX_ADDRESS_FILTERED \
1283 | RAIL_EVENT_RX_SCHEDULED_RX_MISSED)
1284
1285 // TX Event Bitmasks
1286
1287 /**
1288 * Occurs when the number of bytes in the transmit FIFO falls below the
1289 * configured threshold value.
1290 *
1291 * This event does not occur on initialization or after resetting the transmit
1292 * FIFO with \ref RAIL_ResetFifo().
1293 *
1294 * Call \ref RAIL_GetTxFifoSpaceAvailable() to get the
1295 * number of bytes available in the transmit FIFO at the time of the callback
1296 * dispatch. When using this event, the threshold should be set via \ref
1297 * RAIL_SetTxFifoThreshold().
1298 */
1299 #define RAIL_EVENT_TX_FIFO_ALMOST_EMPTY (1ULL << RAIL_EVENT_TX_FIFO_ALMOST_EMPTY_SHIFT)
1300
1301 /**
1302 * Occurs after a packet has been transmitted.
1303 *
1304 * Call \ref RAIL_GetTxPacketDetails()
1305 * to get information about the packet that was transmitted.
1306 *
1307 * @note \ref RAIL_GetTxPacketDetails() is only valid to call during the time frame
1308 * of the \ref RAIL_Config_t::eventsCallback.
1309 */
1310 #define RAIL_EVENT_TX_PACKET_SENT (1ULL << RAIL_EVENT_TX_PACKET_SENT_SHIFT)
1311
1312 /**
1313 * Occurs after an Ack packet has been transmitted.
1314 *
1315 * Call \ref RAIL_GetTxPacketDetails()
1316 * to get information about the packet that was transmitted. This event can only occur
1317 * after calling \ref RAIL_ConfigAutoAck().
1318 *
1319 * @note \ref RAIL_GetTxPacketDetails() is only valid to call during the time frame
1320 * of the \ref RAIL_Config_t::eventsCallback.
1321 */
1322 #define RAIL_EVENT_TXACK_PACKET_SENT (1ULL << RAIL_EVENT_TXACK_PACKET_SENT_SHIFT)
1323
1324 /**
1325 * Occurs when a transmit is aborted by the user.
1326 *
1327 * This can happen due to calling \ref RAIL_Idle() or due to a scheduler
1328 * preemption.
1329 *
1330 * @note The Transmit FIFO is left in an indeterminate state and should be
1331 * reset prior to reuse for sending a new packet. Contrast this
1332 * with \ref RAIL_EVENT_TX_BLOCKED.
1333 */
1334 #define RAIL_EVENT_TX_ABORTED (1ULL << RAIL_EVENT_TX_ABORTED_SHIFT)
1335
1336 /**
1337 * Occurs when an Ack transmit is aborted by the user.
1338 *
1339 * This event can only
1340 * occur after calling \ref RAIL_ConfigAutoAck(), which can happen due to calling
1341 * \ref RAIL_Idle() or due to a scheduler preemption.
1342 */
1343 #define RAIL_EVENT_TXACK_ABORTED (1ULL << RAIL_EVENT_TXACK_ABORTED_SHIFT)
1344
1345 /**
1346 * Occurs when a transmit is blocked from occurring because
1347 * \ref RAIL_EnableTxHoldOff() was called.
1348 *
1349 * @note Since the transmit never started, the Transmit FIFO remains intact
1350 * after this event -- no packet data was consumed from it. Contrast this
1351 * with \ref RAIL_EVENT_TX_ABORTED.
1352 */
1353 #define RAIL_EVENT_TX_BLOCKED (1ULL << RAIL_EVENT_TX_BLOCKED_SHIFT)
1354
1355 /**
1356 * Occurs when an Ack transmit is blocked from occurring because
1357 * \ref RAIL_EnableTxHoldOff() was called.
1358 *
1359 * This event can only occur after calling \ref RAIL_ConfigAutoAck().
1360 */
1361 #define RAIL_EVENT_TXACK_BLOCKED (1ULL << RAIL_EVENT_TXACK_BLOCKED_SHIFT)
1362
1363 /**
1364 * Occurs when the transmit buffer underflows.
1365 *
1366 * This can happen due to the
1367 * transmitted packet specifying an unintended length based on the current
1368 * radio configuration or due to \ref RAIL_WriteTxFifo() calls not keeping up with
1369 * the transmit rate if the entire packet isn't loaded at once.
1370 *
1371 * @note The Transmit FIFO is left in an indeterminate state and should be
1372 * reset prior to reuse for sending a new packet. Contrast this
1373 * with \ref RAIL_EVENT_TX_BLOCKED.
1374 */
1375 #define RAIL_EVENT_TX_UNDERFLOW (1ULL << RAIL_EVENT_TX_UNDERFLOW_SHIFT)
1376
1377 /**
1378 * Occurs when the Ack transmit buffer underflows.
1379 *
1380 * This can happen due to the
1381 * transmitted packet specifying an unintended length based on the current
1382 * radio configuration or due to \ref RAIL_WriteAutoAckFifo() not being called at
1383 * all before an Ack transmit.
1384 *
1385 * This event can only occur after calling \ref RAIL_ConfigAutoAck().
1386 */
1387 #define RAIL_EVENT_TXACK_UNDERFLOW (1ULL << RAIL_EVENT_TXACK_UNDERFLOW_SHIFT)
1388
1389 /**
1390 * Occurs when Carrier Sense Multiple Access (CSMA) or Listen Before Talk (LBT)
1391 * succeeds.
1392 *
1393 * This event can only happen after calling \ref RAIL_StartCcaCsmaTx() or
1394 * \ref RAIL_StartCcaLbtTx() or their scheduled equivalent.
1395 */
1396 #define RAIL_EVENT_TX_CHANNEL_CLEAR (1ULL << RAIL_EVENT_TX_CHANNEL_CLEAR_SHIFT)
1397
1398 /**
1399 * Occurs when Carrier Sense Multiple Access (CSMA) or Listen Before Talk (LBT)
1400 * fails.
1401 *
1402 * This event can only happen after calling \ref RAIL_StartCcaCsmaTx() or
1403 * \ref RAIL_StartCcaLbtTx() or their scheduled equivalent.
1404 *
1405 * @note Since the transmit never started, the Transmit FIFO remains intact
1406 * after this event -- no packet data was consumed from it.
1407 */
1408 #define RAIL_EVENT_TX_CHANNEL_BUSY (1ULL << RAIL_EVENT_TX_CHANNEL_BUSY_SHIFT)
1409
1410 /**
1411 * Occurs during CSMA or LBT when an individual Clear Channel Assessment (CCA)
1412 * check fails, but there are more tries needed before the overall operation
1413 * completes.
1414 *
1415 * This event can occur multiple times based on the configuration
1416 * of the ongoing CSMA or LBT transmission. It can only happen after
1417 * calling \ref RAIL_StartCcaCsmaTx() or \ref RAIL_StartCcaLbtTx()
1418 * or their scheduled equivalent.
1419 */
1420 #define RAIL_EVENT_TX_CCA_RETRY (1ULL << RAIL_EVENT_TX_CCA_RETRY_SHIFT)
1421
1422 /**
1423 * Occurs when the receiver is activated to perform a Clear Channel Assessment
1424 * (CCA) check.
1425 *
1426 * This event generally precedes the actual start of a CCA check by roughly
1427 * the \ref RAIL_StateTiming_t::idleToRx time (subject to
1428 * \ref RAIL_MINIMUM_TRANSITION_US). It can
1429 * occur multiple times based on the configuration of the ongoing CSMA or LBT
1430 * transmission. It can only happen after calling \ref RAIL_StartCcaCsmaTx()
1431 * or \ref RAIL_StartCcaLbtTx() or their scheduled equivalent.
1432 */
1433 #define RAIL_EVENT_TX_START_CCA (1ULL << RAIL_EVENT_TX_START_CCA_SHIFT)
1434
1435 /**
1436 * Occurs when the radio starts transmitting a normal packet on the air.
1437 *
1438 * A start-of-transmit timestamp is captured for this event. It can be
1439 * retrieved by calling \ref RAIL_GetTxTimePreambleStart() passing \ref
1440 * RAIL_TX_STARTED_BYTES for its totalPacketBytes parameter.
1441 *
1442 * @note This event does not apply to Ack transmits. Currently there
1443 * is no equivalent event or timestamp captured for the start of an
1444 * Ack transmit.
1445 */
1446 #define RAIL_EVENT_TX_STARTED (1ULL << RAIL_EVENT_TX_STARTED_SHIFT)
1447
1448 /**
1449 * A value to pass as \ref RAIL_GetTxTimePreambleStart() totalPacketBytes
1450 * parameter to retrieve the \ref RAIL_EVENT_TX_STARTED timestamp.
1451 */
1452 #define RAIL_TX_STARTED_BYTES 0U
1453
1454 /**
1455 * Occurs when a scheduled TX begins turning on the transmitter.
1456 * This event has the same numerical value as \ref RAIL_EVENT_SCHEDULED_RX_STARTED
1457 * because one cannot schedule both RX and TX simultaneously.
1458 */
1459 #define RAIL_EVENT_SCHEDULED_TX_STARTED (1ULL << RAIL_EVENT_SCHEDULED_TX_STARTED_SHIFT)
1460
1461 /**
1462 * Occurs when the start of a scheduled transmit is missed
1463 *
1464 * This can occur if the radio is put to sleep and not woken up with enough time
1465 * to configure the scheduled transmit event.
1466 *
1467 * @note Since the transmit never started, the Transmit FIFO remains intact
1468 * after this event -- no packet data was consumed from it.
1469 */
1470 #define RAIL_EVENT_TX_SCHEDULED_TX_MISSED (1ULL << RAIL_EVENT_TX_SCHEDULED_TX_MISSED_SHIFT)
1471
1472 /**
1473 * A mask representing all events that determine the end of a transmitted
1474 * packet. After a \ref RAIL_STATUS_NO_ERROR return value
1475 * from one of the transmit functions, exactly one of the following
1476 * events will occur. When one of these events occurs, a state transition
1477 * takes place based on the parameter passed to \ref RAIL_SetTxTransitions().
1478 * The RAIL_StateTransitions_t::success transition will be followed only
1479 * if the \ref RAIL_EVENT_TX_PACKET_SENT event occurs. Any of the other
1480 * events will trigger the \ref RAIL_StateTransitions_t::error transition.
1481 */
1482 #define RAIL_EVENTS_TX_COMPLETION (RAIL_EVENT_TX_PACKET_SENT \
1483 | RAIL_EVENT_TX_ABORTED \
1484 | RAIL_EVENT_TX_BLOCKED \
1485 | RAIL_EVENT_TX_UNDERFLOW \
1486 | RAIL_EVENT_TX_CHANNEL_BUSY \
1487 | RAIL_EVENT_TX_SCHEDULED_TX_MISSED)
1488
1489 /**
1490 * A mask representing all events that determine the end of a transmitted
1491 * Ack packet. After an Ack-requesting receive, exactly one of the
1492 * following events will occur. When one of these events occurs, a state
1493 * transition takes place based on the RAIL_AutoAckConfig_t::rxTransitions
1494 * passed to \ref RAIL_ConfigAutoAck(). The receive transitions are used because the
1495 * transmitted Ack packet is considered a part of the Ack-requesting received
1496 * packet. The RAIL_StateTransitions_t::success transition will be followed
1497 * only if the \ref RAIL_EVENT_TXACK_PACKET_SENT event occurs. Any of the other
1498 * events will trigger the RAIL_StateTransitions_t::error transition.
1499 */
1500 #define RAIL_EVENTS_TXACK_COMPLETION (RAIL_EVENT_TXACK_PACKET_SENT \
1501 | RAIL_EVENT_TXACK_ABORTED \
1502 | RAIL_EVENT_TXACK_BLOCKED \
1503 | RAIL_EVENT_TXACK_UNDERFLOW)
1504
1505 // Scheduler Event Bitmasks
1506
1507 /**
1508 * Occurs when the scheduler switches away from this configuration.
1509 *
1510 * This event will occur in dynamic multiprotocol scenarios each
1511 * time a protocol is shutting down. When it does occur, it will be
1512 * the only event passed to \ref RAIL_Config_t::eventsCallback. Therefore,
1513 * to optimize protocol switch time, this event should be handled
1514 * among the first in that callback, and then the application can return
1515 * immediately.
1516 *
1517 * @note: To minimize protocol switch time, Silicon Labs recommends this event
1518 * event being turned off unless it is used.
1519 */
1520 #define RAIL_EVENT_CONFIG_UNSCHEDULED (1ULL << RAIL_EVENT_CONFIG_UNSCHEDULED_SHIFT)
1521
1522 /**
1523 * Occurs when the scheduler switches to this configuration.
1524 *
1525 * This event will occur in dynamic multiprotocol scenarios each time
1526 * a protocol is starting up. When it does occur, it will
1527 * be the only event passed to \ref RAIL_Config_t::eventsCallback. Therefore, in
1528 * order to optimize protocol switch time, this event should be handled among
1529 * the first in that callback, and then the application can return immediately.
1530 *
1531 * @note: To minimize protocol switch time, Silicon Labs recommends this event
1532 * event being turned off unless it is used.
1533 */
1534 #define RAIL_EVENT_CONFIG_SCHEDULED (1ULL << RAIL_EVENT_CONFIG_SCHEDULED_SHIFT)
1535
1536 /**
1537 * Occurs when the scheduler has a status to report.
1538 *
1539 * The exact status can be found with \ref RAIL_GetSchedulerStatus().
1540 * See \ref RAIL_SchedulerStatus_t for more details. When this event
1541 * does occur, it will be the only event passed to \ref RAIL_Config_t::eventsCallback.
1542 * Therefore, to optimize protocol switch time, this event should
1543 * be handled among the first in that callback, and then the application
1544 * can return immediately.
1545 *
1546 * @note \ref RAIL_GetSchedulerStatus() is only valid to call during the time frame
1547 * of the \ref RAIL_Config_t::eventsCallback.
1548 *
1549 * @note: To minimize protocol switch time, Silicon Labs recommends this event
1550 * event being turned off unless it is used.
1551 */
1552 #define RAIL_EVENT_SCHEDULER_STATUS (1ULL << RAIL_EVENT_SCHEDULER_STATUS_SHIFT)
1553
1554 // Other Event Bitmasks
1555
1556 /**
1557 * Occurs when the application needs to run a calibration, as
1558 * determined by the RAIL library.
1559 *
1560 * The application determines the opportune time to call \ref RAIL_Calibrate().
1561 */
1562 #define RAIL_EVENT_CAL_NEEDED (1ULL << RAIL_EVENT_CAL_NEEDED_SHIFT)
1563
1564 /**
1565 * Occurs when RF energy is sensed from the radio. This event can be used as
1566 * an alternative to the callback passed as \ref RAIL_RfSense_CallbackPtr_t
1567 * or the application polling with \ref RAIL_IsRfSensed().
1568 *
1569 * @note This event will not occur when waking up from EM4. Prefer
1570 * \ref RAIL_IsRfSensed() when waking from EM4.
1571 */
1572 #define RAIL_EVENT_RF_SENSED (1ULL << RAIL_EVENT_RF_SENSED_SHIFT)
1573
1574 /**
1575 * Occurs when PA protection circuit kicks in.
1576 */
1577 #define RAIL_EVENT_PA_PROTECTION (1ULL << RAIL_EVENT_PA_PROTECTION_SHIFT)
1578
1579 /**
1580 * Occurs after enabling the signal detection using \ref RAIL_BLE_EnableSignalDetection()
1581 * or \ref RAIL_IEEE802154_EnableSignalDetection() when a signal is detected.
1582 * This is only used on platforms that support signal identifier, where
1583 * \ref RAIL_BLE_SUPPORTS_SIGNAL_IDENTIFIER or
1584 * \ref RAIL_IEEE802154_SUPPORTS_SIGNAL_IDENTIFIER is true.
1585 */
1586 #define RAIL_EVENT_SIGNAL_DETECTED (1ULL << RAIL_EVENT_SIGNAL_DETECTED_SHIFT)
1587
1588 /**
1589 * Occurs when a Wi-SUN mode switch packet has been received, after switching to the new PHY.
1590 *
1591 * It doesn't occur when a mode switch packet is transmitted.
1592 *
1593 * IEEE 802.15.4 option \ref RAIL_IEEE802154_G_OPTION_WISUN_MODESWITCH must be enabled for this event to occur.
1594 *
1595 * Only available on platforms where \ref RAIL_IEEE802154_SUPPORTS_G_MODESWITCH is true.
1596 */
1597 #define RAIL_EVENT_IEEE802154_MODESWITCH_START (1ULL << RAIL_EVENT_IEEE802154_MODESWITCH_START_SHIFT)
1598
1599 /**
1600 * Occurs when switching back to the original base PHY in effect prior to the Wi-SUN mode switch reception.
1601 *
1602 * This typically occurs if no packet is seen within some timeframe after the mode switch packet was received
1603 * or if the first packet received in the new PHY is aborted, filtered, or fails CRC.
1604 *
1605 * IEEE 802.15.4 option \ref RAIL_IEEE802154_G_OPTION_WISUN_MODESWITCH must be enabled for this event to occur.
1606 *
1607 * Only available on platforms where \ref RAIL_IEEE802154_SUPPORTS_G_MODESWITCH is true.
1608 */
1609 #define RAIL_EVENT_IEEE802154_MODESWITCH_END (1ULL << RAIL_EVENT_IEEE802154_MODESWITCH_END_SHIFT)
1610
1611 /**
1612 * Occurs when the sampled RSSI is above the threshold set by
1613 * \ref RAIL_SetRssiDetectThreshold().
1614 */
1615 #define RAIL_EVENT_DETECT_RSSI_THRESHOLD (1ULL << RAIL_EVENT_DETECT_RSSI_THRESHOLD_SHIFT)
1616
1617 /**
1618 * Occurs when the thermistor has finished its measurement in response to
1619 * \ref RAIL_StartThermistorMeasurement().
1620 */
1621 #define RAIL_EVENT_THERMISTOR_DONE (1ULL << RAIL_EVENT_THERMISTOR_DONE_SHIFT)
1622
1623 /**
1624 * Occurs when a Tx has been blocked because of temperature exceeding
1625 * the safety threshold.
1626 * @deprecated but reserved for possible future use.
1627 */
1628 #define RAIL_EVENT_TX_BLOCKED_TOO_HOT (1ULL << RAIL_EVENT_TX_BLOCKED_TOO_HOT_SHIFT)
1629
1630 /**
1631 * Occurs when die internal temperature exceeds the temperature threshold subtracted
1632 * by the cool down parameter from \ref RAIL_ChipTempConfig_t.
1633 * Transmits are blocked until temperature has cooled enough, indicated by
1634 * \ref RAIL_EVENT_TEMPERATURE_COOL_DOWN.
1635 *
1636 * Only occurs on platforms where \ref RAIL_SUPPORTS_THERMAL_PROTECTION is true.
1637 */
1638 #define RAIL_EVENT_TEMPERATURE_TOO_HOT (1ULL << RAIL_EVENT_TEMPERATURE_TOO_HOT_SHIFT)
1639
1640 /**
1641 * Occurs when die internal temperature falls below the temperature threshold subtracted
1642 * by the cool down parameter from \ref RAIL_ChipTempConfig_t.
1643 * Transmits are no longer blocked by temperature limitation, indicated by
1644 * \ref RAIL_EVENT_TEMPERATURE_TOO_HOT.
1645 *
1646 * Only occurs on platforms where \ref RAIL_SUPPORTS_THERMAL_PROTECTION is true.
1647 */
1648 #define RAIL_EVENT_TEMPERATURE_COOL_DOWN (1ULL << RAIL_EVENT_TEMPERATURE_COOL_DOWN_SHIFT)
1649
1650 /**
1651 * Occurs when the user received a mailbox message.
1652 */
1653 #define RAIL_EVENT_USER_MBOX (1ULL << RAIL_EVENT_USER_MBOX_SHIFT)
1654
1655 /** A value representing all possible events */
1656 #define RAIL_EVENTS_ALL 0xFFFFFFFFFFFFFFFFULL
1657
1658 /** @} */ // end of group Events
1659
1660 /******************************************************************************
1661 * General Structures (part 2)
1662 *****************************************************************************/
1663 /**
1664 * @addtogroup General
1665 * @{
1666 */
1667
1668 /**
1669 * @struct RAIL_Config_t
1670 * @brief RAIL configuration structure.
1671 */
1672 typedef struct RAIL_Config {
1673 /**
1674 * A pointer to a function, which is called whenever a RAIL event occurs.
1675 *
1676 * @param[in] railHandle The corresponding real RAIL instance handle.
1677 * @param[in] events A bit mask of RAIL events.
1678 *
1679 * See the \ref RAIL_Events_t documentation for the list of RAIL events.
1680 */
1681 void (*eventsCallback)(RAIL_Handle_t railHandle, RAIL_Events_t events);
1682 /**
1683 * Provided for backwards compatibility. Ignored.
1684 */
1685 void *protocol;
1686 /**
1687 * Provided for backwards compatibility. Ignored.
1688 */
1689 RAILSched_Config_t *scheduler;
1690 /**
1691 * Provided for backwards compatibility. Ignored.
1692 */
1693 RAIL_StateBuffer_t buffer;
1694 } RAIL_Config_t;
1695
1696 /** @} */ // end of group General
1697
1698 /******************************************************************************
1699 * PA Power Amplifier Structures
1700 *****************************************************************************/
1701 /**
1702 * @addtogroup PA Power Amplifier (PA)
1703 * @ingroup Transmit
1704 * @{
1705 */
1706
1707 /**
1708 * The transmit power in deci-dBm units (e.g., 4.5 dBm -> 45 deci-dBm). These
1709 * values are used by the conversion functions to convert a \ref
1710 * RAIL_TxPowerLevel_t to deci-dBm for the application consumption. On EFR32,
1711 * they can range from \ref RAIL_TX_POWER_MIN to \ref RAIL_TX_POWER_MAX.
1712 */
1713 typedef int16_t RAIL_TxPower_t;
1714
1715 /** The maximum valid value for a \ref RAIL_TxPower_t. */
1716 #define RAIL_TX_POWER_MAX ((RAIL_TxPower_t)0x7FFF)
1717 /** The minimum valid value for a \ref RAIL_TxPower_t. */
1718 #define RAIL_TX_POWER_MIN ((RAIL_TxPower_t)0x8000)
1719
1720 /** The maximum power in deci-dBm the curve supports */
1721 #define RAIL_TX_POWER_CURVE_DEFAULT_MAX ((RAIL_TxPower_t)200)
1722 /** The increment step in deci-dBm for calculating power level*/
1723 #define RAIL_TX_POWER_CURVE_DEFAULT_INCREMENT ((RAIL_TxPower_t)40)
1724
1725 /// mV are used for all TX power voltage values.
1726 /// TX power voltages take and return voltages multiplied by this factor.
1727 #define RAIL_TX_POWER_VOLTAGE_SCALING_FACTOR 1000
1728
1729 /// deci-dBm are used for all TX power dBm values.
1730 /// All dBm inputs to TX power functions take dBm power times this factor.
1731 #define RAIL_TX_POWER_DBM_SCALING_FACTOR 10
1732
1733 /**
1734 * Raw power levels used directly by \ref RAIL_GetTxPower() and \ref RAIL_SetTxPower() where a higher
1735 * numerical value corresponds to a higher output power. These are referred to
1736 * as 'raw (values/units)'. On EFR32, they can range from one of \ref
1737 * RAIL_TX_POWER_LEVEL_2P4_LP_MIN, \ref RAIL_TX_POWER_LEVEL_2P4_HP_MIN, or
1738 * \ref RAIL_TX_POWER_LEVEL_SUBGIG_HP_MIN to one of \ref
1739 * RAIL_TX_POWER_LEVEL_2P4_LP_MAX, \ref RAIL_TX_POWER_LEVEL_2P4_HP_MAX, and \ref
1740 * RAIL_TX_POWER_LEVEL_SUBGIG_HP_MAX, respectively, depending on the selected \ref
1741 * RAIL_TxPowerMode_t.
1742 */
1743 typedef uint8_t RAIL_TxPowerLevel_t;
1744
1745 /**
1746 * Invalid \ref RAIL_TxPowerLevel_t value returned when an error occurs
1747 * with \ref RAIL_GetTxPower().
1748 */
1749 #define RAIL_TX_POWER_LEVEL_INVALID (255U)
1750
1751 /**
1752 * Sentinel value that can be passed to \ref RAIL_SetTxPower() to set
1753 * the highest power level available on the current PA, regardless
1754 * of which one is selected.
1755 */
1756 #define RAIL_TX_POWER_LEVEL_MAX (254U)
1757
1758 /**
1759 * PA power setting used directly by \ref RAIL_GetPaPowerSetting() and
1760 * \ref RAIL_SetPaPowerSetting() which is decoded to the actual
1761 * hardware register value(s).
1762 */
1763 typedef uint32_t RAIL_PaPowerSetting_t;
1764
1765 /**
1766 * Returned by \ref RAIL_GetPaPowerSetting() when the device does
1767 * not support the dBm to power setting mapping table.
1768 */
1769 #define RAIL_TX_PA_POWER_SETTING_UNSUPPORTED (0U)
1770
1771 /**
1772 * @enum RAIL_TxPowerMode_t
1773 * @brief An enumeration of the EFR32 power modes.
1774 *
1775 * The power modes on the EFR32 correspond to the different on-chip PAs that
1776 * are available. For more information about the power and performance
1777 * characteristics of a given amplifier, see the data sheet.
1778 */
RAIL_ENUM(RAIL_TxPowerMode_t)1779 RAIL_ENUM(RAIL_TxPowerMode_t) {
1780 /**
1781 * High-power 2.4 GHz amplifier
1782 * EFR32xG21: up to 20 dBm, raw values: 1-180
1783 * EFR32xG22: up to 6 dBm, raw values: 1-128
1784 * EFR32xG24: up to 20 dBm, raw values: 0-180, or
1785 * up to 10 dBm, raw values: 0-90
1786 * EFR32xG26: same as EFR32xG24
1787 * EFR32xG27: up to 6 dBm, raw values: 1-128
1788 * EFR32xG28: up to 10 dBm, raw values: 0-240
1789 * Not supported on other platforms.
1790 */
1791 RAIL_TX_POWER_MODE_2P4GIG_HP = 0U,
1792 /** @deprecated Please use \ref RAIL_TX_POWER_MODE_2P4GIG_HP instead. */
1793 RAIL_TX_POWER_MODE_2P4_HP = RAIL_TX_POWER_MODE_2P4GIG_HP,
1794 /**
1795 * Mid-power 2.4 GHz amplifier
1796 * EFR32xG21: up to 10 dBm, raw values: 1-90
1797 * Not supported on other platforms.
1798 */
1799 RAIL_TX_POWER_MODE_2P4GIG_MP = 1U,
1800 /** @deprecated Please use \ref RAIL_TX_POWER_MODE_2P4GIG_MP instead. */
1801 RAIL_TX_POWER_MODE_2P4_MP = RAIL_TX_POWER_MODE_2P4GIG_MP,
1802 /**
1803 * Low-power 2.4 GHz amplifier
1804 * EFR32xG21: up to 0 dBm, raw values: 1-64
1805 * EFR32xG22: up to 0 dBm, raw values: 1-16
1806 * EFR32xG24: up to 0 dBm, raw values: 1-16
1807 * EFR32xG26: same as EFR32xG24
1808 * EFR32xG27: up to 0 dBm, raw values: 1-16
1809 * Not supported on other platforms.
1810 */
1811 RAIL_TX_POWER_MODE_2P4GIG_LP = 2U,
1812 /** @deprecated Please use \ref RAIL_TX_POWER_MODE_2P4GIG_LP instead. */
1813 RAIL_TX_POWER_MODE_2P4_LP = RAIL_TX_POWER_MODE_2P4GIG_LP,
1814 /**
1815 * Low-Low-power 2.4 GHz amplifier
1816 * Not currently supported on any EFR32 platform.
1817 */
1818 RAIL_TX_POWER_MODE_2P4GIG_LLP = 3U,
1819 /**
1820 * Select the highest 2.4 GHz power PA available on the current chip.
1821 */
1822 RAIL_TX_POWER_MODE_2P4GIG_HIGHEST = 4U,
1823 /** @deprecated Please use \ref RAIL_TX_POWER_MODE_2P4GIG_HIGHEST instead. */
1824 RAIL_TX_POWER_MODE_2P4_HIGHEST = RAIL_TX_POWER_MODE_2P4GIG_HIGHEST,
1825 /**
1826 * PA for all Sub-GHz dBm values in range, using \ref
1827 * RAIL_PaPowerSetting_t table.
1828 * Only supported on platforms with \ref
1829 * RAIL_SUPPORTS_DBM_POWERSETTING_MAPPING_TABLE (e.g., EFR32xG25).
1830 */
1831 RAIL_TX_POWER_MODE_SUBGIG_POWERSETTING_TABLE = 5U,
1832 /**
1833 * High-power Sub-GHz amplifier (Class D mode)
1834 * Supported on EFR32xG23 and EFR32xG28.
1835 * Not supported other Sub-GHz-incapable platforms or those with \ref
1836 * RAIL_SUPPORTS_DBM_POWERSETTING_MAPPING_TABLE.
1837 */
1838 RAIL_TX_POWER_MODE_SUBGIG_HP = 6U,
1839 /** @deprecated Please use \ref RAIL_TX_POWER_MODE_SUBGIG_HP instead. */
1840 RAIL_TX_POWER_MODE_SUBGIG = RAIL_TX_POWER_MODE_SUBGIG_HP,
1841 /**
1842 * Mid-power Sub-GHz amplifier
1843 * Supported only on EFR32xG23 and EFR32xG28.
1844 * Not supported other Sub-GHz-incapable platforms or those with \ref
1845 * RAIL_SUPPORTS_DBM_POWERSETTING_MAPPING_TABLE.
1846 */
1847 RAIL_TX_POWER_MODE_SUBGIG_MP = 7U,
1848 /**
1849 * Low-power Sub-GHz amplifier
1850 * Supported only on EFR32xG23 and EFR32xG28.
1851 * Not supported other Sub-GHz-incapable platforms or those with \ref
1852 * RAIL_SUPPORTS_DBM_POWERSETTING_MAPPING_TABLE.
1853 */
1854 RAIL_TX_POWER_MODE_SUBGIG_LP = 8U,
1855 /**
1856 * Low-Low-power Sub-GHz amplifier
1857 * Supported only on EFR32xG23 and EFR32xG28.
1858 * Not supported other Sub-GHz-incapable platforms or those with \ref
1859 * RAIL_SUPPORTS_DBM_POWERSETTING_MAPPING_TABLE.
1860 */
1861 RAIL_TX_POWER_MODE_SUBGIG_LLP = 9U,
1862 /**
1863 * Select the highest Sub-GHz power PA available on the current chip.
1864 */
1865 RAIL_TX_POWER_MODE_SUBGIG_HIGHEST = 10U,
1866 /**
1867 * PA for all OFDM Sub-GHz dBm values in range, using \ref
1868 * RAIL_PaPowerSetting_t table.
1869 * Supported only on platforms with both \ref
1870 * RAIL_SUPPORTS_DBM_POWERSETTING_MAPPING_TABLE and \ref
1871 * RAIL_SUPPORTS_OFDM_PA (e.g., EFR32xG25).
1872 */
1873 RAIL_TX_POWER_MODE_OFDM_PA_POWERSETTING_TABLE = 11U,
1874 /** @deprecated Please use \ref RAIL_TX_POWER_MODE_OFDM_PA_POWERSETTING_TABLE instead. */
1875 RAIL_TX_POWER_MODE_OFDM_PA = RAIL_TX_POWER_MODE_OFDM_PA_POWERSETTING_TABLE,
1876 /** Invalid amplifier Selection. Must be last. */
1877 RAIL_TX_POWER_MODE_NONE
1878 };
1879
1880 #ifndef DOXYGEN_SHOULD_SKIP_THIS
1881 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
1882 // Refer to rail_chip_specific.h for per-platform defines of supported ones.
1883 #define RAIL_TX_POWER_MODE_NONE ((RAIL_TxPowerMode_t) RAIL_TX_POWER_MODE_NONE)
1884 #endif//DOXYGEN_SHOULD_SKIP_THIS
1885
1886 /**
1887 * @def RAIL_TX_POWER_MODE_NAMES
1888 * @brief The names of the TX power modes.
1889 *
1890 * A list of the names for the TX power modes on EFR32 parts. This
1891 * macro is useful for test applications and debugging output.
1892 */
1893 #define RAIL_TX_POWER_MODE_NAMES { \
1894 "RAIL_TX_POWER_MODE_2P4GIG_HP", \
1895 "RAIL_TX_POWER_MODE_2P4GIG_MP", \
1896 "RAIL_TX_POWER_MODE_2P4GIG_LP", \
1897 "RAIL_TX_POWER_MODE_2P4GIG_LLP", \
1898 "RAIL_TX_POWER_MODE_2P4GIG_HIGHEST", \
1899 "RAIL_TX_POWER_MODE_SUBGIG_POWERSETTING_TABLE", \
1900 "RAIL_TX_POWER_MODE_SUBGIG_HP", \
1901 "RAIL_TX_POWER_MODE_SUBGIG_MP", \
1902 "RAIL_TX_POWER_MODE_SUBGIG_LP", \
1903 "RAIL_TX_POWER_MODE_SUBGIG_LLP", \
1904 "RAIL_TX_POWER_MODE_SUBGIG_HIGHEST", \
1905 "RAIL_TX_POWER_MODE_OFDM_PA_POWERSETTING_TABLE", \
1906 "RAIL_TX_POWER_MODE_NONE" \
1907 }
1908
1909 /**
1910 * @struct RAIL_TxPowerConfig_t
1911 *
1912 * @brief A structure containing values used to initialize the power amplifiers.
1913 */
1914 typedef struct RAIL_TxPowerConfig {
1915 /** TX power mode */
1916 RAIL_TxPowerMode_t mode;
1917 /**
1918 * Power amplifier supply voltage in mV, generally:
1919 * DCDC supply ~ 1800 mV (1.8 V)
1920 * Battery supply ~ 3300 mV (3.3 V)
1921 */
1922 uint16_t voltage;
1923 /** The amount of time to spend ramping for TX in microseconds. */
1924 uint16_t rampTime;
1925 } RAIL_TxPowerConfig_t;
1926
1927 /** Convenience macro for any OFDM mapping table mode. */
1928 #define RAIL_POWER_MODE_IS_DBM_POWERSETTING_MAPPING_TABLE_OFDM(x) \
1929 ((x) == RAIL_TX_POWER_MODE_OFDM_PA_POWERSETTING_TABLE)
1930 /** Convenience macro for any Sub-GHz mapping table mode. */
1931 #define RAIL_POWER_MODE_IS_DBM_POWERSETTING_MAPPING_TABLE_SUBGIG(x) \
1932 ((x) == RAIL_TX_POWER_MODE_SUBGIG_POWERSETTING_TABLE)
1933 /** Convenience macro for any OFDM mode. */
1934 #define RAIL_POWER_MODE_IS_ANY_OFDM(x) \
1935 RAIL_POWER_MODE_IS_DBM_POWERSETTING_MAPPING_TABLE_OFDM(x)
1936
1937 /** @} */ // PA Power Amplifier (PA)
1938
1939 /******************************************************************************
1940 * Radio Configuration Structures
1941 *****************************************************************************/
1942 /**
1943 * @addtogroup Radio_Configuration
1944 * @{
1945 */
1946
1947 /**
1948 * @brief Pointer to a radio configuration array.
1949 *
1950 * The radio configuration properly configures the
1951 * radio for operation on a protocol. These configurations are very
1952 * chip-specific should not be created or edited by hand.
1953 */
1954 typedef const uint32_t *RAIL_RadioConfig_t;
1955
1956 /**
1957 * @struct RAIL_FrameType_t
1958 * @brief Configures if there is a frame type in your frame and the lengths of
1959 * each frame. The number of bits set in the mask determines the number of
1960 * elements in frameLen. A maximum of 8 different frame types may be specified.
1961 */
1962 typedef struct RAIL_FrameType {
1963 /**
1964 * A pointer to an array of frame byte lengths for each frame type.
1965 * The number of elements in this array should be equal to the number of
1966 * frame types. The memory to which frameLen points should not
1967 * change location or be modified.
1968 */
1969 uint16_t *frameLen;
1970 /**
1971 * Zero-indexed byte offset location of the byte containing the frame type field.
1972 */
1973 uint8_t offset;
1974 /**
1975 * A bitmask of the frame type field, which determines a number of frames expected
1976 * based on the number of bits set. No more than 3 bits can be set in the mask and
1977 * they must be contiguous ones. For example, if the highest three bits of the byte
1978 * specified by offset constitute the frame type, then mask should be 0xE0,
1979 * which has 3 bits set, indicating 8 possible frame types.
1980 */
1981 uint8_t mask;
1982 /**
1983 * A bitmask that marks if each frame is valid or should be filtered. Frame type
1984 * 0 corresponds to the lowest bit in isValid. If the frame is filtered, a
1985 * \ref RAIL_EVENT_RX_PACKET_ABORTED will be raised.
1986 */
1987 uint8_t isValid;
1988 /**
1989 * A bitmask that marks if each frame should have the address filter applied.
1990 * Frame type 0 corresponds to the least significant bit in addressFilter.
1991 */
1992 uint8_t addressFilter;
1993 } RAIL_FrameType_t;
1994
1995 /**
1996 * @def RAIL_SETFIXEDLENGTH_INVALID
1997 * @brief An invalid return value when calling \ref RAIL_SetFixedLength().
1998 *
1999 * An invalid return value when calling \ref RAIL_SetFixedLength() while the radio is
2000 * not in fixed-length mode.
2001 */
2002 #define RAIL_SETFIXEDLENGTH_INVALID (0xFFFFU)
2003
2004 /**
2005 * @struct RAIL_ChannelConfigEntryAttr_t
2006 * @brief A channel configuration entry attribute structure. Items listed
2007 * are designed to be altered and updated during run-time.
2008 */
2009 typedef struct RAIL_ChannelConfigEntryAttr RAIL_ChannelConfigEntryAttr_t;
2010
2011 /**
2012 * @enum RAIL_ChannelConfigEntryType_t
2013 * @brief Define if the channel support using concurrent PHY during channel
2014 * hopping. \ref RAIL_RX_CHANNEL_HOPPING_MODE_CONC and \ref RAIL_RX_CHANNEL_HOPPING_MODE_VT
2015 * can only be used if the channel supports it.
2016 */
RAIL_ENUM(RAIL_ChannelConfigEntryType_t)2017 RAIL_ENUM(RAIL_ChannelConfigEntryType_t) {
2018 /** Not a concurrent PHY. */
2019 RAIL_CH_TYPE_NORMAL,
2020 /** Base concurrent PHY. */
2021 RAIL_CH_TYPE_CONC_BASE,
2022 /** Virtual concurrent PHY. */
2023 RAIL_CH_TYPE_CONC_VIRTUAL,
2024 };
2025
2026 #ifndef DOXYGEN_SHOULD_SKIP_THIS
2027 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
2028 #define RAIL_CH_TYPE_NORMAL ((RAIL_ChannelConfigEntryType_t) RAIL_CH_TYPE_NORMAL)
2029 #define RAIL_CH_TYPE_CONC_BASE ((RAIL_ChannelConfigEntryType_t) RAIL_CH_TYPE_CONC_BASE)
2030 #define RAIL_CH_TYPE_CONC_VIRTUAL ((RAIL_ChannelConfigEntryType_t) RAIL_CH_TYPE_CONC_VIRTUAL)
2031 #endif//DOXYGEN_SHOULD_SKIP_THIS
2032
2033 /**
2034 * @def RADIO_CONFIG_ENABLE_CONC_PHY
2035 * @brief Indicates this version of RAIL supports concurrent PHY information in
2036 * radio configurator output. Needed for backwards compatibility.
2037 */
2038 #define RADIO_CONFIG_ENABLE_CONC_PHY 1
2039
2040 /**
2041 * @def RADIO_CONFIG_ENABLE_STACK_INFO
2042 * @brief Indicates this version of RAIL supports stack info feature in
2043 * radio configurator output. Needed for backwards compatibility.
2044 */
2045 #define RADIO_CONFIG_ENABLE_STACK_INFO
2046
2047 /**
2048 * @struct RAIL_AlternatePhy_t
2049 * @brief Alternate PHY configuration entry structure, which gathers some info
2050 * on the alternate PHY in the context of concurrent mode.
2051 */
2052 typedef struct RAIL_AlternatePhy {
2053 /** A base frequency in Hz of this channel set. */
2054 uint32_t baseFrequency;
2055 /** A channel spacing in Hz of this channel set. */
2056 uint32_t channelSpacing;
2057 /** The number of channels (and not the channel number !) */
2058 uint16_t numberOfChannels;
2059 /** minimum IF for the alternate PHY in kHz. */
2060 uint16_t minIf_kHz;
2061 /** minimum IF for the base PHY in kHz. */
2062 uint16_t minBaseIf_kHz;
2063 /** Indicates that OFDM modem is used by this alternate PHY. */
2064 bool isOfdmModem;
2065 /** Rate info of the alternate PHY. */
2066 uint32_t rateInfo;
2067 /** Used to adjust the AGC for CCA between hard and soft modems. */
2068 uint32_t hwModemAgcCtrl1;
2069 } RAIL_AlternatePhy_t;
2070
2071 /**
2072 * @struct RAIL_ChannelConfigEntry_t
2073 * @brief A channel configuration entry structure, which defines a channel range
2074 * and parameters across which a corresponding radio configuration is valid.
2075 *
2076 * operating frequency hz = baseFrequency
2077 * + channelSpacing * (channel - physicalChannelOffset);
2078 */
2079 typedef struct RAIL_ChannelConfigEntry {
2080 /**
2081 * The minimum radio configuration to apply to the base
2082 * configuration for this channel set.
2083 */
2084 RAIL_RadioConfig_t phyConfigDeltaAdd;
2085 /** A base frequency in Hz of this channel set. */
2086 uint32_t baseFrequency;
2087 /** A channel spacing in Hz of this channel set. */
2088 uint32_t channelSpacing;
2089 /**
2090 * The offset to subtract from the logical
2091 * channel to align them with the zero based physical channels which are
2092 * relative to baseFrequency. (i.e., By default ch 0 = base freq, but if
2093 * offset = 11, ch 11 = base freq.)
2094 */
2095 uint16_t physicalChannelOffset;
2096 /** The first valid RAIL channel number for this channel set. */
2097 uint16_t channelNumberStart;
2098 /** The last valid RAIL channel number for this channel set. */
2099 uint16_t channelNumberEnd;
2100 /** The maximum power allowed in this channel set. */
2101 RAIL_TxPower_t maxPower;
2102 /**
2103 * A pointer to a structure containing attributes specific to this
2104 * channel set.
2105 */
2106 RAIL_ChannelConfigEntryAttr_t *attr;
2107 /** Indicates channel config type. */
2108 RAIL_ChannelConfigEntryType_t entryType;
2109 /** to align to 32-bit boundary. */
2110 uint8_t reserved[3];
2111 /**
2112 * Array containing information according to the \ref RAIL_PtiProtocol_t in
2113 * the first byte of this array. The first 2 fields are common to all
2114 * protocols and accessible by RAIL, others are ignored by RAIL
2115 * and only used by the application. Common fields are listed in
2116 * \ref RAIL_StackInfoCommon_t.
2117 */
2118 const uint8_t *stackInfo;
2119 /** Pointer to alternate PHY. */
2120 RAIL_AlternatePhy_t *alternatePhy;
2121 } RAIL_ChannelConfigEntry_t;
2122
2123 /// @struct RAIL_ChannelConfig_t
2124 /// @brief A channel configuration structure, which defines the channel meaning
2125 /// when a channel number is passed into a RAIL function, e.g., \ref RAIL_StartTx()
2126 /// and \ref RAIL_StartRx().
2127 ///
2128 /// A \ref RAIL_ChannelConfig_t structure defines the channel scheme that an
2129 /// application uses when registered in \ref RAIL_ConfigChannels().
2130 ///
2131 /// These are a few examples of different channel configurations:
2132 /// @code{.c}
2133 /// // 21 channels starting at 2.45 GHz with channel spacing of 1 MHz
2134 /// // ... generated by Simplicity Studio (i.e., rail_config.c) ...
2135 /// const uint32_t generated[] = { ... };
2136 /// RAIL_ChannelConfigEntryAttr_t generated_entryAttr = { ... };
2137 /// const RAIL_ChannelConfigEntry_t generated_channels[] = {
2138 /// {
2139 /// .phyConfigDeltaAdd = NULL, // Add this to default configuration for this entry
2140 /// .baseFrequency = 2450000000,
2141 /// .channelSpacing = 1000000,
2142 /// .physicalChannelOffset = 0,
2143 /// .channelNumberStart = 0,
2144 /// .channelNumberEnd = 20,
2145 /// .maxPower = RAIL_TX_POWER_MAX,
2146 /// .attr = &generated_entryAttr,
2147 /// },
2148 /// };
2149 /// const RAIL_ChannelConfig_t generated_channelConfig = {
2150 /// .phyConfigBase = generated, // Default radio configuration for all entries
2151 /// .phyConfigDeltaSubtract = NULL, // Subtract this to restore the default configuration
2152 /// .configs = generated_channels,
2153 /// .length = 1, // There are this many channel configuration entries
2154 /// };
2155 /// const RAIL_ChannelConfig_t *channelConfigs[] = {
2156 /// &generated_channelConfig,
2157 /// NULL,
2158 /// };
2159 /// // ... in main code ...
2160 /// // Associate a specific channel configuration with a particular RAIL instance.
2161 /// RAIL_ConfigChannels(railHandle, channelConfigs[0]);
2162 ///
2163 /// // 4 nonlinear channels
2164 /// // ... in rail_config.c ...
2165 /// const uint32_t generated[] = { ... };
2166 /// RAIL_ChannelConfigEntryAttr_t generated_entryAttr = { ... };
2167 /// const RAIL_ChannelConfigEntry_t generated_channels[] = {
2168 /// {
2169 /// .phyConfigDeltaAdd = NULL, // Add this to default configuration for this entry
2170 /// .baseFrequency = 910123456,
2171 /// .channelSpacing = 0,
2172 /// .physicalChannelOffset = 0,
2173 /// .channelNumberStart = 0,
2174 /// .channelNumberEnd = 0,
2175 /// .maxPower = RAIL_TX_POWER_MAX,
2176 /// .attr = &generated_entryAttr,
2177 /// },
2178 /// {
2179 /// .phyConfigDeltaAdd = NULL,
2180 /// .baseFrequency = 911654789,
2181 /// .channelSpacing = 0,
2182 /// .physicalChannelOffset = 0, // Since ch spacing = 0, offset can be 0
2183 /// .channelNumberStart = 1,
2184 /// .channelNumberEnd = 1,
2185 /// .maxPower = RAIL_TX_POWER_MAX,
2186 /// .attr = &generated_entryAttr,
2187 /// },
2188 /// {
2189 /// .phyConfigDeltaAdd = NULL,
2190 /// .baseFrequency = 912321456,
2191 /// .channelSpacing = 100000,
2192 /// .physicalChannelOffset = 2, // Since ch spacing != 0, offset = 2
2193 /// .channelNumberStart = 2, // ch 2 = baseFrequency
2194 /// .channelNumberEnd = 2,
2195 /// .maxPower = RAIL_TX_POWER_MAX,
2196 /// .attr = &generated_entryAttr,
2197 /// },
2198 /// {
2199 /// .phyConfigDeltaAdd = NULL,
2200 /// .baseFrequency = 913147852,
2201 /// .channelSpacing = 0,
2202 /// .physicalChannelOffset = 0,
2203 /// .channelNumberStart = 3,
2204 /// .channelNumberEnd = 3,
2205 /// .maxPower = RAIL_TX_POWER_MAX,
2206 /// .attr = &generated_entryAttr,
2207 /// },
2208 /// };
2209 /// const RAIL_ChannelConfig_t generated_channelConfig = {
2210 /// .phyConfigBase = generated, // Default radio configuration for all entries
2211 /// .phyConfigDeltaSubtract = NULL, // Subtract this to restore the default configuration
2212 /// .configs = generated_channels,
2213 /// .length = 4, // There are this many channel configuration entries
2214 /// };
2215 /// const RAIL_ChannelConfig_t *channelConfigs[] = {
2216 /// &generated_channelConfig,
2217 /// NULL,
2218 /// };
2219 /// // ... in main code ...
2220 /// // Associate a specific channel configuration with a particular RAIL instance.
2221 /// RAIL_ConfigChannels(railHandle, channelConfigs[0]);
2222 ///
2223 /// // Multiple radio configurations
2224 /// // ... in rail_config.c ...
2225 /// const uint32_t generated0[] = { ... };
2226 /// RAIL_ChannelConfigEntryAttr_t generated0_entryAttr = { ... };
2227 /// const RAIL_ChannelConfigEntry_t generated0_channels[] = {
2228 /// {
2229 /// .phyConfigDeltaAdd = NULL, // Add this to the default configuration for this entry
2230 /// .baseFrequency = 2450000000,
2231 /// .channelSpacing = 1000000,
2232 /// .physicalChannelOffset = 0,
2233 /// .channelNumberStart = 0,
2234 /// .channelNumberEnd = 20,
2235 /// .maxPower = RAIL_TX_POWER_MAX,
2236 /// .attr = &generated0_entryAttr,
2237 /// },
2238 /// };
2239 /// const RAIL_ChannelConfig_t generated0_channelConfig = {
2240 /// .phyConfigBase = generated0, // Default radio configuration for all entries
2241 /// .phyConfigDeltaSubtract = NULL, // Subtract this to restore default configuration
2242 /// .configs = generated0_channels,
2243 /// .length = 1, // There are this many channel configuration entries
2244 /// };
2245 /// const uint32_t generated1[] = { ... };
2246 /// RAIL_ChannelConfigEntryAttr_t generated1_entryAttr = { ... };
2247 /// const RAIL_ChannelConfigEntry_t generated1_channels[] = {
2248 /// {
2249 /// .phyConfigDeltaAdd = NULL,
2250 /// .baseFrequency = 2450000000,
2251 /// .channelSpacing = 1000000,
2252 /// .physicalChannelOffset = 0,
2253 /// .channelNumberStart = 0,
2254 /// .channelNumberEnd = 20,
2255 /// .maxPower = -100, // Use this entry when TX power <= -10dBm
2256 /// .attr = &generated1_entryAttr,
2257 /// },
2258 /// {
2259 /// .phyConfigDeltaAdd = NULL,
2260 /// .baseFrequency = 2450000000,
2261 /// .channelSpacing = 1000000,
2262 /// .physicalChannelOffset = 0,
2263 /// .channelNumberStart = 0,
2264 /// .channelNumberEnd = 20,
2265 /// .maxPower = 15, // Use this entry when TX power > -10dBm
2266 /// // and TX power <= 1.5dBm
2267 /// .attr = &generated1_entryAttr,
2268 /// },
2269 /// {
2270 /// .phyConfigDeltaAdd = NULL,
2271 /// .baseFrequency = 2450000000,
2272 /// .channelSpacing = 1000000,
2273 /// .physicalChannelOffset = 0,
2274 /// .channelNumberStart = 0,
2275 /// .channelNumberEnd = 20,
2276 /// .maxPower = RAIL_TX_POWER_MAX, // Use this entry when TX power > 1.5dBm
2277 /// .attr = &generated1_entryAttr,
2278 /// },
2279 /// };
2280 /// const RAIL_ChannelConfig_t generated1_channelConfig = {
2281 /// .phyConfigBase = generated1,
2282 /// .phyConfigDeltaSubtract = NULL,
2283 /// .configs = generated1_channels,
2284 /// .length = 3,
2285 /// };
2286 /// const uint32_t generated2[] = { ... };
2287 /// RAIL_ChannelConfigEntryAttr_t generated2_entryAttr = { ... };
2288 /// const RAIL_ChannelConfigEntry_t generated2_channels[] = {
2289 /// {
2290 /// .phyConfigDeltaAdd = NULL,
2291 /// .baseFrequency = 2450000000,
2292 /// .channelSpacing = 1000000,
2293 /// .physicalChannelOffset = 0,
2294 /// .channelNumberStart = 0,
2295 /// .channelNumberEnd = 20,
2296 /// .maxPower = RAIL_TX_POWER_MAX,
2297 /// .attr = &generated2_entryAttr,
2298 /// },
2299 /// };
2300 /// const RAIL_ChannelConfig_t generated2_channelConfig = {
2301 /// .phyConfigBase = generated2,
2302 /// .phyConfigDeltaSubtract = NULL,
2303 /// .configs = generated2_channels,
2304 /// .length = 1,
2305 /// };
2306 /// const RAIL_ChannelConfig_t *channelConfigs[] = {
2307 /// &generated0_channelConfig,
2308 /// &generated1_channelConfig,
2309 /// &generated2_channelConfig,
2310 /// NULL,
2311 /// };
2312 /// // ... in main code ...
2313 /// // Create a unique RAIL handle for each unique channel configuration.
2314 /// railHandle0 = RAIL_Init(&railCfg0, &RAILCb_RfReady0);
2315 /// railHandle1 = RAIL_Init(&railCfg1, &RAILCb_RfReady1);
2316 /// railHandle2 = RAIL_Init(&railCfg2, &RAILCb_RfReady2);
2317 /// // Associate each channel configuration with its corresponding RAIL handle.
2318 /// RAIL_ConfigChannels(railHandle0, channelConfigs[0]);
2319 /// RAIL_ConfigChannels(railHandle1, channelConfigs[1]);
2320 /// RAIL_ConfigChannels(railHandle2, channelConfigs[2]);
2321 /// // Use a RAIL handle and channel to access the desired channel configuration entry.
2322 /// RAIL_SetTxPowerDbm(railHandle1, 100); // set 10.0 dBm TX power
2323 /// RAIL_StartRx(railHandle1, 0, &schedInfo); // RX using generated1_channels[2]
2324 /// RAIL_SetTxPowerDbm(railHandle1, 0); // set 0 dBm TX power
2325 /// RAIL_StartRx(railHandle1, 0, &schedInfo); // RX using generated1_channels[1]
2326 /// RAIL_StartRx(railHandle2, 0, &schedInfo); // RX using generated2_channels[0]
2327 /// @endcode
2328 ///
2329 typedef struct RAIL_ChannelConfig {
2330 /**
2331 * Base radio configuration for the corresponding
2332 * channel configuration entries.
2333 */
2334 RAIL_RadioConfig_t phyConfigBase;
2335 /**
2336 * Minimum radio configuration to restore
2337 * channel entries back to base configuration.
2338 */
2339 RAIL_RadioConfig_t phyConfigDeltaSubtract;
2340 /** Pointer to an array of \ref RAIL_ChannelConfigEntry_t entries. */
2341 const RAIL_ChannelConfigEntry_t *configs;
2342 /** Number of \ref RAIL_ChannelConfigEntry_t entries. */
2343 uint32_t length;
2344 /** Signature for this structure. Only used on modules. */
2345 uint32_t signature;
2346 /** Crystal Frequency for the channel config. */
2347 uint32_t xtalFrequencyHz;
2348 } RAIL_ChannelConfig_t;
2349
2350 /**
2351 * @struct RAIL_ChannelMetadata_t
2352 * @brief Container for individual channel metadata.
2353 */
2354 typedef struct RAIL_ChannelMetadata {
2355 /** Channel number */
2356 uint16_t channel;
2357 /** Word alignment */
2358 uint16_t reserved;
2359 /** Channel frequency, in Hz */
2360 uint32_t frequency;
2361 } RAIL_ChannelMetadata_t;
2362
2363 /**
2364 * @struct RAIL_StackInfoCommon_t
2365 * @brief Stack info fields common to all protocols.
2366 */
2367 typedef struct RAIL_StackInfoCommon {
2368 /** Same as \ref RAIL_PtiProtocol_t. */
2369 uint8_t protocolId;
2370 /** PHY Id depending on the protocolId value. */
2371 uint8_t phyId;
2372 } RAIL_StackInfoCommon_t;
2373
2374 /**
2375 * @typedef RAIL_RadioConfigChangedCallback_t
2376 * @brief A pointer to a function called whenever a radio configuration change occurs.
2377 *
2378 * @param[in] railHandle The corresponding RAIL instance handle.
2379 * @param[in] entry A pointer to the radio configuration entry being changed to.
2380 */
2381 typedef void (*RAIL_RadioConfigChangedCallback_t)(RAIL_Handle_t railHandle,
2382 const RAIL_ChannelConfigEntry_t *entry);
2383
2384 /** @} */ // end of group Radio_Configuration
2385
2386 /******************************************************************************
2387 * Packet Trace Interface (PTI) Structures
2388 *****************************************************************************/
2389 /**
2390 * @addtogroup PTI PTI Packet Trace
2391 * @{
2392 *
2393 * These enumerations and structures are used with RAIL PTI API. EFR32 supports
2394 * SPI and UART PTI and is configurable in terms of baud rates and PTI
2395 * pin locations.
2396 */
2397
2398 /** A channel type enumeration. */
RAIL_ENUM(RAIL_PtiMode_t)2399 RAIL_ENUM(RAIL_PtiMode_t) {
2400 /** Turn PTI off entirely. */
2401 RAIL_PTI_MODE_DISABLED = 0,
2402 /** 8-bit SPI mode. */
2403 RAIL_PTI_MODE_SPI = 1,
2404 /** 8-bit UART mode. */
2405 RAIL_PTI_MODE_UART = 2,
2406 /** 9-bit UART mode. */
2407 RAIL_PTI_MODE_UART_ONEWIRE = 3,
2408 };
2409
2410 #ifndef DOXYGEN_SHOULD_SKIP_THIS
2411 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
2412 #define RAIL_PTI_MODE_DISABLED ((RAIL_PtiMode_t) RAIL_PTI_MODE_DISABLED)
2413 #define RAIL_PTI_MODE_SPI ((RAIL_PtiMode_t) RAIL_PTI_MODE_SPI)
2414 #define RAIL_PTI_MODE_UART ((RAIL_PtiMode_t) RAIL_PTI_MODE_UART)
2415 #define RAIL_PTI_MODE_UART_ONEWIRE ((RAIL_PtiMode_t) RAIL_PTI_MODE_UART_ONEWIRE)
2416 #endif//DOXYGEN_SHOULD_SKIP_THIS
2417
2418 /**
2419 * @struct RAIL_PtiConfig_t
2420 * @brief A configuration for PTI.
2421 */
2422 typedef struct RAIL_PtiConfig {
2423 /** Packet Trace mode (UART or SPI). */
2424 RAIL_PtiMode_t mode;
2425 /** Output baudrate for PTI in Hz. */
2426 uint32_t baud;
2427 /** @deprecated No longer used (ignored). */
2428 uint8_t doutLoc;
2429 /** Data output (DOUT) GPIO port. */
2430 uint8_t doutPort;
2431 /** Data output (DOUT) GPIO pin. */
2432 uint8_t doutPin;
2433 /** @deprecated No longer used (ignored). */
2434 uint8_t dclkLoc;
2435 /** Data clock (DCLK) GPIO port. Only used in SPI mode. */
2436 uint8_t dclkPort;
2437 /** Data clock (DCLK) GPIO pin. Only used in SPI mode. */
2438 uint8_t dclkPin;
2439 /** @deprecated No longer used (ignored). */
2440 uint8_t dframeLoc;
2441 /** Data frame (DFRAME) GPIO port. */
2442 uint8_t dframePort;
2443 /** Data frame (DFRAME) GPIO pin. */
2444 uint8_t dframePin;
2445 } RAIL_PtiConfig_t;
2446
2447 /**
2448 * @enum RAIL_PtiProtocol_t
2449 * @brief The protocol that RAIL outputs via the Packet Trace Interface (PTI).
2450 */
RAIL_ENUM(RAIL_PtiProtocol_t)2451 RAIL_ENUM(RAIL_PtiProtocol_t) {
2452 /** PTI output for a custom protocol. */
2453 RAIL_PTI_PROTOCOL_CUSTOM = 0,
2454 /** PTI output for the Thread protocol. */
2455 RAIL_PTI_PROTOCOL_THREAD = 2,
2456 /** PTI output for the Bluetooth Smart protocol. */
2457 RAIL_PTI_PROTOCOL_BLE = 3,
2458 /** PTI output for the Connect protocol. */
2459 RAIL_PTI_PROTOCOL_CONNECT = 4,
2460 /** PTI output for the Zigbee protocol. */
2461 RAIL_PTI_PROTOCOL_ZIGBEE = 5,
2462 /** PTI output for the Z-Wave protocol. */
2463 RAIL_PTI_PROTOCOL_ZWAVE = 6,
2464 /** PTI output for the Wi-SUN protocol. */
2465 RAIL_PTI_PROTOCOL_WISUN = 7,
2466 /** PTI output for a custom protocol using a built-in 802.15.4 radio config. */
2467 RAIL_PTI_PROTOCOL_802154 = 8,
2468 /** PTI output for Sidewalk protocol. */
2469 RAIL_PTI_PROTOCOL_SIDEWALK = 9,
2470 };
2471
2472 #ifndef DOXYGEN_SHOULD_SKIP_THIS
2473 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
2474 #define RAIL_PTI_PROTOCOL_CUSTOM ((RAIL_PtiProtocol_t) RAIL_PTI_PROTOCOL_CUSTOM)
2475 #define RAIL_PTI_PROTOCOL_THREAD ((RAIL_PtiProtocol_t) RAIL_PTI_PROTOCOL_THREAD)
2476 #define RAIL_PTI_PROTOCOL_BLE ((RAIL_PtiProtocol_t) RAIL_PTI_PROTOCOL_BLE)
2477 #define RAIL_PTI_PROTOCOL_CONNECT ((RAIL_PtiProtocol_t) RAIL_PTI_PROTOCOL_CONNECT)
2478 #define RAIL_PTI_PROTOCOL_ZIGBEE ((RAIL_PtiProtocol_t) RAIL_PTI_PROTOCOL_ZIGBEE)
2479 #define RAIL_PTI_PROTOCOL_ZWAVE ((RAIL_PtiProtocol_t) RAIL_PTI_PROTOCOL_ZWAVE)
2480 #define RAIL_PTI_PROTOCOL_802154 ((RAIL_PtiProtocol_t) RAIL_PTI_PROTOCOL_802154)
2481 #define RAIL_PTI_PROTOCOL_SIDEWALK ((RAIL_PtiProtocol_t) RAIL_PTI_PROTOCOL_SIDEWALK)
2482 #endif//DOXYGEN_SHOULD_SKIP_THIS
2483
2484 /** @} */ // end of group PTI
2485
2486 /******************************************************************************
2487 * Data Management Structures
2488 *****************************************************************************/
2489 /**
2490 * @addtogroup Data_Management
2491 * @{
2492 */
2493
2494 /// Fixed-width type indicating the needed alignment for RX and TX FIFOs.
2495 #define RAIL_FIFO_ALIGNMENT_TYPE uint32_t
2496
2497 /// Alignment that is needed for the RX and TX FIFOs.
2498 #define RAIL_FIFO_ALIGNMENT (sizeof(RAIL_FIFO_ALIGNMENT_TYPE))
2499
2500 /**
2501 * @enum RAIL_TxDataSource_t
2502 * @brief Transmit data sources supported by RAIL.
2503 */
RAIL_ENUM(RAIL_TxDataSource_t)2504 RAIL_ENUM(RAIL_TxDataSource_t) {
2505 /** Uses the frame hardware to packetize data. */
2506 TX_PACKET_DATA = 0,
2507 /**
2508 * Uses the multi-level frequency modulation data.
2509 * @note This is only supported on devices where \ref RAIL_SUPPORTS_MFM
2510 * or \ref RAIL_SupportsMfm() are true.
2511 * @note This feature cannot be used with built-in protocols (802.15.4, BLE,
2512 * Z-Wave).
2513 */
2514 TX_MFM_DATA = 1,
2515 /** A count of the choices in this enumeration. Must be last. */
2516 RAIL_TX_DATA_SOURCE_COUNT
2517 };
2518
2519 #ifndef DOXYGEN_SHOULD_SKIP_THIS
2520 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
2521 #define TX_PACKET_DATA ((RAIL_TxDataSource_t) TX_PACKET_DATA)
2522 #define TX_MFM_DATA ((RAIL_TxDataSource_t) TX_MFM_DATA)
2523 #define RAIL_TX_DATA_SOURCE_COUNT ((RAIL_TxDataSource_t) RAIL_TX_DATA_SOURCE_COUNT)
2524 #endif//DOXYGEN_SHOULD_SKIP_THIS
2525
2526 /**
2527 * @enum RAIL_RxDataSource_t
2528 * @brief Receive data sources supported by RAIL.
2529 *
2530 * @note Data sources other than \ref RX_PACKET_DATA require use of
2531 * \ref RAIL_DataMethod_t::FIFO_MODE.
2532 */
RAIL_ENUM(RAIL_RxDataSource_t)2533 RAIL_ENUM(RAIL_RxDataSource_t) {
2534 /** Uses the frame hardware to packetize data. */
2535 RX_PACKET_DATA = 0,
2536 /** Gets 8-bit data output from the demodulator. */
2537 RX_DEMOD_DATA = 1,
2538 /** Gets lower 16 bits of I/Q data provided to the demodulator. */
2539 RX_IQDATA_FILTLSB = 2,
2540 /** Gets highest 16 bits of I/Q data provided to the demodulator. */
2541 RX_IQDATA_FILTMSB = 3,
2542 /**
2543 * Gets RX direct mode data output from the demodulator.
2544 * BCRDEMOD captures bcr_dmod_rawd at the sample rate
2545 * (faster than the bit rate by the OSR), specifically
2546 * the demod_samp_rate trigger.
2547 * Only supported if \ref RAIL_SUPPORTS_RX_DIRECT_MODE_DATA_TO_FIFO is true.
2548 */
2549 RX_DIRECT_MODE_DATA = 4,
2550 /**
2551 * Gets synchronous RX direct mode data output from the demodulator.
2552 * BCRDEMOD_SYNCHRONOUS captures bcr_dmod_rxd_ext at the bit
2553 * rate (bcr_dmod_bitclk_ext trigger).
2554 * Only supported if \ref RAIL_SUPPORTS_RX_DIRECT_MODE_DATA_TO_FIFO is true.
2555 * Only efr32xg23, efr32xg25, or efr32xg28 have this mode.
2556 */
2557 RX_DIRECT_SYNCHRONOUS_MODE_DATA = 5,
2558 /** A count of the choices in this enumeration. Must be last. */
2559 RAIL_RX_DATA_SOURCE_COUNT
2560 };
2561
2562 #ifndef DOXYGEN_SHOULD_SKIP_THIS
2563 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
2564 #define RX_PACKET_DATA ((RAIL_RxDataSource_t) RX_PACKET_DATA)
2565 #define RX_DEMOD_DATA ((RAIL_RxDataSource_t) RX_DEMOD_DATA)
2566 #define RX_IQDATA_FILTLSB ((RAIL_RxDataSource_t) RX_IQDATA_FILTLSB)
2567 #define RX_IQDATA_FILTMSB ((RAIL_RxDataSource_t) RX_IQDATA_FILTMSB)
2568 #define RX_DIRECT_MODE_DATA ((RAIL_RxDataSource_t) RX_DIRECT_MODE_DATA)
2569 #define RX_DIRECT_SYNCHRONOUS_MODE_DATA ((RAIL_RxDataSource_t) RX_DIRECT_SYNCHRONOUS_MODE_DATA)
2570 #define RAIL_RX_DATA_SOURCE_COUNT ((RAIL_RxDataSource_t) RAIL_RX_DATA_SOURCE_COUNT)
2571 #endif//DOXYGEN_SHOULD_SKIP_THIS
2572
2573 /**
2574 * @enum RAIL_DataMethod_t
2575 * @brief Methods for the application to provide and retrieve data from RAIL.
2576 *
2577 * For Transmit the distinction between \ref RAIL_DataMethod_t::PACKET_MODE
2578 * and \ref RAIL_DataMethod_t::FIFO_MODE has become more cosmetic than
2579 * functional, as the \ref RAIL_WriteTxFifo() and \ref RAIL_SetTxFifoThreshold() APIs
2580 * and related \ref RAIL_EVENT_TX_FIFO_ALMOST_EMPTY event can be used in
2581 * either mode. For Receive the distinction is functionally important because
2582 * in \ref RAIL_DataMethod_t::PACKET_MODE rollback occurs automatically for
2583 * unsuccessfully-received packets (\ref RAIL_RxPacketStatus_t ABORT statuses),
2584 * flushing their data. In \ref RAIL_DataMethod_t::FIFO_MODE rollback is
2585 * prevented, leaving the data from unsuccessfully-received packets in the
2586 * receive FIFO for the application to deal with. This allows for packets
2587 * larger than the receive FIFO size where automatic rollback would corrupt
2588 * the receive FIFO.
2589 */
RAIL_ENUM(RAIL_DataMethod_t)2590 RAIL_ENUM(RAIL_DataMethod_t) {
2591 /** Packet-based data method. */
2592 PACKET_MODE = 0,
2593 /** FIFO-based data method. */
2594 FIFO_MODE = 1,
2595 /** A count of the choices in this enumeration. Must be last. */
2596 RAIL_DATA_METHOD_COUNT
2597 };
2598
2599 #ifndef DOXYGEN_SHOULD_SKIP_THIS
2600 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
2601 #define PACKET_MODE ((RAIL_DataMethod_t) PACKET_MODE)
2602 #define FIFO_MODE ((RAIL_DataMethod_t) FIFO_MODE)
2603 #define RAIL_DATA_METHOD_COUNT ((RAIL_DataMethod_t) RAIL_DATA_METHOD_COUNT)
2604 #endif//DOXYGEN_SHOULD_SKIP_THIS
2605
2606 /**
2607 * @def RAIL_FIFO_THRESHOLD_DISABLED
2608 * @brief A FIFO threshold value that disables the threshold.
2609 */
2610 #define RAIL_FIFO_THRESHOLD_DISABLED 0xFFFFU
2611
2612 /**
2613 * @struct RAIL_DataConfig_t
2614 * @brief RAIL data configuration structure
2615 *
2616 * Select the transmit/receive data sources and the
2617 * method the application uses to provide/retrieve data from RAIL.
2618 */
2619 typedef struct {
2620 /** Source of TX Data. */
2621 RAIL_TxDataSource_t txSource;
2622 /** Source of RX Data. */
2623 RAIL_RxDataSource_t rxSource;
2624 /** Method of providing transmit data. */
2625 RAIL_DataMethod_t txMethod;
2626 /** Method of retrieving receive data. */
2627 RAIL_DataMethod_t rxMethod;
2628 } RAIL_DataConfig_t;
2629
2630 /** @} */ // end of group Data Management
2631
2632 /******************************************************************************
2633 * State Transitions
2634 *****************************************************************************/
2635 /**
2636 * @addtogroup State_Transitions
2637 * @{
2638 */
2639
2640 /**
2641 * @typedef RAIL_TransitionTime_t
2642 * @brief Suitable type for the supported transition time range.
2643 *
2644 * Refer to platform-specific \ref RAIL_MINIMUM_TRANSITION_US and
2645 * \ref RAIL_MAXIMUM_TRANSITION_US for the valid range of this type.
2646 */
2647 typedef uint32_t RAIL_TransitionTime_t;
2648
2649 /**
2650 * @def RAIL_TRANSITION_TIME_KEEP
2651 * @brief A value to use in \ref RAIL_StateTiming_t fields when
2652 * calling \ref RAIL_SetStateTiming() to keep that timing
2653 * parameter at it current setting.
2654 */
2655 #define RAIL_TRANSITION_TIME_KEEP ((RAIL_TransitionTime_t) -1)
2656
2657 /**
2658 * @struct RAIL_StateTiming_t
2659 * @brief A timing configuration structure for the RAIL State Machine.
2660 *
2661 * Configure the timings of the radio state transitions for common situations.
2662 * All of the listed timings are in microseconds. Transitions from an active
2663 * radio state to idle are not configurable, and will always happen as fast
2664 * as possible.
2665 * No timing value can exceed platform-specific \ref RAIL_MAXIMUM_TRANSITION_US.
2666 * Use \ref RAIL_TRANSITION_TIME_KEEP to keep an existing setting.
2667 *
2668 * For idleToRx, idleToTx, rxToTx, txToRx, and txToTx a value of 0 for the
2669 * transition time means that the specified transition should happen as fast
2670 * as possible, even if the timing cannot be as consistent. Otherwise, the
2671 * timing value cannot be below the platform-specific \ref RAIL_MINIMUM_TRANSITION_US.
2672 *
2673 * For idleToTx, rxToTx, and txToTx setting a longer \ref
2674 * RAIL_TxPowerConfig_t::rampTime may result in a larger minimum value.
2675 *
2676 * For rxSearchTimeout and txToRxSearchTimeout, there is no minimum value.
2677 * A value of 0 disables the feature, functioning as an infinite timeout.
2678 */
2679 typedef struct RAIL_StateTiming {
2680 /** Transition time from IDLE to RX. */
2681 RAIL_TransitionTime_t idleToRx;
2682 /** Transition time from TX to RX. */
2683 RAIL_TransitionTime_t txToRx;
2684 /** Transition time from IDLE to TX. */
2685 RAIL_TransitionTime_t idleToTx;
2686 /** Transition time from RX packet to TX. */
2687 RAIL_TransitionTime_t rxToTx;
2688 /** Length of time the radio will search for a packet when coming from idle or RX. */
2689 RAIL_TransitionTime_t rxSearchTimeout;
2690 /** Length of time the radio will search for a packet when coming from TX. */
2691 RAIL_TransitionTime_t txToRxSearchTimeout;
2692 /** Transition time from TX packet to TX. */
2693 RAIL_TransitionTime_t txToTx;
2694 } RAIL_StateTiming_t;
2695
2696 /**
2697 * @enum RAIL_RadioState_t
2698 * @brief The state of the radio.
2699 */
RAIL_ENUM(RAIL_RadioState_t)2700 RAIL_ENUM(RAIL_RadioState_t) {
2701 /** Radio is inactive. */
2702 RAIL_RF_STATE_INACTIVE = 0u,
2703 /**
2704 * Radio is either idle or, in combination with the RX and TX states,
2705 * receiving or transmitting a frame.
2706 */
2707 RAIL_RF_STATE_ACTIVE = (1u << 0),
2708 /** Radio is in receive. */
2709 RAIL_RF_STATE_RX = (1u << 1),
2710 /** Radio is in transmit. */
2711 RAIL_RF_STATE_TX = (1u << 2),
2712 /** Radio is idle. */
2713 RAIL_RF_STATE_IDLE = (RAIL_RF_STATE_ACTIVE),
2714 /** Radio is actively receiving a frame. */
2715 RAIL_RF_STATE_RX_ACTIVE = (RAIL_RF_STATE_RX | RAIL_RF_STATE_ACTIVE),
2716 /** Radio is actively transmitting a frame. */
2717 RAIL_RF_STATE_TX_ACTIVE = (RAIL_RF_STATE_TX | RAIL_RF_STATE_ACTIVE)
2718 };
2719
2720 #ifndef DOXYGEN_SHOULD_SKIP_THIS
2721 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
2722 #define RAIL_RF_STATE_INACTIVE ((RAIL_RadioState_t) RAIL_RF_STATE_INACTIVE)
2723 #define RAIL_RF_STATE_ACTIVE ((RAIL_RadioState_t) RAIL_RF_STATE_ACTIVE)
2724 #define RAIL_RF_STATE_RX ((RAIL_RadioState_t) RAIL_RF_STATE_RX)
2725 #define RAIL_RF_STATE_TX ((RAIL_RadioState_t) RAIL_RF_STATE_TX)
2726 #define RAIL_RF_STATE_IDLE ((RAIL_RadioState_t) RAIL_RF_STATE_IDLE)
2727 #define RAIL_RF_STATE_RX_ACTIVE ((RAIL_RadioState_t) RAIL_RF_STATE_RX_ACTIVE)
2728 #define RAIL_RF_STATE_TX_ACTIVE ((RAIL_RadioState_t) RAIL_RF_STATE_TX_ACTIVE)
2729 #endif//DOXYGEN_SHOULD_SKIP_THIS
2730
2731 #ifndef DOXYGEN_SHOULD_SKIP_THIS
2732 /**
2733 * @enum RAIL_RadioStateEfr32_t
2734 * @brief Detailed EFR32 Radio state machine states.
2735 */
RAIL_ENUM(RAIL_RadioStateEfr32_t)2736 RAIL_ENUM(RAIL_RadioStateEfr32_t) {
2737 /** Radio is off. */
2738 RAIL_RAC_STATE_OFF = 0,
2739 /** Radio is enabling the receiver. */
2740 RAIL_RAC_STATE_RXWARM = 1,
2741 /** Radio is listening for incoming frames. */
2742 RAIL_RAC_STATE_RXSEARCH = 2,
2743 /** Radio is receiving a frame. */
2744 RAIL_RAC_STATE_RXFRAME = 3,
2745 /** Radio is powering down receiver and going to OFF state. */
2746 RAIL_RAC_STATE_RXPD = 4,
2747 /** Radio is going back to receive mode after receiving a frame. */
2748 RAIL_RAC_STATE_RX2RX = 5,
2749 /** Received data was lost due to full receive buffer. */
2750 RAIL_RAC_STATE_RXOVERFLOW = 6,
2751 /** Radio is disabling receiver and enabling transmitter. */
2752 RAIL_RAC_STATE_RX2TX = 7,
2753 /** Radio is enabling transmitter. */
2754 RAIL_RAC_STATE_TXWARM = 8,
2755 /** Radio is transmitting data. */
2756 RAIL_RAC_STATE_TX = 9,
2757 /** Radio is powering down transmitter and going to OFF state. */
2758 RAIL_RAC_STATE_TXPD = 10,
2759 /** Radio is disabling transmitter and enabling reception. */
2760 RAIL_RAC_STATE_TX2RX = 11,
2761 /** Radio is preparing a transmission after the previous transmission was ended. */
2762 RAIL_RAC_STATE_TX2TX = 12,
2763 /** Radio is powering down and going to OFF state. */
2764 RAIL_RAC_STATE_SHUTDOWN = 13,
2765 /** Radio power-on-reset state (EFR32xG22 and later). */
2766 RAIL_RAC_STATE_POR = 14,
2767 /** Invalid Radio state, must be the last entry. */
2768 RAIL_RAC_STATE_NONE
2769 };
2770
2771 #ifndef DOXYGEN_SHOULD_SKIP_THIS
2772 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
2773 #define RAIL_RAC_STATE_OFF ((RAIL_RadioStateEfr32_t) RAIL_RAC_STATE_OFF)
2774 #define RAIL_RAC_STATE_RXWARM ((RAIL_RadioStateEfr32_t) RAIL_RAC_STATE_RXWARM)
2775 #define RAIL_RAC_STATE_RXSEARCH ((RAIL_RadioStateEfr32_t) RAIL_RAC_STATE_RXSEARCH)
2776 #define RAIL_RAC_STATE_RXFRAME ((RAIL_RadioStateEfr32_t) RAIL_RAC_STATE_RXFRAME)
2777 #define RAIL_RAC_STATE_RXPD ((RAIL_RadioStateEfr32_t) RAIL_RAC_STATE_RXPD)
2778 #define RAIL_RAC_STATE_RX2RX ((RAIL_RadioStateEfr32_t) RAIL_RAC_STATE_RX2RX)
2779 #define RAIL_RAC_STATE_RXOVERFLOW ((RAIL_RadioStateEfr32_t) RAIL_RAC_STATE_RXOVERFLOW)
2780 #define RAIL_RAC_STATE_RX2TX ((RAIL_RadioStateEfr32_t) RAIL_RAC_STATE_RX2TX)
2781 #define RAIL_RAC_STATE_TXWARM ((RAIL_RadioStateEfr32_t) RAIL_RAC_STATE_TXWARM)
2782 #define RAIL_RAC_STATE_TX ((RAIL_RadioStateEfr32_t) RAIL_RAC_STATE_TX)
2783 #define RAIL_RAC_STATE_TXPD ((RAIL_RadioStateEfr32_t) RAIL_RAC_STATE_TXPD)
2784 #define RAIL_RAC_STATE_TX2RX ((RAIL_RadioStateEfr32_t) RAIL_RAC_STATE_TX2RX)
2785 #define RAIL_RAC_STATE_TX2TX ((RAIL_RadioStateEfr32_t) RAIL_RAC_STATE_TX2TX)
2786 #define RAIL_RAC_STATE_SHUTDOWN ((RAIL_RadioStateEfr32_t) RAIL_RAC_STATE_SHUTDOWN)
2787 #define RAIL_RAC_STATE_POR ((RAIL_RadioStateEfr32_t) RAIL_RAC_STATE_POR)
2788 #define RAIL_RAC_STATE_NONE ((RAIL_RadioStateEfr32_t) RAIL_RAC_STATE_NONE)
2789 #endif//DOXYGEN_SHOULD_SKIP_THIS
2790 #endif//DOXYGEN_SHOULD_SKIP_THIS
2791
2792 /**
2793 * @struct RAIL_StateTransitions_t
2794 * @brief Used to specify radio states to transition to on success or failure.
2795 */
2796 typedef struct RAIL_StateTransitions {
2797 /**
2798 * Indicate the state the radio should return to after a successful action.
2799 */
2800 RAIL_RadioState_t success;
2801 /**
2802 * Indicate the state the radio should return to after an error.
2803 */
2804 RAIL_RadioState_t error;
2805 } RAIL_StateTransitions_t;
2806
2807 /**
2808 * @enum RAIL_RadioStateDetail_t
2809 * @brief The detailed state of the radio.
2810 *
2811 * The three radio state bits \ref RAIL_RF_STATE_DETAIL_IDLE_STATE, \ref
2812 * RAIL_RF_STATE_DETAIL_RX_STATE, and \ref RAIL_RF_STATE_DETAIL_TX_STATE
2813 * comprise a set of mutually exclusive core radio states. Only one (or none)
2814 * of these bits can be set at a time. Otherwise, the value is invalid.
2815 *
2816 * The precise meaning of each of these three core bits, when set, depends on
2817 * the value of the two bits \ref RAIL_RF_STATE_DETAIL_TRANSITION and \ref
2818 * RAIL_RF_STATE_DETAIL_ACTIVE. When \ref RAIL_RF_STATE_DETAIL_TRANSITION is
2819 * set, the radio is transitioning into the core radio state corresponding
2820 * to the set state bit. When it is clear, the radio is already in the core
2821 * radio state that corresponds to the set state bit. When \ref
2822 * RAIL_RF_STATE_DETAIL_ACTIVE is set, the radio is actively transmitting or
2823 * receiving. When it is clear, the radio is not actively transmitting or receiving.
2824 * This bit will always be clear when \ref RAIL_RF_STATE_DETAIL_IDLE_STATE is
2825 * set, and will always be set when \ref RAIL_RF_STATE_DETAIL_TX_STATE is set.
2826 * Otherwise, the value is invalid.
2827 *
2828 * The bit \ref RAIL_RF_STATE_DETAIL_NO_FRAMES is set if the radio is currently
2829 * operating with frame detection disabled, and clear otherwise. The bit \ref
2830 * RAIL_RF_STATE_DETAIL_LBT_SHIFT is set if an LBT/CSMA operation
2831 * (e.g., performing CCA) is currently ongoing, and clear otherwise.
2832 */
RAIL_ENUM(RAIL_RadioStateDetail_t)2833 RAIL_ENUM(RAIL_RadioStateDetail_t) {
2834 /** Shift position of \ref RAIL_RF_STATE_DETAIL_IDLE_STATE bit. */
2835 RAIL_RF_STATE_DETAIL_IDLE_STATE_SHIFT = 0,
2836 /** Shift position of \ref RAIL_RF_STATE_DETAIL_RX_STATE bit. */
2837 RAIL_RF_STATE_DETAIL_RX_STATE_SHIFT = 1,
2838 /** Shift position of \ref RAIL_RF_STATE_DETAIL_TX_STATE bit. */
2839 RAIL_RF_STATE_DETAIL_TX_STATE_SHIFT = 2,
2840 /** Shift position of \ref RAIL_RF_STATE_DETAIL_TRANSITION bit. */
2841 RAIL_RF_STATE_DETAIL_TRANSITION_SHIFT = 3,
2842 /** Shift position of \ref RAIL_RF_STATE_DETAIL_ACTIVE bit. */
2843 RAIL_RF_STATE_DETAIL_ACTIVE_SHIFT = 4,
2844 /** Shift position of \ref RAIL_RF_STATE_DETAIL_NO_FRAMES bit. */
2845 RAIL_RF_STATE_DETAIL_NO_FRAMES_SHIFT = 5,
2846 /** Shift position of \ref RAIL_RF_STATE_DETAIL_LBT bit. */
2847 RAIL_RF_STATE_DETAIL_LBT_SHIFT = 6,
2848 };
2849
2850 /** Radio is inactive. */
2851 #define RAIL_RF_STATE_DETAIL_INACTIVE (0U)
2852 /** Radio is in or headed to the idle state. */
2853 #define RAIL_RF_STATE_DETAIL_IDLE_STATE (1U << RAIL_RF_STATE_DETAIL_IDLE_STATE_SHIFT)
2854 /** Radio is in or headed to the receive state. */
2855 #define RAIL_RF_STATE_DETAIL_RX_STATE (1U << RAIL_RF_STATE_DETAIL_RX_STATE_SHIFT)
2856 /** Radio is in or headed to the transmit state. */
2857 #define RAIL_RF_STATE_DETAIL_TX_STATE (1U << RAIL_RF_STATE_DETAIL_TX_STATE_SHIFT)
2858 /** Radio is headed to the idle, receive, or transmit state. */
2859 #define RAIL_RF_STATE_DETAIL_TRANSITION (1U << RAIL_RF_STATE_DETAIL_TRANSITION_SHIFT)
2860 /** Radio is actively transmitting or receiving. */
2861 #define RAIL_RF_STATE_DETAIL_ACTIVE (1U << RAIL_RF_STATE_DETAIL_ACTIVE_SHIFT)
2862 /** Radio has frame detect disabled. */
2863 #define RAIL_RF_STATE_DETAIL_NO_FRAMES (1U << RAIL_RF_STATE_DETAIL_NO_FRAMES_SHIFT)
2864 /** LBT/CSMA operation is currently ongoing. */
2865 #define RAIL_RF_STATE_DETAIL_LBT (1U << RAIL_RF_STATE_DETAIL_LBT_SHIFT)
2866 /** Mask for core radio state bits. */
2867 #define RAIL_RF_STATE_DETAIL_CORE_STATE_MASK (RAIL_RF_STATE_DETAIL_IDLE_STATE \
2868 | RAIL_RF_STATE_DETAIL_RX_STATE \
2869 | RAIL_RF_STATE_DETAIL_TX_STATE)
2870
2871 /**
2872 * @enum RAIL_IdleMode_t
2873 * @brief An enumeration for the different types of supported idle modes. These
2874 * vary how quickly and destructively they put the radio into idle.
2875 */
RAIL_ENUM(RAIL_IdleMode_t)2876 RAIL_ENUM(RAIL_IdleMode_t) {
2877 /**
2878 * Idle the radio by turning off receive and canceling any future scheduled
2879 * receive or transmit operations. It does not abort a receive or
2880 * transmit in progress.
2881 */
2882 RAIL_IDLE = 0u,
2883 /**
2884 * Idle the radio by turning off receive and any scheduled events. It
2885 * also aborts any receive, transmit, or scheduled events in progress.
2886 */
2887 RAIL_IDLE_ABORT = 1u,
2888 /**
2889 * Force the radio into a shutdown mode by stopping whatever state is in
2890 * progress. This is a more destructive shutdown than \ref RAIL_IDLE or
2891 * \ref RAIL_IDLE_ABORT and can be useful in certain situations when directed
2892 * by the support team or for debugging. Note that this method may corrupt
2893 * receive and transmit buffers so it requires a more thorough cleanup
2894 * and any held packets will be lost.
2895 */
2896 RAIL_IDLE_FORCE_SHUTDOWN = 2u,
2897 /**
2898 * Similar to the \ref RAIL_IDLE_FORCE_SHUTDOWN command, however, it will also
2899 * clear any pending RAIL events related to receive and transmit.
2900 */
2901 RAIL_IDLE_FORCE_SHUTDOWN_CLEAR_FLAGS = 3u,
2902 };
2903
2904 #ifndef DOXYGEN_SHOULD_SKIP_THIS
2905 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
2906 #define RAIL_IDLE ((RAIL_IdleMode_t) RAIL_IDLE)
2907 #define RAIL_IDLE_ABORT ((RAIL_IdleMode_t) RAIL_IDLE_ABORT)
2908 #define RAIL_IDLE_FORCE_SHUTDOWN ((RAIL_IdleMode_t) RAIL_IDLE_FORCE_SHUTDOWN)
2909 #define RAIL_IDLE_FORCE_SHUTDOWN_CLEAR_FLAGS ((RAIL_IdleMode_t) RAIL_IDLE_FORCE_SHUTDOWN_CLEAR_FLAGS)
2910 #endif//DOXYGEN_SHOULD_SKIP_THIS
2911
2912 /** @} */ // end of group State_Transitions
2913
2914 /******************************************************************************
2915 * TX Channel Hopping
2916 *****************************************************************************/
2917 /**
2918 * @addtogroup Tx_Channel_Hopping TX Channel Hopping
2919 * @{
2920 */
2921
2922 /**
2923 * @struct RAIL_TxChannelHoppingConfigEntry_t
2924 * @brief Structure that represents one of the channels that is part of a
2925 * \ref RAIL_TxChannelHoppingConfig_t sequence of channels used in
2926 * channel hopping.
2927 */
2928 typedef struct RAIL_TxChannelHoppingConfigEntry {
2929 /**
2930 * The channel number to be used for this entry in the channel hopping
2931 * sequence. If this is an invalid channel for the current PHY, the
2932 * call to \ref RAIL_SetNextTxRepeat() will fail.
2933 */
2934 uint16_t channel;
2935 /**
2936 * Pad bytes reserved for future use and currently ignored.
2937 */
2938 uint8_t reserved[2];
2939 /**
2940 * Idle time in microseconds to wait before transmitting on the channel
2941 * indicated by this entry.
2942 */
2943 uint32_t delay;
2944 } RAIL_TxChannelHoppingConfigEntry_t;
2945
2946 /**
2947 * @struct RAIL_TxChannelHoppingConfig_t
2948 * @brief Wrapper struct that will contain the sequence of
2949 * \ref RAIL_TxChannelHoppingConfigEntry_t that represents the channel
2950 * sequence to use during TX Channel Hopping.
2951 */
2952 typedef struct RAIL_TxChannelHoppingConfig {
2953 /**
2954 * Pointer to contiguous global read-write memory that will be used
2955 * by RAIL to store channel hopping information throughout its operation.
2956 * It need not be initialized and applications should never write
2957 * data anywhere in this buffer.
2958 *
2959 * @note The size of this buffer must be at least as large as
2960 * 3 + \ref RAIL_CHANNEL_HOPPING_BUFFER_SIZE_PER_CHANNEL * numberOfChannels,
2961 * plus the sum of the sizes of the
2962 * radioConfigDeltaAdd's of the required channels, plus the size of the
2963 * radioConfigDeltaSubtract. In the case that one channel
2964 * appears two or more times in your channel sequence
2965 * (e.g., 1, 2, 3, 2), you must account for the radio configuration
2966 * size that number of times (i.e., need to count channel 2's
2967 * radio configuration size twice for the given example). The buffer is
2968 * for internal use to the library.
2969 */
2970 uint32_t *buffer;
2971 /**
2972 * This parameter must be set to the length of the buffer array, in 32 bit
2973 * words. This way, during configuration, the software can confirm it's
2974 * writing within the bounds of the buffer. The configuration API will return
2975 * an error or trigger \ref RAIL_ASSERT_CHANNEL_HOPPING_BUFFER_TOO_SHORT if
2976 * bufferLength is insufficient.
2977 */
2978 uint16_t bufferLength;
2979 /**
2980 * The number of channels in the channel hopping sequence, which is the
2981 * number of elements in the array that entries points to.
2982 */
2983 uint8_t numberOfChannels;
2984 /**
2985 * Pad byte reserved for future use and currently ignored.
2986 */
2987 uint8_t reserved;
2988 /**
2989 * A pointer to the first element of an array of \ref
2990 * RAIL_TxChannelHoppingConfigEntry_t that represents the channels
2991 * used during channel hopping. The length of this array must be
2992 * numberOfChannels.
2993 */
2994 RAIL_TxChannelHoppingConfigEntry_t *entries;
2995 } RAIL_TxChannelHoppingConfig_t;
2996
2997 /// The worst-case platform-agnostic static amount of memory needed per
2998 /// channel for channel hopping, measured in 32 bit words, regardless of
2999 /// the size of radio configuration structures.
3000 #define RAIL_CHANNEL_HOPPING_BUFFER_SIZE_PER_CHANNEL_WORST_CASE (65U)
3001
3002 /** @} */ // end of group Tx_Channel_Hopping
3003
3004 /******************************************************************************
3005 * TX/RX Configuration Structures
3006 *****************************************************************************/
3007 /**
3008 * @addtogroup Transmit
3009 * @{
3010 */
3011
3012 /**
3013 * @enum RAIL_StopMode_t
3014 * @brief Stop radio operation options bit mask
3015 */
RAIL_ENUM(RAIL_StopMode_t)3016 RAIL_ENUM(RAIL_StopMode_t) {
3017 /** Shift position of \ref RAIL_STOP_MODE_ACTIVE bit. */
3018 RAIL_STOP_MODE_ACTIVE_SHIFT = 0,
3019 /** Shift position of \ref RAIL_STOP_MODE_PENDING bit. */
3020 RAIL_STOP_MODE_PENDING_SHIFT = 1,
3021 };
3022
3023 /** Do not stop any radio operations */
3024 #define RAIL_STOP_MODES_NONE (0U)
3025 /** Stop active radio operations only */
3026 #define RAIL_STOP_MODE_ACTIVE (1U << RAIL_STOP_MODE_ACTIVE_SHIFT)
3027 /** Stop pending radio operations */
3028 #define RAIL_STOP_MODE_PENDING (1U << RAIL_STOP_MODE_PENDING_SHIFT)
3029 /** Stop all radio operations */
3030 #define RAIL_STOP_MODES_ALL (0xFFU)
3031
3032 /**
3033 * @enum RAIL_TxOptions_t
3034 * @brief Transmit options, in reality a bitmask.
3035 */
RAIL_ENUM_GENERIC(RAIL_TxOptions_t,uint32_t)3036 RAIL_ENUM_GENERIC(RAIL_TxOptions_t, uint32_t) {
3037 /** Shift position of \ref RAIL_TX_OPTION_WAIT_FOR_ACK bit. */
3038 RAIL_TX_OPTION_WAIT_FOR_ACK_SHIFT = 0,
3039 /** Shift position of \ref RAIL_TX_OPTION_REMOVE_CRC bit. */
3040 RAIL_TX_OPTION_REMOVE_CRC_SHIFT = 1,
3041 /** Shift position of \ref RAIL_TX_OPTION_SYNC_WORD_ID bit. */
3042 RAIL_TX_OPTION_SYNC_WORD_ID_SHIFT = 2,
3043 /** Shift position of \ref RAIL_TX_OPTION_ANTENNA0 bit. */
3044 RAIL_TX_OPTION_ANTENNA0_SHIFT = 3,
3045 /** Shift position of \ref RAIL_TX_OPTION_ANTENNA1 bit. */
3046 RAIL_TX_OPTION_ANTENNA1_SHIFT = 4,
3047 /** Shift position of \ref RAIL_TX_OPTION_ALT_PREAMBLE_LEN bit. */
3048 RAIL_TX_OPTION_ALT_PREAMBLE_LEN_SHIFT = 5,
3049 /** Shift position of \ref RAIL_TX_OPTION_CCA_PEAK_RSSI bit. */
3050 RAIL_TX_OPTION_CCA_PEAK_RSSI_SHIFT = 6,
3051 /** Shift position of \ref RAIL_TX_OPTION_CCA_ONLY bit. */
3052 RAIL_TX_OPTION_CCA_ONLY_SHIFT = 7,
3053 /** Shift position of \ref RAIL_TX_OPTION_RESEND bit. */
3054 RAIL_TX_OPTION_RESEND_SHIFT = 8,
3055 /** Shift position of \ref RAIL_TX_OPTION_CONCURRENT_PHY_ID bit. */
3056 RAIL_TX_OPTION_CONCURRENT_PHY_ID_SHIFT = 9,
3057 /** A count of the choices in this enumeration. Must be last. */
3058 RAIL_TX_OPTIONS_COUNT
3059 };
3060
3061 /** A value representing no options enabled. */
3062 #define RAIL_TX_OPTIONS_NONE 0UL
3063
3064 /** All options disabled by default. This is the fastest TX option to apply. */
3065 #define RAIL_TX_OPTIONS_DEFAULT RAIL_TX_OPTIONS_NONE
3066
3067 /**
3068 * An option when Auto-Ack has been configured, enabled, and not TX paused, to
3069 * configure whether or not the transmitting node will listen for an Ack
3070 * response.
3071 * If this is false, the \ref RAIL_RxPacketDetails_t::isAck flag of a received
3072 * packet will always be false.
3073 * If Auto-Ack is enabled, for instance using \ref RAIL_ConfigAutoAck() or
3074 * \ref RAIL_IEEE802154_Init(), and if this option is false, the radio
3075 * transitions to \ref RAIL_AutoAckConfig_t::txTransitions's
3076 * \ref RAIL_StateTransitions_t::success state directly after transmitting a
3077 * packet and does not wait for an Ack.
3078 */
3079 #define RAIL_TX_OPTION_WAIT_FOR_ACK (1UL << RAIL_TX_OPTION_WAIT_FOR_ACK_SHIFT)
3080
3081 /**
3082 * An option to remove CRC bytes from TX packets. To receive packets when the
3083 * sender has this option set true, set \ref RAIL_RX_OPTION_IGNORE_CRC_ERRORS
3084 * on the receive side.
3085 */
3086 #define RAIL_TX_OPTION_REMOVE_CRC (1UL << RAIL_TX_OPTION_REMOVE_CRC_SHIFT)
3087
3088 /**
3089 * An option to select which sync word is used during the transmission.
3090 * When two sync words are configured by the PHY or \ref RAIL_ConfigSyncWords()
3091 * enabling this option selects SYNC2 rather than SYNC1 for the upcoming transmit.
3092 *
3093 * This option should not be used when only one sync word has been configured.
3094 *
3095 * @note There are a few special radio configurations (e.g., BLE Viterbi) that do
3096 * not support transmitting different sync words.
3097 */
3098 #define RAIL_TX_OPTION_SYNC_WORD_ID (1UL << RAIL_TX_OPTION_SYNC_WORD_ID_SHIFT)
3099
3100 /**
3101 * An option to select antenna 0 for transmission. If the antenna selection
3102 * option is not set or if both antenna options are set, then the transmit
3103 * will occur on either antenna depending on the last receive or transmit
3104 * selection. This option is only valid on platforms that support
3105 * \ref Antenna_Control and have been configured via \ref RAIL_ConfigAntenna().
3106 *
3107 * @note These TX antenna options do not control the antenna used for
3108 * \ref Auto_Ack transmissions, which always occur on the same antenna
3109 * used to receive the packet being acknowledged.
3110 */
3111 #define RAIL_TX_OPTION_ANTENNA0 (1UL << RAIL_TX_OPTION_ANTENNA0_SHIFT)
3112
3113 /**
3114 * An option to select antenna 1 for transmission. If the antenna selection
3115 * option is not set or if both antenna options are set, then the transmit
3116 * will occur on either antenna depending on the last receive or transmit
3117 * selection. This option is only valid on platforms that support
3118 * \ref Antenna_Control and have been configured via \ref RAIL_ConfigAntenna().
3119 *
3120 * @note These TX antenna options do not control the antenna used for
3121 * \ref Auto_Ack transmissions, which always occur on the same antenna
3122 * used to receive the packet being acknowledged.
3123 */
3124 #define RAIL_TX_OPTION_ANTENNA1 (1UL << RAIL_TX_OPTION_ANTENNA1_SHIFT)
3125
3126 /**
3127 * An option to use the alternate preamble length established
3128 * by \ref RAIL_SetTxAltPreambleLength() for the transmission.
3129 * When not set, the PHY configuration's preamble length is used.
3130 */
3131 #define RAIL_TX_OPTION_ALT_PREAMBLE_LEN (1UL << RAIL_TX_OPTION_ALT_PREAMBLE_LEN_SHIFT)
3132
3133 /**
3134 * An option to use peak rather than average RSSI energy detected during
3135 * CSMA's \ref RAIL_CsmaConfig_t::ccaDuration or LBT's \ref
3136 * RAIL_LbtConfig_t::lbtDuration to determine whether the channel is clear
3137 * or busy. This option is only valid when calling one of the CCA transmit
3138 * routines: \ref RAIL_StartCcaCsmaTx(), \ref RAIL_StartCcaLbtTx(), \ref
3139 * RAIL_StartScheduledCcaCsmaTx(), or \ref RAIL_StartScheduledCcaLbtTx().
3140 */
3141 #define RAIL_TX_OPTION_CCA_PEAK_RSSI (1UL << RAIL_TX_OPTION_CCA_PEAK_RSSI_SHIFT)
3142
3143 /**
3144 * An option to only perform the CCA (CSMA/LBT) operation but *not*
3145 * automatically transmit if the channel is clear. This option is only valid
3146 * when calling one of the CCA transmit routines: \ref RAIL_StartCcaCsmaTx(),
3147 * \ref RAIL_StartCcaLbtTx(), \ref RAIL_StartScheduledCcaCsmaTx(), or \ref
3148 * RAIL_StartScheduledCcaLbtTx().
3149 *
3150 * Application can then use the \ref RAIL_EVENT_TX_CHANNEL_CLEAR to
3151 * initiate transmit manually, e.g., giving it the opportunity to adjust
3152 * outgoing packet data before the packet goes out.
3153 *
3154 * @note Configured state transitions to Rx or Idle are suspended during
3155 * this CSMA/LBT operation. If packet reception occurs, the radio will
3156 * return to the state it was in just prior to the CSMA/LBT operation
3157 * when that reception (including any Auto-Ack response) is complete.
3158 */
3159 #define RAIL_TX_OPTION_CCA_ONLY (1UL << RAIL_TX_OPTION_CCA_ONLY_SHIFT)
3160
3161 /**
3162 * An option to resend packet at the beginning of the Transmit FIFO.
3163 *
3164 * The packet to be resent must have been previously provided by
3165 * \ref RAIL_SetTxFifo() or \ref RAIL_WriteTxFifo() passing true for
3166 * the latter's reset parameter. It works by setting the
3167 * transmit FIFO's read offset to the beginning of the FIFO while
3168 * leaving its write offset intact. For this to work,
3169 * \ref RAIL_DataConfig_t::txMethod must be RAIL_DataMethod_t::PACKET_MODE
3170 * (i.e., the packet can't exceed the Transmit FIFO's size), otherwise
3171 * undefined behavior will result.
3172 *
3173 * This option can also be used with \ref RAIL_SetNextTxRepeat() to cause
3174 * the repeated packet(s) to all be the same as the first.
3175 */
3176 #define RAIL_TX_OPTION_RESEND (1UL << RAIL_TX_OPTION_RESEND_SHIFT)
3177
3178 /**
3179 * An option to specify which PHY is used to transmit in the case of concurrent mode.
3180 * Concurrent mode is only allowed on EFR32xG25 for some predefined combinations of Wi-SUN PHYs.
3181 * When set/unset, the alternate/base PHY is used to transmit.
3182 */
3183 #define RAIL_TX_OPTION_CONCURRENT_PHY_ID (1UL << RAIL_TX_OPTION_CONCURRENT_PHY_ID_SHIFT)
3184
3185 /** A value representing all possible options. */
3186 #define RAIL_TX_OPTIONS_ALL 0xFFFFFFFFUL
3187
3188 /**
3189 * @struct RAIL_TxPacketDetails_t
3190 * @brief Detailed information requested about the packet that was just,
3191 * or is currently being, transmitted.
3192 */
3193 typedef struct RAIL_TxPacketDetails {
3194 /**
3195 * The timestamp of the transmitted packet in the RAIL timebase,
3196 * filled in by \ref RAIL_GetTxPacketDetails().
3197 */
3198 RAIL_PacketTimeStamp_t timeSent;
3199 /**
3200 * Indicate whether the transmitted packet was an automatic Ack. In a generic
3201 * sense, an automatic Ack is defined as a packet sent in response to a
3202 * received Ack-requesting frame when Auto-Ack is enabled. In a protocol
3203 * specific sense this definition may be more or less restrictive to match the
3204 * specification and you should refer to that protocol's documentation.
3205 */
3206 bool isAck;
3207 } RAIL_TxPacketDetails_t;
3208
3209 /**
3210 * @enum RAIL_ScheduledTxDuringRx_t
3211 * @brief Enumerates the possible outcomes of what will occur if a
3212 * scheduled TX ends up firing during RX. Because RX and TX can't
3213 * happen at the same time, it is up to the user how the TX should be
3214 * handled. This enumeration is passed into \ref RAIL_StartScheduledTx()
3215 * as part of \ref RAIL_ScheduleTxConfig_t.
3216 */
RAIL_ENUM(RAIL_ScheduledTxDuringRx_t)3217 RAIL_ENUM(RAIL_ScheduledTxDuringRx_t) {
3218 /**
3219 * The scheduled TX will be postponed until RX completes and then sent.
3220 */
3221 RAIL_SCHEDULED_TX_DURING_RX_POSTPONE_TX = 0,
3222 /**
3223 * The scheduled TX will be aborted and a
3224 * \ref RAIL_EVENT_TX_BLOCKED event will fire.
3225 */
3226 RAIL_SCHEDULED_TX_DURING_RX_ABORT_TX = 1,
3227 };
3228
3229 #ifndef DOXYGEN_SHOULD_SKIP_THIS
3230 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
3231 #define RAIL_SCHEDULED_TX_DURING_RX_POSTPONE_TX ((RAIL_ScheduledTxDuringRx_t) RAIL_SCHEDULED_TX_DURING_RX_POSTPONE_TX)
3232 #define RAIL_SCHEDULED_TX_DURING_RX_ABORT_TX ((RAIL_ScheduledTxDuringRx_t) RAIL_SCHEDULED_TX_DURING_RX_ABORT_TX)
3233 #endif//DOXYGEN_SHOULD_SKIP_THIS
3234
3235 /**
3236 * @struct RAIL_ScheduleTxConfig_t
3237 * @brief A configuration structure for a scheduled transmit.
3238 */
3239 typedef struct RAIL_ScheduleTxConfig {
3240 /**
3241 * The time when to transmit this packet. The exact interpretation of
3242 * this value depends on the mode specified below.
3243 */
3244 RAIL_Time_t when;
3245 /**
3246 * The type of delay. See the \ref RAIL_TimeMode_t documentation for
3247 * more information. Be sure to use \ref RAIL_TIME_ABSOLUTE delays for
3248 * time-critical protocols.
3249 */
3250 RAIL_TimeMode_t mode;
3251 /**
3252 * Indicate which action to take with a scheduled TX if it occurs during RX.
3253 * See \ref RAIL_ScheduledTxDuringRx_t structure for more information on
3254 * potential options.
3255 */
3256 RAIL_ScheduledTxDuringRx_t txDuringRx;
3257 } RAIL_ScheduleTxConfig_t;
3258
3259 /**
3260 * @def RAIL_MAX_LBT_TRIES
3261 * @brief The maximum number of LBT/CSMA retries supported.
3262 */
3263 #define RAIL_MAX_LBT_TRIES (15U)
3264
3265 /**
3266 * @def RAIL_MAX_CSMA_EXPONENT
3267 * @brief The maximum power-of-2 exponent for CSMA backoffs.
3268 */
3269 #define RAIL_MAX_CSMA_EXPONENT (8U)
3270
3271 ///
3272 /// @struct RAIL_CsmaConfig_t
3273 /// @brief A configuration structure for the CSMA transmit algorithm.
3274 ///
3275 /// One of RAIL's schemes for polite spectrum access is an implementation of
3276 /// a Carrier-Sense Multiple Access (CSMA) algorithm based on IEEE 802.15.4
3277 /// (unslotted).
3278 /// \n In pseudo-code it works like this, showing relevant event notifications:
3279 /// @code{.c}
3280 /// // Return true to transmit packet, false to not transmit packet.
3281 /// bool performCsma(const RAIL_CsmaConfig_t *csmaConfig)
3282 /// {
3283 /// bool isFixedBackoff = ((csmaConfig->csmaMinBoExp == 0)
3284 /// && (csmaConfig->csmaMaxBoExp == 0));
3285 /// int backoffExp = csmaConfig->csmaMinBoExp; // Initial backoff exponent
3286 /// int backoffMultiplier = 1; // Assume fixed backoff
3287 /// int try;
3288 ///
3289 /// // Special-case tries == 0 to transmit immediately without backoff+CCA
3290 /// if (csmaConfig->csmaTries == 0) {
3291 /// return true;
3292 /// }
3293 ///
3294 /// // Start overall timeout if specified:
3295 /// if (csmaConfig->csmaTimeout > 0) {
3296 /// StartAbortTimer(csmaConfig->csmaTimeout, RAIL_EVENT_TX_CHANNEL_BUSY);
3297 /// // If timeout occurs, abort and signal the indicated event.
3298 /// }
3299 ///
3300 /// for (try = 0; try < csmaConfig->csmaTries; try++) {
3301 /// if (try > 0) {
3302 /// signalEvent(RAIL_EVENT_TX_CCA_RETRY);
3303 /// }
3304 /// // Determine the backoff multipler for this try:
3305 /// if (isFixedBackoff) {
3306 /// // backoffMultiplier already set to 1 for fixed backoff
3307 /// } else {
3308 /// // Start with the backoff exponent for this try:
3309 /// if (try > 0) {
3310 /// backoffExp++;
3311 /// if (backoffExp > csmaConfig->csmaMaxBoExp) {
3312 /// backoffExp = csmaConfig->csmaMaxBoExp;
3313 /// }
3314 /// }
3315 /// // Pick random multiplier between 0 and 2^backoffExp - 1 inclusive:
3316 /// backoffMultiplier = pickRandomInteger(0, (1 << backoffExp) - 1);
3317 /// }
3318 /// // Perform the backoff:
3319 /// delayMicroseconds(backoffMultiplier * csmaConfig->ccaBackoff);
3320 /// // Perform the Clear-Channel Assessment (CCA):
3321 /// // Channel is considered busy if radio is actively receiving or
3322 /// // transmitting, or the average energy detected across duration
3323 /// // is above the threshold.
3324 /// signalEvent(RAIL_EVENT_TX_START_CCA);
3325 /// if (performCca(csmaConfig->ccaDuration, csmaConfig->ccaThreshold)) {
3326 /// // CCA (and CSMA) success: Transmit after RX-to-TX turnaround
3327 /// StopAbortTimer();
3328 /// signalEvent(RAIL_EVENT_TX_CHANNEL_CLEAR);
3329 /// return true;
3330 /// } else {
3331 /// // CCA failed: loop to try again, or exit if out of tries
3332 /// }
3333 /// }
3334 /// // Overall CSMA failure: Don't transmit
3335 /// StopAbortTimer();
3336 /// signalEvent(RAIL_EVENT_TX_CHANNEL_BUSY);
3337 /// return false;
3338 /// }
3339 /// @endcode
3340 ///
3341 typedef struct RAIL_CsmaConfig {
3342 /**
3343 * The minimum (starting) exponent for CSMA random backoff (2^exp - 1).
3344 * It can range from 0 to \ref RAIL_MAX_CSMA_EXPONENT.
3345 *
3346 * @warning On EFR32, due to a hardware limitation, this can only be 0
3347 * if \ref csmaMaxBoExp is also 0 specifying a non-random fixed backoff.
3348 * \ref RAIL_STATUS_INVALID_PARAMETER will result otherwise.
3349 * If you really want CSMA's first iteration to have no backoff prior to
3350 * CCA, with subsequent iterations having random backoff as the exponent
3351 * is increased, you must do a fixed backoff of 0 operation first
3352 * (\ref csmaMinBoExp = 0, \ref csmaMaxBoExp = 0, \ref ccaBackoff = 0,
3353 * \ref csmaTries = 1), and if that fails (\ref RAIL_EVENT_TX_CHANNEL_BUSY),
3354 * follow up with a random backoff operation starting at \ref csmaMinBoExp
3355 * = 1 for the remaining iterations.
3356 */
3357 uint8_t csmaMinBoExp;
3358 /**
3359 * The maximum exponent for CSMA random backoff (2^exp - 1).
3360 * It can range from 0 to \ref RAIL_MAX_CSMA_EXPONENT and must be greater
3361 * than or equal to \ref csmaMinBoExp.
3362 * \n If both exponents are 0, a non-random fixed backoff of \ref ccaBackoff
3363 * duration results.
3364 */
3365 uint8_t csmaMaxBoExp;
3366 /**
3367 * The number of backoff-then-CCA iterations that can fail before reporting
3368 * \ref RAIL_EVENT_TX_CHANNEL_BUSY. Typically ranges from 1 to \ref
3369 * RAIL_MAX_LBT_TRIES; higher values are disallowed. A value 0 always
3370 * transmits immediately without performing CSMA, similar to calling
3371 * \ref RAIL_StartTx().
3372 */
3373 uint8_t csmaTries;
3374 /**
3375 * The CCA RSSI threshold, in dBm, above which the channel is
3376 * considered 'busy'.
3377 */
3378 int8_t ccaThreshold;
3379 /**
3380 * The backoff unit period in RAIL's microsecond time base. It is
3381 * multiplied by the random backoff exponential controlled by \ref
3382 * csmaMinBoExp and \ref csmaMaxBoExp to determine the overall backoff
3383 * period. For random backoffs, any value above 32768 microseconds for
3384 * the 'EFR Series 2' and 8192 microseconds for the 'Series 3' will be truncated
3385 * for a single backoff period. Up to 255 backoff periods are supported.
3386 * For fixed backoffs it can go up to 65535 microseconds.
3387 */
3388 uint16_t ccaBackoff;
3389 /**
3390 * The minimum desired CCA check duration in microseconds. The RSSI is
3391 * averaged over this duration by default but can be set to use the peak RSSI,
3392 * on supported platforms, using the \ref RAIL_TX_OPTION_CCA_PEAK_RSSI option.
3393 *
3394 * @note Depending on the radio configuration, due to hardware constraints,
3395 * the actual duration may be longer. Also, if the requested duration
3396 * is too large for the radio to accommodate, \ref RAIL_StartCcaCsmaTx()
3397 * will fail returning \ref RAIL_STATUS_INVALID_PARAMETER.
3398 */
3399 uint16_t ccaDuration;
3400 /**
3401 * An overall timeout, in RAIL's microsecond time base, for the operation.
3402 * If the transmission doesn't start before this timeout expires, the
3403 * transmission will fail with \ref RAIL_EVENT_TX_CHANNEL_BUSY.
3404 * A value 0 means no timeout is imposed.
3405 */
3406 RAIL_Time_t csmaTimeout;
3407 } RAIL_CsmaConfig_t;
3408
3409 /**
3410 * @def RAIL_CSMA_CONFIG_802_15_4_2003_2p4_GHz_OQPSK_CSMA
3411 * @brief \ref RAIL_CsmaConfig_t initializer configuring CSMA per IEEE 802.15.4-2003
3412 * on 2.4 GHz OSPSK, commonly used by Zigbee.
3413 */
3414 #define RAIL_CSMA_CONFIG_802_15_4_2003_2p4_GHz_OQPSK_CSMA { \
3415 /* CSMA per 802.15.4-2003 on 2.4 GHz OSPSK, commonly used by Zigbee */ \
3416 .csmaMinBoExp = 3, /* 2^3-1 for 0..7 backoffs on 1st try */ \
3417 .csmaMaxBoExp = 5, /* 2^5-1 for 0..31 backoffs on 3rd+ tries */ \
3418 .csmaTries = 5, /* 5 tries overall (4 re-tries) */ \
3419 .ccaThreshold = -75, /* 10 dB above sensitivity */ \
3420 .ccaBackoff = 320, /* 20 symbols at 16 us/symbol */ \
3421 .ccaDuration = 128, /* 8 symbols at 16 us/symbol */ \
3422 .csmaTimeout = 0, /* No timeout */ \
3423 }
3424
3425 /**
3426 * @def RAIL_CSMA_CONFIG_SINGLE_CCA
3427 * @brief \ref RAIL_CsmaConfig_t initializer configuring a single CCA prior to TX.
3428 * It can be used to as a basis for implementing other channel access schemes
3429 * with custom backoff delays. Users can override ccaBackoff with a fixed
3430 * delay on each use.
3431 */
3432 #define RAIL_CSMA_CONFIG_SINGLE_CCA { \
3433 /* Perform a single CCA after 'fixed' delay */ \
3434 .csmaMinBoExp = 0, /* Used for fixed backoff */ \
3435 .csmaMaxBoExp = 0, /* Used for fixed backoff */ \
3436 .csmaTries = 1, /* Single try */ \
3437 .ccaThreshold = -75, /* Override if not desired choice */ \
3438 .ccaBackoff = 0, /* No backoff (override with fixed value) */ \
3439 .ccaDuration = 128, /* Override if not desired length */ \
3440 .csmaTimeout = 0, /* no timeout */ \
3441 }
3442
3443 ///
3444 /// @struct RAIL_LbtConfig_t
3445 /// @brief A configuration structure for the LBT transmit algorithm.
3446 ///
3447 /// One of RAIL's schemes for polite spectrum access is an implementation of
3448 /// a Listen-Before-Talk (LBT) algorithm, loosely based on ETSI 300 220-1.
3449 /// \n Currently, however, it is constrained by the EFR32's CSMA-oriented hardware
3450 /// so is turned into an equivalent \ref RAIL_CsmaConfig_t configuration and
3451 /// passed to the CSMA engine:
3452 /// @code{.c}
3453 /// if (lbtMaxBoRand == lbtMinBoRand) {
3454 /// // Fixed backoff
3455 /// csmaMinBoExp = csmaMaxBoExp = 0;
3456 /// if (lbtMinBoRand == 0) {
3457 /// ccaBackoff = lbtBackoff;
3458 /// } else {
3459 /// ccaBackoff = lbtMinBoRand * lbtBackoff;
3460 /// }
3461 /// ccaDuration = lbtDuration;
3462 /// } else {
3463 /// // Random backoff: map to random range 0 .. (lbtMaxBoRand - lbtMinBoRand)
3464 /// csmaMinBoExp = csmaMaxBoExp = ceiling(log2(lbtMaxBoRand - lbtMinBoRand));
3465 /// ccaBackoff = round((lbtBackoff * (lbtMaxBoRand - lbtMinBoRand))
3466 /// / (1 << csmaMinBoExp));
3467 /// ccaDuration = lbtDuration + (lbtMinBoRand * lbtBackoff);
3468 /// }
3469 /// csmaTries = lbtTries;
3470 /// ccaThreshold = lbtThreshold;
3471 /// csmaTimeout = lbtTimeout;
3472 /// @endcode
3473 ///
3474 typedef struct RAIL_LbtConfig {
3475 /**
3476 * The minimum backoff random multiplier.
3477 */
3478 uint8_t lbtMinBoRand;
3479 /**
3480 * The maximum backoff random multiplier.
3481 * It must be greater than or equal to \ref lbtMinBoRand.
3482 * \n If both backoff multipliers are identical, a non-random fixed backoff
3483 * of \ref lbtBackoff times the multiplier (minimum 1) duration results.
3484 */
3485 uint8_t lbtMaxBoRand;
3486 /**
3487 * The number of LBT iterations that can fail before reporting
3488 * \ref RAIL_EVENT_TX_CHANNEL_BUSY. Typically ranges from 1 to \ref
3489 * RAIL_MAX_LBT_TRIES; higher values are disallowed. A value 0 always
3490 * transmits immediately without performing LBT, similar to calling
3491 * \ref RAIL_StartTx().
3492 */
3493 uint8_t lbtTries;
3494 /**
3495 * The LBT RSSI threshold, in dBm, above which the channel is
3496 * considered 'busy'.
3497 */
3498 int8_t lbtThreshold;
3499 /**
3500 * The backoff unit period, in RAIL's microsecond time base. It is
3501 * multiplied by the random backoff multiplier controlled by \ref
3502 * lbtMinBoRand and \ref lbtMaxBoRand to determine the overall backoff
3503 * period. For random backoffs, any value above 32768 microseconds for
3504 * the 'EFR Series 2' and 8192 microseconds for the 'Series 3' will be truncated
3505 * for a single backoff period. Up to 255 backoff periods are supported.
3506 * For fixed backoffs, it can go up to 65535 microseconds.
3507 */
3508 uint16_t lbtBackoff;
3509 /**
3510 * The minimum desired LBT check duration in microseconds.
3511 *
3512 * @note Depending on the radio configuration, due to hardware constraints,
3513 * the actual duration may be longer. Also, if the requested duration
3514 * is too large for the radio to accommodate, \ref RAIL_StartCcaLbtTx()
3515 * will fail returning \ref RAIL_STATUS_INVALID_PARAMETER.
3516 */
3517 uint16_t lbtDuration;
3518 /**
3519 * An overall timeout, in RAIL's microsecond time base, for the operation.
3520 * If the transmission doesn't start before this timeout expires, the
3521 * transmission will fail with \ref RAIL_EVENT_TX_CHANNEL_BUSY.
3522 * This is important for limiting LBT due to LBT's unbounded requirement
3523 * that if the channel is busy, the next try must wait for the channel to
3524 * clear. A value 0 means no timeout is imposed.
3525 */
3526 RAIL_Time_t lbtTimeout;
3527 } RAIL_LbtConfig_t;
3528
3529 /**
3530 * @def RAIL_LBT_CONFIG_ETSI_EN_300_220_1_V2_4_1
3531 * @brief \ref RAIL_LbtConfig_t initializer configuring LBT per ETSI 300 220-1
3532 * V2.4.1 for a typical Sub-GHz band. To be practical, users should override
3533 * lbtTries and/or lbtTimeout so channel access failure will be reported in a
3534 * reasonable time frame rather than the unbounded time frame ETSI defined.
3535 */
3536 #define RAIL_LBT_CONFIG_ETSI_EN_300_220_1_V2_4_1 { \
3537 /* LBT per ETSI 300 220-1 V2.4.1 */ \
3538 /* LBT time = random backoff of 0-5 ms in .5 ms increments plus 5 ms fixed */ \
3539 .lbtMinBoRand = 0, /* */ \
3540 .lbtMaxBoRand = 10, /* */ \
3541 .lbtTries = RAIL_MAX_LBT_TRIES, /* the maximum supported */ \
3542 .lbtThreshold = -87, /* */ \
3543 .lbtBackoff = 500, /* 0.5 ms */ \
3544 .lbtDuration = 5000, /* 5 ms */ \
3545 .lbtTimeout = 0, /* No timeout (recommend user override) */ \
3546 }
3547
3548 /**
3549 * @def RAIL_LBT_CONFIG_ETSI_EN_300_220_1_V3_1_0
3550 * @brief \ref RAIL_LbtConfig_t initializer configuring LBT per ETSI 300 220-1
3551 * V3.1.0 for a typical Sub-GHz band. To be practical, users should override
3552 * lbtTries and/or lbtTimeout so channel access failure will be reported in a
3553 * reasonable time frame rather than the unbounded time frame ETSI defined.
3554 */
3555 #define RAIL_LBT_CONFIG_ETSI_EN_300_220_1_V3_1_0 { \
3556 /* LBT per ETSI 300 220-1 V3.1.0 */ \
3557 /* LBT time = random backoff of 160-4960 us in 160 us increments */ \
3558 .lbtMinBoRand = 1, /* */ \
3559 .lbtMaxBoRand = 31, /* app-chosen; 31*lbtBackoff = 4960 us */ \
3560 .lbtTries = RAIL_MAX_LBT_TRIES, /* the maximum supported */ \
3561 .lbtThreshold = -85, /* 15 dB above Rx sensitivity per Table 45 */ \
3562 .lbtDuragion = 160, /* 160 us per Table 48 Minimum CCA interval */ \
3563 .lbtTimeout = 0, /* No timeout (recommend user override) */ \
3564 }
3565
3566 /**
3567 * @struct RAIL_SyncWordConfig_t
3568 * @brief RAIL sync words and length configuration.
3569 *
3570 */
3571 typedef struct RAIL_SyncWordConfig {
3572 /** Sync word length in bits, between 2 and 32, inclusive.*/
3573 uint8_t syncWordBits;
3574 /**
3575 * Sync Word1
3576 * @note Only the least-significant \ref syncWordBits bits are used,
3577 * which are sent or received on air least-significant-bit first.
3578 */
3579 uint32_t syncWord1;
3580 /**
3581 * Sync Word2
3582 * @note Only the least-significant \ref syncWordBits bits are used,
3583 * which are sent or received on air least-significant-bit first.
3584 */
3585 uint32_t syncWord2;
3586 } RAIL_SyncWordConfig_t;
3587
3588 /**
3589 * @enum RAIL_TxRepeatOptions_t
3590 * @brief Transmit repeat options, in reality a bitmask.
3591 */
RAIL_ENUM_GENERIC(RAIL_TxRepeatOptions_t,uint16_t)3592 RAIL_ENUM_GENERIC(RAIL_TxRepeatOptions_t, uint16_t) {
3593 /** Shift position of \ref RAIL_TX_REPEAT_OPTION_HOP bit. */
3594 RAIL_TX_REPEAT_OPTION_HOP_SHIFT = 0,
3595 /** Shift position of the \ref RAIL_TX_REPEAT_OPTION_START_TO_START bit. */
3596 RAIL_TX_REPEAT_OPTION_START_TO_START_SHIFT = 1,
3597 };
3598
3599 /** A value representing no repeat options enabled. */
3600 #define RAIL_TX_REPEAT_OPTIONS_NONE 0U
3601 /** All repeat options disabled by default. */
3602 #define RAIL_TX_REPEAT_OPTIONS_DEFAULT RAIL_TX_REPEAT_OPTIONS_NONE
3603 /**
3604 * An option to configure whether or not to channel-hop before each
3605 * repeated transmit.
3606 */
3607 #define RAIL_TX_REPEAT_OPTION_HOP (1U << RAIL_TX_REPEAT_OPTION_HOP_SHIFT)
3608
3609 /**
3610 * An option to configure the delay between transmissions to be from start to start
3611 * instead of end to start. Delay must be long enough to cover the prior transmit's time.
3612 */
3613 #define RAIL_TX_REPEAT_OPTION_START_TO_START (1 << RAIL_TX_REPEAT_OPTION_START_TO_START_SHIFT)
3614
3615 /// @struct RAIL_TxRepeatConfig_t
3616 /// @brief A configuration structure for repeated transmits
3617 ///
3618 /// @note The PA will always be ramped down and up in between transmits so
3619 /// there will always be some minimum delay between transmits depending on the
3620 /// ramp time configuration.
3621 typedef struct RAIL_TxRepeatConfig {
3622 /**
3623 * The number of repeated transmits to run. A total of (iterations + 1)
3624 * transmits will go on-air in the absence of errors.
3625 */
3626 uint16_t iterations;
3627 /**
3628 * Repeat option(s) to apply.
3629 */
3630 RAIL_TxRepeatOptions_t repeatOptions;
3631 /**
3632 * Per-repeat delay or hopping configuration, depending on repeatOptions.
3633 */
3634 union {
3635 /**
3636 * When \ref RAIL_TX_REPEAT_OPTION_HOP is not set, specifies
3637 * the delay time between each repeated transmit. Specify \ref
3638 * RAIL_TRANSITION_TIME_KEEP to use the current \ref
3639 * RAIL_StateTiming_t::txToTx transition time setting.
3640 * When using \ref RAIL_TX_REPEAT_OPTION_START_TO_START the delay
3641 * must be long enough to cover the prior transmit's time.
3642 */
3643 RAIL_TransitionTime_t delay;
3644 /**
3645 * When \ref RAIL_TX_REPEAT_OPTION_HOP is set, this specifies
3646 * the channel hopping configuration to use when hopping between
3647 * repeated transmits. Per-hop delays are configured within each
3648 * \ref RAIL_TxChannelHoppingConfigEntry_t::delay rather than
3649 * this union's delay field.
3650 * When using \ref RAIL_TX_REPEAT_OPTION_START_TO_START the hop delay
3651 * must be long enough to cover the prior transmit's time.
3652 */
3653 RAIL_TxChannelHoppingConfig_t channelHopping;
3654 } delayOrHop;
3655 } RAIL_TxRepeatConfig_t;
3656
3657 /// \ref RAIL_TxRepeatConfig_t::iterations initializer configuring infinite
3658 /// repeated transmissions.
3659 #define RAIL_TX_REPEAT_INFINITE_ITERATIONS (0xFFFFU)
3660
3661 /** @} */ // end of group Transmit
3662
3663 /******************************************************************************
3664 * Receive Structures
3665 *****************************************************************************/
3666 /**
3667 * @addtogroup Receive
3668 * @{
3669 */
3670
3671 /**
3672 * @addtogroup Address_Filtering
3673 * @{
3674 */
3675
3676 /// A default address filtering match table for configurations that use only one
3677 /// address field. The truth table for address matching is shown below.
3678 ///
3679 /// | | No Match | Address 0 | Address 1 | Address 2 | Address 3 |
3680 /// |----------------|----------|-----------|-----------|-----------|-----------|
3681 /// | __No Match__ | 0 | 1 | 1 | 1 | 1 |
3682 /// | __Address 0__ | 1 | 1 | 1 | 1 | 1 |
3683 /// | __Address 1__ | 1 | 1 | 1 | 1 | 1 |
3684 /// | __Address 2__ | 1 | 1 | 1 | 1 | 1 |
3685 /// | __Address 3__ | 1 | 1 | 1 | 1 | 1 |
3686 ///
3687 #define ADDRCONFIG_MATCH_TABLE_SINGLE_FIELD (0x1FFFFFE)
3688 /// A default address filtering match table for configurations that use two
3689 /// address fields and want to match the same index in each. The truth
3690 /// table for address matching is shown below.
3691 ///
3692 /// | | No Match | Address 0 | Address 1 | Address 2 | Address 3 |
3693 /// |----------------|----------|-----------|-----------|-----------|-----------|
3694 /// | __No Match__ | 0 | 0 | 0 | 0 | 0 |
3695 /// | __Address 0__ | 0 | 1 | 0 | 0 | 0 |
3696 /// | __Address 1__ | 0 | 0 | 1 | 0 | 0 |
3697 /// | __Address 2__ | 0 | 0 | 0 | 1 | 0 |
3698 /// | __Address 3__ | 0 | 0 | 0 | 0 | 1 |
3699 #define ADDRCONFIG_MATCH_TABLE_DOUBLE_FIELD (0x1041040)
3700
3701 /// The maximum number of address fields that can be used by the address
3702 /// filtering logic.
3703 #define ADDRCONFIG_MAX_ADDRESS_FIELDS (2)
3704
3705 /**
3706 * @struct RAIL_AddrConfig_t
3707 * @brief A structure to configure the address filtering functionality in RAIL.
3708 */
3709 typedef struct RAIL_AddrConfig {
3710 /**
3711 * A list of the start offsets for each field.
3712 *
3713 * These offsets are specified relative to the previous field's end.
3714 * For the first field, it is relative to either the beginning of the packet
3715 * or the end of the frame type byte if frame type decoding is enabled. If a
3716 * field is unused, it's offset should be set to 0.
3717 */
3718 uint8_t offsets[ADDRCONFIG_MAX_ADDRESS_FIELDS];
3719
3720 /**
3721 * A list of the address field sizes.
3722 *
3723 * These sizes are specified in bytes from 0 to 8. If you choose a
3724 * size of 0, this field is effectively disabled.
3725 */
3726 uint8_t sizes[ADDRCONFIG_MAX_ADDRESS_FIELDS];
3727
3728 /**
3729 * The truth table to determine how the two fields combine to create a match.
3730 *
3731 * For detailed information about how this truth table is formed, see the
3732 * detailed description of \ref Address_Filtering.
3733 *
3734 * For simple predefined configurations use the following defines.
3735 * - ADDRCONFIG_MATCH_TABLE_SINGLE_FIELD
3736 * - For filtering that only uses a single address field.
3737 * - ADDRCONFIG_MATCH_TABLE_DOUBLE_FIELD for two field filtering where you
3738 * - For filtering that uses two address fields in a configurations where
3739 * you want the following logic `((Field_0, Index_0) && (Field_1, Index_0))
3740 * || ((Field_0, Index_1) && (Field_1, Index_1)) || ...`
3741 */
3742 uint32_t matchTable;
3743 } RAIL_AddrConfig_t;
3744
3745 /**
3746 * @brief A bitmask representation of which 4 filters passed for each
3747 * \ref ADDRCONFIG_MAX_ADDRESS_FIELDS when filtering has completed
3748 * successfully.
3749 *
3750 * It's layout is:
3751 * | Bit 7 | Bit 6 | Bit 5 | Bit 4 | Bit 3 | Bit 2 | Bit 1 | Bit 0 |
3752 * |--------+--------+--------+--------+--------+--------+--------+--------|
3753 * | Second Address Field Nibble | First Address Field Nibble |
3754 * | Addr 3 | Addr 2 | Addr 1 | Addr 0 | Addr 3 | Addr 2 | Addr 1 | Addr 0 |
3755 * | match | match | match | match | match | match | match | match |
3756 * |--------+--------+--------+--------+--------+--------+--------+--------|
3757 *
3758 * @note This information is valid in \ref RAIL_IEEE802154_Address_t on all
3759 * platforms, but is only valid in \ref RAIL_RxPacketInfo_t on platforms
3760 * where \ref RAIL_SUPPORTS_ADDR_FILTER_MASK is true.
3761 */
3762 typedef uint8_t RAIL_AddrFilterMask_t;
3763
3764 /** @} */ // end of group Address_Filtering
3765
3766 /**
3767 * @enum RAIL_RxOptions_t
3768 * @brief Receive options, in reality a bitmask.
3769 */
RAIL_ENUM_GENERIC(RAIL_RxOptions_t,uint32_t)3770 RAIL_ENUM_GENERIC(RAIL_RxOptions_t, uint32_t) {
3771 /** Shift position of \ref RAIL_RX_OPTION_STORE_CRC bit. */
3772 RAIL_RX_OPTION_STORE_CRC_SHIFT = 0,
3773 /** Shift position of \ref RAIL_RX_OPTION_IGNORE_CRC_ERRORS bit. */
3774 RAIL_RX_OPTION_IGNORE_CRC_ERRORS_SHIFT = 1,
3775 /** Shift position of \ref RAIL_RX_OPTION_ENABLE_DUALSYNC bit. */
3776 RAIL_RX_OPTION_ENABLE_DUALSYNC_SHIFT = 2,
3777 /** Shift position of \ref RAIL_RX_OPTION_TRACK_ABORTED_FRAMES bit. */
3778 RAIL_RX_OPTION_TRACK_ABORTED_FRAMES_SHIFT = 3,
3779 /** Shift position of \ref RAIL_RX_OPTION_REMOVE_APPENDED_INFO bit. */
3780 RAIL_RX_OPTION_REMOVE_APPENDED_INFO_SHIFT = 4,
3781 /** Shift position of \ref RAIL_RX_OPTION_ANTENNA0 bit. */
3782 RAIL_RX_OPTION_ANTENNA0_SHIFT = 5,
3783 /** Shift position of \ref RAIL_RX_OPTION_ANTENNA1 bit. */
3784 RAIL_RX_OPTION_ANTENNA1_SHIFT = 6,
3785 /** Shift position of \ref RAIL_RX_OPTION_DISABLE_FRAME_DETECTION bit. */
3786 RAIL_RX_OPTION_DISABLE_FRAME_DETECTION_SHIFT = 7,
3787 #ifndef DOXYGEN_SHOULD_SKIP_THIS
3788 /** Shift position of \ref RAIL_RX_OPTION_SKIP_DC_CAL bit. */
3789 RAIL_RX_OPTION_SKIP_DC_CAL_SHIFT = 8,
3790 /** Shift position of \ref RAIL_RX_OPTION_SKIP_SYNTH_CAL bit. */
3791 RAIL_RX_OPTION_SKIP_SYNTH_CAL_SHIFT = 9,
3792 #endif //DOXYGEN_SHOULD_SKIP_THIS
3793 /** Shift position of \ref RAIL_RX_OPTION_CHANNEL_SWITCHING bit. */
3794 RAIL_RX_OPTION_CHANNEL_SWITCHING_SHIFT = 10,
3795 /** Shift position of \ref RAIL_RX_OPTION_FAST_RX2RX bit. */
3796 RAIL_RX_OPTION_FAST_RX2RX_SHIFT = 11,
3797 /** Shift position of \ref RAIL_RX_OPTION_ENABLE_COLLISION_DETECTION bit. */
3798 RAIL_RX_OPTION_ENABLE_COLLISION_DETECTION_SHIFT = 12,
3799 };
3800
3801 /** A value representing no options enabled. */
3802 #define RAIL_RX_OPTIONS_NONE 0
3803 /** All options are disabled by default. */
3804 #define RAIL_RX_OPTIONS_DEFAULT RAIL_RX_OPTIONS_NONE
3805
3806 /**
3807 * An option to configure whether the CRC portion of the packet is included in
3808 * the packet payload exposed to the app on packet reception.
3809 * Defaults to false.
3810 */
3811 #define RAIL_RX_OPTION_STORE_CRC (1UL << RAIL_RX_OPTION_STORE_CRC_SHIFT)
3812
3813 /**
3814 * An option to configure whether CRC errors will be ignored.
3815 * If this is set, RX will still be successful, even if
3816 * the CRC does not pass the check. Defaults to false.
3817 *
3818 * @note An expected Ack that fails CRC with this option set
3819 * will still be considered the expected Ack, terminating
3820 * the \ref RAIL_AutoAckConfig_t::ackTimeout period.
3821 */
3822 #define RAIL_RX_OPTION_IGNORE_CRC_ERRORS (1UL << RAIL_RX_OPTION_IGNORE_CRC_ERRORS_SHIFT)
3823
3824 /**
3825 * An option to control which sync words will be accepted. Setting it to
3826 * 0 (default) will cause the receiver to listen for SYNC1 only. Setting it to
3827 * 1 causes the receiver to listen for either SYNC1 or SYNC2. RX appended info
3828 * will contain which sync word was detected. Note, this only affects which
3829 * sync word(s) are received, but not what each of the sync words actually are.
3830 * This feature may not be available on some combinations of chips, PHYs, and
3831 * protocols. Use the compile time symbol \ref RAIL_SUPPORTS_DUAL_SYNC_WORDS or
3832 * the runtime call \ref RAIL_SupportsDualSyncWords() to check whether the
3833 * platform supports this feature. Also, DUALSYNC may be incompatible
3834 * with certain radio configurations. In these cases, setting this bit will
3835 * be ignored. See the data sheet or support team for more details.
3836 */
3837 #define RAIL_RX_OPTION_ENABLE_DUALSYNC (1UL << RAIL_RX_OPTION_ENABLE_DUALSYNC_SHIFT)
3838
3839 /**
3840 * An option to configure whether frames which are aborted during reception
3841 * should continue to be tracked. Setting this option allows viewing Packet
3842 * Trace information for frames which get discarded. Defaults to false.
3843 *
3844 * This option is ignored when doing a \ref RAIL_IDLE_FORCE_SHUTDOWN or
3845 * \ref RAIL_IDLE_FORCE_SHUTDOWN_CLEAR_FLAGS.
3846 *
3847 * @note This option should not be used with coded PHYs since packet data
3848 * received after the abort will not be decoded properly.
3849 */
3850 #define RAIL_RX_OPTION_TRACK_ABORTED_FRAMES (1UL << RAIL_RX_OPTION_TRACK_ABORTED_FRAMES_SHIFT)
3851
3852 /**
3853 * An option to suppress capturing the appended information after
3854 * received frames. Defaults to false. When suppressed, certain
3855 * \ref RAIL_RxPacketDetails_t details will not be available for received
3856 * packets whose \ref RAIL_RxPacketStatus_t is among the RAIL_RX_PACKET_READY_
3857 * set.
3858 *
3859 * @warning This option should be changed only when the radio is idle
3860 * and the receive FIFO is empty or has been reset,
3861 * otherwise \ref RAIL_GetRxPacketInfo() and \ref RAIL_GetRxPacketDetails()
3862 * may think appended info is packet data or vice-versa.
3863 */
3864 #define RAIL_RX_OPTION_REMOVE_APPENDED_INFO (1UL << RAIL_RX_OPTION_REMOVE_APPENDED_INFO_SHIFT)
3865
3866 /**
3867 * An option to select the use of antenna 0 during receive (including
3868 * \ref Auto_Ack receive). If no antenna option is selected, the packet
3869 * will be received on the last antenna used for receive or transmit.
3870 * Defaults to false. This option is only valid on platforms that support
3871 * \ref Antenna_Control and have been configured via \ref RAIL_ConfigAntenna().
3872 */
3873 #define RAIL_RX_OPTION_ANTENNA0 (1UL << RAIL_RX_OPTION_ANTENNA0_SHIFT)
3874
3875 /**
3876 * An option to select the use of antenna 1 during receive (including
3877 * \ref Auto_Ack receive). If no antenna option is selected, the packet
3878 * will be received on the last antenna used for receive or transmit.
3879 * Defaults to false. This option is only valid on platforms that support
3880 * \ref Antenna_Control and have been configured via \ref RAIL_ConfigAntenna().
3881 */
3882 #define RAIL_RX_OPTION_ANTENNA1 (1UL << RAIL_RX_OPTION_ANTENNA1_SHIFT)
3883
3884 /**
3885 * An option combination to automatically choose an antenna during receive
3886 * (including \ref Auto_Ack receive). If both antenna 0 and antenna 1
3887 * options are set, the radio will dynamically switch between antennas
3888 * during packet detection and choose the best one for completing the
3889 * reception. This option is only valid when the antenna diversity
3890 * field is properly configured via Simplicity Studio.
3891 * This option is only valid on platforms that support
3892 * \ref Antenna_Control and have been configured via \ref RAIL_ConfigAntenna().
3893 */
3894 #define RAIL_RX_OPTION_ANTENNA_AUTO (RAIL_RX_OPTION_ANTENNA0 | RAIL_RX_OPTION_ANTENNA1)
3895
3896 /**
3897 * An option to disable frame detection. This can be useful for doing energy
3898 * detection without risking packet reception. Enabling this will abort any
3899 * frame currently being received in addition to preventing further frames
3900 * from being received. Defaults to false.
3901 */
3902 #define RAIL_RX_OPTION_DISABLE_FRAME_DETECTION (1UL << RAIL_RX_OPTION_DISABLE_FRAME_DETECTION_SHIFT)
3903
3904 #ifndef DOXYGEN_SHOULD_SKIP_THIS
3905 /**
3906 * An option to skip DC calibration when transitioning from RX to RX. This can be
3907 * useful for reducing the state transition time, but risks impacting
3908 * receive capability. Enabling this bypasses DC calibration (like
3909 * \ref RAIL_RX_CHANNEL_HOPPING_OPTION_SKIP_DC_CAL)
3910 * Defaults to false.
3911 */
3912 #define RAIL_RX_OPTION_SKIP_DC_CAL (1UL << RAIL_RX_OPTION_SKIP_DC_CAL_SHIFT)
3913
3914 /**
3915 * An option to skip synth calibration when transitioning from RX to RX. This can
3916 * be useful for reducing the state transition time, but risks impacting receive
3917 * capability. Enabling this bypasses synth calibration (like
3918 * \ref RAIL_RX_CHANNEL_HOPPING_OPTION_SKIP_SYNTH_CAL)
3919 * Defaults to false.
3920 */
3921 #define RAIL_RX_OPTION_SKIP_SYNTH_CAL (1U << RAIL_RX_OPTION_SKIP_SYNTH_CAL_SHIFT)
3922 #endif //DOXYGEN_SHOULD_SKIP_THIS
3923
3924 /**
3925 * An option to enable IEEE 802.15.4 RX channel switching.
3926 * See \ref RAIL_IEEE802154_ConfigRxChannelSwitching() for more information.
3927 * Defaults to false.
3928 *
3929 * @note This option is only supported on specific chips where
3930 * \ref RAIL_IEEE802154_SUPPORTS_RX_CHANNEL_SWITCHING is true.
3931 *
3932 * @note This option overrides \ref RAIL_RX_OPTION_ANTENNA0,
3933 * \ref RAIL_RX_OPTION_ANTENNA1 and \ref RAIL_RX_OPTION_ANTENNA_AUTO antenna
3934 * selection options.
3935 */
3936 #define RAIL_RX_OPTION_CHANNEL_SWITCHING (1U << RAIL_RX_OPTION_CHANNEL_SWITCHING_SHIFT)
3937
3938 /**
3939 * An option to enable fast RX2RX state transition.
3940 *
3941 * Once enabled, the sequencer will send the radio to RXSEARCH and get ready to
3942 * receive the next packet while still processing the previous one. This will
3943 * reduce RX to RX state transition time but risks impacting receive capability.
3944 *
3945 * @note This option is only supported on specific chips where
3946 * \ref RAIL_SUPPORTS_FAST_RX2RX is true.
3947 */
3948 #define RAIL_RX_OPTION_FAST_RX2RX (1U << RAIL_RX_OPTION_FAST_RX2RX_SHIFT)
3949
3950 /**
3951 * An option to enable collision detection.
3952 *
3953 * Once enabled, when a collision with a strong enough packet is detected, the demod
3954 * will stop the current packet decoding and try to detect the preamble of the incoming
3955 * packet.
3956 *
3957 * @note This option is only supported on specific chips where
3958 * \ref RAIL_SUPPORTS_COLLISION_DETECTION is true.
3959 */
3960 #define RAIL_RX_OPTION_ENABLE_COLLISION_DETECTION (1U << RAIL_RX_OPTION_ENABLE_COLLISION_DETECTION_SHIFT)
3961
3962 /** A value representing all possible options. */
3963 #define RAIL_RX_OPTIONS_ALL 0xFFFFFFFFUL
3964
3965 /** The value returned by RAIL for an invalid RSSI, in dBm. */
3966 #define RAIL_RSSI_INVALID_DBM (-128)
3967 /** The value returned by RAIL for an invalid RSSI: in quarter dBm. */
3968 #define RAIL_RSSI_INVALID ((int16_t)(RAIL_RSSI_INVALID_DBM * 4))
3969 /** The lowest RSSI value returned by RAIL: in quarter dBm. */
3970 #define RAIL_RSSI_LOWEST ((int16_t)(RAIL_RSSI_INVALID + 1))
3971
3972 /** Maximum absolute value for RSSI offset */
3973 #define RAIL_RSSI_OFFSET_MAX 35
3974
3975 /** A sentinel value to indicate waiting for a valid RSSI without a timeout. */
3976 #define RAIL_GET_RSSI_WAIT_WITHOUT_TIMEOUT ((RAIL_Time_t)0xFFFFFFFFU)
3977 /** A sentinel value to indicate no waiting for a valid RSSI. */
3978 #define RAIL_GET_RSSI_NO_WAIT ((RAIL_Time_t)0U)
3979
3980 /**
3981 * @struct RAIL_ScheduleRxConfig_t
3982 * @brief Configures the scheduled RX algorithm.
3983 *
3984 * Defines the start and end times of the receive window created
3985 * for a scheduled receive. If either start or end times are disabled, they
3986 * will be ignored.
3987 */
3988 typedef struct RAIL_ScheduleRxConfig {
3989 /**
3990 * The time to start receive. See startMode for more information about the
3991 * types of start times that you can specify.
3992 */
3993 RAIL_Time_t start;
3994 /**
3995 * How to interpret the time value specified in the start parameter. See the
3996 * \ref RAIL_TimeMode_t documentation for more information. Use
3997 * \ref RAIL_TIME_ABSOLUTE for absolute times, \ref RAIL_TIME_DELAY for times
3998 * relative to the current time and \ref RAIL_TIME_DISABLED to ignore the
3999 * start time.
4000 */
4001 RAIL_TimeMode_t startMode;
4002 /**
4003 * The time to end receive. See endMode for more information about the types
4004 * of end times you can specify.
4005 */
4006 RAIL_Time_t end;
4007 /**
4008 * How to interpret the time value specified in the end parameter. See the
4009 * \ref RAIL_TimeMode_t documentation for more information. Note that, in
4010 * this API, if you specify a \ref RAIL_TIME_DELAY, it is relative to the
4011 * start time if given and relative to now if none is specified. Also, using
4012 * \ref RAIL_TIME_DISABLED means that this window will not end unless you
4013 * explicitly call \ref RAIL_Idle() or add an end event through a future
4014 * update to this configuration.
4015 */
4016 RAIL_TimeMode_t endMode;
4017 /**
4018 * While in scheduled RX, you can still control the radio state via
4019 * state transitions. This option configures whether a transition
4020 * to RX goes back to scheduled RX or to the normal RX state. Once in the
4021 * normal RX state, you will effectively end the scheduled RX window and can
4022 * continue to receive indefinitely depending on the state transitions. Set
4023 * to 1 to transition to normal RX and 0 to stay in the scheduled RX.
4024 *
4025 * This setting also influences the posting of
4026 * \ref RAIL_EVENT_RX_SCHEDULED_RX_END when the scheduled Rx window is
4027 * implicitly ended by a packet receive (any of the
4028 * \ref RAIL_EVENTS_RX_COMPLETION events). See that event for details.
4029 *
4030 * @note An Rx transition to Idle state will always terminate the
4031 * scheduled Rx window, regardless of this setting. This can be used
4032 * to ensure Scheduled RX terminates on the first packet received
4033 * (or first successful packet if the RX error transition is to Rx
4034 * while the Rx success transition is to Idle).
4035 */
4036 uint8_t rxTransitionEndSchedule;
4037 /**
4038 * This setting tells RAIL what to do with a packet being received
4039 * when the window end event occurs. If set to 0, such a packet
4040 * will be allowed to complete. Any other setting will cause that
4041 * packet to be aborted. In either situation, any posting of
4042 * \ref RAIL_EVENT_RX_SCHEDULED_RX_END is deferred briefly to when
4043 * the packet's corresponding \ref RAIL_EVENTS_RX_COMPLETION occurs.
4044 */
4045 uint8_t hardWindowEnd;
4046 } RAIL_ScheduleRxConfig_t;
4047
4048 /**
4049 * @enum RAIL_RxPacketStatus_t
4050 * @brief The packet status code associated with a packet received or
4051 * currently being received.
4052 *
4053 * @note RECEIVING implies some packet data may be available, but
4054 * is untrustworthy (not CRC-verified) and might disappear if the packet
4055 * is rolled back on error. No packet details are yet available.
4056 * @note In RX \ref RAIL_DataMethod_t::FIFO_MODE, ABORT statuses imply some
4057 * packet data may be available, but it's incomplete and not trustworthy.
4058 */
RAIL_ENUM(RAIL_RxPacketStatus_t)4059 RAIL_ENUM(RAIL_RxPacketStatus_t) {
4060 /**
4061 * The radio is idle or searching for a packet.
4062 */
4063 RAIL_RX_PACKET_NONE = 0,
4064 /**
4065 * The packet was aborted during filtering because of illegal frame length,
4066 * CRC or block decoding errors, other RAIL built-in protocol-specific
4067 * packet content errors, or by the application or multiprotocol scheduler
4068 * idling the radio with \ref RAIL_IDLE_ABORT or higher.
4069 *
4070 * Corresponding \ref RAIL_EVENT_RX_PACKET_ABORTED is triggered.
4071 */
4072 RAIL_RX_PACKET_ABORT_FORMAT = 1,
4073 /**
4074 * The packet failed address filtering.
4075 *
4076 * Corresponding \ref RAIL_EVENT_RX_ADDRESS_FILTERED is triggered.
4077 */
4078 RAIL_RX_PACKET_ABORT_FILTERED = 2,
4079 /**
4080 * The packet passed any filtering but was aborted by the application
4081 * or multiprotocol scheduler idling the radio with \ref RAIL_IDLE_ABORT
4082 * or higher.
4083 *
4084 * Corresponding \ref RAIL_EVENT_RX_PACKET_ABORTED is triggered.
4085 */
4086 RAIL_RX_PACKET_ABORT_ABORTED = 3,
4087 /**
4088 * The packet overflowed the receive buffer.
4089 *
4090 * Corresponding \ref RAIL_EVENT_RX_FIFO_OVERFLOW is triggered.
4091 */
4092 RAIL_RX_PACKET_ABORT_OVERFLOW = 4,
4093 /**
4094 * The packet passed any filtering but subsequently failed CRC check(s)
4095 * block decoding, or illegal frame length, and was aborted.
4096 *
4097 * Corresponding \ref RAIL_EVENT_RX_FRAME_ERROR is triggered.
4098 */
4099 RAIL_RX_PACKET_ABORT_CRC_ERROR = 5,
4100 /**
4101 * The packet passed any filtering but subsequently failed CRC check(s)
4102 * with \ref RAIL_RX_OPTION_IGNORE_CRC_ERRORS in effect. Can also occur
4103 * when the packet prematurely ended successfully during filtering,
4104 * and either the \ref RAIL_EVENT_RX_PACKET_ABORTED or
4105 * \ref RAIL_EVENT_RX_ADDRESS_FILTERED events had been enabled
4106 * requesting notification of such packets.
4107 *
4108 * Corresponding \ref RAIL_EVENT_RX_PACKET_RECEIVED is triggered.
4109 */
4110 RAIL_RX_PACKET_READY_CRC_ERROR = 6,
4111 /**
4112 * The packet was successfully received, passing CRC check(s).
4113 *
4114 * Corresponding \ref RAIL_EVENT_RX_PACKET_RECEIVED is triggered.
4115 */
4116 RAIL_RX_PACKET_READY_SUCCESS = 7,
4117 /**
4118 * A packet is being received and is not yet complete.
4119 */
4120 RAIL_RX_PACKET_RECEIVING = 8,
4121 };
4122
4123 #ifndef DOXYGEN_SHOULD_SKIP_THIS
4124 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
4125 #define RAIL_RX_PACKET_NONE ((RAIL_RxPacketStatus_t) RAIL_RX_PACKET_NONE)
4126 #define RAIL_RX_PACKET_ABORT_FORMAT ((RAIL_RxPacketStatus_t) RAIL_RX_PACKET_ABORT_FORMAT)
4127 #define RAIL_RX_PACKET_ABORT_FILTERED ((RAIL_RxPacketStatus_t) RAIL_RX_PACKET_ABORT_FILTERED)
4128 #define RAIL_RX_PACKET_ABORT_ABORTED ((RAIL_RxPacketStatus_t) RAIL_RX_PACKET_ABORT_ABORTED)
4129 #define RAIL_RX_PACKET_ABORT_OVERFLOW ((RAIL_RxPacketStatus_t) RAIL_RX_PACKET_ABORT_OVERFLOW)
4130 #define RAIL_RX_PACKET_ABORT_CRC_ERROR ((RAIL_RxPacketStatus_t) RAIL_RX_PACKET_ABORT_CRC_ERROR)
4131 #define RAIL_RX_PACKET_READY_CRC_ERROR ((RAIL_RxPacketStatus_t) RAIL_RX_PACKET_READY_CRC_ERROR)
4132 #define RAIL_RX_PACKET_READY_SUCCESS ((RAIL_RxPacketStatus_t) RAIL_RX_PACKET_READY_SUCCESS)
4133 #define RAIL_RX_PACKET_RECEIVING ((RAIL_RxPacketStatus_t) RAIL_RX_PACKET_RECEIVING)
4134 #endif//DOXYGEN_SHOULD_SKIP_THIS
4135
4136 /**
4137 * @typedef RAIL_RxPacketHandle_t
4138 * @brief A handle used to reference a packet during reception processing.
4139 * There are several sentinel handle values that pertain to certain
4140 * circumstances: \ref RAIL_RX_PACKET_HANDLE_INVALID, \ref
4141 * RAIL_RX_PACKET_HANDLE_OLDEST, \ref RAIL_RX_PACKET_HANDLE_OLDEST_COMPLETE
4142 * and \ref RAIL_RX_PACKET_HANDLE_NEWEST.
4143 */
4144 typedef const void *RAIL_RxPacketHandle_t;
4145
4146 /** An invalid RX packet handle value. */
4147 #define RAIL_RX_PACKET_HANDLE_INVALID (NULL)
4148
4149 /** A special RX packet handle to refer to the oldest unreleased packet.
4150 * This includes the newest unread packet which is possibly incomplete or not
4151 * yet started.
4152 * This handle is used implicitly by \ref RAIL_ReadRxFifo().
4153 */
4154 #define RAIL_RX_PACKET_HANDLE_OLDEST ((RAIL_RxPacketHandle_t) 1)
4155
4156 /** A special RX packet handle to refer to the oldest unreleased
4157 * complete packet. This never includes incomplete or unstarted packets.
4158 * (Using \ref RAIL_RX_PACKET_HANDLE_OLDEST is inappropriate for this
4159 * purpose because it can refer to an unstarted, incomplete, or
4160 * unheld packet which are inappropriate to be consumed by the application.)
4161 */
4162 #define RAIL_RX_PACKET_HANDLE_OLDEST_COMPLETE ((RAIL_RxPacketHandle_t) 2)
4163
4164 /** A special RX packet handle to refer to the newest unreleased packet
4165 * when in callback context. For a callback involving a completed
4166 * receive event, this refers to the packet just completed. For
4167 * other callback events, this refers to the next packet to be
4168 * completed, which might be in-progress or might not have even
4169 * started yet.
4170 */
4171 #define RAIL_RX_PACKET_HANDLE_NEWEST ((RAIL_RxPacketHandle_t) 3)
4172
4173 /**
4174 * @struct RAIL_RxPacketInfo_t
4175 * @brief Basic information about a packet being received or already
4176 * completed and awaiting processing, including memory pointers to
4177 * its data in the circular receive FIFO buffer. This packet information
4178 * refers to remaining packet data that has not already been consumed
4179 * by \ref RAIL_ReadRxFifo().
4180 *
4181 * @note Because the receive FIFO buffer is circular, a packet might start
4182 * near the end of the buffer and wrap around to the beginning of
4183 * the buffer to finish, hence the distinction between the first
4184 * and last portions. Packets that fit without wrapping only have
4185 * a first portion (firstPortionBytes == packetBytes and lastPortionData
4186 * will be NULL).
4187 */
4188 typedef struct RAIL_RxPacketInfo {
4189 /** The packet status of this packet. */
4190 RAIL_RxPacketStatus_t packetStatus;
4191 /** The number of packet data bytes available to read in this packet. */
4192 uint16_t packetBytes;
4193 /** The number of bytes in the first portion. */
4194 uint16_t firstPortionBytes;
4195 /**
4196 * The pointer to the first portion of packet data containing
4197 * firstPortionBytes number of bytes.
4198 */
4199 uint8_t *firstPortionData;
4200 /**
4201 * The pointer to the last portion of a packet, if any; NULL otherwise.
4202 * The number of bytes in this portion is
4203 * packetBytes - firstPortionBytes.
4204 */
4205 uint8_t *lastPortionData;
4206 /**
4207 * A bitmask representing which address filter(s) this packet has passed.
4208 * Will be 0 when not filtering or if packet info is retrieved before
4209 * filtering has completed. It's undefined on platforms lacking \ref
4210 * RAIL_SUPPORTS_ADDR_FILTER_MASK.
4211 */
4212 RAIL_AddrFilterMask_t filterMask;
4213 } RAIL_RxPacketInfo_t;
4214
4215 /**
4216 * @struct RAIL_RxPacketDetails_t
4217 * @brief Received packet details obtained via \ref RAIL_GetRxPacketDetails()
4218 * or RAIL_GetRxPacketDetailsAlt().
4219 *
4220 * @note Certain details are always available, while others are only available
4221 * if the \ref RAIL_RxOptions_t \ref RAIL_RX_OPTION_REMOVE_APPENDED_INFO
4222 * option is not in effect and the received packet's
4223 * \ref RAIL_RxPacketStatus_t is among the RAIL_RX_PACKET_READY_ set.
4224 * Each detail's description indicates its availability.
4225 *
4226 */
4227 typedef struct RAIL_RxPacketDetails {
4228 /**
4229 * The timestamp of the received packet in the RAIL timebase.
4230 *
4231 * When not available it will be \ref RAIL_PACKET_TIME_INVALID.
4232 */
4233 RAIL_PacketTimeStamp_t timeReceived;
4234 /**
4235 * Indicates whether the CRC passed or failed for the received packet.
4236 * It is true for \ref RAIL_RX_PACKET_READY_SUCCESS packets and false
4237 * for all others.
4238 *
4239 * It is always available.
4240 */
4241 bool crcPassed;
4242 /**
4243 * Indicate whether the received packet was the expected Ack.
4244 * It is true for the expected Ack and false otherwise.
4245 *
4246 * It is always available.
4247 *
4248 * An expected Ack is defined as a protocol-correct Ack packet
4249 * successfully-received (\ref RAIL_RX_PACKET_READY_SUCCESS or
4250 * \ref RAIL_RX_PACKET_READY_CRC_ERROR) and whose sync word was
4251 * detected within the
4252 * RAIL_AutoAckConfig_t::ackTimeout period following a transmit
4253 * which specified \ref RAIL_TX_OPTION_WAIT_FOR_ACK, requested
4254 * an Ack, and Auto-Ack is enabled. When true, the ackTimeout
4255 * period was terminated so no \ref RAIL_EVENT_RX_ACK_TIMEOUT
4256 * will be subsequently posted for the transmit.
4257 *
4258 * A "protocol-correct Ack" applies to the 802.15.4 or Z-Wave
4259 * protocols for which RAIL can discern the frame type and match
4260 * the Ack's sequence number with that of the transmitted frame.
4261 * For other protocols, the first packet successfully-received
4262 * whose sync word was detected within the \ref
4263 * RAIL_AutoAckConfig_t::ackTimeout period is
4264 * considered the expected Ack; upper layers are responsible for
4265 * confirming this.
4266 */
4267 bool isAck;
4268 /**
4269 * RSSI of the received packet in integer dBm. This RSSI measurement is
4270 * started as soon as the sync word is detected. The duration of the
4271 * measurement is PHY-specific.
4272 *
4273 * When not available it will be \ref RAIL_RSSI_INVALID_DBM.
4274 */
4275 int8_t rssi;
4276 /**
4277 * The link quality indicator of the received packet. A zero would
4278 * indicate a very low quality packet while a 255 would indicate a very
4279 * high quality packet.
4280 *
4281 * When not available it will be 0.
4282 */
4283 uint8_t lqi;
4284 /**
4285 * For radios and PHY configurations that support multiple sync words, this
4286 * number is the ID of the sync word that was used for this packet.
4287 *
4288 * It is always available.
4289 */
4290 uint8_t syncWordId;
4291 /**
4292 * In configurations where the radio has the option of receiving a given
4293 * packet in multiple ways, indicates which of the sub-PHY options
4294 * was used to receive the packet. Most radio configurations do not have
4295 * this ability and the subPhyId is set to 0.
4296 *
4297 * Currently, this field is used by the BLE Coded PHY, the BLE Simulscan PHY
4298 * and the SUN OFDM PHYs.
4299 * In BLE cases, a value of 0 marks a 500 kbps packet, a value of 1 marks a 125
4300 * kbps packet, and a value of 2 marks a 1 Mbps packet.
4301 * Also, see \ref RAIL_BLE_ConfigPhyCoded() and \ref RAIL_BLE_ConfigPhySimulscan().
4302 *
4303 * In SUN OFDM cases, the value corresponds to the numerical value of the
4304 * Modulation and Coding Scheme (MCS) level of the last received packet.
4305 * The packet bitrate depends on the MCS value, as well as the OFDM option.
4306 * Packets bitrates for SUN OFDM PHYs can be found in 802.15.4-2020 specification,
4307 * chapter 20.3, table 20-10.
4308 * Ex: Packet bitrate for OFDM option 1 MCS0 is 100kb/s and 2400kb/s for MCS6.
4309 *
4310 * In WMBUS cases, when using PHY_wMbus_ModeTC_M2O_100k_frameA with simultaneous
4311 * RX of T and C modes enabled (\ref RAIL_WMBUS_Config()), the value corresponds
4312 * to \ref RAIL_WMBUS_Phy_t.
4313 *
4314 * It is always available.
4315 */
4316 uint8_t subPhyId;
4317 /**
4318 * For \ref Antenna_Control configurations where the device has multiple
4319 * antennas, this indicates which antenna received the packet. When there
4320 * is only one antenna, this will be set to the default of 0.
4321 *
4322 * It is always available.
4323 */
4324 uint8_t antennaId;
4325 /**
4326 * When channel hopping is enabled, this field will contain the index
4327 * of the channel in \ref RAIL_RxChannelHoppingConfig_t::entries on which
4328 * this packet was received, or a sentinel value.
4329 *
4330 * It is always available.
4331 */
4332 uint8_t channelHoppingChannelIndex;
4333 /**
4334 * The channel on which the packet was received.
4335 *
4336 * It is always available.
4337 *
4338 * @note It is best to fully process (empty or clear) the receive FIFO
4339 * before changing channel configurations (\ref RAIL_ConfigChannels()
4340 * or a built-in configuration) as unprocessed packets' channel
4341 * could reflect the wrong configuration.
4342 */
4343 uint16_t channel;
4344 } RAIL_RxPacketDetails_t;
4345
4346 /**
4347 * @typedef RAIL_ConvertLqiCallback_t
4348 * @brief A pointer to a function called before LQI is copied into the
4349 * \ref RAIL_RxPacketDetails_t structure.
4350 *
4351 * @param[in] lqi The LQI value obtained by hardware and being readied for
4352 * application consumption. This LQI value is in integral units ranging from
4353 * 0 to 255.
4354 * @param[in] rssi The RSSI value corresponding to the packet from which the
4355 * hardware LQI value was obtained. This RSSI value is in integral dBm units.
4356 * @return uint8_t The converted LQI value that will be loaded into the
4357 * \ref RAIL_RxPacketDetails_t structure in preparation for application
4358 * consumption. This value should likewise be in integral units ranging from
4359 * 0 to 255.
4360 */
4361 typedef uint8_t (*RAIL_ConvertLqiCallback_t)(uint8_t lqi,
4362 int8_t rssi);
4363
4364 /**
4365 * @struct RAIL_PrsLnaBypassConfig_t
4366 * @brief Configures the automatic PRS LNA bypass.
4367 */
4368 typedef struct RAIL_PrsLnaBypassConfig {
4369 /**
4370 * Maximum time in microseconds to wait for frame detection after the LNA has
4371 * been bypassed. It must be greater than 0 to enable automatic PRS LNA
4372 * bypass with \ref RAIL_EnablePrsLnaBypass().
4373 */
4374 uint32_t timeoutUs;
4375 /**
4376 * Threshold (without unit) from which LNA bypass is turned on.
4377 * The table below shows EFR32XG25 thresholds corresponding to received power
4378 * level without the LNA gain.
4379 *
4380 * | Level dB | FSK_1a | FSK_1b | FSK_2a | FSK_2b | FSK_3 | FSK_4a | FSK_4b | FSK_5 | OFDM1 | OFDM2 | OFDM3 | OFDM4 |
4381 * |------------|--------|--------|--------|--------|-------|--------|--------|-------|-------|-------|-------|-------|
4382 * | __-25__ | | | | | | | | | 9 | 9 | 9 | 10 |
4383 * | __-20__ | | 7 | 7 | 7 | 8 | 8 | 7 | 8 | 11 | 12 | 12 | 12 |
4384 * | __-15__ | 7 | 10 | 10 | 10 | 9 | 9 | 10 | 10 | 14 | 14 | 14 | 15 |
4385 * | __-10__ | 9 | 12 | 12 | 12 | 12 | 12 | 12 | 12 | 16 | 16 | 16 | 16 |
4386 * | __-5__ | 11 | 14 | 14 | 14 | 16 | 16 | 14 | 16 | | | | |
4387 * | __0__ | 14 | 17 | 18 | 17 | 17 | 18 | 18 | 18 | | | | |
4388 *
4389 * For example, with OFDM1 PHY, setting the threshold to 11 will turn on the
4390 * bypass when the power level at EFR32XG25 input is greater than -20 dB.
4391 */
4392 uint8_t threshold;
4393 /**
4394 * Compensation in dBm applied by RAIL to RSSI during LNA bypass. The RSSI
4395 * offset set using \ref RAIL_SetRssiOffset() must corespond to the case
4396 * with FEM LNA not bypassed. deltaRssiDbm is typically the FEM LNA gain
4397 * value.
4398 */
4399 uint8_t deltaRssiDbm;
4400 /**
4401 * PRS Channel used for the bypass.
4402 * PRS_GetFreeChannel() can be use to find a free channel. Then the signal
4403 * can be routed to GPIO pin and port using PRS_PinOutput(). This allows
4404 * logical operations with other PRS channels and so to adapt to the FEM
4405 * control logic table. Any call to PRS_Combine() with
4406 * \ref RAIL_PrsLnaBypassConfig_t::prsChannel as chA must be done after
4407 * the \ref RAIL_EnablePrsLnaBypass() call.
4408 */
4409 uint8_t prsChannel;
4410 /**
4411 * PRS signal polarity for bypass.
4412 *
4413 * With a polarity of 1, PRS signal is set to 1 for bypass and 0 for un-bypass.
4414 * with a polarity of 0, PRS signal is set to 0 for bypass and 1 for un-bypass.
4415 */
4416 bool polarity;
4417 } RAIL_PrsLnaBypassConfig_t;
4418
4419 /** @} */ // end of group Receive
4420
4421 /******************************************************************************
4422 * Auto-Ack Structures
4423 *****************************************************************************/
4424 /**
4425 * @addtogroup Auto_Ack
4426 * @{
4427 */
4428 /**
4429 * @struct RAIL_AutoAckConfig_t
4430 * @brief Enable/disable the Auto-Ack algorithm, based on "enable".
4431 *
4432 * The structure provides a default state (the "success" of TX/RX transitions
4433 * when Acking is enabled) for the radio to return to after an Ack
4434 * operation occurs (transmitting or attempting to receive an Ack), or normal
4435 * state transitions to return to in the case Acking is
4436 * disabled. Regardless whether the Ack operation was successful, the
4437 * radio returns to the specified success state.
4438 *
4439 * ackTimeout specifies how long to stay in receive and wait for an Ack
4440 * to start (sync detected) before issuing a \ref RAIL_EVENT_RX_ACK_TIMEOUT
4441 * event and return to the default state.
4442 */
4443 typedef struct RAIL_AutoAckConfig {
4444 /**
4445 * Indicate whether Auto-Acking should be enabled or disabled.
4446 */
4447 bool enable;
4448 // Unnamed 'uint8_t reserved1[1]' pad byte field here.
4449 /**
4450 * Define the RX Ack timeout duration in microseconds up to 65535
4451 * microseconds maximum. Only applied when Auto-Acking is enabled.
4452 * The Ack timeout timer starts at the completion of a \ref
4453 * RAIL_TX_OPTION_WAIT_FOR_ACK transmit and expires only while waiting
4454 * for a packet (prior to SYNC detect), triggering \ref
4455 * RAIL_EVENT_RX_ACK_TIMEOUT. During packet reception that event is
4456 * held off until packet completion and suppressed entirely if the
4457 * received packet is the expected Ack.
4458 */
4459 uint16_t ackTimeout;
4460 /**
4461 * State transitions to do after receiving a packet. When Auto-Acking is
4462 * enabled, the "error" transition is always ignored and the radio will
4463 * return to the "success" state after any Acking sequence
4464 * (\ref RAIL_RF_STATE_RX or \ref RAIL_RF_STATE_IDLE).
4465 * See \ref RAIL_ConfigAutoAck() for more details on this.
4466 */
4467 RAIL_StateTransitions_t rxTransitions;
4468 /**
4469 * State transitions to do after transmitting a packet. When Auto-Acking is
4470 * enabled, the "error" transition is always ignored and the radio will
4471 * return to the "success" state after any Acking sequence
4472 * (\ref RAIL_RF_STATE_RX or \ref RAIL_RF_STATE_IDLE).
4473 * See \ref RAIL_ConfigAutoAck() for more details on this.
4474 */
4475 RAIL_StateTransitions_t txTransitions;
4476 } RAIL_AutoAckConfig_t;
4477
4478 /**
4479 * @def RAIL_AUTOACK_MAX_LENGTH
4480 * @brief Acknowledgment packets cannot be longer than 64 bytes.
4481 */
4482 #define RAIL_AUTOACK_MAX_LENGTH (64U)
4483
4484 /** @} */ // end of group Auto_Ack
4485
4486 /******************************************************************************
4487 * Antenna Control
4488 *****************************************************************************/
4489 /**
4490 * @addtogroup Antenna_Control
4491 * @{
4492 *
4493 * These enumerations and structures are used with RAIL Antenna Control API.
4494 * EFR32 supports up to two antennas with configurable pin locations.
4495 */
4496
4497 /** Antenna path Selection enumeration. */
RAIL_ENUM(RAIL_AntennaSel_t)4498 RAIL_ENUM(RAIL_AntennaSel_t) {
4499 /** Enum for antenna path 0. */
4500 RAIL_ANTENNA_0 = 0,
4501 /** Enum for antenna path 1. */
4502 RAIL_ANTENNA_1 = 1,
4503 /** Enum for antenna path auto. */
4504 RAIL_ANTENNA_AUTO = 255,
4505 };
4506
4507 #ifndef DOXYGEN_SHOULD_SKIP_THIS
4508 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
4509 #define RAIL_ANTENNA_0 ((RAIL_AntennaSel_t) RAIL_ANTENNA_0)
4510 #define RAIL_ANTENNA_1 ((RAIL_AntennaSel_t) RAIL_ANTENNA_1)
4511 #define RAIL_ANTENNA_AUTO ((RAIL_AntennaSel_t) RAIL_ANTENNA_AUTO)
4512 #endif//DOXYGEN_SHOULD_SKIP_THIS
4513
4514 /**
4515 * @struct RAIL_AntennaConfig_t
4516 * @brief A configuration for antenna selection.
4517 */
4518 typedef struct RAIL_AntennaConfig {
4519 /** Antenna 0 Pin Enable */
4520 bool ant0PinEn;
4521 /** Antenna 1 Pin Enable */
4522 bool ant1PinEn;
4523 /**
4524 * A \ref RAIL_AntennaSel_t
4525 * value specifying the internal default RF path. It is ignored
4526 * on EFR32 parts that have only one RF path bonded
4527 * out and on EFR32xG28 dual-band OPNs where the appropriate
4528 * RF path is automatically set by RAIL to 0 for 2.4 GHz band
4529 * and 1 for Sub-GHz band PHYs. On EFR32xG23 and EFR32xG28
4530 * single-band OPNs where both RF paths are bonded out this can
4531 * be set to \ref RAIL_ANTENNA_AUTO to effect internal RF path
4532 * diversity on PHYs supporting diversity. This avoids the need
4533 * for an external RF switch and the associated GPIO(s) needed
4534 * to control its antenna selection.
4535 */
4536 uint8_t defaultPath;
4537 /** Antenna 0 output GPIO port */
4538 uint8_t ant0Port;
4539 /** Antenna 0 output GPIO pin */
4540 uint8_t ant0Pin;
4541 /** @deprecated No longer used (ignored). */
4542 uint8_t ant1Loc;
4543 /** Antenna 1 output GPIO port */
4544 uint8_t ant1Port;
4545 /** Antenna 1 output GPIO pin */
4546 uint8_t ant1Pin;
4547 } RAIL_AntennaConfig_t;
4548
4549 /**
4550 * @deprecated Backwards compatible name for
4551 * \ref RAIL_AntennaConfig_t::defaultPath field.
4552 */
4553 #define ant0Loc defaultPath
4554
4555 /** @} */ // end of group Antenna_Control
4556
4557 /******************************************************************************
4558 * External_Thermistor Structures
4559 *****************************************************************************/
4560 /**
4561 * @addtogroup External_Thermistor
4562 * @{
4563 */
4564
4565 /// A sentinel value to indicate an invalid thermistor measurement value.
4566 #define RAIL_INVALID_THERMISTOR_VALUE (0xFFFFFFFFU)
4567 /// A sentinel value to indicate an invalid PPM calculation value.
4568 #define RAIL_INVALID_PPM_VALUE (-128)
4569
4570 /**
4571 * @struct RAIL_HFXOThermistorConfig_t
4572 * @brief Configure the port and pin of the thermistor.
4573 *
4574 * @note This configuration is chip OPN dependent.
4575 */
4576 typedef struct RAIL_HFXOThermistorConfig {
4577 /**
4578 * The GPIO port to access the thermistor.
4579 */
4580 uint8_t port;
4581 /**
4582 * The GPIO pin to set the thermistor.
4583 */
4584 uint8_t pin;
4585 } RAIL_HFXOThermistorConfig_t;
4586
4587 /**
4588 * @struct RAIL_HFXOCompensationConfig_t
4589 * @brief Set compensation specific parameters
4590 */
4591 typedef struct RAIL_HFXOCompensationConfig {
4592 /**
4593 * Indicates whether the HFXO compensation in temperature is activated.
4594 */
4595 bool enableCompensation;
4596 /**
4597 * The temperature reference delimiting the nominal zone from the critical one.
4598 * This field is relevant if enableCompensation is set to true.
4599 */
4600 int8_t zoneTemperatureC;
4601 /**
4602 * The temperature shift used to start a new compensation, in the nominal zone.
4603 * This field is relevant if enableCompensation is set to true.
4604 */
4605 uint8_t deltaNominal;
4606 /**
4607 * The temperature shift used to start a new compensation, in the critical zone.
4608 * This field is relevant if enableCompensation is set to true.
4609 */
4610 uint8_t deltaCritical;
4611 } RAIL_HFXOCompensationConfig_t;
4612
4613 /** @} */ // end of group External_Thermistor
4614
4615 /******************************************************************************
4616 * Calibration Structures
4617 *****************************************************************************/
4618 /**
4619 * @addtogroup Calibration
4620 * @{
4621 *
4622 * The EFR32 supports the Image Rejection (IR)
4623 * calibration and a temperature-dependent calibration. The IR calibration
4624 * can be computed once and stored off or computed each time at
4625 * startup. Because it is PHY-specific and provides sensitivity improvements,
4626 * it is highly recommended. The IR calibration should only be run when the
4627 * radio is IDLE.
4628 *
4629 * The temperature-dependent calibrations are used to recalibrate the synth if
4630 * the temperature crosses 0C or the temperature delta since the last
4631 * calibration exceeds 70C while in receive. RAIL will run the VCO calibration
4632 * automatically upon entering receive or transmit states, so the application
4633 * can omit this calibration if the stack re-enters receive or transmit with
4634 * enough frequency to avoid reaching the temperature delta. If the application
4635 * does not calibrate for temperature, it's possible to miss receive packets due
4636 * to a drift in the carrier frequency.
4637 */
4638
4639 /**
4640 * @typedef RAIL_CalMask_t
4641 * @brief A calibration mask type
4642 *
4643 * This type is a bitmask of different RAIL calibration values. The exact
4644 * meaning of these bits depends on what a particular chip supports.
4645 */
4646 typedef uint32_t RAIL_CalMask_t;
4647
4648 /** EFR32-specific temperature calibration bit. */
4649 #define RAIL_CAL_TEMP_VCO (0x00000001U)
4650 /** EFR32-specific HFXO temperature check bit.
4651 * (Ignored if platform lacks \ref RAIL_SUPPORTS_HFXO_COMPENSATION.) */
4652 #define RAIL_CAL_TEMP_HFXO (0x00000002U)
4653 /** EFR32-specific HFXO compensation bit.
4654 * (Ignored if platform lacks \ref RAIL_SUPPORTS_HFXO_COMPENSATION.) */
4655 #define RAIL_CAL_COMPENSATE_HFXO (0x00000004U)
4656 /** EFR32-specific IR calibration bit. */
4657 #define RAIL_CAL_RX_IRCAL (0x00010000U)
4658 /** EFR32-specific Tx IR calibration bit.
4659 * (Ignored if platform lacks \ref RAIL_SUPPORTS_OFDM_PA.) */
4660 #define RAIL_CAL_OFDM_TX_IRCAL (0x00100000U)
4661
4662 /** A mask to run EFR32-specific IR calibrations. */
4663 #define RAIL_CAL_ONETIME_IRCAL (RAIL_CAL_RX_IRCAL | RAIL_CAL_OFDM_TX_IRCAL)
4664 /** A mask to run temperature-dependent calibrations. */
4665 #define RAIL_CAL_TEMP (RAIL_CAL_TEMP_VCO | RAIL_CAL_TEMP_HFXO | RAIL_CAL_COMPENSATE_HFXO)
4666 /** A mask to run one-time calibrations. */
4667 #define RAIL_CAL_ONETIME (RAIL_CAL_ONETIME_IRCAL)
4668 /** A mask to run optional performance calibrations. */
4669 #define RAIL_CAL_PERF (0)
4670 /** A mask for calibrations that require the radio to be off. */
4671 #define RAIL_CAL_OFFLINE (RAIL_CAL_ONETIME_IRCAL)
4672 /** A mask to run all possible calibrations for this chip. */
4673 #define RAIL_CAL_ALL (RAIL_CAL_TEMP | RAIL_CAL_ONETIME)
4674 /** A mask to run all pending calibrations. */
4675 #define RAIL_CAL_ALL_PENDING (0x00000000U)
4676 /** An invalid calibration value. */
4677 #define RAIL_CAL_INVALID_VALUE (0xFFFFFFFFU)
4678
4679 /**
4680 * @def RAIL_MAX_RF_PATHS
4681 * @brief Indicates the maximum number of RF Paths supported across all
4682 * platforms.
4683 */
4684 #define RAIL_MAX_RF_PATHS 2
4685
4686 /**
4687 * RAIL_RxIrCalValues_t
4688 * @brief RX IR calibration values.
4689 *
4690 * Platforms with fewer \ref RAIL_RF_PATHS than \ref RAIL_MAX_RF_PATHS
4691 * will only respect and update \ref RAIL_RF_PATHS indices and ignore
4692 * the rest.
4693 */
4694 typedef uint32_t RAIL_RxIrCalValues_t[RAIL_MAX_RF_PATHS];
4695
4696 /**
4697 * A define to set all \ref RAIL_RxIrCalValues_t values to uninitialized.
4698 *
4699 * This define can be used when you have no data to pass to the calibration
4700 * routines but wish to compute and save all possible calibrations.
4701 */
4702 #define RAIL_IRCALVALUES_RX_UNINIT { \
4703 [0 ... RAIL_MAX_RF_PATHS - 1] = RAIL_CAL_INVALID_VALUE, \
4704 }
4705
4706 /**
4707 * @struct RAIL_TxIrCalValues_t
4708 * @brief A Tx IR calibration value structure.
4709 *
4710 * This definition contains the set of persistent calibration values for
4711 * OFDM on EFR32. You can set these beforehand and apply them at startup
4712 * to save the time required to compute them. Any of these values may be
4713 * set to \ref RAIL_CAL_INVALID_VALUE to force the code to compute that
4714 * calibration value.
4715 *
4716 * Only supported on platforms with \ref RAIL_SUPPORTS_OFDM_PA enabled.
4717 */
4718 typedef struct RAIL_TxIrCalValues {
4719 /** TXIRCAL result */
4720 uint32_t dcOffsetIQ;
4721 /** TXIRCAL result */
4722 uint32_t phiEpsilon;
4723 } RAIL_TxIrCalValues_t;
4724
4725 /**
4726 * A define to set all \ref RAIL_TxIrCalValues_t values to uninitialized.
4727 *
4728 * This define can be used when you have no data to pass to the calibration
4729 * routines but wish to compute and save all possible calibrations.
4730 */
4731 #define RAIL_IRCALVALUES_TX_UNINIT { \
4732 .dcOffsetIQ = RAIL_CAL_INVALID_VALUE, \
4733 .phiEpsilon = RAIL_CAL_INVALID_VALUE, \
4734 }
4735
4736 /**
4737 * @struct RAIL_IrCalValues_t
4738 * @brief An IR calibration value structure.
4739 *
4740 * This definition contains the set of persistent calibration values for
4741 * EFR32. You can set these beforehand and apply them at startup to save the
4742 * time required to compute them. Any of these values may be set to
4743 * \ref RAIL_CAL_INVALID_VALUE to force the code to compute that calibration value.
4744 */
4745 typedef struct RAIL_IrCalValues {
4746 /** RX Image Rejection (IR) calibration value(s) */
4747 RAIL_RxIrCalValues_t rxIrCalValues;
4748 /** TX Image Rejection (IR) calibration value(s) for OFDM */
4749 RAIL_TxIrCalValues_t txIrCalValues;
4750 } RAIL_IrCalValues_t;
4751
4752 /**
4753 * A define to set all \ref RAIL_IrCalValues_t values to uninitialized.
4754 *
4755 * This define can be used when you have no data to pass to the calibration
4756 * routines but wish to compute and save all possible calibrations.
4757 */
4758 #define RAIL_IRCALVALUES_UNINIT { \
4759 .rxIrCalValues = RAIL_IRCALVALUES_RX_UNINIT, \
4760 .txIrCalValues = RAIL_IRCALVALUES_TX_UNINIT, \
4761 }
4762
4763 /**
4764 * A define allowing Rx calibration value access compatibility
4765 * between non-OFDM and OFDM platforms.
4766 */
4767 #define RAIL_IRCALVAL(irCalStruct, rfPath) \
4768 (((RAIL_IrCalValues_t *)(&(irCalStruct)))->rxIrCalValues[(rfPath)])
4769
4770 /**
4771 * @typedef RAIL_CalValues_t
4772 * @brief A calibration value structure.
4773 *
4774 * This structure contains the set of persistent calibration values for
4775 * EFR32. You can set these beforehand and apply them at startup to save the
4776 * time required to compute them. Any of these values may be set to \ref
4777 * RAIL_CAL_INVALID_VALUE to force the code to compute that calibration value.
4778 */
4779 typedef RAIL_IrCalValues_t RAIL_CalValues_t;
4780
4781 /**
4782 * A define to set all \ref RAIL_CalValues_t values to uninitialized.
4783 *
4784 * This define can be used when you have no data to pass to the calibration
4785 * routines but wish to compute and save all possible calibrations.
4786 */
4787 #define RAIL_CALVALUES_UNINIT RAIL_IRCALVALUES_UNINIT
4788
4789 /// Use this value with either TX or RX values in \ref RAIL_SetPaCTune()
4790 /// to use whatever value is already set and do no update. This
4791 /// value is provided to provide consistency across EFR32 chips,
4792 /// but technically speaking, all PA capacitance tuning values are
4793 /// invalid on EFR32xG21 parts, as \ref RAIL_SetPaCTune() is not supported
4794 /// on those parts.
4795 #define RAIL_PACTUNE_IGNORE (255U)
4796
4797 /** @} */ // end of group Calibration
4798
4799 /******************************************************************************
4800 * RF Sense Structures
4801 *****************************************************************************/
4802 /**
4803 * @addtogroup Rf_Sense
4804 * @{
4805 */
4806
4807 /**
4808 * A pointer to an RF Sense callback function.
4809 *
4810 * Consider using the event \ref RAIL_EVENT_RF_SENSED as an alternative.
4811 */
4812 typedef void (*RAIL_RfSense_CallbackPtr_t)(void);
4813
4814 /**
4815 * RF Sense low sensitivity offset.
4816 */
4817 #define RAIL_RFSENSE_LOW_SENSITIVITY_OFFSET (0x20U)
4818
4819 /**
4820 * @enum RAIL_RfSenseBand_t
4821 * @brief An enumeration for specifying the RF Sense frequency band.
4822 */
RAIL_ENUM(RAIL_RfSenseBand_t)4823 RAIL_ENUM(RAIL_RfSenseBand_t) {
4824 /** RF Sense is disabled. */
4825 RAIL_RFSENSE_OFF,
4826 /** RF Sense is in 2.4 GHz band. */
4827 RAIL_RFSENSE_2_4GHZ,
4828 /** RF Sense is in Sub-GHz band. */
4829 RAIL_RFSENSE_SUBGHZ,
4830 /** RF Sense is in both bands. */
4831 RAIL_RFSENSE_ANY,
4832 /**
4833 * A count of the basic choices in this enumeration.
4834 * Must be last before sensitivity options.
4835 */
4836 RAIL_RFSENSE_MAX,
4837
4838 /** RF Sense is in low sensitivity 2.4 GHz band */
4839 RAIL_RFSENSE_2_4GHZ_LOW_SENSITIVITY = RAIL_RFSENSE_LOW_SENSITIVITY_OFFSET + RAIL_RFSENSE_2_4GHZ,
4840 /** RF Sense is in low sensitivity Sub-GHz band */
4841 RAIL_RFSENSE_SUBGHZ_LOW_SENSITIVITY = RAIL_RFSENSE_LOW_SENSITIVITY_OFFSET + RAIL_RFSENSE_SUBGHZ,
4842 /** RF Sense is in low sensitivity for both bands. */
4843 RAIL_RFENSE_ANY_LOW_SENSITIVITY = RAIL_RFSENSE_LOW_SENSITIVITY_OFFSET + RAIL_RFSENSE_ANY,
4844 };
4845
4846 #ifndef DOXYGEN_SHOULD_SKIP_THIS
4847 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
4848 #define RAIL_RFSENSE_OFF ((RAIL_RfSenseBand_t) RAIL_RFSENSE_OFF)
4849 #define RAIL_RFSENSE_2_4GHZ ((RAIL_RfSenseBand_t) RAIL_RFSENSE_2_4GHZ)
4850 #define RAIL_RFSENSE_SUBGHZ ((RAIL_RfSenseBand_t) RAIL_RFSENSE_SUBGHZ)
4851 #define RAIL_RFSENSE_ANY ((RAIL_RfSenseBand_t) RAIL_RFSENSE_ANY)
4852 #define RAIL_RFSENSE_MAX ((RAIL_RfSenseBand_t) RAIL_RFSENSE_MAX)
4853 #define RAIL_RFSENSE_2_4GHZ_LOW_SENSITIVITY ((RAIL_RfSenseBand_t) RAIL_RFSENSE_2_4GHZ_LOW_SENSITIVITY)
4854 #define RAIL_RFSENSE_SUBGHZ_LOW_SENSITIVITY ((RAIL_RfSenseBand_t) RAIL_RFSENSE_SUBGHZ_LOW_SENSITIVITY)
4855 #define RAIL_RFENSE_ANY_LOW_SENSITIVITY ((RAIL_RfSenseBand_t) RAIL_RFENSE_ANY_LOW_SENSITIVITY)
4856 #endif//DOXYGEN_SHOULD_SKIP_THIS
4857
4858 /**
4859 * Use the MODEM default sync word.
4860 */
4861 #define RAIL_RFSENSE_USE_HW_SYNCWORD (0U)
4862
4863 /**
4864 * @struct RAIL_RfSenseSelectiveOokConfig_t
4865 * @brief Structure to configure RFSENSE Selective(OOK) mode.
4866 */
4867 typedef struct RAIL_RfSenseSelectiveOokConfig {
4868 /**
4869 * The frequency band(s) on which to sense the
4870 * RF energy. To stop RF Sense, specify \ref RAIL_RFSENSE_OFF.
4871 */
4872 RAIL_RfSenseBand_t band;
4873 /**
4874 * Syncword Length in bytes, 1-4 bytes.
4875 * @note When \ref syncWord is set to use \ref RAIL_RFSENSE_USE_HW_SYNCWORD,
4876 * the \ref syncWordNumBytes value will be ignored since we rely on the
4877 * HW default settings for sync word.
4878 */
4879 uint8_t syncWordNumBytes;
4880 /**
4881 * Sync Word Value.
4882 * To use HW default sync word, set to \ref RAIL_RFSENSE_USE_HW_SYNCWORD.
4883 */
4884 uint32_t syncWord;
4885 /**
4886 * The callback function, called when RF is sensed.
4887 *
4888 * @note Set to NULL and instead use \ref RAIL_EVENT_RF_SENSED or poll
4889 * via \ref RAIL_IsRfSensed().
4890 */
4891 RAIL_RfSense_CallbackPtr_t cb;
4892 } RAIL_RfSenseSelectiveOokConfig_t;
4893
4894 /** @} */ // end of group Rf_Sense
4895
4896 /******************************************************************************
4897 * RX Channel Hopping
4898 *****************************************************************************/
4899 /**
4900 * @addtogroup Rx_Channel_Hopping RX Channel Hopping
4901 * @{
4902 */
4903
4904 /**
4905 * @enum RAIL_RxChannelHoppingMode_t
4906 * @brief Modes by which RAIL can determine when to proceed to the next
4907 * channel during channel hopping
4908 */
RAIL_ENUM(RAIL_RxChannelHoppingMode_t)4909 RAIL_ENUM(RAIL_RxChannelHoppingMode_t) {
4910 /**
4911 * Switch to the next channel each time the radio re-enters RX after
4912 * packet reception or a transmit based on the corresponding \ref
4913 * State_Transitions. A hop can also be manually triggered by calling
4914 * \ref RAIL_CalibrateTemp() while the radio is listening.
4915 *
4916 * @warning This mode currently does not issue \ref
4917 * RAIL_EVENT_RX_CHANNEL_HOPPING_COMPLETE when hopping out of
4918 * the last channel in the hop sequence.
4919 * As a workaround, an application can monitor the current hop channel
4920 * with \ref RAIL_GetChannelAlt().
4921 */
4922 RAIL_RX_CHANNEL_HOPPING_MODE_MANUAL = 0,
4923 /**
4924 * Switch to the next channel after a certain amount of time passes.
4925 * The time should be specified in microseconds in \ref
4926 * RAIL_RxChannelHoppingConfigEntry_t::parameter, and must be less
4927 * than \ref RAIL_RX_CHANNEL_HOPPING_MAX_SENSE_TIME_US.
4928 */
4929 RAIL_RX_CHANNEL_HOPPING_MODE_TIMEOUT = 1,
4930 /**
4931 * Listen in receive RX for at least a specified timeout. If,
4932 * by the end of the timeout, the radio has packet timing,
4933 * remain in the current channel until the radio loses it. The
4934 * timeout should be specified in microseconds in \ref
4935 * RAIL_RxChannelHoppingConfigEntry_t::parameter, and must be less
4936 * than \ref RAIL_RX_CHANNEL_HOPPING_MAX_SENSE_TIME_US.
4937 */
4938 RAIL_RX_CHANNEL_HOPPING_MODE_TIMING_SENSE = 2,
4939 /**
4940 * Listen in receive RX for at least a specified timeout. If,
4941 * by the end of the timeout, the radio has a packet preamble,
4942 * remain in the current channel until the radio loses it. The
4943 * timeout should be specified in microseconds in \ref
4944 * RAIL_RxChannelHoppingConfigEntry_t::parameter, and must be less
4945 * than \ref RAIL_RX_CHANNEL_HOPPING_MAX_SENSE_TIME_US.
4946 */
4947 RAIL_RX_CHANNEL_HOPPING_MODE_PREAMBLE_SENSE = 3,
4948 /**
4949 * Placeholder for a reserved hopping mode that is not supported.
4950 */
4951 RAIL_RX_CHANNEL_HOPPING_MODE_RESERVED1 = 4,
4952 /**
4953 * A mode that combines modes TIMING_SENSE, PREAMBLE_SENSE, and
4954 * TIMEOUT (sync detect) all running in parallel. Refer to \ref
4955 * RAIL_RxChannelHoppingConfigMultiMode_t for further details.
4956 * A pointer to that structure, allocated in global read-write
4957 * memory and initialized to the desired configuration values, is
4958 * specified as the \ref RAIL_RxChannelHoppingConfigEntry_t::parameter
4959 * or \ref RAIL_RxDutyCycleConfig_t::parameter, cast appropriately:
4960 * @code{.c}
4961 * .parameter = (uint32_t)(void *)&hoppingConfigMultiMode,
4962 * @endcode
4963 *
4964 * @note RAIL will overwrite the contents of the \ref
4965 * RAIL_RxChannelHoppingConfigMultiMode_t during operation so it
4966 * must be reinitialized with the desired configuration prior to
4967 * every call to \ref RAIL_ConfigRxChannelHopping() or
4968 * \ref RAIL_ConfigRxDutyCycle().
4969 *
4970 * @note Multiple \ref RAIL_RxChannelHoppingConfigEntry_t entries may
4971 * share the same \ref RAIL_RxChannelHoppingConfigMultiMode_t if their
4972 * settings are identical, otherwise a separate \ref
4973 * RAIL_RxChannelHoppingConfigMultiMode_t is needed for each
4974 * \ref RAIL_RxChannelHoppingConfigEntry_t that uses this mode.
4975 */
4976 RAIL_RX_CHANNEL_HOPPING_MODE_MULTI_SENSE = 5,
4977 /**
4978 * Switch to the next channel based on the demodulation settings in the PHY
4979 * config. This mode is PHY and chip dependent. The
4980 * \ref RAIL_RxChannelHoppingConfigEntry_t::parameter is ignored, and should
4981 * be set to 0 for future compatibility.
4982 */
4983 RAIL_RX_CHANNEL_HOPPING_MODE_SQ = 6,
4984 /**
4985 * Marks that the channel is concurrent with another channel, and otherwise
4986 * behaves identically to \ref RAIL_RX_CHANNEL_HOPPING_MODE_SQ.
4987 */
4988 RAIL_RX_CHANNEL_HOPPING_MODE_CONC = 7,
4989 /**
4990 * Indicates that this channel is a virtual channel that is concurrently
4991 * detected with the channel indicated by the
4992 * \ref RAIL_RxChannelHoppingConfigEntry_t::parameter. Otherwise behaves
4993 * identically to \ref RAIL_RX_CHANNEL_HOPPING_MODE_SQ.
4994 */
4995 RAIL_RX_CHANNEL_HOPPING_MODE_VT = 8,
4996 /**
4997 * This is the transmit channel used for Auto-Ack if the regular channel,
4998 * specified in RAIL_RxChannelHoppingConfigEntry::parameter, is
4999 * optimized for RX which may degrade some TX performance
5000 */
5001 RAIL_RX_CHANNEL_HOPPING_MODE_TX = 9,
5002 /**
5003 * A count of the basic choices in this enumeration.
5004 * Must be last before _WITH_OPTIONS twins.
5005 */
5006 RAIL_RX_CHANNEL_HOPPING_MODES_COUNT,
5007
5008 /**
5009 * The start of equivalent modes requiring non-default \ref
5010 * RAIL_RxDutyCycleConfig_t::options, needed for backwards-compatibility
5011 * with earlier \ref RAIL_RxDutyCycleConfig_t format. Non-default options
5012 * are supported with \ref RAIL_RxChannelHoppingConfigEntry_t in all modes.
5013 */
5014 RAIL_RX_CHANNEL_HOPPING_MODES_WITH_OPTIONS_BASE = 0x80,
5015 /** Variant of \ref RAIL_RX_CHANNEL_HOPPING_MODE_MANUAL with options. */
5016 RAIL_RX_CHANNEL_HOPPING_MODE_MANUAL_WITH_OPTIONS
5017 = (RAIL_RX_CHANNEL_HOPPING_MODES_WITH_OPTIONS_BASE
5018 + RAIL_RX_CHANNEL_HOPPING_MODE_MANUAL),
5019 /** Variant of \ref RAIL_RX_CHANNEL_HOPPING_MODE_TIMEOUT with options. */
5020 RAIL_RX_CHANNEL_HOPPING_MODE_TIMEOUT_WITH_OPTIONS
5021 = (RAIL_RX_CHANNEL_HOPPING_MODES_WITH_OPTIONS_BASE
5022 + RAIL_RX_CHANNEL_HOPPING_MODE_TIMEOUT),
5023 /** Variant of \ref RAIL_RX_CHANNEL_HOPPING_MODE_TIMING_SENSE with options. */
5024 RAIL_RX_CHANNEL_HOPPING_MODE_TIMING_SENSE_WITH_OPTIONS
5025 = (RAIL_RX_CHANNEL_HOPPING_MODES_WITH_OPTIONS_BASE
5026 + RAIL_RX_CHANNEL_HOPPING_MODE_TIMING_SENSE),
5027 /** Variant of \ref RAIL_RX_CHANNEL_HOPPING_MODE_PREAMBLE_SENSE with options. */
5028 RAIL_RX_CHANNEL_HOPPING_MODE_PREAMBLE_SENSE_WITH_OPTIONS
5029 = (RAIL_RX_CHANNEL_HOPPING_MODES_WITH_OPTIONS_BASE
5030 + RAIL_RX_CHANNEL_HOPPING_MODE_PREAMBLE_SENSE),
5031 /** Variant of \ref RAIL_RX_CHANNEL_HOPPING_MODE_RESERVED1 with options. */
5032 RAIL_RX_CHANNEL_HOPPING_MODE_RESERVED1_WITH_OPTIONS
5033 = (RAIL_RX_CHANNEL_HOPPING_MODES_WITH_OPTIONS_BASE
5034 + RAIL_RX_CHANNEL_HOPPING_MODE_RESERVED1),
5035 /** Variant of \ref RAIL_RX_CHANNEL_HOPPING_MODE_MULTI_SENSE with options. */
5036 RAIL_RX_CHANNEL_HOPPING_MODE_MULTI_SENSE_WITH_OPTIONS
5037 = (RAIL_RX_CHANNEL_HOPPING_MODES_WITH_OPTIONS_BASE
5038 + RAIL_RX_CHANNEL_HOPPING_MODE_MULTI_SENSE),
5039 /** Variant of \ref RAIL_RX_CHANNEL_HOPPING_MODE_SQ with options. */
5040 RAIL_RX_CHANNEL_HOPPING_MODE_SQ_WITH_OPTIONS
5041 = (RAIL_RX_CHANNEL_HOPPING_MODES_WITH_OPTIONS_BASE
5042 + RAIL_RX_CHANNEL_HOPPING_MODE_SQ),
5043 /** Variant of \ref RAIL_RX_CHANNEL_HOPPING_MODE_CONC with options. */
5044 RAIL_RX_CHANNEL_HOPPING_MODE_CONC_WITH_OPTIONS
5045 = (RAIL_RX_CHANNEL_HOPPING_MODES_WITH_OPTIONS_BASE
5046 + RAIL_RX_CHANNEL_HOPPING_MODE_CONC),
5047 /** Variant of \ref RAIL_RX_CHANNEL_HOPPING_MODE_VT with options. */
5048 RAIL_RX_CHANNEL_HOPPING_MODE_VT_WITH_OPTIONS
5049 = (RAIL_RX_CHANNEL_HOPPING_MODES_WITH_OPTIONS_BASE
5050 + RAIL_RX_CHANNEL_HOPPING_MODE_VT),
5051 /** Variant of \ref RAIL_RX_CHANNEL_HOPPING_MODE_TX with options. */
5052 RAIL_RX_CHANNEL_HOPPING_MODE_TX_WITH_OPTIONS
5053 = (RAIL_RX_CHANNEL_HOPPING_MODES_WITH_OPTIONS_BASE
5054 + RAIL_RX_CHANNEL_HOPPING_MODE_TX),
5055 };
5056
5057 #ifndef DOXYGEN_SHOULD_SKIP_THIS
5058 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
5059 #define RAIL_RX_CHANNEL_HOPPING_MODE_MANUAL ((RAIL_RxChannelHoppingMode_t) RAIL_RX_CHANNEL_HOPPING_MODE_MANUAL)
5060 #define RAIL_RX_CHANNEL_HOPPING_MODE_TIMEOUT ((RAIL_RxChannelHoppingMode_t) RAIL_RX_CHANNEL_HOPPING_MODE_TIMEOUT)
5061 #define RAIL_RX_CHANNEL_HOPPING_MODE_TIMING_SENSE ((RAIL_RxChannelHoppingMode_t) RAIL_RX_CHANNEL_HOPPING_MODE_TIMING_SENSE)
5062 #define RAIL_RX_CHANNEL_HOPPING_MODE_PREAMBLE_SENSE ((RAIL_RxChannelHoppingMode_t) RAIL_RX_CHANNEL_HOPPING_MODE_PREAMBLE_SENSE)
5063 #define RAIL_RX_CHANNEL_HOPPING_MODE_RESERVED1 ((RAIL_RxChannelHoppingMode_t) RAIL_RX_CHANNEL_HOPPING_MODE_RESERVED1)
5064 #define RAIL_RX_CHANNEL_HOPPING_MODE_MULTI_SENSE ((RAIL_RxChannelHoppingMode_t) RAIL_RX_CHANNEL_HOPPING_MODE_MULTI_SENSE)
5065 #define RAIL_RX_CHANNEL_HOPPING_MODE_SQ ((RAIL_RxChannelHoppingMode_t) RAIL_RX_CHANNEL_HOPPING_MODE_SQ)
5066 #define RAIL_RX_CHANNEL_HOPPING_MODE_CONC ((RAIL_RxChannelHoppingMode_t) RAIL_RX_CHANNEL_HOPPING_MODE_CONC)
5067 #define RAIL_RX_CHANNEL_HOPPING_MODE_VT ((RAIL_RxChannelHoppingMode_t) RAIL_RX_CHANNEL_HOPPING_MODE_VT)
5068 #define RAIL_RX_CHANNEL_HOPPING_MODE_TX ((RAIL_RxChannelHoppingMode_t) RAIL_RX_CHANNEL_HOPPING_MODE_TX)
5069 #define RAIL_RX_CHANNEL_HOPPING_MODES_WITH_OPTIONS_BASE ((RAIL_RxChannelHoppingMode_t) RAIL_RX_CHANNEL_HOPPING_MODES_WITH_OPTIONS_BASE)
5070 #define RAIL_RX_CHANNEL_HOPPING_MODE_MANUAL_WITH_OPTIONS ((RAIL_RxChannelHoppingMode_t) RAIL_RX_CHANNEL_HOPPING_MODE_MANUAL_WITH_OPTIONS)
5071 #define RAIL_RX_CHANNEL_HOPPING_MODE_TIMEOUT_WITH_OPTIONS ((RAIL_RxChannelHoppingMode_t) RAIL_RX_CHANNEL_HOPPING_MODE_TIMEOUT_WITH_OPTIONS)
5072 #define RAIL_RX_CHANNEL_HOPPING_MODE_TIMING_SENSE_WITH_OPTIONS ((RAIL_RxChannelHoppingMode_t) RAIL_RX_CHANNEL_HOPPING_MODE_TIMING_SENSE_WITH_OPTIONS)
5073 #define RAIL_RX_CHANNEL_HOPPING_MODE_PREAMBLE_SENSE_WITH_OPTIONS ((RAIL_RxChannelHoppingMode_t) RAIL_RX_CHANNEL_HOPPING_MODE_PREAMBLE_SENSE_WITH_OPTIONS)
5074 #define RAIL_RX_CHANNEL_HOPPING_MODE_RESERVED1_WITH_OPTIONS ((RAIL_RxChannelHoppingMode_t) RAIL_RX_CHANNEL_HOPPING_MODE_RESERVED1_WITH_OPTIONS)
5075 #define RAIL_RX_CHANNEL_HOPPING_MODE_MULTI_SENSE_WITH_OPTIONS ((RAIL_RxChannelHoppingMode_t) RAIL_RX_CHANNEL_HOPPING_MODE_MULTI_SENSE_WITH_OPTIONS)
5076 #define RAIL_RX_CHANNEL_HOPPING_MODE_SQ_WITH_OPTIONS ((RAIL_RxChannelHoppingMode_t) RAIL_RX_CHANNEL_HOPPING_MODE_SQ_WITH_OPTIONS)
5077 #define RAIL_RX_CHANNEL_HOPPING_MODE_CONC_WITH_OPTIONS ((RAIL_RxChannelHoppingMode_t) RAIL_RX_CHANNEL_HOPPING_MODE_CONC_WITH_OPTIONS)
5078 #define RAIL_RX_CHANNEL_HOPPING_MODE_VT_WITH_OPTIONS ((RAIL_RxChannelHoppingMode_t) RAIL_RX_CHANNEL_HOPPING_MODE_VT_WITH_OPTIONS)
5079 #define RAIL_RX_CHANNEL_HOPPING_MODE_TX_WITH_OPTIONS ((RAIL_RxChannelHoppingMode_t) RAIL_RX_CHANNEL_HOPPING_MODE_TX_WITH_OPTIONS)
5080 #endif//DOXYGEN_SHOULD_SKIP_THIS
5081
5082 /**
5083 * The maximum sense time supported for those \ref RAIL_RxChannelHoppingMode_t
5084 * modes whose parameter(s) specify a sensing time.
5085 */
5086 #define RAIL_RX_CHANNEL_HOPPING_MAX_SENSE_TIME_US 0x08000000UL
5087
5088 /**
5089 * @enum RAIL_RxChannelHoppingDelayMode_t
5090 * @deprecated Set only to RAIL_RX_CHANNEL_DELAY_MODE_STATIC.
5091 */
RAIL_ENUM(RAIL_RxChannelHoppingDelayMode_t)5092 RAIL_ENUM(RAIL_RxChannelHoppingDelayMode_t) {
5093 /**
5094 * Always delay for exactly the amount of time specified
5095 * in the delay parameter, regardless of how other channel
5096 * hopping channels were extended via preamble sense or other means.
5097 */
5098 RAIL_RX_CHANNEL_HOPPING_DELAY_MODE_STATIC = 0,
5099 };
5100
5101 #ifndef DOXYGEN_SHOULD_SKIP_THIS
5102 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
5103 #define RAIL_RX_CHANNEL_HOPPING_DELAY_MODE_STATIC ((RAIL_RxChannelHoppingDelayMode_t) RAIL_RX_CHANNEL_HOPPING_DELAY_MODE_STATIC)
5104 #endif//DOXYGEN_SHOULD_SKIP_THIS
5105
5106 /**
5107 * @typedef RAIL_RxChannelHoppingParameter_t
5108 * @brief Rx channel hopping on-channel time
5109 */
5110 typedef uint32_t RAIL_RxChannelHoppingParameter_t;
5111
5112 /**
5113 * @enum RAIL_RxChannelHoppingOptions_t
5114 * @brief Options that can customize channel hopping behavior
5115 * on a per-hop basis.
5116 */
RAIL_ENUM(RAIL_RxChannelHoppingOptions_t)5117 RAIL_ENUM(RAIL_RxChannelHoppingOptions_t) {
5118 /** Shift position of \ref RAIL_RX_CHANNEL_HOPPING_OPTION_SKIP_SYNTH_CAL bit. */
5119 RAIL_RX_CHANNEL_HOPPING_OPTION_SKIP_SYNTH_CAL_SHIFT = 0,
5120 /** Shift position of \ref RAIL_RX_CHANNEL_HOPPING_OPTION_SKIP_DC_CAL bit. */
5121 RAIL_RX_CHANNEL_HOPPING_OPTION_SKIP_DC_CAL_SHIFT = 1,
5122 /** Shift position of \ref RAIL_RX_CHANNEL_HOPPING_OPTION_RSSI_THRESHOLD bit. */
5123 RAIL_RX_CHANNEL_HOPPING_OPTION_RSSI_THRESHOLD_SHIFT = 2,
5124 /** Stop hopping on this hop. */
5125 RAIL_RX_CHANNEL_HOPPING_OPTION_STOP_SHIFT = 3,
5126 /** A count of the choices in this enumeration. Must be last. */
5127 RAIL_RX_CHANNEL_HOPPING_OPTIONS_COUNT
5128 };
5129
5130 /** A value representing no options enabled. */
5131 #define RAIL_RX_CHANNEL_HOPPING_OPTIONS_NONE 0U
5132 /**
5133 * All options disabled by default.
5134 * Channel hopping will behave as described by other
5135 * parameters as it did in RAIL 2.7 and earlier.
5136 */
5137 #define RAIL_RX_CHANNEL_HOPPING_OPTIONS_DEFAULT RAIL_RX_CHANNEL_HOPPING_OPTIONS_NONE
5138 /**
5139 * @deprecated Please use \ref RAIL_RX_CHANNEL_HOPPING_OPTIONS_DEFAULT instead.
5140 */
5141 #define RAIL_RX_CHANNEL_HOPPING_OPTION_DEFAULT RAIL_RX_CHANNEL_HOPPING_OPTIONS_DEFAULT
5142 /**
5143 * An option to skip synth calibration while *hopping into* the channel
5144 * specified in the current entry.
5145 */
5146 #define RAIL_RX_CHANNEL_HOPPING_OPTION_SKIP_SYNTH_CAL (1U << RAIL_RX_CHANNEL_HOPPING_OPTION_SKIP_SYNTH_CAL_SHIFT)
5147 /**
5148 * An option to skip DC calibration while *hopping into* the channel
5149 * specified in the current entry.
5150 */
5151 #define RAIL_RX_CHANNEL_HOPPING_OPTION_SKIP_DC_CAL (1U << RAIL_RX_CHANNEL_HOPPING_OPTION_SKIP_DC_CAL_SHIFT)
5152 /**
5153 * An option to check RSSI after *hopping into* the channel specified
5154 * in the current entry and hop if that RSSI is below the threshold
5155 * specified in \ref RAIL_RxChannelHoppingConfigEntry_t::rssiThresholdDbm.
5156 * This check runs in parallel with the \ref RAIL_RxChannelHoppingMode_t
5157 * specified and may cause a hop sooner than that mode otherwise would.
5158 */
5159 #define RAIL_RX_CHANNEL_HOPPING_OPTION_RSSI_THRESHOLD (1U << RAIL_RX_CHANNEL_HOPPING_OPTION_RSSI_THRESHOLD_SHIFT)
5160 /**
5161 * An option to stop the hopping sequence at this entry in the hop
5162 * table.
5163 */
5164 #define RAIL_RX_CHANNEL_HOPPING_OPTION_STOP (1U << RAIL_RX_CHANNEL_HOPPING_OPTION_STOP_SHIFT)
5165
5166 /// @struct RAIL_RxChannelHoppingConfigMultiMode_t
5167 /// @brief Structure that parameterizes \ref
5168 /// RAIL_RX_CHANNEL_HOPPING_MODE_MULTI_SENSE.
5169 ///
5170 /// Every \ref RAIL_RxChannelHoppingConfigEntry_t or
5171 /// \ref RAIL_RxDutyCycleConfig_t that uses \ref
5172 /// RAIL_RX_CHANNEL_HOPPING_MODE_MULTI_SENSE must allocate one of these
5173 /// structures in global read-write memory to provide the settings
5174 /// for this mode and for RAIL to use during hopping or duty cycling.
5175 /// A pointer to this structure, cast appropriately, is what is passed
5176 /// in the corresponding \ref RAIL_RxChannelHoppingConfigEntry_t::parameter
5177 /// or \ref RAIL_RxDutyCycleConfig_t::parameter.
5178 ///
5179 /// The contents of this structure must be initialized prior to each
5180 /// \ref RAIL_ConfigRxChannelHopping() or \ref RAIL_ConfigRxDutyCycle()
5181 /// call and must not be touched thereafter until the next such call.
5182 /// RAIL may change these contents during configuration or operation.
5183 ///
5184 /// This mode of operation functions algorithmically like this pseudocode:
5185 /// @code{.c}
5186 /// extern bool channelHopping; // true if channel hopping, false if duty cycling
5187 /// extern RAIL_RxChannelHoppingConfigEntry_t *hopConfigEntry; // current channel
5188 ///
5189 /// static RAIL_RxChannelHoppingConfigMultiMode_t *multiParams;
5190 /// static RAIL_Time_t rxStartTime;
5191 /// static bool preambleSensed;
5192 ///
5193 /// static void hopOrSuspendRx(uint32_t delay)
5194 /// {
5195 /// disableDemodEvents();
5196 /// disableTimerEvents();
5197 /// stopTimer();
5198 /// if (channelHopping) {
5199 /// hopToNextChannel(delay, &hopConfigEntry); // updates hopConfigEntry
5200 /// } else {
5201 /// suspendRx(delay);
5202 /// }
5203 /// onStartRx(); // resume receive after delay (on new channel if hopping)
5204 /// }
5205 ///
5206 /// void onStartRx(void) // called upon entry to receive
5207 /// {
5208 /// rxStartTime = RAIL_GetTime();
5209 /// multiParams = (RAIL_RxChannelHoppingConfigMultiMode_t *)
5210 /// (void *)hopConfigEntry->parameter;
5211 /// startTimer(rxStartTime + multiParams->timingSense);
5212 /// preambleSensed = false;
5213 /// enableTimerEvents(); // timer will trigger onTimerEvent() handler
5214 /// enableDemodEvents(); // demod will trigger onDemodEvent() handler
5215 /// }
5216 ///
5217 /// void onTimerEvent(void) // called when timer expires
5218 /// {
5219 /// hopOrSuspendRx(hopConfigEntry->delay);
5220 /// }
5221 ///
5222 /// void onDemodEvent(void) // called when demodulator state changes
5223 /// {
5224 /// if (DEMOD_TIMING_SENSED) {
5225 /// stopTimer();
5226 /// startTimer(rxStartTime + multiParams->syncDetect);
5227 /// }
5228 /// if (DEMOD_TIMING_LOST) {
5229 /// stopTimer();
5230 /// uint32_t newTimeout = RAIL_GetTime() + multiParams->timingReSense;
5231 /// uint32_t limitTimeout;
5232 /// if (preambleSensed) {
5233 /// limitTimeout = rxStartTime + multiParams->syncDetect;
5234 /// } else {
5235 /// limitTimeout = rxStartTime + multiParams->preambleSense;
5236 /// }
5237 /// if (newTimeout > limitTimeout) {
5238 /// newTimeout = limitTimeout;
5239 /// }
5240 /// if (newTimeout > RAIL_GetTime()) {
5241 /// startTimer(newTimeout);
5242 /// } else {
5243 /// hopOrSuspendRx(hopConfigEntry->delay);
5244 /// }
5245 /// }
5246 /// if (DEMOD_PREAMBLE_SENSED) {
5247 /// preambleSensed = true;
5248 /// }
5249 /// if (DEMOD_PREAMBLE_LOST) {
5250 /// preambleSensed = false;
5251 /// }
5252 /// if (DEMOD_SYNC_DETECTED) {
5253 /// disableDemodEvents();
5254 /// disableTimerEvents();
5255 /// stopTimer();
5256 /// receivePacket(); // stay on channel to receive frame
5257 /// hopOrSuspendRx(0); // continue RX per state transitions with no delay
5258 /// }
5259 /// }
5260 /// @endcode
5261
5262 typedef struct RAIL_RxChannelHoppingConfigMultiMode {
5263 /**
5264 * Switch to the next channel if sync is not detected before
5265 * this time, in microseconds, measured from entry to Rx.
5266 * This must be greater than preambleSense and less than
5267 * \ref RAIL_RX_CHANNEL_HOPPING_MAX_SENSE_TIME_US.
5268 */
5269 uint32_t syncDetect;
5270 /**
5271 * Switch to the next channel if timing was sensed but then
5272 * lost after this time, in microseconds, measured from entry
5273 * to Rx -- unless preamble had been sensed in which case any
5274 * switching is deferred to timingReSense and, if timing is
5275 * regained, to syncDetect. This must be greater than timingSense
5276 * and less than \ref RAIL_RX_CHANNEL_HOPPING_MAX_SENSE_TIME_US.
5277 */
5278 uint32_t preambleSense;
5279 /**
5280 * Switch to the next channel if timing is not sensed before
5281 * this time, in microseconds, measured from entry to Rx. This
5282 * must be greater than 2 and less than
5283 * \ref RAIL_RX_CHANNEL_HOPPING_MAX_SENSE_TIME_US.
5284 */
5285 uint32_t timingSense;
5286 /**
5287 * Switch to the next channel if timing was sensed but then
5288 * lost and not regained before this time, in microseconds,
5289 * measured from when timing was lost. This must be less than
5290 * \ref RAIL_RX_CHANNEL_HOPPING_MAX_SENSE_TIME_US.
5291 */
5292 uint32_t timingReSense;
5293 /**
5294 * Set this to 0. This field, along with the others, may be
5295 * used internally by RAIL during configuration or operation.
5296 */
5297 uint32_t status;
5298 } RAIL_RxChannelHoppingConfigMultiMode_t;
5299
5300 /**
5301 * @struct RAIL_RxChannelHoppingConfigEntry_t
5302 * @brief Structure that represents one of the channels that is part of a
5303 * \ref RAIL_RxChannelHoppingConfig_t sequence of channels used in
5304 * channel hopping.
5305 */
5306 typedef struct RAIL_RxChannelHoppingConfigEntry {
5307 /**
5308 * The channel number to be used for this entry in the channel hopping
5309 * sequence. If this is an invalid channel for the current PHY, the
5310 * call to \ref RAIL_ConfigRxChannelHopping() will fail.
5311 */
5312 uint16_t channel;
5313 /** The mode by which RAIL determines when to hop to the next channel. */
5314 RAIL_RxChannelHoppingMode_t mode;
5315 // Unnamed 'uint8_t reserved1[1]' pad byte field here.
5316 /**
5317 * Depending on the 'mode' parameter that was specified, this member
5318 * is used to parameterize that mode. See the comments on each value of
5319 * \ref RAIL_RxChannelHoppingMode_t to learn what to specify here.
5320 */
5321 RAIL_RxChannelHoppingParameter_t parameter;
5322 /**
5323 * Idle time in microseconds to wait before hopping into the
5324 * channel indicated by this entry.
5325 */
5326 uint32_t delay;
5327 /** @deprecated Set delayMode to \ref RAIL_RX_CHANNEL_HOPPING_DELAY_MODE_STATIC. */
5328 RAIL_RxChannelHoppingDelayMode_t delayMode;
5329 /**
5330 * Bitmask of various options that can be applied to the current
5331 * channel hop.
5332 */
5333 RAIL_RxChannelHoppingOptions_t options;
5334 /**
5335 * The RSSI threshold (in dBm) below which a hop will occur in
5336 * any mode when \ref RAIL_RX_CHANNEL_HOPPING_OPTION_RSSI_THRESHOLD is
5337 * specified.
5338 */
5339 int8_t rssiThresholdDbm;
5340 /**
5341 * Pad bytes reserved for future use and currently ignored.
5342 */
5343 uint8_t reserved2[1];
5344 } RAIL_RxChannelHoppingConfigEntry_t;
5345
5346 /**
5347 * @struct RAIL_RxChannelHoppingConfig_t
5348 * @brief Wrapper struct that will contain the sequence of
5349 * \ref RAIL_RxChannelHoppingConfigEntry_t that represents the channel
5350 * sequence to use during RX Channel Hopping.
5351 */
5352 typedef struct RAIL_RxChannelHoppingConfig {
5353 /**
5354 * Pointer to contiguous global read-write memory that will be used
5355 * by RAIL to store channel hopping information throughout its operation.
5356 * It need not be initialized and applications should never write
5357 * data anywhere in this buffer.
5358 *
5359 * @note The size of this buffer must be at least as large as
5360 * 3 + \ref RAIL_CHANNEL_HOPPING_BUFFER_SIZE_PER_CHANNEL * numberOfChannels,
5361 * plus the sum of the sizes of the
5362 * radioConfigDeltaAdd's of the required channels, plus the size of the
5363 * radioConfigDeltaSubtract. In the case that one channel
5364 * appears two or more times in your channel sequence
5365 * (e.g., 1, 2, 3, 2), you must account for the radio configuration
5366 * size that number of times (i.e., need to count channel 2's
5367 * radio configuration size twice for the given example). The buffer is
5368 * for internal use to the library.
5369 */
5370 uint32_t *buffer;
5371 /**
5372 * This parameter must be set to the length of the buffer array, in 32 bit
5373 * words. This way, during configuration, the software can confirm it's
5374 * writing within the bounds of the buffer. The configuration API will return
5375 * an error or trigger \ref RAIL_ASSERT_CHANNEL_HOPPING_BUFFER_TOO_SHORT if
5376 * bufferLength is insufficient.
5377 */
5378 uint16_t bufferLength;
5379 /**
5380 * The number of channels in the channel hopping sequence, which is the
5381 * number of elements in the array that entries points to.
5382 */
5383 uint8_t numberOfChannels;
5384 /**
5385 * A pointer to the first element of an array of \ref
5386 * RAIL_RxChannelHoppingConfigEntry_t that represents the channels
5387 * used during channel hopping. This array must have numberOfChannels
5388 * entries.
5389 */
5390 RAIL_RxChannelHoppingConfigEntry_t *entries;
5391 } RAIL_RxChannelHoppingConfig_t;
5392
5393 /**
5394 * @struct RAIL_RxDutyCycleConfig_t
5395 * @brief Structure to configure duty cycled receive mode.
5396 */
5397 typedef struct RAIL_RxDutyCycleConfig {
5398 /** The mode by which RAIL determines when to exit RX. */
5399 RAIL_RxChannelHoppingMode_t mode;
5400 // Unnamed 'uint8_t reserved[3]' pad byte field here.
5401 /**
5402 * Depending on the 'mode' parameter that was specified, this member
5403 * is used to parameterize that mode. See the comments on each value of
5404 * \ref RAIL_RxChannelHoppingMode_t to learn what to specify here.
5405 */
5406 RAIL_RxChannelHoppingParameter_t parameter;
5407 /**
5408 * Idle time in microseconds to wait before re-entering RX.
5409 */
5410 uint32_t delay;
5411 /** @deprecated Set delayMode to \ref RAIL_RX_CHANNEL_HOPPING_DELAY_MODE_STATIC. */
5412 RAIL_RxChannelHoppingDelayMode_t delayMode;
5413 /**
5414 * Bitmask of various options that can be applied to the current
5415 * duty cycle operation when the mode is >= \ref
5416 * RAIL_RX_CHANNEL_HOPPING_MODE_MANUAL_WITH_OPTIONS (ignored otherwise).
5417 */
5418 RAIL_RxChannelHoppingOptions_t options;
5419 /**
5420 * The RSSI threshold (in dBm) below which Rx will end in
5421 * any mode when \ref RAIL_RX_CHANNEL_HOPPING_OPTION_RSSI_THRESHOLD
5422 * is specified.
5423 */
5424 int8_t rssiThresholdDbm;
5425 /**
5426 * Pad bytes reserved for future use and currently ignored.
5427 */
5428 uint8_t reserved2[1];
5429 } RAIL_RxDutyCycleConfig_t;
5430
5431 /// A sentinel value to flag an invalid channel hopping index.
5432 #define RAIL_CHANNEL_HOPPING_INVALID_INDEX (0xFEU)
5433
5434 /** @} */ // end of group Rx_Channel_Hopping
5435
5436 /******************************************************************************
5437 * Diagnostic Structures
5438 *****************************************************************************/
5439 /**
5440 * @addtogroup Diagnostic
5441 * @{
5442 */
5443
5444 /**
5445 * @typedef RAIL_FrequencyOffset_t
5446 * @brief Type that represents the number of Frequency Offset
5447 * units. It is used with \ref RAIL_GetRxFreqOffset() and
5448 * \ref RAIL_SetFreqOffset().
5449 *
5450 * The units are chip-specific. For EFR32 they are radio synthesizer
5451 * resolution steps (synth ticks) and is limited to 15 bits.
5452 * A value of \ref RAIL_FREQUENCY_OFFSET_INVALID
5453 * means that this value is invalid.
5454 */
5455 typedef int16_t RAIL_FrequencyOffset_t;
5456
5457 /**
5458 * The maximum frequency offset value supported.
5459 */
5460 #define RAIL_FREQUENCY_OFFSET_MAX ((RAIL_FrequencyOffset_t) 0x3FFF)
5461
5462 /**
5463 * The minimum frequency offset value supported.
5464 */
5465 #define RAIL_FREQUENCY_OFFSET_MIN ((RAIL_FrequencyOffset_t) -RAIL_FREQUENCY_OFFSET_MAX)
5466
5467 /**
5468 * Specify an invalid frequency offset value. This will be returned if you
5469 * call \ref RAIL_GetRxFreqOffset() at an invalid time.
5470 */
5471 #define RAIL_FREQUENCY_OFFSET_INVALID ((RAIL_FrequencyOffset_t) 0x8000)
5472
5473 /**
5474 * @struct RAIL_DirectModeConfig_t
5475 * @brief Allows the user to specify direct mode
5476 * parameters using \ref RAIL_ConfigDirectMode().
5477 */
5478 typedef struct RAIL_DirectModeConfig {
5479 /** Enable synchronous RX DOUT using DCLK vs. asynchronous RX DOUT. */
5480 bool syncRx;
5481 /** Enable synchronous TX DIN using DCLK vs. asynchronous TX DIN. */
5482 bool syncTx;
5483
5484 /** RX Data output (DOUT) GPIO port. */
5485 uint8_t doutPort;
5486 /** RX Data output (DOUT) GPIO pin. */
5487 uint8_t doutPin;
5488
5489 /** Data clock (DCLK) GPIO port. Only used in synchronous mode. */
5490 uint8_t dclkPort;
5491 /** Data clock (DCLK) GPIO pin. Only used in synchronous mode. */
5492 uint8_t dclkPin;
5493
5494 /** TX Data input (DIN) GPIO port. */
5495 uint8_t dinPort;
5496 /** TX Data input (DIN) GPIO pin. */
5497 uint8_t dinPin;
5498
5499 /** @deprecated No longer used (ignored). */
5500 uint8_t doutLoc;
5501 /** @deprecated No longer used (ignored). */
5502 uint8_t dclkLoc;
5503 /** @deprecated No longer used (ignored). */
5504 uint8_t dinLoc;
5505 } RAIL_DirectModeConfig_t;
5506
5507 /**
5508 * @enum RAIL_StreamMode_t
5509 * @brief Possible stream output modes.
5510 */
RAIL_ENUM(RAIL_StreamMode_t)5511 RAIL_ENUM(RAIL_StreamMode_t) {
5512 /** An unmodulated carrier wave. */
5513 RAIL_STREAM_CARRIER_WAVE = 0,
5514 /** PN9 byte sequence. */
5515 RAIL_STREAM_PN9_STREAM = 1,
5516 /** 101010 sequence. */
5517 RAIL_STREAM_10_STREAM = 2,
5518 /** An unmodulated carrier wave with no change to PLL BW. Same as \ref RAIL_STREAM_CARRIER_WAVE. */
5519 RAIL_STREAM_CARRIER_WAVE_PHASENOISE = 3,
5520 /** ramp sequence starting at a different offset for consecutive packets. Only available for some modulations. Fall back to \ref RAIL_STREAM_PN9_STREAM if not available. */
5521 RAIL_STREAM_RAMP_STREAM = 4,
5522 /** 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 \ref RAIL_STREAM_CARRIER_WAVE_PHASENOISE if not available. */
5523 RAIL_STREAM_CARRIER_WAVE_SHIFTED = 5,
5524 /** 10001000 sequence. */
5525 RAIL_STREAM_1000_STREAM = 6,
5526 /** A count of the choices in this enumeration. Must be last. */
5527 RAIL_STREAM_MODES_COUNT
5528 };
5529
5530 #ifndef DOXYGEN_SHOULD_SKIP_THIS
5531 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
5532 #define RAIL_STREAM_CARRIER_WAVE ((RAIL_StreamMode_t) RAIL_STREAM_CARRIER_WAVE)
5533 #define RAIL_STREAM_PN9_STREAM ((RAIL_StreamMode_t) RAIL_STREAM_PN9_STREAM)
5534 #define RAIL_STREAM_10_STREAM ((RAIL_StreamMode_t) RAIL_STREAM_10_STREAM)
5535 #define RAIL_STREAM_CARRIER_WAVE_PHASENOISE ((RAIL_StreamMode_t) RAIL_STREAM_CARRIER_WAVE_PHASENOISE)
5536 #define RAIL_STREAM_RAMP_STREAM ((RAIL_StreamMode_t) RAIL_STREAM_RAMP_STREAM)
5537 #define RAIL_STREAM_CARRIER_WAVE_SHIFTED ((RAIL_StreamMode_t) RAIL_STREAM_CARRIER_WAVE_SHIFTED)
5538 #define RAIL_STREAM_1000_STREAM ((RAIL_StreamMode_t) RAIL_STREAM_1000_STREAM)
5539 #define RAIL_STREAM_MODES_COUNT ((RAIL_StreamMode_t) RAIL_STREAM_MODES_COUNT)
5540 #endif//DOXYGEN_SHOULD_SKIP_THIS
5541
5542 /**
5543 * @def RAIL_VERIFY_DURATION_MAX
5544 * @brief This radio state verification duration indicates to RAIL that
5545 * all memory contents should be verified by RAIL before returning to the
5546 * application.
5547 */
5548 #define RAIL_VERIFY_DURATION_MAX 0xFFFFFFFFUL
5549
5550 /**
5551 * A pointer to a verification callback function. This will be called by the
5552 * radio state verification feature built into RAIL when a verified memory
5553 * value is different from its reference value.
5554 *
5555 * @param[in] address The address of the data in question.
5556 * @param[in] expectedValue The expected value of the data in question.
5557 * @param[in] actualValue The actual value of the data in question.
5558 * @return true indicates a data value difference is acceptable. false
5559 * indicates a data value difference in unacceptable.
5560 *
5561 * @note This callback will be issued when an address' value is different from
5562 * its reference value and either of the following conditions are met:
5563 * 1. The default radio configuration provided by the radio configurator is used
5564 * for verification purposes (i.e., a custom radio configuration is not supplied
5565 * as an input to \ref RAIL_ConfigVerification()), and the radio
5566 * configurator has flagged the address under question as being verifiable.
5567 * 2. A custom radio configuration is provided to the verification API (i.e.,
5568 * a custom radio configuration is supplied as an input to \ref
5569 * RAIL_ConfigVerification()). When providing a custom radio configuration for
5570 * verification purposes, all addresses in that configuration will be verified,
5571 * regardless of whether or not the addresses are flagged as verifiable.
5572 */
5573 typedef bool (*RAIL_VerifyCallbackPtr_t)(uint32_t address,
5574 uint32_t expectedValue,
5575 uint32_t actualValue);
5576
5577 /**
5578 * @struct RAIL_VerifyConfig_t
5579 * @brief The configuration array provided to RAIL for use by the radio state
5580 * verification feature. This structure will be populated with appropriate
5581 * values by calling \ref RAIL_ConfigVerification(). The application should
5582 * not set or alter any of these structure elements.
5583 */
5584 typedef struct RAIL_VerifyConfig {
5585 /** Internal verification tracking information. */
5586 RAIL_Handle_t correspondingHandle;
5587 /** Internal verification tracking information. */
5588 uint32_t nextIndexToVerify;
5589 /** Internal verification tracking information. */
5590 RAIL_RadioConfig_t override;
5591 /** Internal verification tracking information. */
5592 RAIL_VerifyCallbackPtr_t cb;
5593 } RAIL_VerifyConfig_t;
5594
5595 /** @} */ // end of group Diagnostic
5596
5597 /******************************************************************************
5598 * Front End Module Voltage Detection (VDET)
5599 *****************************************************************************/
5600 /**
5601 * @addtogroup VDET
5602 * @{
5603 */
5604
5605 /**
5606 * @enum RAIL_Vdet_Mode_t
5607 * @brief VDET Modes.
5608 *
5609 * The VDET Mode is passed to \ref RAIL_ConfigVdet() via \ref RAIL_VdetConfig_t.
5610 * The \ref rail_util_vdet component allows customers to measure their Front End Module performance
5611 * at specified points in the Transmit packet.
5612 */
RAIL_ENUM(RAIL_Vdet_Mode_t)5613 RAIL_ENUM(RAIL_Vdet_Mode_t) {
5614 /** VDET is completely disabled. */
5615 RAIL_VDET_MODE_DISABLED = 0u,
5616 /** AUTOMATIC causes VDET measurements to be taken every Tx packet at the specified time. */
5617 RAIL_VDET_MODE_AUTOMATIC = 1u,
5618 /** IMMEDIATE causes an immediate VDET measurement. VDET must not be in \ref RAIL_VDET_MODE_AUTOMATIC. */
5619 RAIL_VDET_MODE_IMMEDIATE = 2u,
5620 /** A count of the choices in this enumeration. Must be last. */
5621 RAIL_VDET_MODE_COUNT
5622 };
5623
5624 #ifndef DOXYGEN_SHOULD_SKIP_THIS
5625 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
5626 #define RAIL_VDET_MODE_DISABLED ((RAIL_Vdet_Mode_t) RAIL_VDET_MODE_DISABLED)
5627 #define RAIL_VDET_MODE_AUTOMATIC ((RAIL_Vdet_Mode_t) RAIL_VDET_MODE_AUTOMATIC)
5628 #define RAIL_VDET_MODE_IMMEDIATE ((RAIL_Vdet_Mode_t) RAIL_VDET_MODE_IMMEDIATE)
5629 #define RAIL_VDET_MODE_COUNT ((RAIL_Vdet_Mode_t) RAIL_VDET_MODE_COUNT)
5630 #endif//DOXYGEN_SHOULD_SKIP_THIS
5631
5632 /**
5633 * @def RAIL_VDET_MODE_ENUM_NAMES
5634 * @brief A macro that is string versions of the calibration enums.
5635 */
5636 #define RAIL_VDET_MODE_ENUM_NAMES { \
5637 "RAIL_VDET_MODE_DISABLED", \
5638 "RAIL_VDET_MODE_AUTOMATIC", \
5639 "RAIL_VDET_MODE_IMMEDIATE", \
5640 }
5641
5642 /**
5643 * @enum RAIL_Vdet_Resolution_t
5644 * @brief VDET Resolution for the Aux ADC.
5645 *
5646 * The VDET Resolution is passed to \ref RAIL_ConfigVdet() via \ref RAIL_VdetConfig_t.
5647 * Shows available resolution options.
5648 */
RAIL_ENUM(RAIL_Vdet_Resolution_t)5649 RAIL_ENUM(RAIL_Vdet_Resolution_t) {
5650 /** ~10 bit resolution. */
5651 RAIL_VDET_RESOLUTION_10_BIT = 0u,
5652 /** ~11 bit resolution. */
5653 RAIL_VDET_RESOLUTION_11_BIT = 1u,
5654 /** ~12 bit resolution. */
5655 RAIL_VDET_RESOLUTION_12_BIT = 2u,
5656 /** A count of the choices in this enumeration. Must be last. */
5657 RAIL_VDET_RESOLUTION_COUNT
5658 };
5659
5660 #ifndef DOXYGEN_SHOULD_SKIP_THIS
5661 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
5662 #define RAIL_VDET_RESOLUTION_10_BIT ((RAIL_Vdet_Resolution_t) RAIL_VDET_RESOLUTION_10_BIT)
5663 #define RAIL_VDET_RESOLUTION_11_BIT ((RAIL_Vdet_Resolution_t) RAIL_VDET_RESOLUTION_11_BIT)
5664 #define RAIL_VDET_RESOLUTION_12_BIT ((RAIL_Vdet_Resolution_t) RAIL_VDET_RESOLUTION_12_BIT)
5665 #define RAIL_VDET_RESOLUTION_COUNT ((RAIL_Vdet_Resolution_t) RAIL_VDET_RESOLUTION_COUNT)
5666 #endif//DOXYGEN_SHOULD_SKIP_THIS
5667
5668 /**
5669 * @def RAIL_VDET_RESOLUTION_ENUM_NAMES
5670 * @brief A macro that is string versions of the resolution enums.
5671 */
5672 #define RAIL_VDET_RESOLUTION_ENUM_NAMES { \
5673 "RAIL_VDET_RESOLUTION_10_BIT", \
5674 "RAIL_VDET_RESOLUTION_11_BIT", \
5675 "RAIL_VDET_RESOLUTION_12_BIT", \
5676 }
5677
5678 /**
5679 * @enum RAIL_Vdet_Status_t
5680 * @brief VDET Status.
5681 *
5682 * The VDET Status for internal debug.
5683 * Shows states.
5684 */
5685 // MUST BE KEPT IN ALIGNMENT WITH #DEFINES FOR VDET_STATUS IN RFLDMA YAML FILE!
RAIL_ENUM(RAIL_Vdet_Status_t)5686 RAIL_ENUM(RAIL_Vdet_Status_t) {
5687 /** IDLE - Waiting for next command/measurement */
5688 RAIL_VDET_STATUS_IDLE = 0u,
5689 /** START of the VDET measurement activity. */
5690 RAIL_VDET_STATUS_START = 1u,
5691 /** Completion of a 10 bit measurement. */
5692 RAIL_VDET_STATUS_10_BIT_DONE = 2u,
5693 /** Completion of a 11 bit measurement. */
5694 RAIL_VDET_STATUS_11_BIT_DONE = 3u,
5695 /** Completion of a 12 bit measurement. */
5696 RAIL_VDET_STATUS_12_BIT_DONE = 4u,
5697 /** Conflict with another AuxADC user */
5698 RAIL_VDET_STATUS_BLOCKED = 5u,
5699 /** An error has occurred. */
5700 RAIL_VDET_STATUS_ERROR = 6u,
5701 /** A count of the choices in this enumeration. Must be last. */
5702 RAIL_VDET_STATUS_COUNT
5703 };
5704
5705 #ifndef DOXYGEN_SHOULD_SKIP_THIS
5706 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
5707 #define RAIL_VDET_STATUS_IDLE ((RAIL_Vdet_Status_t) RAIL_VDET_STATUS_IDLE)
5708 #define RAIL_VDET_STATUS_START ((RAIL_Vdet_Status_t) RAIL_VDET_STATUS_START)
5709 #define RAIL_VDET_STATUS_10_BIT_DONE ((RAIL_Vdet_Status_t) RAIL_VDET_STATUS_10_BIT_DONE)
5710 #define RAIL_VDET_STATUS_11_BIT_DONE ((RAIL_Vdet_Status_t) RAIL_VDET_STATUS_11_BIT_DONE)
5711 #define RAIL_VDET_STATUS_12_BIT_DONE ((RAIL_Vdet_Status_t) RAIL_VDET_STATUS_12_BIT_DONE)
5712 #define RAIL_VDET_STATUS_BLOCKED ((RAIL_Vdet_Status_t) RAIL_VDET_STATUS_BLOCKED)
5713 #define RAIL_VDET_STATUS_ERROR ((RAIL_Vdet_Status_t) RAIL_VDET_STATUS_ERROR)
5714 #define RAIL_VDET_STATUS_COUNT ((RAIL_Vdet_Status_t) RAIL_VDET_STATUS_COUNT)
5715 #endif//DOXYGEN_SHOULD_SKIP_THIS
5716
5717 /**
5718 * @def RAIL_VDET_STATUS_ENUM_NAMES
5719 * @brief A macro that is string versions of the status enums.
5720 */
5721 #define RAIL_VDET_STATUS_ENUM_NAMES { \
5722 "RAIL_VDET_STATUS_IDLE", \
5723 "RAIL_VDET_STATUS_START", \
5724 "RAIL_VDET_STATUS_10_BIT_DONE", \
5725 "RAIL_VDET_STATUS_11_BIT_DONE", \
5726 "RAIL_VDET_STATUS_12_BIT_DONE", \
5727 "RAIL_VDET_STATUS_BLOCKED", \
5728 "RAIL_VDET_STATUS_ERROR", \
5729 }
5730
5731 /**
5732 * @struct RAIL_VdetConfig_t
5733 * @brief Configuration information for FEM Voltage Detection plugin.
5734 *
5735 * A structure of type \ref RAIL_VdetConfig_t is passed to \ref RAIL_ConfigVdet().
5736 */
5737 typedef struct RAIL_VdetConfig {
5738 /** Mode for the VDET. */
5739 RAIL_Vdet_Mode_t mode;
5740 /** Resolution to use for the capture. */
5741 RAIL_Vdet_Resolution_t resolution;
5742 /** Delay in microseconds for the capture from Tx Start in \ref RAIL_VDET_MODE_AUTOMATIC. Minimum 5 us, maximum 100000 us. */
5743 uint32_t delayUs;
5744 } RAIL_VdetConfig_t;
5745
5746 /** @} */ // end of group VDET
5747
5748 /******************************************************************************
5749 * Thermal Protection
5750 *****************************************************************************/
5751 /**
5752 * @addtogroup Thermal_Protection Thermal Protection
5753 * @{
5754 */
5755
5756 /** Maximum junction temperature in Kelvin. A margin is subtracted before using it when
5757 * \ref RAIL_SUPPORTS_THERMAL_PROTECTION is enabled.
5758 */
5759 #define RAIL_CHIP_TEMP_THRESHOLD_MAX (398U)
5760
5761 /**
5762 * Default number of Kelvin degrees below threshold needed to allow transmissions.
5763 */
5764 #define RAIL_CHIP_TEMP_COOLDOWN_DEFAULT (7U)
5765
5766 /**
5767 * @struct RAIL_ChipTempConfig_t
5768 * @brief Configuration parameters for thermal protection.
5769 */
5770 typedef struct RAIL_ChipTempConfig {
5771 /** Indicates whether the protection is enabled */
5772 bool enable;
5773 /** Mandatory temperature cool down when the threshold is exceeded, in degrees Kelvin */
5774 uint8_t coolDownK;
5775 /** Temperature above which transmit is blocked, in degrees Kelvin */
5776 uint16_t thresholdK;
5777 } RAIL_ChipTempConfig_t;
5778
5779 /** Number of temperature values provided for the chip thermal protection */
5780 #define RAIL_CHIP_TEMP_MEASURE_COUNT (3U)
5781
5782 /**
5783 * @struct RAIL_ChipTempMetrics_t
5784 * @brief Data used for thermal protection.
5785 */
5786 typedef struct RAIL_ChipTempMetrics {
5787 /** Store chip temperature for metrics */
5788 uint16_t tempK;
5789 /** Minimum temperature recorded */
5790 uint16_t minTempK;
5791 /** Maximum temperature recorded */
5792 uint16_t maxTempK;
5793 /** Indicates if data should be reset */
5794 bool resetPending;
5795 /** Reserved for future use */
5796 uint8_t reservedChipTemp;
5797 } RAIL_ChipTempMetrics_t;
5798
5799 /** @} */ // end of group Thermal_Protection
5800
5801 /******************************************************************************
5802 * Retiming Structures
5803 *****************************************************************************/
5804 /**
5805 * @addtogroup Retiming
5806 * @{
5807 */
5808
5809 /**
5810 * @enum RAIL_RetimeOptions_t
5811 * @brief Retiming options bit shifts.
5812 */
RAIL_ENUM(RAIL_RetimeOptions_t)5813 RAIL_ENUM(RAIL_RetimeOptions_t) {
5814 /** Shift position of \ref RAIL_RETIME_OPTION_HFXO bit. */
5815 RAIL_RETIME_OPTION_HFXO_SHIFT = 0,
5816 /** Shift position of \ref RAIL_RETIME_OPTION_HFRCO bit. */
5817 RAIL_RETIME_OPTION_HFRCO_SHIFT = 1,
5818 /** Shift position of \ref RAIL_RETIME_OPTION_DCDC bit. */
5819 RAIL_RETIME_OPTION_DCDC_SHIFT = 2,
5820 /** Shift position of \ref RAIL_RETIME_OPTION_LCD bit. */
5821 RAIL_RETIME_OPTION_LCD_SHIFT = 3,
5822 };
5823
5824 /**
5825 * An option to configure HFXO retiming.
5826 */
5827 #define RAIL_RETIME_OPTION_HFXO \
5828 (1U << RAIL_RETIME_OPTION_HFXO_SHIFT)
5829
5830 /**
5831 * An option to configure HFRCO retiming.
5832 */
5833 #define RAIL_RETIME_OPTION_HFRCO \
5834 (1U << RAIL_RETIME_OPTION_HFRCO_SHIFT)
5835
5836 /**
5837 * An option to configure DCDC retiming.
5838 * Ignored on platforms that lack DCDC.
5839 */
5840 #define RAIL_RETIME_OPTION_DCDC \
5841 (1U << RAIL_RETIME_OPTION_DCDC_SHIFT)
5842
5843 /**
5844 * An option to configure LCD retiming.
5845 * Ignored on platforms that lack LCD.
5846 */
5847 #define RAIL_RETIME_OPTION_LCD \
5848 (1U << RAIL_RETIME_OPTION_LCD_SHIFT)
5849
5850 /** A value representing no retiming options. */
5851 #define RAIL_RETIME_OPTIONS_NONE 0x0U
5852
5853 /** A value representing all retiming options. */
5854 #define RAIL_RETIME_OPTIONS_ALL 0xFFU
5855
5856 /** @} */ // end of group Retiming
5857
5858 #ifndef DOXYGEN_SHOULD_SKIP_THIS
5859
5860 /******************************************************************************
5861 * Debug Structures
5862 *****************************************************************************/
5863 /**
5864 * @addtogroup Debug
5865 * @{
5866 */
5867
5868 /**
5869 * @def RAIL_DEBUG_MODE_FREQ_OVERRIDE
5870 * @brief A bitmask to enable the frequency override debug mode to
5871 * manually tune to a specified frequency. Note that this should only be used
5872 * for testing and is not as tuned as frequencies from the calculator.
5873 */
5874 #define RAIL_DEBUG_MODE_FREQ_OVERRIDE 0x00000001UL
5875
5876 /**
5877 * @def RAIL_DEBUG_MODE_VALID_MASK
5878 * @brief Any debug mode bits outside of this mask are invalid and ignored.
5879 */
5880 #define RAIL_DEBUG_MODE_VALID_MASK (~(RAIL_DEBUG_MODE_FREQ_OVERRIDE))
5881
5882 /** @} */ // end of group Debug
5883
5884 /******************************************************************************
5885 * Detailed Timing Structures
5886 *****************************************************************************/
5887 /**
5888 * @addtogroup Detailed_Timing Detailed Timing
5889 * @{
5890 */
5891
5892 /**
5893 * @enum RAIL_TimerTickType_t
5894 * @brief Enumerate the timer tick channel.
5895 */
RAIL_ENUM(RAIL_TimerTickType_t)5896 RAIL_ENUM(RAIL_TimerTickType_t) {
5897 /**
5898 * RAIL default timer tick channel.
5899 * This is used to query the current RAIL timer tick value.
5900 */
5901 RAIL_TIMER_TICK_DEFAULT = 0,
5902 /**
5903 * Radio state timer tick channel.
5904 * This is used to query the timer tick corresponding to the latest radio
5905 * state.
5906 */
5907 RAIL_TIMER_TICK_RADIO_STATE = 1,
5908 /**
5909 * RX timestamp timer tick channel.
5910 * This is used to query the timer tick at the time of latest RX frame
5911 * detection.
5912 */
5913 RAIL_TIMER_TICK_RXSTAMP = 2,
5914 };
5915
5916 #ifndef DOXYGEN_SHOULD_SKIP_THIS
5917 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
5918 #define RAIL_TIMER_TICK_DEFAULT ((RAIL_TimerTickType_t) RAIL_TIMER_TICK_DEFAULT)
5919 #define RAIL_TIMER_TICK_RADIO_STATE ((RAIL_TimerTickType_t) RAIL_TIMER_TICK_RADIO_STATE)
5920 #define RAIL_TIMER_TICK_RXSTAMP ((RAIL_TimerTickType_t) RAIL_TIMER_TICK_RXSTAMP)
5921 #endif //DOXYGEN_SHOULD_SKIP_THIS
5922
5923 /** @} */ // end of group Detailed Timing
5924
5925 #endif //DOXYGEN_SHOULD_SKIP_THIS
5926
5927 /******************************************************************************
5928 * TrustZone
5929 *****************************************************************************/
5930 /**
5931 * @addtogroup TrustZone
5932 * @{
5933 */
5934
5935 /**
5936 * @typedef RAIL_TZ_ChangedDcdcCallbackPtr_t
5937 * @brief A pointer to the callback used to switch to secure world and run
5938 * \ref RAIL_ChangedDcdc().
5939 *
5940 * @return Status code indicating success of the function call.
5941 */
5942 typedef RAIL_Status_t (*RAIL_TZ_ChangedDcdcCallbackPtr_t)(void);
5943
5944 /**
5945 * @typedef RAIL_TZ_ConfigAntennaGpioCallbackPtr_t
5946 * @brief A pointer to the callback used to switch to secure world and run
5947 * \ref RAIL_TZ_ConfigAntennaGpio().
5948 *
5949 * @param[in] config A pointer to a configuration structure applied to the relevant Antenna
5950 * Configuration registers. A NULL configuration will produce undefined behavior.
5951 * @return Status code indicating success of the function call.
5952 *
5953 */
5954 typedef RAIL_Status_t (*RAIL_TZ_ConfigAntennaGpioCallbackPtr_t)(const RAIL_AntennaConfig_t *config);
5955
5956 /**
5957 * @typedef RAIL_TZ_RadioClockEnableCallbackPtr_t
5958 * @brief A pointer to the callback used to switch to secure world and run
5959 * \ref RAIL_TZ_RadioClockEnable().
5960 *
5961 */
5962 typedef void (*RAIL_TZ_RadioClockEnableCallbackPtr_t)(void);
5963
5964 /**
5965 * @typedef RAIL_TZ_GetRadioClockFreqHzCallbackPtr_t
5966 * @brief A pointer to the callback used to switch to secure world and run
5967 * \ref RAIL_GetRadioClockFreqHz().
5968 *
5969 * @return Radio subsystem clock frequency in Hz.
5970 *
5971 */
5972 typedef uint32_t (*RAIL_TZ_GetRadioClockFreqHzCallbackPtr_t)(void);
5973
5974 /**
5975 * @typedef RAIL_TZ_RfecaClockEnableCallbackPtr_t
5976 * @brief A pointer to the callback used to switch to secure world and run
5977 * \ref RAIL_TZ_RfecaClockEnable().
5978 *
5979 */
5980 typedef void (*RAIL_TZ_RfecaClockEnableCallbackPtr_t)(void);
5981
5982 /**
5983 * @typedef RAIL_TZ_RfecaIsClockEnabledCallbackPtr_t
5984 * @brief A pointer to the callback used to switch to secure world and run
5985 * \ref RAIL_TZ_RfecaIsClockEnabled().
5986 *
5987 * @return true if RFECA clocks are enabled; false otherwise
5988 *
5989 */
5990 typedef bool (*RAIL_TZ_RfecaIsClockEnabledCallbackPtr_t)(void);
5991
5992 /**
5993 * @typedef RAIL_TZ_ReadInternalTemperatureCallbackPtr_t
5994 * @brief A pointer to the callback used to switch to secure world and run
5995 * \ref RAIL_TZ_ReadInternalTemperature().
5996 *
5997 * @param[out] internalTemperatureKelvin A pointer to the internal temperature
5998 * in Kelvin.
5999 * @param[in] enableTemperatureInterrupts Indicate whether temperature
6000 * interrupts are enabled.
6001 * @return Status code indicating success of the function call.
6002 *
6003 */
6004 typedef RAIL_Status_t (*RAIL_TZ_ReadInternalTemperatureCallbackPtr_t)(uint16_t *internalTemperatureKelvin,
6005 bool enableTemperatureInterrupts);
6006
6007 /**
6008 * @typedef RAIL_TZ_EnableSecureRadioIrqsCallbackPtr_t
6009 * @brief A pointer to the callback used to switch to secure world and run
6010 * \ref RAIL_TZ_EnableSecureRadioIrqs().
6011 *
6012 */
6013 typedef void (*RAIL_TZ_EnableSecureRadioIrqsCallbackPtr_t)(void);
6014
6015 /**
6016 * @typedef RAIL_TZ_DisableSecureRadioIrqsCallbackPtr_t
6017 * @brief A pointer to the callback used to switch to secure world and run
6018 * \ref RAIL_TZ_DisableSecureRadioIrqs().
6019 *
6020 */
6021 typedef void (*RAIL_TZ_DisableSecureRadioIrqsCallbackPtr_t)(void);
6022
6023 /**
6024 * @typedef RAIL_TZ_RadioPerformM2mLdmaCallbackPtr_t
6025 * @brief A pointer to the callback used to switch to secure world and run
6026 * \ref RAIL_TZ_RadioPerformM2mLdma().
6027 *
6028 * @param[in] pDest A pointer to the destination data.
6029 * @param[in] pSrc A pointer to the source data.
6030 * @param[in] numWords Number of words to transfer.
6031 * @return Status code indicating success of the function call.
6032 *
6033 */
6034 typedef RAIL_Status_t (*RAIL_TZ_RadioPerformM2mLdmaCallbackPtr_t)(uint32_t *pDest,
6035 const uint32_t *pSrc,
6036 uint32_t numWords);
6037
6038 /**
6039 * @typedef RAIL_TZ_ConfigureHfxoCallbackPtr_t
6040 * @brief A pointer to the callback used to switch to secure world and run
6041 * \ref RAIL_TZ_ConfigureHfxo().
6042 *
6043 */
6044 typedef RAIL_Status_t (*RAIL_TZ_ConfigureHfxoCallbackPtr_t)(void);
6045
6046 /**
6047 * @struct RAIL_TZ_Config_t
6048 * @brief Gather RAIL TrustZone callbacks pointers and booleans indicating
6049 * peripheral secure configuration.
6050 */
6051 typedef struct RAIL_TZ_Config {
6052 /**
6053 * See \ref RAIL_TZ_ChangedDcdcCallbackPtr_t.
6054 * In non-secure world, it must be NULL if CMU is a non-secure peripheral.
6055 */
6056 RAIL_TZ_ChangedDcdcCallbackPtr_t changedDcdcCallback;
6057 /**
6058 * See \ref RAIL_TZ_ConfigAntennaGpioCallbackPtr_t.
6059 * In non-secure world, it must be NULL if CMU and GPIO are non-secure
6060 * peripherals.
6061 */
6062 RAIL_TZ_ConfigAntennaGpioCallbackPtr_t configAntennaGpioCallback;
6063 /**
6064 * See \ref RAIL_TZ_RadioClockEnableCallbackPtr_t.
6065 * In non-secure world, it must be NULL if CMU is a non-secure peripheral.
6066 */
6067 RAIL_TZ_RadioClockEnableCallbackPtr_t radioClockEnableCallback;
6068 /**
6069 * See \ref RAIL_TZ_GetRadioClockFreqHzCallbackPtr_t.
6070 * In non-secure world, it must be NULL if CMU is a non-secure peripheral.
6071 */
6072 RAIL_TZ_GetRadioClockFreqHzCallbackPtr_t getRadioClockFreqHzCallback;
6073 /**
6074 * See \ref RAIL_TZ_RfecaClockEnableCallbackPtr_t.
6075 * In non-secure world, it must be NULL if CMU is a non-secure peripheral.
6076 */
6077 RAIL_TZ_RfecaClockEnableCallbackPtr_t rfecaClockEnableCallback;
6078 /**
6079 * See \ref RAIL_TZ_RfecaIsClockEnabledCallbackPtr_t.
6080 * In non-secure world, it must be NULL if CMU is a non-secure peripheral.
6081 */
6082 RAIL_TZ_RfecaIsClockEnabledCallbackPtr_t rfecaIsClockEnabledCallback;
6083 /**
6084 * See \ref RAIL_TZ_ReadInternalTemperatureCallbackPtr_t.
6085 * In non-secure world, it must be NULL if EMU is a non-secure peripheral.
6086 */
6087 RAIL_TZ_ReadInternalTemperatureCallbackPtr_t readInternalTemperatureCallback;
6088 /**
6089 * See \ref RAIL_TZ_EnableSecureRadioIrqsCallbackPtr_t.
6090 * In non-secure world, it must be NULL if EMU is a non-secure peripheral.
6091 */
6092 RAIL_TZ_EnableSecureRadioIrqsCallbackPtr_t enableSecureRadioIrqsCallback;
6093 /**
6094 * See \ref RAIL_TZ_DisableSecureRadioIrqsCallbackPtr_t.
6095 * In non-secure world, it must be NULL if EMU is a non-secure peripheral.
6096 */
6097 RAIL_TZ_DisableSecureRadioIrqsCallbackPtr_t disableSecureRadioIrqsCallback;
6098 /**
6099 * See \ref RAIL_TZ_RadioPerformM2mLdmaCallbackPtr_t.
6100 * In non-secure world, it must be NULL if LDMA is a non-secure peripheral or
6101 * if RAIL must not use LDMA.
6102 */
6103 RAIL_TZ_RadioPerformM2mLdmaCallbackPtr_t radioPerformM2mLdmaCallback;
6104 /**
6105 * See \ref RAIL_TZ_ConfigureHfxoCallbackPtr_t.
6106 * In non-secure world, it must be NULL if HFXO is a non-secure peripheral.
6107 */
6108 RAIL_TZ_ConfigureHfxoCallbackPtr_t configureHfxoCallback;
6109 /**
6110 * Indicate whether CMU is configured as secure peripheral.
6111 */
6112 bool isCmuSecure;
6113 /**
6114 * Indicate whether EMU is configured as secure peripheral.
6115 */
6116 bool isEmuSecure;
6117 /**
6118 * Indicate whether GPIO is configured as secure peripheral.
6119 */
6120 bool isGpioSecure;
6121 /**
6122 * Indicate whether LDMA is configured as secure peripheral.
6123 */
6124 bool isLdmaSecure;
6125 /**
6126 * Indicate whether HFXO is configured as secure peripheral.
6127 */
6128 bool isHfxoSecure;
6129 /**
6130 * Indicate whether PRS is configured as secure peripheral.
6131 */
6132 bool isPrsSecure;
6133 /**
6134 * Indicate whether SYSRTC is configured as secure peripheral.
6135 */
6136 bool isSysrtcSecure;
6137 } RAIL_TZ_Config_t;
6138
6139 /** @} */ // end of group TrustZone
6140
6141 #ifdef SLI_LIBRARY_BUILD
6142 #ifndef DOXYGEN_SHOULD_SKIP_THIS
6143 // SLI_LIBRARY_BUILD is defined for library builds that do not include
6144 // chip-dependent defines. This may limit functionality but allows building
6145 // generic libraries that are not tied to any given chip.
6146
6147 // Platform-agnostic worst-case settings and types
6148
6149 #define RAIL_CHANNEL_HOPPING_BUFFER_SIZE_PER_CHANNEL \
6150 RAIL_CHANNEL_HOPPING_BUFFER_SIZE_PER_CHANNEL_WORST_CASE
6151
6152 struct RAIL_ChannelConfigEntryAttr {
6153 RAIL_RxIrCalValues_t calValues;
6154 RAIL_TxIrCalValues_t txCalValues; // placeholder for size
6155 };
6156
6157 #endif//DOXYGEN_SHOULD_SKIP_THIS
6158 #endif//SLI_LIBRARY_BUILD
6159
6160 /** @} */ // end of RAIL_API
6161
6162 #ifdef __cplusplus
6163 }
6164 #endif
6165
6166 #ifndef SLI_LIBRARY_BUILD
6167 // Include appropriate chip-specific types and APIs *after* common types, and
6168 // *before* types that depend on chip-specific types.
6169 #include "rail_chip_specific.h"
6170
6171 // (Currently no types depend on chip-specific types.)
6172
6173 #endif //!SLI_LIBRARY_BUILD
6174
6175 #endif // __RAIL_TYPES_H__
6176
