Contiki-NG
rf-core.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2015, Texas Instruments Incorporated - http://www.ti.com/
3  * All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  * 1. Redistributions of source code must retain the above copyright
9  * notice, this list of conditions and the following disclaimer.
10  * 2. Redistributions in binary form must reproduce the above copyright
11  * notice, this list of conditions and the following disclaimer in the
12  * documentation and/or other materials provided with the distribution.
13  * 3. Neither the name of the copyright holder nor the names of its
14  * contributors may be used to endorse or promote products derived
15  * from this software without specific prior written permission.
16  *
17  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
18  * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
19  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
20  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
21  * COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
22  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
23  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
24  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
26  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
28  * OF THE POSSIBILITY OF SUCH DAMAGE.
29  */
30 /*---------------------------------------------------------------------------*/
31 /**
32  * \addtogroup cc26xx
33  * @{
34  *
35  * \defgroup rf-core CC13xx/CC26xx RF core
36  *
37  * Different flavours of chips of the CC13xx/CC26xx family have different
38  * radio capability. For example, the CC2650 can operate in IEEE 802.15.4 mode
39  * at 2.4GHz, but it can also operate in BLE mode. The CC1310 only supports
40  * sub-ghz mode.
41  *
42  * However, there are many radio functionalities that are identical across
43  * all chips. The rf-core driver provides support for this common functionality
44  *
45  * @{
46  *
47  * \file
48  * Header file for the CC13xx/CC26xx RF core driver
49  */
50 /*---------------------------------------------------------------------------*/
51 #ifndef RF_CORE_H_
52 #define RF_CORE_H_
53 /*---------------------------------------------------------------------------*/
54 #include "contiki.h"
55 #include "driverlib/rf_common_cmd.h"
56 
57 #include <stdint.h>
58 #include <stdbool.h>
59 /*---------------------------------------------------------------------------*/
60 #define RF_CORE_FRONT_END_MODE_DIFFERENTIAL 0
61 #define RF_CORE_FRONT_END_MODE_SINGLE_RFP 1
62 #define RF_CORE_FRONT_END_MODE_SINGLE_RFN 2
63 
64 #define RF_CORE_BIAS_MODE_INTERNAL 0
65 #define RF_CORE_BIAS_MODE_EXTERNAL 1
66 /*---------------------------------------------------------------------------*/
67 /*
68  * RF Front-End Mode and Bias for CMD_RADIO_SETUP (IEEE and BLE)
69  * Default: Differential mode, internal bias
70  */
71 #ifdef RF_CORE_CONF_RADIO_SETUP_FRONT_END_MODE
72 #define RF_CORE_RADIO_SETUP_FRONT_END_MODE RF_CORE_CONF_RADIO_SETUP_FRONT_END_MODE
73 #else
74 #define RF_CORE_RADIO_SETUP_FRONT_END_MODE RF_CORE_FRONT_END_MODE_DIFFERENTIAL
75 #endif
76 
77 #ifdef RF_CORE_CONF_RADIO_SETUP_BIAS_MODE
78 #define RF_CORE_RADIO_SETUP_BIAS_MODE RF_CORE_CONF_RADIO_SETUP_BIAS_MODE
79 #else
80 #define RF_CORE_RADIO_SETUP_BIAS_MODE RF_CORE_BIAS_MODE_INTERNAL
81 #endif
82 /*---------------------------------------------------------------------------*/
83 /*
84  * RF Front-End Mode and Bias for CMD_PROP_DIV_RADIO_SETUP (PROP mode)
85  * Default: Differential mode, external bias
86  */
87 #ifdef RF_CORE_CONF_PROP_FRONT_END_MODE
88 #define RF_CORE_PROP_FRONT_END_MODE RF_CORE_CONF_PROP_FRONT_END_MODE
89 #else
90 #define RF_CORE_PROP_FRONT_END_MODE RF_CORE_FRONT_END_MODE_DIFFERENTIAL
91 #endif
92 
93 #ifdef RF_CORE_CONF_PROP_BIAS_MODE
94 #define RF_CORE_PROP_BIAS_MODE RF_CORE_CONF_PROP_BIAS_MODE
95 #else
96 #define RF_CORE_PROP_BIAS_MODE RF_CORE_BIAS_MODE_EXTERNAL
97 #endif
98 /*---------------------------------------------------------------------------*/
99 #define RF_CORE_CMD_ERROR 0
100 #define RF_CORE_CMD_OK 1
101 /*---------------------------------------------------------------------------*/
102 /**
103  * \brief A data strcuture representing the radio's primary mode of operation
104  *
105  * The CC13xx / CC26xx radio supports up to potentially 3 modes: IEEE, Prop and
106  * BLE. Within Contiki, we assume that the radio is by default in one of IEEE
107  * or Prop in order to support standard 6LoWPAN / .15.4 operation. The BLE
108  * mode interrupts this so called "primary" mode in order to send BLE adv
109  * messages. Once BLE is done advertising, we need to be able to restore the
110  * previous .15.4 mode. Unfortunately, the only way this can be done with
111  * NETSTACK_RADIO API is by fully power-cycling the radio, which is something
112  * we do not want to do.
113  *
114  * Thus, we declare a secondary data structure for primary mode drivers (IEEE
115  * or Prop). We use this data structure to issue "soft off" and "back on"
116  * commands. Soft off in this context means stopping RX (e.g. the respective
117  * IEEE RX operation), but without shutting down the RF core (which is what
118  * NETSTACK_RADIO.off() would have done). We then remember what mode we were
119  * using in order to be able to re-enter RX mode for this mode.
120  *
121  * A NETSTACK_RADIO driver will declare those two functions somewhere within
122  * its module of implementation. During its init() routine, it will notify
123  * the RF core module so that the latter can abort and restore operations.
124  */
125 typedef struct rf_core_primary_mode_s {
126  /**
127  * \brief A pointer to a function used to abort the current radio op
128  */
129  void (*abort)(void);
130 
131  /**
132  * \brief A pointer to a function that will restore the previous radio op
133  * \return RF_CORE_CMD_OK or RF_CORE_CMD_ERROR
134  */
135  uint8_t (*restore)(void);
136 
137  /**
138  * \brief A pointer to a function that checks if the radio is on
139  * \return 1 or 0
140  */
141  uint8_t (*is_on)(void);
142 
143  /**
144  * \brief Offset of the end of SFD when compared to the radio HW-generated timestamp
145  */
148 /*---------------------------------------------------------------------------*/
149 /* RF Command status constants - Correspond to values in the CMDSTA register */
150 #define RF_CORE_CMDSTA_PENDING 0x00
151 #define RF_CORE_CMDSTA_DONE 0x01
152 #define RF_CORE_CMDSTA_ILLEGAL_PTR 0x81
153 #define RF_CORE_CMDSTA_UNKNOWN_CMD 0x82
154 #define RF_CORE_CMDSTA_UNKNOWN_DIR_CMD 0x83
155 #define RF_CORE_CMDSTA_CONTEXT_ERR 0x85
156 #define RF_CORE_CMDSTA_SCHEDULING_ERR 0x86
157 #define RF_CORE_CMDSTA_PAR_ERR 0x87
158 #define RF_CORE_CMDSTA_QUEUE_ERR 0x88
159 #define RF_CORE_CMDSTA_QUEUE_BUSY 0x89
160 
161 /* Status values starting with 0x8 correspond to errors */
162 #define RF_CORE_CMDSTA_ERR_MASK 0x80
163 
164 /* CMDSTA is 32-bits. Return value in bits 7:0 */
165 #define RF_CORE_CMDSTA_RESULT_MASK 0xFF
166 
167 #define RF_CORE_RADIO_OP_STATUS_IDLE 0x0000
168 /*---------------------------------------------------------------------------*/
169 #define RF_CORE_NOT_ACCESSIBLE 0x00
170 #define RF_CORE_ACCESSIBLE 0x01
171 /*---------------------------------------------------------------------------*/
172 /* RF Radio Op status constants. Field 'status' in Radio Op command struct */
173 #define RF_CORE_RADIO_OP_STATUS_IDLE 0x0000
174 #define RF_CORE_RADIO_OP_STATUS_PENDING 0x0001
175 #define RF_CORE_RADIO_OP_STATUS_ACTIVE 0x0002
176 #define RF_CORE_RADIO_OP_STATUS_SKIPPED 0x0003
177 #define RF_CORE_RADIO_OP_STATUS_DONE_OK 0x0400
178 #define RF_CORE_RADIO_OP_STATUS_DONE_COUNTDOWN 0x0401
179 #define RF_CORE_RADIO_OP_STATUS_DONE_RXERR 0x0402
180 #define RF_CORE_RADIO_OP_STATUS_DONE_TIMEOUT 0x0403
181 #define RF_CORE_RADIO_OP_STATUS_DONE_STOPPED 0x0404
182 #define RF_CORE_RADIO_OP_STATUS_DONE_ABORT 0x0405
183 #define RF_CORE_RADIO_OP_STATUS_ERROR_PAST_START 0x0800
184 #define RF_CORE_RADIO_OP_STATUS_ERROR_START_TRIG 0x0801
185 #define RF_CORE_RADIO_OP_STATUS_ERROR_CONDITION 0x0802
186 #define RF_CORE_RADIO_OP_STATUS_ERROR_PAR 0x0803
187 #define RF_CORE_RADIO_OP_STATUS_ERROR_POINTER 0x0804
188 #define RF_CORE_RADIO_OP_STATUS_ERROR_CMDID 0x0805
189 #define RF_CORE_RADIO_OP_STATUS_ERROR_NO_SETUP 0x0807
190 #define RF_CORE_RADIO_OP_STATUS_ERROR_NO_FS 0x0808
191 #define RF_CORE_RADIO_OP_STATUS_ERROR_SYNTH_PROG 0x0809
192 
193 /* Additional Op status values for IEEE mode */
194 #define RF_CORE_RADIO_OP_STATUS_IEEE_SUSPENDED 0x2001
195 #define RF_CORE_RADIO_OP_STATUS_IEEE_DONE_OK 0x2400
196 #define RF_CORE_RADIO_OP_STATUS_IEEE_DONE_BUSY 0x2401
197 #define RF_CORE_RADIO_OP_STATUS_IEEE_DONE_STOPPED 0x2402
198 #define RF_CORE_RADIO_OP_STATUS_IEEE_DONE_ACK 0x2403
199 #define RF_CORE_RADIO_OP_STATUS_IEEE_DONE_ACKPEND 0x2404
200 #define RF_CORE_RADIO_OP_STATUS_IEEE_DONE_TIMEOUT 0x2405
201 #define RF_CORE_RADIO_OP_STATUS_IEEE_DONE_BGEND 0x2406
202 #define RF_CORE_RADIO_OP_STATUS_IEEE_DONE_ABORT 0x2407
203 #define RF_CORE_RADIO_OP_STATUS_ERROR_WRONG_BG 0x0806
204 #define RF_CORE_RADIO_OP_STATUS_IEEE_ERROR_PAR 0x2800
205 #define RF_CORE_RADIO_OP_STATUS_IEEE_ERROR_NO_SETUP 0x2801
206 #define RF_CORE_RADIO_OP_STATUS_IEEE_ERROR_NO_FS 0x2802
207 #define RF_CORE_RADIO_OP_STATUS_IEEE_ERROR_SYNTH_PROG 0x2803
208 #define RF_CORE_RADIO_OP_STATUS_IEEE_ERROR_RXOVF 0x2804
209 #define RF_CORE_RADIO_OP_STATUS_IEEE_ERROR_TXUNF 0x2805
210 
211 /* Op status values for BLE mode */
212 #define RF_CORE_RADIO_OP_STATUS_BLE_DONE_OK 0x1400
213 #define RF_CORE_RADIO_OP_STATUS_BLE_DONE_RXTIMEOUT 0x1401
214 #define RF_CORE_RADIO_OP_STATUS_BLE_DONE_NOSYNC 0x1402
215 #define RF_CORE_RADIO_OP_STATUS_BLE_DONE_RXERR 0x1403
216 #define RF_CORE_RADIO_OP_STATUS_BLE_DONE_CONNECT 0x1404
217 #define RF_CORE_RADIO_OP_STATUS_BLE_DONE_MAXNACK 0x1405
218 #define RF_CORE_RADIO_OP_STATUS_BLE_DONE_ENDED 0x1406
219 #define RF_CORE_RADIO_OP_STATUS_BLE_DONE_ABORT 0x1407
220 #define RF_CORE_RADIO_OP_STATUS_BLE_DONE_STOPPED 0x1408
221 #define RF_CORE_RADIO_OP_STATUS_BLE_ERROR_PAR 0x1800
222 #define RF_CORE_RADIO_OP_STATUS_BLE_ERROR_RXBUF 0x1801
223 #define RF_CORE_RADIO_OP_STATUS_BLE_ERROR_NO_SETUP 0x1802
224 #define RF_CORE_RADIO_OP_STATUS_BLE_ERROR_NO_FS 0x1803
225 #define RF_CORE_RADIO_OP_STATUS_BLE_ERROR_SYNTH_PROG 0x1804
226 #define RF_CORE_RADIO_OP_STATUS_BLE_ERROR_RXOVF 0x1805
227 #define RF_CORE_RADIO_OP_STATUS_BLE_ERROR_TXUNF 0x1806
228 
229 /* Op status values for proprietary mode */
230 #define RF_CORE_RADIO_OP_STATUS_PROP_DONE_OK 0x3400
231 #define RF_CORE_RADIO_OP_STATUS_PROP_DONE_RXTIMEOUT 0x3401
232 #define RF_CORE_RADIO_OP_STATUS_PROP_DONE_BREAK 0x3402
233 #define RF_CORE_RADIO_OP_STATUS_PROP_DONE_ENDED 0x3403
234 #define RF_CORE_RADIO_OP_STATUS_PROP_DONE_STOPPED 0x3404
235 #define RF_CORE_RADIO_OP_STATUS_PROP_DONE_ABORT 0x3405
236 #define RF_CORE_RADIO_OP_STATUS_PROP_DONE_RXERR 0x3406
237 #define RF_CORE_RADIO_OP_STATUS_PROP_DONE_IDLE 0x3407
238 #define RF_CORE_RADIO_OP_STATUS_PROP_DONE_BUSY 0x3408
239 #define RF_CORE_RADIO_OP_STATUS_PROP_DONE_IDLETIMEOUT 0x3409
240 #define RF_CORE_RADIO_OP_STATUS_PROP_DONE_BUSYTIMEOUT 0x340A
241 #define RF_CORE_RADIO_OP_STATUS_PROP_ERROR_PAR 0x3800
242 #define RF_CORE_RADIO_OP_STATUS_PROP_ERROR_RXBUF 0x3801
243 #define RF_CORE_RADIO_OP_STATUS_PROP_ERROR_RXFULL 0x3802
244 #define RF_CORE_RADIO_OP_STATUS_PROP_ERROR_NO_SETUP 0x3803
245 #define RF_CORE_RADIO_OP_STATUS_PROP_ERROR_NO_FS 0x3804
246 #define RF_CORE_RADIO_OP_STATUS_PROP_ERROR_RXOVF 0x3805
247 #define RF_CORE_RADIO_OP_STATUS_PROP_ERROR_TXUNF 0x3806
248 
249 /* Bits 15:12 signify the protocol */
250 #define RF_CORE_RADIO_OP_STATUS_PROTO_MASK 0xF000
251 #define RF_CORE_RADIO_OP_STATUS_PROTO_GENERIC 0x0000
252 #define RF_CORE_RADIO_OP_STATUS_PROTO_BLE 0x1000
253 #define RF_CORE_RADIO_OP_STATUS_PROTO_IEEE 0x2000
254 #define RF_CORE_RADIO_OP_STATUS_PROTO_PROP 0x3000
255 
256 /* Bits 11:10 signify Running / Done OK / Done with error */
257 #define RF_CORE_RADIO_OP_MASKED_STATUS 0x0C00
258 #define RF_CORE_RADIO_OP_MASKED_STATUS_RUNNING 0x0000
259 #define RF_CORE_RADIO_OP_MASKED_STATUS_DONE 0x0400
260 #define RF_CORE_RADIO_OP_MASKED_STATUS_ERROR 0x0800
261 /*---------------------------------------------------------------------------*/
262 /* Command Types */
263 #define RF_CORE_COMMAND_TYPE_MASK 0x0C00
264 #define RF_CORE_COMMAND_TYPE_RADIO_OP 0x0800
265 #define RF_CORE_COMMAND_TYPE_IEEE_BG_RADIO_OP 0x0800
266 #define RF_CORE_COMMAND_TYPE_IEEE_FG_RADIO_OP 0x0C00
267 
268 #define RF_CORE_COMMAND_PROTOCOL_MASK 0x3000
269 #define RF_CORE_COMMAND_PROTOCOL_COMMON 0x0000
270 #define RF_CORE_COMMAND_PROTOCOL_BLE 0x1000
271 #define RF_CORE_COMMAND_PROTOCOL_IEEE 0x2000
272 #define RF_CORE_COMMAND_PROTOCOL_PROP 0x3000
273 /*---------------------------------------------------------------------------*/
274 /* Radio timer register */
275 #define RATCNT 0x00000004
276 /*---------------------------------------------------------------------------*/
277 /* Special value returned by CMD_IEEE_CCA_REQ when an RSSI is not available */
278 #define RF_CORE_CMD_CCA_REQ_RSSI_UNKNOWN -128
279 
280 /* Used for the return value of channel_clear */
281 #define RF_CORE_CCA_CLEAR 1
282 #define RF_CORE_CCA_BUSY 0
283 
284 /* Used as an error return value for get_cca_info */
285 #define RF_CORE_GET_CCA_INFO_ERROR 0xFF
286 
287 /*
288  * Values of the individual bits of the ccaInfo field in CMD_IEEE_CCA_REQ's
289  * status struct
290  */
291 #define RF_CORE_CMD_CCA_REQ_CCA_STATE_IDLE 0 /* 00 */
292 #define RF_CORE_CMD_CCA_REQ_CCA_STATE_BUSY 1 /* 01 */
293 #define RF_CORE_CMD_CCA_REQ_CCA_STATE_INVALID 2 /* 10 */
294 
295 #define RF_CORE_CMD_CCA_REQ_CCA_CORR_IDLE (0 << 4)
296 #define RF_CORE_CMD_CCA_REQ_CCA_CORR_BUSY (1 << 4)
297 #define RF_CORE_CMD_CCA_REQ_CCA_CORR_INVALID (3 << 4)
298 #define RF_CORE_CMD_CCA_REQ_CCA_CORR_MASK (3 << 4)
299 
300 #define RF_CORE_CMD_CCA_REQ_CCA_SYNC_BUSY (1 << 6)
301 /*---------------------------------------------------------------------------*/
302 #define RF_CORE_RX_BUF_INCLUDE_CRC 0
303 #define RF_CORE_RX_BUF_INCLUDE_RSSI 1
304 #define RF_CORE_RX_BUF_INCLUDE_CORR 1
305 #define RF_CORE_RX_BUF_INCLUDE_TIMESTAMP 1
306 /*---------------------------------------------------------------------------*/
307 /* How long to wait for an ongoing ACK TX to finish before starting frame TX */
308 #define RF_CORE_TX_TIMEOUT (RTIMER_SECOND >> 11)
309 
310 /* How long to wait for the RF to enter RX in rf_cmd_ieee_rx */
311 #define RF_CORE_ENTER_RX_TIMEOUT (RTIMER_SECOND >> 10)
312 
313 /* How long to wait for the RF to react on CMD_ABORT: around 1 msec */
314 #define RF_CORE_TURN_OFF_TIMEOUT (RTIMER_SECOND >> 10)
315 
316 /* How long to wait for the RF to finish TX of a packet or an ACK */
317 #define RF_CORE_TX_FINISH_TIMEOUT (RTIMER_SECOND >> 7)
318 
319 /*---------------------------------------------------------------------------*/
320 /* Make the main driver process visible to mode drivers */
321 PROCESS_NAME(rf_core_process);
322 /*---------------------------------------------------------------------------*/
323 /* Buffer full flag */
324 extern volatile bool rf_core_rx_is_full;
325 /*---------------------------------------------------------------------------*/
326 /* RSSI of the last read frame */
327 extern volatile int8_t rf_core_last_rssi;
328 /* Correlation/LQI of the last read frame */
329 extern volatile uint8_t rf_core_last_corr_lqi;
330 /* SFD timestamp of the last read frame, in rtimer ticks */
331 extern volatile uint32_t rf_core_last_packet_timestamp;
332 /*---------------------------------------------------------------------------*/
333 /* Are we currently in poll mode? */
334 extern uint8_t rf_core_poll_mode;
335 /*---------------------------------------------------------------------------*/
336 /**
337  * \brief Check whether the RF core is accessible
338  * \retval RF_CORE_ACCESSIBLE The core is powered and ready for access
339  * \retval RF_CORE_NOT_ACCESSIBLE The core is not ready
340  *
341  * If this function returns RF_CORE_NOT_ACCESSIBLE, rf_core_power_up() must be
342  * called before any attempt to access the core.
343  */
344 uint8_t rf_core_is_accessible(void);
345 
346 /**
347  * \brief Sends a command to the RF core.
348  *
349  * \param cmd The command value or a pointer to a command buffer
350  * \param status A pointer to a variable which will hold the status
351  * \return RF_CORE_CMD_OK or RF_CORE_CMD_ERROR
352  *
353  * This function supports all three types of command (Radio OP, immediate and
354  * direct)
355  *
356  * For immediate and Radio OPs, cmd is a pointer to the data structure
357  * containing the command and its parameters. This data structure must be
358  * 4-byte aligned.
359  *
360  * For direct commands, cmd contains the value of the command alongside its
361  * parameters. This value will be written to CMDSTA verbatim, so the command
362  * ID must be in the 16 high bits, and the 2 LS bits must be set to 01 by the
363  * caller.
364  *
365  * The caller is responsible of allocating and populating cmd for Radio OP and
366  * immediate commands
367  *
368  * The caller is responsible for allocating status
369  *
370  * For immediate commands and radio Ops, this function will set the command's
371  * status field to RF_CORE_RADIO_OP_STATUS_IDLE before sending it to the RF
372  */
373 uint_fast8_t rf_core_send_cmd(uint32_t cmd, uint32_t *status);
374 
375 /**
376  * \brief Block and wait for a Radio op to complete
377  * \param cmd A pointer to any command's structure
378  * \retval RF_CORE_CMD_OK the command completed with status _DONE_OK
379  * \retval RF_CORE_CMD_ERROR Timeout exceeded or the command completed with
380  * status _DONE_xxx (e.g. RF_CORE_RADIO_OP_STATUS_DONE_TIMEOUT)
381  */
382 uint_fast8_t rf_core_wait_cmd_done(void *cmd);
383 
384 /**
385  * \brief Turn on power to the RFC and boot it.
386  * \return RF_CORE_CMD_OK or RF_CORE_CMD_ERROR
387  */
388 int rf_core_power_up(void);
389 
390 /**
391  * \brief Disable RFCORE clock domain in the MCU VD and turn off the RFCORE PD
392  */
393 void rf_core_power_down(void);
394 
395 /**
396  * \brief Initialise RF APIs in the RF core
397  * \return RF_CORE_CMD_OK or RF_CORE_CMD_ERROR
398  *
399  * Depending on chip family and capability, this function will set the correct
400  * value to PRCM.RFCMODESEL
401  */
402 uint8_t rf_core_set_modesel(void);
403 
404 /**
405  * \brief Start the CM0 RAT
406  * \return RF_CORE_CMD_OK or RF_CORE_CMD_ERROR
407  *
408  * This function must be called each time the CM0 boots. The boot sequence
409  * can be performed automatically by calling rf_core_boot() if patches are not
410  * required. If patches are required then the patches must be applied after
411  * power up and before calling this function.
412  */
413 uint8_t rf_core_start_rat(void);
414 
415 /**
416  * \brief Stop the CM0 RAT synchronously
417  * \return RF_CORE_CMD_OK or RF_CORE_CMD_ERROR
418  *
419  * This function is not strictly necessary, but through calling it it's possibly
420  * to learn the RAT / RTC offset, which useful to get accurate radio timestamps.
421  */
422 uint8_t rf_core_stop_rat(void);
423 
424 /**
425  * \brief Restart the CM0 RAT
426  * \return RF_CORE_CMD_OK or RF_CORE_CMD_ERROR
427  *
428  * This function restarts the CM0 RAT and therefore resynchornizes it with RTC.
429  * To achieve good timing accuracy, it should be called periodically.
430  */
431 uint8_t rf_core_restart_rat(void);
432 
433 /**
434  * \brief Boot the RF Core
435  * \return RF_CORE_CMD_OK or RF_CORE_CMD_ERROR
436  *
437  * This function will perform the CM0 boot sequence. It will first power it up
438  * and then start the RAT. If a patch is required, then the mode driver must
439  * not call this function and perform the sequence manually, applying patches
440  * after boot and before calling rf_core_start_rat().
441  *
442  * The function will return RF_CORE_CMD_ERROR if any of those steps fails. If
443  * the boot sequence fails to complete, the RF Core will be powered down.
444  */
445 uint8_t rf_core_boot(void);
446 
447 /**
448  * \brief Setup RF core interrupts
449  */
450 void rf_core_setup_interrupts(void);
451 
452 /**
453  * \brief Enable interrupt on command done.
454  * \param fg set true to enable irq on foreground command done and false for
455  * background commands or if not in ieee mode.
456  *
457  * This is used within TX routines in order to be able to sleep the CM3 and
458  * wake up after TX has finished
459  *
460  * \sa rf_core_cmd_done_dis()
461  */
462 void rf_core_cmd_done_en(bool fg);
463 
464 /**
465  * \brief Disable the LAST_CMD_DONE and LAST_FG_CMD_DONE interrupts.
466  *
467  * This is used within TX routines after TX has completed
468  *
469  * \sa rf_core_cmd_done_en()
470  */
471 void rf_core_cmd_done_dis(void);
472 
473 /**
474  * \brief Returns a pointer to the most recent proto-dependent Radio Op
475  * \return The pointer
476  *
477  * The RF Core driver will remember the most recent proto-dependent Radio OP
478  * issued, so that other modules can inspect its type and state at a subsequent
479  * stage. The assumption is that those commands will be issued by a function
480  * that will then return. The following commands will be "remembered"
481  *
482  * - All BLE Radio Ops (0x18nn)
483  * - All Prop Radio Ops (0x38nn)
484  * - IEEE BG Radio Ops (0x28nn)
485  *
486  * The following commands are assumed to be executed synchronously and will
487  * thus not be remembered by the core and not returned by this function:
488  *
489  * - Direct commands
490  * - Proto-independent commands (including Radio Ops and Immediate ones)
491  * - IEEE FG Radio Ops (0x2Cxx)
492  *
493  * This assumes that all commands will be sent to the radio using
494  * rf_core_send_cmd()
495  */
496 rfc_radioOp_t *rf_core_get_last_radio_op(void);
497 
498 /**
499  * \brief Prepare a buffer to host a Radio Op
500  * \param buf A pointer to the buffer that will host the Radio Op
501  * \param len The buffer's length
502  * \param command The command ID
503  *
504  * The caller is responsible to allocate the buffer
505  *
506  * This function will not check whether the buffer is large enough to hold the
507  * command. This is the caller's responsibility
508  *
509  * This function will wipe out the buffer's contents.
510  */
511 void rf_core_init_radio_op(rfc_radioOp_t *buf, uint16_t len, uint16_t command);
512 
513 /**
514  * \brief Register a primary mode for radio operation
515  * \param mode A pointer to the struct representing the mode
516  *
517  * A normal NESTACK_RADIO driver will normally register itself by calling
518  * this function during its own init().
519  *
520  * \sa rf_core_primary_mode_t
521  */
523 
524 /**
525  * \brief Abort the currently running primary radio op
526  */
527 void rf_core_primary_mode_abort(void);
528 
529 /**
530  * \brief Abort the currently running primary radio op
531  */
532 uint8_t rf_core_primary_mode_restore(void);
533 
534 /**
535  * \brief Initialize the RAT to RTC conversion machinery
536  */
537 uint8_t rf_core_rat_init(void);
538 
539 /**
540  * \brief Check if RAT overflow has occured and increment the overflow counter if so
541  */
542 uint8_t rf_core_check_rat_overflow(void);
543 
544 /**
545  * \brief Convert from RAT timestamp to rtimer ticks
546  */
547 uint32_t rf_core_convert_rat_to_rtimer(uint32_t rat_timestamp);
548 
549 /*---------------------------------------------------------------------------*/
550 #endif /* RF_CORE_H_ */
551 /*---------------------------------------------------------------------------*/
552 /**
553  * @}
554  * @}
555  */
rfc_radioOp_t * rf_core_get_last_radio_op()
Returns a pointer to the most recent proto-dependent Radio Op.
Definition: rf-core.c:534
struct rf_core_primary_mode_s rf_core_primary_mode_t
A data strcuture representing the radio&#39;s primary mode of operation.
int rf_core_power_up()
Turn on power to the RFC and boot it.
Definition: rf-core.c:263
void rf_core_power_down()
Disable RFCORE clock domain in the MCU VD and turn off the RFCORE PD.
Definition: rf-core.c:372
uint8_t rf_core_set_modesel()
Initialise RF APIs in the RF core.
Definition: rf-core.c:410
void rf_core_primary_mode_abort()
Abort the currently running primary radio op.
Definition: rf-core.c:555
int16_t sfd_timestamp_offset
Offset of the end of SFD when compared to the radio HW-generated timestamp.
Definition: rf-core.h:146
uint32_t rf_core_convert_rat_to_rtimer(uint32_t rat_timestamp)
Convert from RAT timestamp to rtimer ticks.
Definition: rf-core.c:652
void rf_core_primary_mode_register(const rf_core_primary_mode_t *mode)
Register a primary mode for radio operation.
Definition: rf-core.c:549
A data strcuture representing the radio&#39;s primary mode of operation.
Definition: rf-core.h:125
uint8_t(* is_on)(void)
A pointer to a function that checks if the radio is on.
Definition: rf-core.h:141
uint8_t rf_core_rat_init(void)
Initialize the RAT to RTC conversion machinery.
Definition: rf-core.c:577
#define PROCESS_NAME(name)
Declare the name of a process.
Definition: process.h:286
void rf_core_cmd_done_dis(void)
Disable the LAST_CMD_DONE and LAST_FG_CMD_DONE interrupts.
Definition: rf-core.c:527
uint8_t(* restore)(void)
A pointer to a function that will restore the previous radio op.
Definition: rf-core.h:135
void rf_core_init_radio_op(rfc_radioOp_t *op, uint16_t len, uint16_t command)
Prepare a buffer to host a Radio Op.
Definition: rf-core.c:540
uint8_t rf_core_primary_mode_restore()
Abort the currently running primary radio op.
Definition: rf-core.c:565
uint8_t rf_core_is_accessible()
Check whether the RF core is accessible.
Definition: rf-core.c:145
void(* abort)(void)
A pointer to a function used to abort the current radio op.
Definition: rf-core.h:129
uint_fast8_t rf_core_send_cmd(uint32_t cmd, uint32_t *status)
Sends a command to the RF core.
Definition: rf-core.c:154
void rf_core_setup_interrupts(void)
Setup RF core interrupts.
Definition: rf-core.c:479
uint8_t rf_core_start_rat(void)
Start the CM0 RAT.
Definition: rf-core.c:312
uint8_t rf_core_restart_rat(void)
Restart the CM0 RAT.
Definition: rf-core.c:460
uint8_t rf_core_boot()
Boot the RF Core.
Definition: rf-core.c:438
void rf_core_cmd_done_en(bool fg)
Enable interrupt on command done.
Definition: rf-core.c:513
uint8_t rf_core_stop_rat(void)
Stop the CM0 RAT synchronously.
Definition: rf-core.c:340
uint8_t rf_core_check_rat_overflow(void)
Check if RAT overflow has occured and increment the overflow counter if so.
Definition: rf-core.c:588
uint_fast8_t rf_core_wait_cmd_done(void *cmd)
Block and wait for a Radio op to complete.
Definition: rf-core.c:220