1 /***************************************************************************//**
2  * @file
3  * @brief This file contains the type definitions for SIxx3xx chip-specific
4  *   aspects of RAIL.
5  *******************************************************************************
6  * # License
7  * <b>Copyright 2024 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 #ifdef  SLI_LIBRARY_BUILD
33 
34 // This file should not be included when doing SLI_LIBRARY_BUILDs
35 
36 #else//!SLI_LIBRARY_BUILD
37 
38 #ifndef __RAIL_CHIP_SPECIFIC_H_
39 #if !defined(__RAIL_TYPES_H__) && !defined(DOXYGEN_SHOULD_SKIP_THIS)
40 #warning rail_chip_specific.h should only be included by rail_types.h
41 #include "rail_types.h" // Force rail_chip_specific.h only within rail_types.h
42 #else // __RAIL_TYPES_H__
43 /// Include guard
44 #define __RAIL_CHIP_SPECIFIC_H_
45 
46 #include "rail_features.h"
47 #ifdef RAIL_INTERNAL_BUILD
48 #include "rail_chip_specific_internal.h"
49 #endif
50 
51 #ifdef __cplusplus
52 extern "C" {
53 #endif
54 
55 #if     (defined(DOXYGEN_SHOULD_SKIP_THIS) && !defined(RAIL_ENUM))
56 //  Copied from rail_types.h to satisfy doxygen build.
57 /// The RAIL library does not use enumerations because the ARM EABI leaves their
58 /// size ambiguous, which causes problems if the application is built
59 /// with different flags than the library. Instead, uint8_t typedefs
60 /// are used in compiled code for all enumerations. For documentation purposes, this is
61 /// converted to an actual enumeration since it's much easier to read in Doxygen.
62 #define RAIL_ENUM(name) enum name
63 /// This macro is a more generic version of the \ref RAIL_ENUM() macro that
64 /// allows the size of the type to be overridden instead of forcing the use of
65 /// a uint8_t. See \ref RAIL_ENUM() for more information.
66 #define RAIL_ENUM_GENERIC(name, type) enum name
67 #endif //(defined(DOXYGEN_SHOULD_SKIP_THIS) && !defined(RAIL_ENUM))
68 
69 /******************************************************************************
70  * General Structures
71  *****************************************************************************/
72 /**
73  * @addtogroup General_SIXX3XX SIxx3xx
74  * @ingroup General
75  * @{
76  * @brief Types specific to the SIxx3xx for general configuration.
77  */
78 
79 /** Synonym of \ref RAIL_EFR32_HANDLE for Series 3 */
80 #define RAIL_S3LPW_HANDLE RAIL_EFR32_HANDLE
81 
82 #ifndef DOXYGEN_SHOULD_SKIP_THIS
83 
84 /**
85  * @def RAIL_SIXG301_STATE_BUFFER_BYTES
86  * @brief The SIxG301 series size needed for
87  *   \ref RAIL_StateBufferEntry_t::bufferBytes.
88  */
89 #define RAIL_SIXG301_STATE_BUFFER_BYTES 624
90 
91 #ifndef RAIL_STATE_BUFFER_BYTES
92 /**
93  * @def RAIL_STATE_BUFFER_BYTES
94  * @brief The size needed for \ref RAIL_StateBufferEntry_t::bufferBytes
95  *   on this platform for this radio. This compile-time size may be slightly
96  *   larger than what \ref RAIL_GetStateBufferSize() determines at run-time.
97  */
98 #if (_SILICON_LABS_32B_SERIES_3_CONFIG == 301) || (_SILICON_LABS_32B_SERIES_3_CONFIG == 300)
99 #define RAIL_STATE_BUFFER_BYTES RAIL_SIXG301_STATE_BUFFER_BYTES
100 #else
101 #define RAIL_STATE_BUFFER_BYTES 0 // Sate Doxygen
102 #error "Unsupported platform!"
103 #endif
104 #endif //#ifndef RAIL_STATE_BUFFER_BYTES
105 
106 #endif//DOXYGEN_SHOULD_SKIP_THIS
107 
108 #ifndef DOXYGEN_SHOULD_SKIP_THIS
109 
110 /**
111  * @typedef RAIL_TimerTick_t
112  * @brief Internal RAIL hardware timer tick that drives the RAIL timebase.
113  *   A tick is roughly 0.125 microseconds and it has a full 64-bit range
114  *   (i.e, spanning 2^61 microseconds or ~73 millenia).
115  *
116  * @note \ref RAIL_TimerTicksToUs() can be used to convert the delta between
117  *   two \ref RAIL_TimerTick_t values to microseconds.
118  */
119 typedef uint64_t RAIL_TimerTick_t;
120 
121 /**
122  * @typedef RAIL_GetTimerTick_t
123  * @brief A function pointer type for reading RAIL internal timer ticks.
124  *
125  * @param[in] timerTickType A timer tick type to read.
126  * @return RAIL timer tick corresponding to the timerTickType.
127  */
128 typedef RAIL_TimerTick_t (*RAIL_GetTimerTick_t)(RAIL_TimerTickType_t timerTickType);
129 
130 /**
131  * Function pointer of type \ref RAIL_GetTimerTick_t to read RAIL internal
132  * timer ticks.
133  */
134 extern RAIL_GetTimerTick_t RAIL_GetTimerTick;
135 
136 /**
137  * A global pointer to the memory address of the least significant 32 bits
138  * of the \ref RAIL_TimerTick_t internal RAIL hardware timer that drives
139  * the RAIL timebase.
140  * It's 0.125 microsecond tick range is 2^29 microseconds or ~9 minutes.
141  */
142 extern const volatile uint32_t *RAIL_TimerTick;
143 
144 /**
145  * A global pointer to the memory address of the least significant 32 bits
146  * of the \ref RAIL_TimerTick_t internal RAIL hardware timer that captures
147  * the latest RX packet reception time.
148  * It's 0.125 microsecond tick range is 2^29 microseconds or ~9 minutes.
149  *
150  * @note This would not include the RX chain delay, so may not exactly
151  *   correspond to the \ref RAIL_Time_t packet timestamp available within
152  *   \ref RAIL_RxPacketDetails_t::timeReceived which reflects the actual
153  *   on-air time that the packet finished.
154  */
155 extern const volatile uint32_t *RAIL_RxPacketTimestamp;
156 
157 /**
158  * Get elapsed time, in microseconds, between two \ref RAIL_TimerTick_t ticks.
159  *
160  * @param[in] startTick Tick recorded at the start of the operation.
161  * @param[in] endTick Tick recorded at the end of the operation.
162  * @return The elapsed time, in microseconds, between two timer ticks.
163  */
164 RAIL_Time_t RAIL_TimerTicksToUs(RAIL_TimerTick_t startTick,
165                                 RAIL_TimerTick_t endTick);
166 
167 /**
168  * Get \ref RAIL_TimerTick_t tick corresponding to a \ref RAIL_Time_t time.
169  *
170  * @param[in] microseconds Time in microseconds.
171  * @return The \ref RAIL_TimerTick_t tick corresponding to the
172  *   \ref RAIL_Time_t time.
173  */
174 RAIL_TimerTick_t RAIL_UsToTimerTicks(RAIL_Time_t microseconds);
175 
176 #endif//DOXYGEN_SHOULD_SKIP_THIS
177 
178 /** @} */ // end of group General_SIXX3XX
179 
180 /******************************************************************************
181  * Multiprotocol
182  *****************************************************************************/
183 /**
184  * @addtogroup Multiprotocol_SIXX3XX SIxx3xx
185  * @ingroup Multiprotocol
186  * @{
187  * @brief SIxx3xx-specific multiprotocol support defines.
188  */
189 
190 /**
191  * @def TRANSITION_TIME_US
192  * @brief Time it takes to take care of protocol switching.
193  */
194 #define TRANSITION_TIME_US 510
195 
196 /** @} */ // end of group Multiprotocol_SIXX3XX
197 
198 /******************************************************************************
199  * Calibration
200  *****************************************************************************/
201 /**
202  * @addtogroup Calibration_SIXX3XX SIxx3xx
203  * @ingroup Calibration
204  * @{
205  * @brief SIxx3xx-specific Calibrations.
206  */
207 
208 /**
209  * @def RAIL_RF_PATHS_2P4GIG
210  * @brief Indicates the number of 2.4 GHz RF Paths suppported.
211  */
212 #if (_SILICON_LABS_32B_SERIES_3_CONFIG == 301) || (_SILICON_LABS_32B_SERIES_3_CONFIG == 300)
213 #define RAIL_RF_PATHS_2P4GIG 1
214 #else
215 #define RAIL_RF_PATHS_2P4GIG 0
216 #endif
217 
218 /**
219  * @def RAIL_RF_PATHS_SUBGIG
220  * @brief Indicates the number of Sub-GHz RF Paths supported.
221  */
222 #define RAIL_RF_PATHS_SUBGIG 0
223 
224 /**
225  * @def RAIL_RF_PATHS
226  * @brief Indicates the number of RF Paths supported.
227  */
228 #define RAIL_RF_PATHS (RAIL_RF_PATHS_SUBGIG + RAIL_RF_PATHS_2P4GIG)
229 
230 #if     (RAIL_RF_PATHS > RAIL_MAX_RF_PATHS)
231 #error "Update rail_types.h RAIL_MAX_RF_PATHS"
232 #endif
233 
234 /**
235  * @def RADIO_CONFIG_ENABLE_IRCAL_MULTIPLE_RF_PATHS
236  * @brief Indicates this version of RAIL supports IR calibration on multiple RF paths
237  * Needed for backwards compatibility.
238  */
239 #if RAIL_RF_PATHS > 1
240 #define RADIO_CONFIG_ENABLE_IRCAL_MULTIPLE_RF_PATHS 1
241 #else
242 #ifdef  DOXYGEN_SHOULD_SKIP_THIS // Leave undefined except for doxygen
243 #define RADIO_CONFIG_ENABLE_IRCAL_MULTIPLE_RF_PATHS 0
244 #endif //DOXYGEN_SHOULD_SKIP_THIS
245 #endif //RAIL_RF_PATHS
246 
247 /**
248  * @struct RAIL_ChannelConfigEntryAttr
249  * @brief A channel configuration entry attribute structure. Items listed
250  *  are designed to be altered and updated during run-time.
251  */
252 struct RAIL_ChannelConfigEntryAttr {
253   /** IR calibration attributes specific to each channel configuration entry. */
254  #if     RAIL_SUPPORTS_OFDM_PA
255   RAIL_IrCalValues_t calValues;
256  #else//!RAIL_SUPPORTS_OFDM_PA
257   RAIL_RxIrCalValues_t calValues;
258  #endif//RAIL_SUPPORTS_OFDM_PA
259 };
260 
261 /** @} */ // end of group Calibration_SIXX3XX
262 
263 /******************************************************************************
264  * Transmit
265  *****************************************************************************/
266 /**
267  * @addtogroup PA_SIXX3XX SIxx3xx
268  * @ingroup PA
269  * @{
270  * @brief Types specific to the SIxx3xx for dealing with the on-chip PAs.
271  */
272 
273 #if (_SILICON_LABS_32B_SERIES_3_CONFIG == 301) || (_SILICON_LABS_32B_SERIES_3_CONFIG == 300)
274 /**
275  * The maximum valid value for the \ref RAIL_TxPowerLevel_t when in \ref
276  * RAIL_TX_POWER_MODE_2P4GIG_HP or \ref RAIL_TX_POWER_MODE_2P4GIG_LP modes.
277  */
278 #define RAIL_TX_POWER_LEVEL_2P4GIG_HP_LP_MAX     (95U)
279 /**
280  * The minimum valid value for the \ref RAIL_TxPowerLevel_t when in \ref
281  * RAIL_TX_POWER_MODE_2P4GIG_HP or \ref RAIL_TX_POWER_MODE_2P4GIG_LP modes.
282  */
283 #define RAIL_TX_POWER_LEVEL_2P4GIG_HP_LP_MIN     (0U)
284 /** Legacy define for High Power (HP) and Low Power (LP) modes. */
285 #define RAIL_TX_POWER_LEVEL_2P4_LP_MIN        (RAIL_TX_POWER_LEVEL_2P4GIG_HP_LP_MIN)
286 /** Legacy define for High Power (HP) and Low Power (LP) modes. */
287 #define RAIL_TX_POWER_LEVEL_2P4_LP_MAX        (RAIL_TX_POWER_LEVEL_2P4GIG_HP_LP_MAX)
288 /** Legacy define for High Power (HP) and Low Power (LP) modes. */
289 #define RAIL_TX_POWER_LEVEL_2P4_HP_MIN        (RAIL_TX_POWER_LEVEL_2P4GIG_HP_LP_MIN)
290 /** Legacy define for High Power (HP) and Low Power (LP) modes. */
291 #define RAIL_TX_POWER_LEVEL_2P4_HP_MAX        (RAIL_TX_POWER_LEVEL_2P4GIG_HP_LP_MAX)
292 #else
293 #error "RAIL_TX_POWER_LEVEL not defined for this device"
294 #endif
295 
296 /**
297  * The number of PA's on this chip (including Virtual PAs).
298  */
299 #if (_SILICON_LABS_32B_SERIES_3_CONFIG == 301) || (_SILICON_LABS_32B_SERIES_3_CONFIG == 300)
300 #define RAIL_NUM_PA (2U)
301 #else
302 #error "RAIL_NUM_PA undefined for platform"
303 #endif
304 
305 #ifndef DOXYGEN_SHOULD_SKIP_THIS
306 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
307 // Only those supported per-platform are defined, for use with #ifdef in
308 // apps or librail code.
309 #if     RAIL_SUPPORTS_2P4GHZ_BAND
310 #define RAIL_TX_POWER_MODE_2P4GIG_HP ((RAIL_TxPowerMode_t) RAIL_TX_POWER_MODE_2P4GIG_HP)
311 #define RAIL_TX_POWER_MODE_2P4_HP ((RAIL_TxPowerMode_t) RAIL_TX_POWER_MODE_2P4_HP)
312 #define RAIL_TX_POWER_MODE_2P4GIG_LP ((RAIL_TxPowerMode_t) RAIL_TX_POWER_MODE_2P4GIG_LP)
313 #define RAIL_TX_POWER_MODE_2P4_LP ((RAIL_TxPowerMode_t) RAIL_TX_POWER_MODE_2P4_LP)
314 #define RAIL_TX_POWER_MODE_2P4GIG_HIGHEST ((RAIL_TxPowerMode_t) RAIL_TX_POWER_MODE_2P4GIG_HIGHEST)
315 #define RAIL_TX_POWER_MODE_2P4_HIGHEST ((RAIL_TxPowerMode_t) RAIL_TX_POWER_MODE_2P4_HIGHEST)
316 #endif//RAIL_SUPPORTS_2P4GHZ_BAND
317 #endif//DOXYGEN_SHOULD_SKIP_THIS
318 
319 /** Convenience macro for any mapping table mode. */
320 #define RAIL_POWER_MODE_IS_ANY_DBM_POWERSETTING_MAPPING_TABLE(x) \
321   (((x) == RAIL_TX_POWER_MODE_2P4GIG_HP)                         \
322    || ((x) == RAIL_TX_POWER_MODE_2P4GIG_LP))
323 
324 /** Convenience macro to check if the power mode supports raw setting. */
325 #define RAIL_POWER_MODE_SUPPORTS_RAW_SETTING(x) \
326   (((x) == RAIL_TX_POWER_MODE_2P4GIG_HP) || ((x) == RAIL_TX_POWER_MODE_2P4GIG_LP))
327 
328 /** @} */ // end of group PA_SIXX3XX
329 
330 /******************************************************************************
331  * RX Channel Hopping
332  *****************************************************************************/
333 /**
334  * @addtogroup Rx_Channel_Hopping_SIXX3XX SIxx3xx
335  * @ingroup Rx_Channel_Hopping
336  * @{
337  * @brief SIxx3xx-specific RX channel hopping.
338  */
339 
340 /// The static amount of memory needed per channel for channel hopping, measured
341 /// in 32 bit words, regardless of the size of radio configuration structures.
342 #define RAIL_CHANNEL_HOPPING_BUFFER_SIZE_PER_CHANNEL (54U)
343 
344 #if     (RAIL_CHANNEL_HOPPING_BUFFER_SIZE_PER_CHANNEL \
345          > RAIL_CHANNEL_HOPPING_BUFFER_SIZE_PER_CHANNEL_WORST_CASE)
346 #error "Update rail_types.h RAIL_CHANNEL_HOPPING_BUFFER_SIZE_PER_CHANNEL_WORST_CASE"
347 #endif
348 
349 /** @} */  // end of group Rx_Channel_Hopping_SIXX3XX
350 
351 /******************************************************************************
352  * Sleep Structures
353  *****************************************************************************/
354 /**
355  * @addtogroup Sleep_SIXX3XX SIxx3xx
356  * @ingroup Sleep
357  * @{
358  * @brief SIxx3xx-specific Sleeping.
359  */
360 
361 /// Default PRS channel to use when configuring sleep
362 #define RAIL_TIMER_SYNC_PRS_CHANNEL_DEFAULT  (7U)
363 
364 /// Default RTCC channel to use when configuring sleep
365 #define RAIL_TIMER_SYNC_RTCC_CHANNEL_DEFAULT (0U)
366 
367 /** @} */ // end of group Sleep_SIXX3XX
368 
369 /******************************************************************************
370  * State Transitions
371  *****************************************************************************/
372 /**
373  * @addtogroup State_Transitions_SIXX3XX SIxx3xx
374  * @ingroup State_Transitions
375  * @{
376  * @brief SIxx3xx-specific State Transitions.
377  */
378 
379 /**
380  * @def RAIL_MINIMUM_TRANSITION_US
381  * @brief The minimum value for a consistent RAIL transition
382  * @note Transitions may need to be slower than this when using longer
383  *   \ref RAIL_TxPowerConfig_t::rampTime values
384  */
385 #define RAIL_MINIMUM_TRANSITION_US (100U)
386 
387 /**
388  * @def RAIL_MAXIMUM_TRANSITION_US
389  * @brief The maximum value for a consistent RAIL transition
390  */
391 #define RAIL_MAXIMUM_TRANSITION_US (1000000U)
392 
393 /**
394  * @enum RAIL_RadioStateSix3x_t
395  * @brief Detailed Series 3 Radio state machine states.
396  */
RAIL_ENUM(RAIL_RadioStateSix3x_t)397 RAIL_ENUM(RAIL_RadioStateSix3x_t) {
398   /** Radio is off. */
399   RAIL_RAC_STATE_SIX3X_OFF = 0,
400   /** Radio is enabling the receiver. */
401   RAIL_RAC_STATE_SIX3X_RXWARM = 1,
402   /** Radio is listening for incoming frames. */
403   RAIL_RAC_STATE_SIX3X_RXSEARCH = 2,
404   /** Radio is receiving a frame. */
405   RAIL_RAC_STATE_SIX3X_RXFRAME = 3,
406   /** Radio is wrapping up after receiving a frame. */
407   RAIL_RAC_STATE_SIX3X_RXWRAPUP = 4,
408   /** Radio is enabling transmitter. */
409   RAIL_RAC_STATE_SIX3X_TXWARM = 5,
410   /** Radio is transmitting data. */
411   RAIL_RAC_STATE_SIX3X_TX = 6,
412   /** Radio is wrapping up after transmitting a frame. */
413   RAIL_RAC_STATE_SIX3X_TXWRAPUP = 7,
414   /** Radio is powering down and going to OFF state. */
415   RAIL_RAC_STATE_SIX3X_SHUTDOWN = 8,
416   /** Radio power-on-reset state. */
417   RAIL_RAC_STATE_SIX3X_POR = 9,
418   /** Invalid Radio state, must be the last entry. */
419   RAIL_RAC_STATE_SIX3X_NONE
420 };
421 
422 #ifndef DOXYGEN_SHOULD_SKIP_THIS
423 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
424 #define RAIL_RAC_STATE_SIX3X_OFF         ((RAIL_RadioStateSix3x_t) RAIL_RAC_STATE_SIX3X_OFF)
425 #define RAIL_RAC_STATE_SIX3X_RXWARM      ((RAIL_RadioStateSix3x_t) RAIL_RAC_STATE_SIX3X_RXWARM)
426 #define RAIL_RAC_STATE_SIX3X_RXSEARCH    ((RAIL_RadioStateSix3x_t) RAIL_RAC_STATE_SIX3X_RXSEARCH)
427 #define RAIL_RAC_STATE_SIX3X_RXFRAME     ((RAIL_RadioStateSix3x_t) RAIL_RAC_STATE_SIX3X_RXFRAME)
428 #define RAIL_RAC_STATE_SIX3X_RXWRAPUP    ((RAIL_RadioStateSix3x_t) RAIL_RAC_STATE_SIX3X_RXWRAPUP)
429 #define RAIL_RAC_STATE_SIX3X_TXWARM      ((RAIL_RadioStateSix3x_t) RAIL_RAC_STATE_SIX3X_TXWARM)
430 #define RAIL_RAC_STATE_SIX3X_TX          ((RAIL_RadioStateSix3x_t) RAIL_RAC_STATE_SIX3X_TX)
431 #define RAIL_RAC_STATE_SIX3X_TXWRAPUP    ((RAIL_RadioStateSix3x_t) RAIL_RAC_STATE_SIX3X_TXWRAPUP)
432 #define RAIL_RAC_STATE_SIX3X_SHUTDOWN    ((RAIL_RadioStateSix3x_t) RAIL_RAC_STATE_SIX3X_SHUTDOWN)
433 #define RAIL_RAC_STATE_SIX3X_POR         ((RAIL_RadioStateSix3x_t) RAIL_RAC_STATE_SIX3X_POR)
434 #define RAIL_RAC_STATE_SIX3X_NONE        ((RAIL_RadioStateSix3x_t) RAIL_RAC_STATE_SIX3X_NONE)
435 /**
436  * Redefined to use \ref RAIL_RadioStateSix3x_t instead of \ref RAIL_RadioStateEfr32_t.
437  */
438 #ifdef  RAIL_RAC_STATE_NONE
439 #undef  RAIL_RAC_STATE_NONE
440 #define RAIL_RAC_STATE_NONE RAIL_RAC_STATE_SIX3X_NONE
441 #endif
442 #endif//DOXYGEN_SHOULD_SKIP_THIS
443 
444 /**
445  * Internal Radio State type mapping for SIxx3xx chips.
446  */
447 typedef RAIL_RadioStateSix3x_t RAIL_RacRadioState_t;
448 
449 /** @} */ // end of group State_Transitions_SIXX3XX
450 
451 #ifndef DOXYGEN_SHOULD_SKIP_THIS
452 
453 /******************************************************************************
454  * Sequencer User Structures
455  *****************************************************************************/
456 /**
457  * @addtogroup Sequencer_User_SIXX3XX Sequencer User
458  * @ingroup RAIL_API
459  * @{
460  * @brief Types specific to the SIxx3xx for dealing with the Sequencer User.
461  */
462 
463 /**
464  * TODO: Document and cleanup.
465  */
466 typedef struct RAIL_UserCommonGlobal {
467   void *pLocSeqVirtualReg;
468   void *pLocSeqTiming;
469   void *pLocUserSeqConfig;
470   void *pLocRtccsyncConfig;
471   void *pLocStateVarConfig;
472   void *pLocGenericPhyConfig;
473   void *pLocpSeqTimestamp;
474   void *pLocpSeqMisc;
475   void *pLocpNewFeatureConfig;
476 } RAIL_UserCommonGlobal_t;
477 
478 /**
479  * TODO: Document and cleanup.
480  */
481 typedef struct UserSeqShMem {
482   /**
483    * pointer to the start of M33 and sequencer shared memory.
484    * TBD: This part of memory should be moved to user memory instead of in generic_seq_common.h
485    */
486   void *pStart;
487   /**
488    * size of shared memory in bytes.
489    * TBD: This part of memory should be moved to user memory instead of in generic_seq_common.h
490    */
491   uint32_t szBytes;
492 } UserSeqShMem_t;
493 
494 /**
495  * TODO: Document and cleanup.
496  */
497 typedef void (*RAIL_SEQ_UserStartMain_t)(void);
498 
499 /**
500  * @struct RAIL_SeqUserAppInfo_t
501  * @brief RAIL sequencer user application structure.
502  *
503  * This structure describes the user application that is loaded on the sequencer.
504  */
505 // TBD: Is this the right place for this structure?  This should probably stays internal?????
506 typedef struct {
507   /// Version of the structure? do we need this? how would this work?
508   uint32_t version;
509   /// Pointer to the start of user executable in memory.
510   uint8_t *pProgramStartMem;
511   /// Pointer to the start of user executable storage.
512   uint8_t *pProgramStartLoc;
513   /// Size of user executable in bytes.
514   uint32_t programSzB;
515   /// Main user function entry.
516   RAIL_SEQ_UserStartMain_t programInitStart;
517   /// Pointer to the start of user initialized data in memory.
518   uint8_t *pDataStartMem;
519   /// Pointer to the start of user initialized data storage.
520   uint8_t *pDataStartLoc;
521   /// Size of user initialized data in bytes.
522   uint32_t dataSzB;
523   /// Pointer to the start of user un-initialized data in memory.
524   uint8_t *pScratchStartMem;
525   /// Size of user un-initialized data in bytes.
526   uint32_t scratchSzB;
527 } RAIL_SeqUserAppInfo_t;
528 
529 /**
530  * @typedef RAIL_UserCpReqCb_t
531  * @brief Callback function type used to indicate status of user copy request.
532  *
533  * @param[in] pCpReq A non-NULL pointer to the user copy request.
534  * @param[in] reqStatus The status of the request.
535  */
536 typedef void(*RAIL_UserCpReqCb_t)(const void *pCpReq,
537                                   RAIL_Status_t reqStatus);
538 
539 //FIXME: these are not RAIL_Status_t values, and need doxygen
540 #define RAIL_USER_CP_REQ_STATUS_FLAG_STARTED           1U
541 #define RAIL_USER_CP_REQ_STATUS_FLAG_COMPLETED         2U
542 #define RAIL_USER_CP_REQ_STATUS_FLAG_REQ_HOST          4U
543 #define RAIL_USER_CP_REQ_STATUS_FLAG_INVALID_PARAMETER 8U
544 
545 /**
546  * @struct RAIL_UserCpReq_t
547  * @brief Memory copy request configuration structure.
548  *
549  * This structure describes the user request to copy contents from one memory area to another.
550  */
551 typedef struct RAIL_UserCpReq {
552   // Pointer to the next request; NULL if none.
553   struct RAIL_UserCpReq *pNext;
554   // Non-NULL pointer to the location to copy from.
555   const uint8_t *pSrc;
556   // Non-NULL pointer to the location to copy to.
557   uint8_t *pDst;
558   // The number of bytes to copy.
559   uint16_t xferSzBytes;
560   // Status of the request.
561   volatile uint8_t statusFlag;
562   // Reserved.
563   volatile uint8_t reserved;
564   // A pointer to the callback called on completion or error. May be NULL.
565   RAIL_UserCpReqCb_t pCpReqCB;
566 } RAIL_UserCpReq_t;
567 
568 /**
569  * Load sequencer user application to memory.
570  *
571  * @param[in] railHandle A RAIL instance handle.
572  * @param[in] pSeqUserApp A pointer to the structure describing the user
573  *   sequencer application metadata.
574  * @return Status code indicating success of the function call.
575  *
576  * Attempts to load sequencer user application to the sequencer memory and
577  * execute its initialization function.
578  */
579 RAIL_Status_t RAIL_LoadUserSeqApp(RAIL_Handle_t railHandle,
580                                   const RAIL_SeqUserAppInfo_t *pSeqUserApp);
581 
582 /**
583  * Send a shutdown message to the sequencer user application.
584  *
585  * @param[in] railHandle A RAIL instance handle.
586  * @return Status code indicating success of the function call.
587  */
588 RAIL_Status_t RAIL_ShutdownUserSeqApp(RAIL_Handle_t railHandle);
589 
590 /**
591  * Indicate whether this chip supports Sequencer User.
592  *
593  * @param[in] railHandle A RAIL instance handle.
594  * @return true if Sequencer User is supported; false otherwise.
595  */
596 bool RAIL_SupportsUserSequencer(RAIL_Handle_t railHandle);
597 
598 /**
599  * Get the sequencer user common global variables.
600  *
601  * @param[in] railHandle A RAIL instance handle.
602  * @param[out] pCommonGlobal A non-NULL pointer to store the common global variables.
603  * @return Status code indicating success of the function call.
604  */
605 RAIL_Status_t RAIL_USER_printCommonGlobal(RAIL_Handle_t railHandle,
606                                           RAIL_UserCommonGlobal_t *pCommonGlobal);
607 
608 /**
609  * Get sequencer user mailbox message.
610  *
611  * @param[in] railHandle A RAIL instance handle.
612  * @param[out] pMsg A non-NULL pointer to the message filled in by the call.
613  * @return Status code indicating success of the function call.
614  */
615 RAIL_Status_t RAIL_USER_GetMboxMsg(RAIL_Handle_t railHandle,
616                                    uint32_t *pMsg);
617 
618 /**
619  * Send user mailbox message to the sequencer.
620  *
621  * @param[in] railHandle A RAIL instance handle.
622  * @param[in] msg A message to send.
623  * @return Status code indicating success of the function call.
624  */
625 RAIL_Status_t RAIL_USER_SendMbox(RAIL_Handle_t railHandle,
626                                  uint32_t msg);
627 
628 /**
629  * Initialize internal RAIL state used to run a user application on
630  * the sequencer.
631  *
632  * @param[in] railHandle A RAIL instance handle.
633  * @return Status code indicating success of the function call.
634  */
635 RAIL_Status_t RAIL_USER_startSeqCtrl(RAIL_Handle_t railHandle);
636 
637 /**
638  * Initialize a semaphore.
639  *
640  * @param[in] railHandle A RAIL instance handle.
641  * @param[in,out] pSemaphore A non-NULL pointer to a 32-bit aligned
642  *   semaphore location updated to become an unacquired semaphore.
643  * @return Status code indicating success of the function call.
644  *
645  * @note This must be called from the hsot for each semaphore's memory location.
646  */
647 RAIL_Status_t RAIL_USER_InitSemaphore(RAIL_Handle_t railHandle,
648                                       uint32_t *pSemaphore);
649 
650 /**
651  * Acquire a semaphore lock.
652  *
653  * @param[in] railHandle A RAIL instance handle.
654  * @param[in,out] pSemaphore A non-NULL pointer to the semaphore location
655  *   which will be updated if the lock was acquired.
656  * @return Status code indicating success of the function call:
657  *   \ref RAIL_STATUS_NO_ERROR if lock was acquired;
658  *   \ref RAIL_STATUS_INVALID_PARAMETER if the lock is corrupted (the lock need to be initialized with \ref RAIL_USER_InitSemaphore());
659  *   \ref RAIL_STATUS_INVALID_CALL if the lock has been acquired by another processor;
660  *   \ref RAIL_STATUS_INVALID_STATE if the lock has been acquired before by the current processor;
661  *   \ref RAIL_STATUS_SUSPENDED if the lock has been changed recently, user can try to acuire it again
662  *
663  * This function attempts to acquire (lock) a semaphore that was previously
664  * initialized by \ref RAIL_USER_InitSemaphore().
665  */
666 RAIL_Status_t RAIL_USER_TryLockSemaphore(RAIL_Handle_t railHandle,
667                                          uint32_t *pSemaphore);
668 
669 /**
670  * Release a semaphore.
671  *
672  * @param[in] railHandle A RAIL instance handle.
673  * @param[in,out] pSemaphore A non-NULL pointer to the semaphore location
674  *   which will be updated if the semaphore was released.
675  * @return Status code indicating success of the function call.
676  *
677  * This function releases a semaphore that was previously initialized by
678  * \ref RAIL_USER_InitSemaphore() and acquired by \ref RAIL_USER_TryLockSemaphore().
679  */
680 RAIL_Status_t RAIL_USER_ReleaseSemaphore(RAIL_Handle_t railHandle,
681                                          uint32_t *pSemaphore);
682 
683 /**
684  * Initilize which DMA to use to copy user data.
685  *
686  * @param[in] railHandle A RAIL instance handle.
687  * @param[in] dmaChannel The DMA channel to use.
688  * @return Status code indicating success of the function call.
689  */
690 RAIL_Status_t RAIL_USER_InitCp(RAIL_Handle_t railHandle,
691                                uint32_t dmaChannel);
692 
693 /**
694  * Start a request to copy user data.
695  *
696  * @param[in] railHandle A RAIL instance handle.
697  * @param[in,out] pCpReqHead A non-NULL pointer to the start of a chain of user copy request configurations.
698  * @param[in,out] pCpReqTail A non-NULL pointer to the last configuration in the chain.
699  * @return Status code indicating success of the function call.
700  *
701  * This function will initiate copy operations for each element in the linked
702  * list chain between pCpReqHead and pCpReqTail, inclusive.  The \ref
703  * RAIL_UserCpReq_t::statusFlag of each element in the chain will be
704  * updated as the operation progresses to completion or failure.
705  *
706  * @note Before using this function, \ref RAIL_USER_InitCp() must be
707  *   called once from the host.
708  */
709 RAIL_Status_t RAIL_USER_StartCpReq(RAIL_Handle_t railHandle,
710                                    RAIL_UserCpReq_t *pCpReqHead,
711                                    RAIL_UserCpReq_t *pCpReqTail);
712 
713 /** @} */ // end of group Sequencer_User_SIXX3XX
714 
715 #endif//DOXYGEN_SHOULD_SKIP_THIS
716 
717 #ifdef __cplusplus
718 }
719 #endif
720 
721 #endif //__RAIL_TYPES_H__
722 
723 #endif //__RAIL_CHIP_SPECIFIC_H_
724 
725 #endif //SLI_LIBRARY_BUILD
726