RF.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2016-2019, Texas Instruments Incorporated
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  *
9  * * Redistributions of source code must retain the above copyright
10  * notice, this list of conditions and the following disclaimer.
11  *
12  * * Redistributions in binary form must reproduce the above copyright
13  * notice, this list of conditions and the following disclaimer in the
14  * documentation and/or other materials provided with the distribution.
15  *
16  * * Neither the name of Texas Instruments Incorporated nor the names of
17  * its contributors may be used to endorse or promote products derived
18  * from this software without specific prior written permission.
19  *
20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
22  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
23  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
24  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
26  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
27  * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
28  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
29  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
30  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31  */
32 /*!****************************************************************************
33 @file RF.h
34 @brief Radio Frequency (RF) Core Driver for the CC13XX and CC26XX device
35  family.
36 
37 To use the RF driver, ensure that the correct driver library for your device
38 is linked in and include this header file as follows:
39 
40 @code
41 #include <ti/drivers/rf/RF.h>
42 @endcode
43 
44 <hr>
45 @anchor rf_overview
46 Overview
47 ========
48 
49 The RF driver provides access to the radio core on the CC13xx/CC26xx device
50 family. It offers a high-level interface for command execution and to the
51 radio timer (RAT). The RF driver ensures the lowest possible power consumption
52 by providing automatic power management that is fully transparent for the
53 application.
54 
55 @note This document describes the features and usage of the RF driver API. For a
56 detailed explanation of the RF core, please refer to the
57 <a href='../../../proprietary-rf/technical-reference-manual.html'><b>Technical
58 Reference Manual</b></a> or the
59 <a href='../../../proprietary-rf/proprietary-rf-users-guide.html'><b>Proprietary
60 RF User Guide</b></a>.
61 
62 <b>Key features are:</b>
63 
64 @li @ref rf_command_execution "Synchronous execution of direct and immediate radio commands"
65 @li @ref rf_command_execution "Synchronous and asynchronous execution of radio operation commands"
66 @li Various @ref rf_event_callbacks "event hooks" to interact with RF commands and the RF driver
67 @li Automatic @ref rf_power_management "power management"
68 @li @ref rf_scheduling "Preemptive scheduler for RF operations" of different RF driver instances
69 @li Convenient @ref rf_rat "Access to the radio timer" (RAT)
70 @li @ref rf_tx_power "Programming the TX power level"
71 
72 @anchor rf_setup_and_configuration
73 Setup and configuration
74 =======================
75 
76 The RF driver can be configured at 4 different places:
77 
78 1. In the build configuration by choosing either the single-client or
79  multi-client driver version.
80 
81 2. At compile-time by setting hardware and software interrupt priorities
82  in the board support file.
83 
84 3. During run-time initialization by setting #RF_Params when calling
85  #RF_open().
86 
87 4. At run-time via #RF_control().
88 
89 
90 Build configuration
91 -------------------
92 
93 The RF driver comes in two versions: single-client and multi-client. The
94 single-client version allows only one driver instance to access the RF core at
95 a time. The multi-client driver version allows concurrent access to the RF
96 core with different RF settings. The multi-client driver has a slightly larger
97 footprint and is not needed for many proprietary applications. The driver
98 version can be selected in the build configuration by linking either against a
99 RFCC26XX_singleMode or RFCC26XX_multiMode pre-built library. When using the
100 single-client driver, `RF_SINGLEMODE` has to be defined globally in the build
101 configuration. The multi-client driver is the default configuration in the
102 SimpleLink SDKs.
103 
104 
105 Board configuration
106 -------------------
107 
108 The RF driver handles RF core hardware interrupts and uses software interrupts
109 for its internal state machine. For managing the interrupt priorities, it
110 expects the existence of a global #RFCC26XX_HWAttrsV2 object. This is
111 usually defined in the board support file, for example `CC1310_LAUNCHXL.c`,
112 but when developing on custom boards, it might be kept anywhere in the
113 application. By default, the priorities are set to the lowest possible value:
114 
115 @code
116 const RFCC26XX_HWAttrsV2 RFCC26XX_hwAttrs = {
117  .hwiPriority = INT_PRI_LEVEL7, // Lowest HWI priority: INT_PRI_LEVEL7
118  // Highest HWI priority: INT_PRI_LEVEL1
119 
120  .swiPriority = 0, // Lowest SWI priority: 0
121  // Highest SWI priority: Swi.numPriorities - 1
122 
123  .xoscHfAlwaysNeeded = true // Power driver always starts XOSC-HF: true
124  // RF driver will request XOSC-HF if needed: false
125 };
126 @endcode
127 
128 
129 Initialization
130 --------------
131 
132 When initiating an RF driver instance, the function #RF_open() accepts a
133 pointer to a #RF_Params object which might set several driver parameters. In
134 addition, it expects an #RF_Mode object and a setup command which is usually
135 generated by SmartRF Studio:
136 
137 @code
138 RF_Params rfParams;
139 RF_Params_init(&rfParams);
140 rfParams.nInactivityTimeout = 2000;
141 
142 RF_Handle rfHandle = RF_open(&rfObject, &RF_prop,
143  (RF_RadioSetup*)&RF_cmdPropRadioDivSetup, &rfParams);
144 @endcode
145 
146 The function #RF_open() returns a driver handle that is used for accessing the
147 correct driver instance. Please note that the first RF operation command
148 before an RX or TX operation command must be a `CMD_FS` to set the synthesizer
149 frequency. The RF driver caches both, the pointer to the setup command and the
150 physical `CMD_FS` for automatic power management.
151 
152 
153 Run-time configuration
154 ----------------------
155 
156 While a driver instance is opened, it can be re-configured with the function
157 #RF_control(). Various configuration parameters @ref RF_CTRL are available.
158 Example:
159 
160 @code
161 uint32_t timeoutUs = 2000;
162 RF_control(rfHandle, RF_CTRL_SET_INACTIVITY_TIMEOUT, &timeoutUs);
163 @endcode
164 
165 <hr>
166 @anchor rf_command_execution
167 Command execution
168 =================
169 
170 The RF core supports 3 different kinds of commands:
171 
172 1. Direct commands
173 2. Immediate commands
174 3. Radio operation commands
175 
176 Direct and immediate commands are dispatched via #RF_runDirectCmd() and
177 #RF_runImmediateCmd() respectively. These functions block until the command
178 has completed and return a status code of the type #RF_Stat when done.
179 
180 @code
181 #include <ti/devices/${DEVICE_FAMILY}/driverlib/rf_common_cmd.h>
182 
183 RF_Stat status = RF_runDirectCmd(rfHandle, CMD_ABORT);
184 assert(status == RF_StatCmdDoneSuccess);
185 @endcode
186 
187 Radio operation commands are potentially long-running commands and support
188 different triggers as well as conditional execution. Only one command can be
189 executed at a time, but the RF driver provides an internal queue that stores
190 commands until the RF core is free. Two interfaces are provided for radio
191 operation commands:
192 
193 1. Asynchronous: #RF_postCmd() and #RF_pendCmd()
194 2. Synchronous: #RF_runCmd()
195 
196 The asynchronous function #RF_postCmd() posts a radio operation into the
197 driver's internal command queue and returns a command handle of the type
198 #RF_CmdHandle which is an index in the command queue. The command is
199 dispatched as soon as the RF core has completed any previous radio operation
200 command.
201 
202 @code
203 #include <ti/devices/${DEVICE_FAMILY}/driverlib/rf_common_cmd.h>
204 
205 RF_Callback callback = NULL;
206 RF_EventMask subscribedEvents = 0;
207 RF_CmdHandle rxCommandHandle = RF_postCmd(rfHandle, (RF_Op*)&RF_cmdRx,
208  RF_PriorityNormal, callback, subscribedEvents);
209 
210 assert(rxCommandHandle != RF_ALLOC_ERROR); // The command queue is full.
211 @endcode
212 
213 Command execution happens in background. The calling task may proceed with
214 other work or execute direct and immediate commands to interact with the
215 posted radio operation. But beware that the posted command might not have
216 started, yet. By calling the function #RF_pendCmd() and subscribing events of
217 the type #RF_EventMask, it is possible to re-synchronize to a posted command:
218 
219 @code
220 // RF_EventRxEntryDone must have been subscribed in RF_postCmd().
221 RF_EventMask events = RF_pendCmd(rfHandle, rxCommandHandle,
222  RF_EventRxEntryDone);
223 
224 // Program proceeds after RF_EventRxEntryDone or after a termination event.
225 @endcode
226 
227 The function #RF_runCmd() is a combination of both, #RF_postCmd() and
228 #RF_pendCmd() and allows synchronous execution.
229 
230 A pending or already running command might be aborted at any time by calling
231 the function #RF_cancelCmd() or #RF_flushCmd(). These functions take command
232 handles as parameters, but can also just abort anything in the RF driver's
233 queue:
234 
235 @code
236 uint8_t abortGraceful = 1;
237 
238 // Abort a single command
239 RF_cancelCmd(rfHandle, rxCommandHandle, abortGraceful);
240 
241 // Abort anything
242 RF_flushCmd(rfHandle, RF_CMDHANDLE_FLUSH_ALL, abortGraceful);
243 @endcode
244 
245 When aborting a command, the return value of #RF_runCmd() or #RF_pendCmd()
246 will contain the termination reason in form of event flags. If the command is
247 in the RF driver queue, but has not yet start, the #RF_EventCmdCancelled event is
248 raised.
249 
250 <hr>
251 @anchor rf_event_callbacks
252 Event callbacks
253 ===============
254 
255 The RF core generates multiple interrupts during command execution. The RF
256 driver maps these interrupts 1:1 to callback events of the type #RF_EventMask.
257 Hence, it is unnecessary to implement own interrupt handlers. Callback events
258 are divided into 3 groups:
259 
260 - Command-specific events, documented for each radio operation command. An example
261  is the #RF_EventRxEntryDone for the `CMD_PROP_RX`.
262 
263 - Generic events, defined for all radio operations and originating on the RF core.
264  These are for instance #RF_EventCmdDone and #RF_EventLastCmdDone. Both events
265  indicate the termination of one or more RF operations.
266 
267 - Generic events, defined for all radio operations and originating in the RF driver,
268  for instance #RF_EventCmdCancelled.
269 
270 @sa @ref RF_Core_Events, @ref RF_Driver_Events.
271 
272 How callback events are subscribed was shown in the previous section. The
273 following snippet shows a typical event handler callback for a proprietary RX
274 operation:
275 
276 @code
277 void rxCallback(RF_Handle handle, RF_CmdHandle command, RF_EventMask events)
278 {
279  if (events & RF_EventRxEntryDone)
280  {
281  Semaphore_post(rxPacketSemaphore);
282  }
283  if (events & RF_EventLastCmdDone)
284  {
285  // ...
286  }
287 }
288 @endcode
289 
290 In addition, the RF driver can generate error and power-up events that do not
291 relate directly to the execution of a radio command. Such events can be
292 subscribed by specifying the callback function pointers #RF_Params::pErrCb and
293 #RF_Params::pPowerCb.
294 
295 All callback functions run in software interrupt (SWI) context. Therefore,
296 only a minimum amount of code should be executed. When using absolute timed
297 commands with tight timing constraints, then it is recommended to set the RF
298 driver SWIs to a high priority.
299 See @ref rf_setup_and_configuration "Setup and configuration" for more details.
300 
301 <hr>
302 @anchor rf_power_management
303 Power management
304 ================
305 
306 The RF core is a hardware peripheral and can be switched on and off. The RF
307 driver handles that automatically and provides the following power
308 optimization features:
309 
310 - Lazy power-up and radio setup caching
311 - Power-down on inactivity
312 - Deferred dispatching of commands with absolute timing
313 
314 
315 Lazy power-up and radio setup caching
316 -------------------------------------
317 
318 The RF core optimizes the power consumption by enabling the RF core as late as
319 possible. For instance does #RF_open() not power up the RF core immediately.
320 Instead, it waits until the first radio operation command is dispatched by
321 #RF_postCmd() or #RF_runCmd().
322 
323 The function #RF_open() takes a radio setup command as parameter and expects a
324 `CMD_FS` command to follow. The pointer to the radio setup command and the
325 whole `CMD_FS` command are cached internally in the RF driver. They will be
326 used for every proceeding power-up procedure. Whenever the client re-runs a
327 setup command or a `CMD_FS` command, the driver updates its internal cache
328 with the new settings.
329 
330 By default, the RF driver measures the time that it needs for the power-up
331 procedure and uses that as an estimate for the next power cycle. On the
332 CC13x0/CC26x0 devices, power-up takes usually 1.6 ms. Automatic measurement
333 can be suppressed by specifying a custom power-up time with
334 #RF_Params::nPowerUpDuration. In addition, the client might set
335 #RF_Params::nPowerUpDurationMargin to cover any uncertainty when doing
336 automatic measurements. This is necessary in applications with a high hardware
337 interrupt load which can delay the RF driver's internal state machine
338 execution.
339 
340 
341 Power-down on inactivity
342 ------------------------
343 
344 Whenever a radio operation completes and there is no other radio operation in
345 the queue, the RF core might be powered down. There are two options in the RF
346 driver:
347 
348 - **Automatic power-down** by setting the parameter
349  #RF_Params::nInactivityTimeout. The RF core will then start a timer after
350  the last command in the queue has completed. The default timeout is "forever"
351  and this feature is disabled.
352 
353 - **Manual power-down** by calling #RF_yield(). The client should do this
354  whenever it knows that no further radio operation will be executed for a
355  couple of milliseconds.
356 
357 During the power-down procedure the RF driver stops the radio timer and saves
358 a synchronization timestamp for the next power-up. This keeps the radio timer
359 virtually in sync with the RTC even though it is not running all the time. The
360 synchronization is done in hardware.
361 
362 
363 Deferred dispatching of commands with absolute timing
364 -----------------------------------------------------
365 
366 When dispatching a radio operation command with an absolute start trigger that
367 is ahead in the future, the RF driver defers the execution and powers the RF
368 core down until the command is due. It does that only, when:
369 
370 1. `cmd.startTrigger.triggerType` is set to `TRIG_ABSTIME`
371 
372 2. The difference between #RF_getCurrentTime() and `cmd.startTime`
373  is at not more than 3/4 of a full RAT cycle. Otherwise the driver assumes
374  that `cmd.startTime` is in the past.
375 
376 3. There is enough time to run a full power cycle before `cmd.startTime` is
377  due. That includes:
378 
379  - the power-down time (fixed value, 1 ms) if the RF core is already
380  powered up,
381 
382  - the measured power-up duration or the value specified by
383  #RF_Params::nPowerUpDuration,
384 
385  - the power-up safety margin #RF_Params::nPowerUpDurationMargin
386  (the default is 282 microseconds).
387 
388 If one of the conditions are not fulfilled, the RF core is kept up and
389 running and the command is dispatched immediately. This ensures, that the
390 command will execute on-time and not miss the configured start trigger.
391 
392 <hr>
393 @anchor rf_scheduling
394 Preemptive scheduling of RF commands in multi-client applications
395 =================================================================
396 
397 Schedule BLE and proprietary radio commands.
398 
399 @code
400 RF_Object rfObject_ble;
401 RF_Object rfObject_prop;
402 
403 RF_Handle rfHandle_ble, rfHandle_prop;
404 RF_Params rfParams_ble, rfParams_prop;
405 RF_ScheduleCmdParams schParams_ble, schParams_prop;
406 
407 RF_Mode rfMode_ble =
408 {
409  .rfMode = RF_MODE_MULTIPLE, // rfMode for dual mode
410  .cpePatchFxn = &rf_patch_cpe_ble,
411  .mcePatchFxn = 0,
412  .rfePatchFxn = &rf_patch_rfe_ble,
413 };
414 
415 RF_Mode rfMode_prop =
416 {
417  .rfMode = RF_MODE_MULTIPLE, // rfMode for dual mode
418  .cpePatchFxn = &rf_patch_cpe_genfsk,
419  .mcePatchFxn = 0,
420  .rfePatchFxn = 0,
421 };
422 
423 // Init RF and specify non-default parameters
424 RF_Params_init(&rfParams_ble);
425 rfParams_ble.nInactivityTimeout = 200; // 200us
426 
427 RF_Params_init(&rfParams_prop);
428 rfParams_prop.nInactivityTimeout = 200; // 200us
429 
430 // Configure RF schedule command parameters directly.
431 schParams_ble.priority = RF_PriorityNormal;
432 schParams_ble.endTime = 0;
433 schParams_ble.allowDelay = RF_AllowDelayAny;
434 
435 // Alternatively, use the helper function to configure the default behavior
436 RF_ScheduleCmdParams_init(&schParams_prop);
437 
438 // Open BLE and proprietary RF handles
439 rfHandle_ble = RF_open(rfObj_ble, &rfMode_ble, (RF_RadioSetup*)&RF_cmdRadioSetup, &rfParams_ble);
440 rfHandle_prop = RF_open(rfObj_prop, &rfMode_prop, (RF_RadioSetup*)&RF_cmdPropRadioDivSetup, &rfParams_prop);
441 
442 // Run a proprietary Fs command
443 RF_runCmd(rfHandle_pro, (RF_Op*)&RF_cmdFs, RF_PriorityNormal, NULL, NULL);
444 
445 // Schedule a proprietary RX command
446 RF_scheduleCmd(rfHandle_pro, (RF_Op*)&RF_cmdPropRx, &schParams_prop, &prop_callback, RF_EventRxOk);
447 
448 // Schedule a BLE advertiser command
449 RF_scheduleCmd(rfHandle_ble, (RF_Op*)&RF_cmdBleAdv, &schParams_ble, &ble_callback,
450  (RF_EventLastCmdDone | RF_EventRxEntryDone | RF_EventTxEntryDone));
451 
452 @endcode
453 
454 Get dual mode schedule map including timing and priority information for access requests and commands.
455 
456 @code
457 
458 RF_ScheduleMap rfSheduleMap;
459 RF_InfoVal rfGetInfoVal;
460 
461 // Get schedule map
462 rfGetInfoVal.pScheduleMap = &rfScheduleMap;
463 RF_getInfo(NULL, RF_GET_SCHEDULE_MAP, &rfGetInfoVal);
464 
465 // RF_scheduleMap includes the following information:
466 // (RF_NUM_SCHEDULE_ACCESS_ENTRIES (default = 2)) entries of access request information
467 // (RF_NUM_SCHEDULE_COMMAND_ENTRIES (default = 8)) entries of radio command information
468 // Each entry has the type of RF_ScheduleMapElement.
469 
470 @endcode
471 
472 <hr>
473 @anchor rf_rat
474 Accessing the Radio Timer (RAT)
475 ==============================
476 
477 The Radio Timer on the RF core is an independent 32 bit timer running at a
478 tick rate of 4 ticks per microsecond. It is only physically active while the
479 RF core is on. But because the RF driver resynchronizes the RAT to the RTC on
480 every power-up, it appears to the application as the timer is always running.
481 The RAT accuracy depends on the system HF clock while the RF core is active
482 and on the LF clock while the RF core is powered down.
483 
484 The current RAT time stamp can be obtained by #RF_getCurrentTime():
485 
486 @code
487 uint32_t now = RF_getCurrentTime();
488 @endcode
489 
490 The RAT has 8 independent channels that can be set up in capture and compare
491 mode by #RF_ratCapture() and #RF_ratCompare() respectively. Three of these
492 channels are accessible by the RF driver. Each channel may be connected to
493 physical hardware signals for input and output or may trigger a callback
494 function.
495 
496 In order to allocate a RAT channel and trigger a callback function at a
497 certain time stamp, use #RF_ratCompare():
498 
499 @code
500 RF_Handle rfDriver;
501 RF_RatConfigCompare config;
502 RF_RatConfigCompare_init(&config);
503 config.callback = &onRatTriggered;
504 config.channel = RF_RatChannelAny;
505 config.timeout = RF_getCurrentTime() + RF_convertMsToRatTicks(1701);
506 
507 RF_RatHandle ratHandle = RF_ratCompare(rfDriver, &config, nullptr);
508 assert(ratHandle != RF_ALLOC_ERROR);
509 
510 void onRatTriggered(RF_Handle h, RF_RatHandle rh, RF_EventMask e, uint32_t compareCaptureTime)
511 {
512  if (e & RF_EventError)
513  {
514  // RF driver failed to trigger the callback on time.
515  }
516  printf("RAT has triggered at %u.", compareCaptureTime);
517 
518  // Trigger precisely with the same period again
519  config.timeout = compareCaptureTime + RF_convertMsToRatTicks(1701);
520  ratHandle = RF_ratCompare(rfDriver, &config, nullptr);
521  assert(ratHandle != RF_ALLOC_ERROR);
522 }
523 @endcode
524 
525 The RAT may be used to capture a time stamp on an edge of a physical pin. This
526 can be achieved with #RF_ratCapture().
527 
528 @code
529 #include <ti/drivers/pin/PINCC26XX.h>
530 // Map IO 26 to RFC_GPI0
531 PINCC26XX_setMux(pinHandle, IOID_26, PINCC26XX_MUX_RFC_GPI0);
532 
533 RF_Handle rfDriver;
534 RF_RatConfigCapture config;
535 RF_RatConfigCapture_init(&config);
536 config.callback = &onSignalTriggered;
537 config.channel = RF_RatChannelAny;
538 config.source = RF_RatCaptureSourceRfcGpi0;
539 config.captureMode = RF_RatCaptureModeRising;
540 config.repeat = RF_RatCaptureRepeat;
541 
542 RF_RatHandle ratHandle = RF_ratCapture(rfDriver, &config, nullptr);
543 assert(ratHandle != RF_ALLOC_ERROR);
544 
545 void onSignalTriggered(RF_Handle h, RF_RatHandle rh, RF_EventMask e, uint32_t compareCaptureTime)
546 {
547  if (e & RF_EventError)
548  {
549  // An internal error has occurred
550  }
551  printf("Rising edge detected on IO 26 at %u.", compareCaptureTime);
552 }
553 @endcode
554 
555 In both cases, the RAT may generate an output signal when being triggered. The
556 signal can be routed to a physical IO pin:
557 
558 @code
559 // Generate a pulse on an internal RAT output signal
560 RF_RatConfigOutput output;
561 RF_RatConfigOutput_init(&output);
562 output.mode = RF_RatOutputModePulse;
563 output.select = RF_RatOutputSelectRatGpo3;
564 RF_ratCompare(...);
565 
566 // Map RatGpo3 to one of four intermediate doorbell signals.
567 // This has to be done in the override list in order to take permanent effect.
568 // The override list can be found in the RF settings .c file exported from
569 // SmartRF Studio.
570 // Attention: This will change the default mapping of the PA and LNA signal as well.
571 #include <ti/devices/[DEVICE_FAMILY]/inc/hw_rfc_dbell.h>
572 static uint32_t pOverrides[] =
573 {
574  HW_REG_OVERRIDE(0x1110, RFC_DBELL_SYSGPOCTL_GPOCTL2_RATGPO3),
575  // ...
576 }
577 
578 // Finally, route the intermediate doorbell signal to a physical pin.
579 #include <ti/drivers/pin/PINCC26XX.h>
580 PINCC26XX_setMux(pinHandle, IOID_17, PINCC26XX_MUX_RFC_GPO2);
581 @endcode
582 
583 <hr>
584 @anchor rf_tx_power
585 Programming the TX power level
586 ==============================
587 
588 The application can program a TX power level for each RF client with the function
589 #RF_setTxPower(). The new value takes immediate effect if the RF core is up and
590 running. Otherwise, it is stored in the RF driver client configuration.
591 
592 TX power may be stored in a lookup table in ascending order. This table is usually
593 generated and exported from SmartRF Studio together with the rest of the PHY configuration.
594 A typical power table my look as follows:
595 @code
596 RF_TxPowerTable_Entry txPowerTable[] = {
597  { .power = 11, .value = { 0x1233, RF_TxPowerTable_DefaultPA }},
598  { .power = 13, .value = { 0x1234, RF_TxPowerTable_DefaultPA }},
599  // ...
600  RF_TxPowerTable_TERMINATION_ENTRY
601 };
602 @endcode
603 
604 @note Some devices offer a high-power PA in addition to the default PA.
605 A client must not mix configuration values in the same power table and must
606 not hop from a default PA configuration to a high-power PA configuration unless it
607 can guarantee that the RF setup command is re-executed in between.
608 
609 Given this power table format, the application may program a new power level in multiple
610 ways. It can use convenience functions to search a certain power level
611 in the power table or may access the table index-based:
612 @code
613 // Set a certain power level. Search a matching level.
614 RF_setTxPower(h, RF_TxPowerTable_findValue(txPowerTable, 17));
615 
616 // Set a certain power level with a known level.
617 RF_setTxPower(h, txPowerTable[3].value);
618 
619 // Set a certain power without using a human readable level.
620 RF_setTxPower(h, value);
621 
622 // Set maximum power. Search the value.
623 RF_setTxPower(h, RF_TxPowerTable_findValue(txPowerTable, RF_TxPowerTable_MAX_DBM));
624 
625 // Set minimum power without searching.
626 RF_setTxPower(h, txPowerTable[0].value);
627 
628 // Set minimum power. Search the value.
629 RF_setTxPower(h, RF_TxPowerTable_findValue(txPowerTable, RF_TxPowerTable_MIN_DBM));
630 
631 // Set maximum power without searching.
632 int32_t lastIndex = sizeof(txPowerTable) / sizeof(RF_TxPowerTable_Entry) - 2;
633 RF_setTxPower(h, txPowerTable[lastIndex].value);
634 @endcode
635 
636 The current configured power level for a client can be retrieved by #RF_getTxPower().
637 @code
638 // Get the current configured power level.
639 int8_t power = RF_TxPowerTable_findPowerLevel(txPowerTable, RF_getTxPower(h));
640 @endcode
641 
642 <hr>
643 @anchor rf_convenience_features
644 Convenience features
645 ====================
646 
647 The RF driver simplifies often needed tasks and provides additional functions.
648 For instance, it can read the RSSI while the RF core is in RX mode using the
649 function :tidrivers_api:`RF_getRssi`:
650 
651 @code
652 int8_t rssi = RF_getRssi(rfHandle);
653 assert (rssi != RF_GET_RSSI_ERROR_VAL); // Could not read the RSSI
654 @endcode
655 
656 <hr>
657  ******************************************************************************
658  */
659 
660 #ifndef ti_drivers_rf__include
661 #define ti_drivers_rf__include
662 
663 #ifdef __cplusplus
664 extern "C" {
665 #endif
666 
667 #include <stdint.h>
668 #include <stdbool.h>
669 
670 #include <ti/drivers/dpl/ClockP.h>
671 #include <ti/drivers/dpl/SemaphoreP.h>
672 #include <ti/drivers/utils/List.h>
673 
674 #include <ti/devices/DeviceFamily.h>
675 #include DeviceFamily_constructPath(driverlib/rf_common_cmd.h)
676 #include DeviceFamily_constructPath(driverlib/rf_prop_cmd.h)
677 #include DeviceFamily_constructPath(driverlib/rf_ble_cmd.h)
678 
690 #define RF_EventCmdDone (1 << 0)
691 #define RF_EventLastCmdDone (1 << 1)
692 #define RF_EventFGCmdDone (1 << 2)
693 #define RF_EventLastFGCmdDone (1 << 3)
694 #define RF_EventTxDone (1 << 4)
695 #define RF_EventTXAck (1 << 5)
696 #define RF_EventTxCtrl (1 << 6)
697 #define RF_EventTxCtrlAck (1 << 7)
698 #define RF_EventTxCtrlAckAck (1 << 8)
699 #define RF_EventTxRetrans (1 << 9)
700 #define RF_EventTxEntryDone (1 << 10)
701 #define RF_EventTxBufferChange (1 << 11)
702 #define RF_EventPaChanged (1 << 14)
703 #define RF_EventRxOk (1 << 16)
704 #define RF_EventRxNOk (1 << 17)
705 #define RF_EventRxIgnored (1 << 18)
706 #define RF_EventRxEmpty (1 << 19)
707 #define RF_EventRxCtrl (1 << 20)
708 #define RF_EventRxCtrlAck (1 << 21)
709 #define RF_EventRxBufFull (1 << 22)
710 #define RF_EventRxEntryDone (1 << 23)
711 #define RF_EventDataWritten (1 << 24)
712 #define RF_EventNDataWritten (1 << 25)
713 #define RF_EventRxAborted (1 << 26)
714 #define RF_EventRxCollisionDetected (1 << 27)
715 #define RF_EventModulesUnlocked (1 << 29)
716 #define RF_EventInternalError (uint32_t)(1 << 31)
717 #define RF_EventMdmSoft 0x0000002000000000
718 
727 #define RF_EventCmdCancelled 0x1000000000000000
728 #define RF_EventCmdAborted 0x2000000000000000
729 #define RF_EventCmdStopped 0x4000000000000000
730 #define RF_EventRatCh 0x0800000000000000
731 #define RF_EventPowerUp 0x0400000000000000
732 #define RF_EventError 0x0200000000000000
733 #define RF_EventCmdPreempted 0x0100000000000000
734 
752 #define RF_CTRL_SET_INACTIVITY_TIMEOUT 0
753 
762 #define RF_CTRL_UPDATE_SETUP_CMD 1
763 
768 #define RF_CTRL_SET_POWERUP_DURATION_MARGIN 2
769 
776 #define RF_CTRL_SET_PHYSWITCHING_DURATION_MARGIN 3
777 
784 #define RF_CTRL_SET_RAT_RTC_ERR_TOL_VAL 4
785 
796 #define RF_CTRL_SET_POWER_MGMT 5
797 
818 #define RF_CTRL_SET_HWI_PRIORITY 6
819 
840 #define RF_CTRL_SET_SWI_PRIORITY 7
841 
850 #define RF_CTRL_SET_AVAILABLE_RAT_CHANNELS_MASK 8
851 
864 #define RF_TxPowerTable_MIN_DBM -128
865 
872 #define RF_TxPowerTable_MAX_DBM 126
873 
879 #define RF_TxPowerTable_INVALID_DBM 127
880 
898 #define RF_TxPowerTable_INVALID_VALUE 0x3fffff
899 
915 #define RF_TxPowerTable_TERMINATION_ENTRY \
916  { .power = RF_TxPowerTable_INVALID_DBM, .value = { .rawValue = RF_TxPowerTable_INVALID_VALUE, .paType = RF_TxPowerTable_DefaultPA } }
917 
924 #define RF_TxPowerTable_DEFAULT_PA_ENTRY(bias, gain, boost, coefficient) \
925  { .rawValue = ((bias) << 0) | ((gain) << 6) | ((boost) << 8) | ((coefficient) << 9), .paType = RF_TxPowerTable_DefaultPA }
926 
933 #define RF_TxPowerTable_HIGH_PA_ENTRY(bias, ibboost, boost, coefficient, ldotrim) \
934  { .rawValue = ((bias) << 0) | ((ibboost) << 6) | ((boost) << 8) | ((coefficient) << 9) | ((ldotrim) << 16), .paType = RF_TxPowerTable_HighPA }
935 
936 
943 #define RF_GET_RSSI_ERROR_VAL (-128)
944 #define RF_CMDHANDLE_FLUSH_ALL (-1)
945 #define RF_ALLOC_ERROR (-2)
946 #define RF_SCHEDULE_CMD_ERROR (-3)
947 #define RF_ERROR_RAT_PROG (-255)
948 #define RF_ERROR_INVALID_RFMODE (-256)
949 #define RF_ERROR_CMDFS_SYNTH_PROG (-257)
950 
951 #define RF_NUM_SCHEDULE_ACCESS_ENTRIES 2
952 #define RF_NUM_SCHEDULE_COMMAND_ENTRIES 8
953 #define RF_NUM_SCHEDULE_MAP_ENTRIES (RF_NUM_SCHEDULE_ACCESS_ENTRIES + RF_NUM_SCHEDULE_COMMAND_ENTRIES)
954 #define RF_SCH_MAP_CURRENT_CMD_OFFSET RF_NUM_SCHEDULE_ACCESS_ENTRIES
955 #define RF_SCH_MAP_PENDING_CMD_OFFSET (RF_SCH_MAP_CURRENT_CMD_OFFSET + 2)
956 
957 #define RF_ABORT_PREEMPTION (1<<2)
958 #define RF_ABORT_GRACEFULLY (1<<0)
959 
960 #define RF_SCH_CMD_EXECUTION_TIME_UNKNOWN 0
961 
962 #define RF_RAT_ANY_CHANNEL (-1)
963 #define RF_RAT_TICKS_PER_US 4
964 
965 #define RF_LODIVIDER_MASK 0x7F
966 
967 
970 #define RF_convertUsToRatTicks(microseconds) \
971  ((microseconds) * (RF_RAT_TICKS_PER_US))
972 
976 #define RF_convertMsToRatTicks(milliseconds) \
977  ((milliseconds) * 1000 * (RF_RAT_TICKS_PER_US))
978 
982 #define RF_convertRatTicksToUs(ticks) \
983  ((ticks) / (RF_RAT_TICKS_PER_US))
984 
988 #define RF_convertRatTicksToMs(ticks) \
989  ((ticks) / (1000 * (RF_RAT_TICKS_PER_US)))
990 
991 
1003 typedef struct {
1004  uint32_t rawValue:22;
1005  uint32_t __dummy:9;
1009  uint32_t paType:1;
1014 
1033 typedef struct
1034 {
1035  int8_t power;
1036 
1039 } __attribute__((packed)) RF_TxPowerTable_Entry;
1040 
1041 
1048 typedef enum {
1052 
1053 
1067 typedef rfc_radioOp_t RF_Op;
1068 
1069 
1078 typedef struct {
1079  uint8_t rfMode;
1080  void (*cpePatchFxn)(void);
1081  void (*mcePatchFxn)(void);
1082  void (*rfePatchFxn)(void);
1083 } RF_Mode;
1084 
1095 typedef enum {
1099 } RF_Priority;
1100 
1109 typedef enum {
1115  RF_StatError = 0x80,
1119 } RF_Stat;
1120 
1125 typedef uint64_t RF_EventMask;
1126 
1136 typedef union {
1137  rfc_command_t commandId;
1138  rfc_CMD_RADIO_SETUP_t common;
1140  rfc_CMD_BLE5_RADIO_SETUP_t ble5;
1141  rfc_CMD_PROP_RADIO_SETUP_t prop;
1142  rfc_CMD_PROP_RADIO_DIV_SETUP_t prop_div;
1143 
1144 #if (DeviceFamily_PARENT == DeviceFamily_PARENT_CC13X2_CC26X2)
1145  rfc_CMD_RADIO_SETUP_PA_t common_pa;
1146  rfc_CMD_BLE5_RADIO_SETUP_PA_t ble5_pa;
1147  rfc_CMD_PROP_RADIO_SETUP_PA_t prop_pa;
1148  rfc_CMD_PROP_RADIO_DIV_SETUP_PA_t prop_div_pa;
1149 #endif
1150 } RF_RadioSetup;
1151 
1180 typedef enum {
1183 
1187 } RF_ClientEvent;
1188 
1226 typedef enum {
1228 
1232 } RF_GlobalEvent;
1235 
1236 
1240 typedef uint32_t RF_ClientEventMask;
1241 
1245 typedef uint32_t RF_GlobalEventMask;
1246 
1259 typedef int16_t RF_CmdHandle;
1260 
1281 #if defined (RF_SINGLEMODE)
1282  typedef struct RF_ObjectSingleMode RF_Object;
1283 #else
1284  typedef struct RF_ObjectMultiMode RF_Object;
1285 #endif
1286 
1287 /* Definition of the RF_Object structure for single-mode applications.
1288  * It is applicable with the single-mode RF driver through the #RF_Object common type.
1289  */
1290 struct RF_ObjectSingleMode{
1292  struct {
1293  uint32_t nInactivityTimeout;
1294  RF_Mode* pRfMode;
1295  RF_RadioSetup* pRadioSetup;
1296  uint32_t nPowerUpDuration;
1297  bool bMeasurePowerUpDuration;
1298  bool bUpdateSetup;
1299  uint16_t nPowerUpDurationMargin;
1300  void* pPowerCb;
1301  void* pErrCb;
1302  } clientConfig;
1304  struct {
1305  struct {
1306  rfc_CMD_FS_t cmdFs;
1307  } mode_state;
1308  SemaphoreP_Struct semSync;
1309  RF_EventMask volatile eventSync;
1310  void* pCbSync;
1311  RF_EventMask unpendCause;
1312  bool bYielded;
1313  } state;
1314 };
1315 
1319 struct RF_ObjectMultiMode{
1321  struct {
1322  uint32_t nInactivityTimeout;
1323  RF_Mode* pRfMode;
1324  RF_RadioSetup* pRadioSetup;
1325  uint32_t nPhySwitchingDuration;
1326  uint32_t nPowerUpDuration;
1327  bool bMeasurePowerUpDuration;
1328  bool bUpdateSetup;
1329  uint16_t nPowerUpDurationMargin;
1330  void* pPowerCb;
1331  void* pErrCb;
1332  void* pClientEventCb;
1333  RF_ClientEventMask nClientEventMask;
1334  uint16_t nPhySwitchingDurationMargin;
1335  } clientConfig;
1337  struct {
1338  struct {
1339  rfc_CMD_FS_t cmdFs;
1340  } mode_state;
1341  SemaphoreP_Struct semSync;
1342  RF_EventMask volatile eventSync;
1343  void* pCbSync;
1344  RF_EventMask unpendCause;
1345  ClockP_Struct clkReqAccess;
1346  bool bYielded;
1347  } state;
1348 };
1349 
1358 
1359 
1368 typedef int8_t RF_RatHandle;
1369 
1373 typedef enum {
1380 } RF_InfoType;
1381 
1387 typedef union {
1388  RF_CmdHandle ch;
1389  uint16_t availRatCh;
1391  RF_Handle pClientList[2];
1392  uint32_t phySwitchingTimeInUs[2];
1394 } RF_InfoVal;
1395 
1399 typedef struct {
1400  RF_CmdHandle ch;
1401  RF_Handle pClient;
1402  uint32_t startTime;
1403  uint32_t endTime;
1406 
1410 typedef struct {
1413 } RF_ScheduleMap;
1414 
1440 typedef void (*RF_Callback)(RF_Handle h, RF_CmdHandle ch, RF_EventMask e);
1441 
1455 typedef void (*RF_RatCallback)(RF_Handle h, RF_RatHandle rh, RF_EventMask e, uint32_t compareCaptureTime);
1456 
1472 typedef void (*RF_ClientCallback)(RF_Handle h, RF_ClientEvent event, void* arg);
1473 
1487 typedef void (*RF_GlobalCallback)(RF_Handle h, RF_GlobalEvent event, void* arg);
1488 
1497 typedef struct {
1499 
1501  uint32_t nPowerUpDuration;
1502 
1506 
1509 
1511 
1516 
1518 
1520  RF_ClientEventMask nClientEventMask;
1521 } RF_Params;
1523 
1524 /* RF command. */
1525 typedef struct RF_Cmd_s RF_Cmd;
1526 
1527 /* RF command . */
1528 struct RF_Cmd_s {
1529  List_Elem _elem; /* Pointer to next and previous elements. */
1530  RF_Callback volatile pCb; /* Pointer to callback function */
1531  RF_Op* pOp; /* Pointer to (chain of) RF operations(s) */
1532  RF_Object* pClient; /* Pointer to client */
1533  RF_EventMask bmEvent; /* Enable mask for interrupts from the command */
1534  RF_EventMask pastifg; /* Accumulated value of events happened within a command chain */
1535  RF_EventMask rfifg; /* Return value for callback 0:31 - RF_CPE0_INT, 32:63 - RF_HW_INT */
1536  uint32_t startTime; /* Command start time (in RAT ticks) */
1537  uint32_t endTime; /* Command end time (in RAT ticks) */
1538  uint32_t allowDelay; /* Delay allowed if the start time cannot be met. */
1539  RF_CmdHandle ch; /* Command handle */
1540  RF_Priority ePri; /* Priority of RF command */
1541  uint8_t volatile flags; /* [0: Aborted, 1: Stopped, 2: canceled] */
1542 };
1543 
1549 typedef struct {
1550  uint8_t hwiPriority;
1551  uint8_t swiPriority;
1554  RF_GlobalEventMask globalEventMask;
1556 
1561 typedef enum
1562 {
1566 } RF_Conflict;
1567 
1570 typedef enum
1571 {
1579 
1598 typedef RF_ScheduleStatus (*RF_SubmitHook)(RF_Cmd* pCmdNew, RF_Cmd* pCmdBg, RF_Cmd* pCmdFg, List_List* pPendQueue, List_List* pDoneQueue);
1599 
1612 typedef RF_Conflict (*RF_ConflictHook)(RF_Cmd* pCmdBg, RF_Cmd* pCmdFg, List_List* pPendQueue, List_List* pDoneQueue);
1613 
1619 typedef struct {
1623 
1627 typedef enum {
1629  RF_AllowDelayAny = UINT32_MAX
1630 } RF_AllowDelay;
1631 
1632 /* @brief RF schedule command parameter struct
1633  *
1634  * RF schedule command parameters are used with the RF_scheduleCmd() call.
1635  */
1636 typedef struct {
1637  uint32_t endTime;
1639  uint32_t allowDelay;
1644 
1649 typedef struct {
1650  uint32_t duration;
1651  uint32_t startTime;
1653 } RF_AccessParams;
1654 
1661 typedef enum {
1667 
1673 typedef enum {
1683 
1689 typedef enum {
1695 
1702 typedef enum {
1706 
1721 typedef enum {
1729 
1739 typedef enum {
1748 
1753 typedef struct {
1755  RF_RatHandle channel;
1760 
1765 typedef struct {
1767  RF_RatHandle channel;
1768  uint32_t timeout;
1771 
1776 typedef struct {
1780 
1813 extern RF_Handle RF_open(RF_Object *pObj, RF_Mode *pRfMode, RF_RadioSetup *pRadioSetup, RF_Params *params);
1814 
1825 extern void RF_close(RF_Handle h);
1826 
1837 extern uint32_t RF_getCurrentTime(void);
1838 
1893 extern RF_CmdHandle RF_postCmd(RF_Handle h, RF_Op *pOp, RF_Priority ePri, RF_Callback pCb, RF_EventMask bmEvent);
1894 
1905 extern RF_ScheduleStatus RF_defaultSubmitPolicy(RF_Cmd* pCmdNew, RF_Cmd* pCmdBg, RF_Cmd* pCmdFg, List_List* pPendQueue, List_List* pDoneQueue);
1906 
1916 extern RF_Conflict RF_defaultConflictPolicy(RF_Cmd* pCmdBg, RF_Cmd* pCmdFg, List_List* pPendQueue, List_List* pDoneQueue);
1917 
1918 
1927 extern void RF_ScheduleCmdParams_init(RF_ScheduleCmdParams *pSchParams);
1928 
1955 extern RF_CmdHandle RF_scheduleCmd(RF_Handle h, RF_Op *pOp, RF_ScheduleCmdParams *pSchParams, RF_Callback pCb, RF_EventMask bmEvent);
1956 
2016 extern RF_EventMask RF_pendCmd(RF_Handle h, RF_CmdHandle ch, RF_EventMask bmEvent);
2017 
2045 extern RF_EventMask RF_runCmd(RF_Handle h, RF_Op *pOp, RF_Priority ePri, RF_Callback pCb, RF_EventMask bmEvent);
2046 
2066 extern RF_EventMask RF_runScheduleCmd(RF_Handle h, RF_Op *pOp, RF_ScheduleCmdParams *pSchParams, RF_Callback pCb, RF_EventMask bmEvent);
2067 
2087 extern RF_Stat RF_cancelCmd(RF_Handle h, RF_CmdHandle ch, uint8_t mode);
2088 
2107 extern RF_Stat RF_flushCmd(RF_Handle h, RF_CmdHandle ch, uint8_t mode);
2108 
2122 extern RF_Stat RF_runImmediateCmd(RF_Handle h, uint32_t *pCmdStruct);
2123 
2137 extern RF_Stat RF_runDirectCmd(RF_Handle h, uint32_t cmd);
2138 
2153 extern void RF_yield(RF_Handle h);
2154 
2165 extern void RF_Params_init(RF_Params *params);
2166 
2177 extern RF_Stat RF_getInfo(RF_Handle h, RF_InfoType type, RF_InfoVal *pValue);
2178 
2187 extern int8_t RF_getRssi(RF_Handle h);
2188 
2198 extern RF_Op* RF_getCmdOp(RF_Handle h, RF_CmdHandle cmdHnd);
2199 
2208 extern void RF_RatConfigCompare_init(RF_RatConfigCompare* channelConfig);
2209 
2218 extern void RF_RatConfigCapture_init(RF_RatConfigCapture* channelConfig);
2219 
2228 extern void RF_RatConfigOutput_init(RF_RatConfigOutput* ioConfig);
2229 
2271 extern RF_RatHandle RF_ratCompare(RF_Handle rfHandle, RF_RatConfigCompare* channelConfig, RF_RatConfigOutput* ioConfig);
2272 
2312 extern RF_RatHandle RF_ratCapture(RF_Handle rfHandle, RF_RatConfigCapture* channelConfig, RF_RatConfigOutput* ioConfig);
2313 
2331 extern RF_Stat RF_ratDisableChannel(RF_Handle rfHandle, RF_RatHandle ratHandle);
2332 
2343 extern RF_Stat RF_control(RF_Handle h, int8_t ctrl, void *args);
2344 
2363 extern RF_Stat RF_requestAccess(RF_Handle h, RF_AccessParams *pParams);
2364 
2384 extern RF_TxPowerTable_Value RF_getTxPower(RF_Handle h);
2385 
2405 extern RF_Stat RF_setTxPower(RF_Handle h, RF_TxPowerTable_Value value);
2406 
2426 
2452 
2453 
2454 #ifdef __cplusplus
2455 }
2456 #endif
2457 
2458 #endif /* ti_drivers_rf__include */
RF Hardware attributes.
Definition: RF.h:1549
uint32_t allowDelay
Definition: RF.h:1639
RF_RatCaptureMode captureMode
Configuration of the mode of event to cause a capture event.
Definition: RF.h:1757
Definition: RF.h:1577
RF_CmdHandle ch
Command handle (RF_GET_CURR_CMD).
Definition: RF.h:1388
Command not executed because RF core is powered down.
Definition: RF.h:1111
Definition: RF.h:1576
RF_ScheduleStatus RF_defaultSubmitPolicy(RF_Cmd *pCmdNew, RF_Cmd *pCmdBg, RF_Cmd *pCmdFg, List_List *pPendQueue, List_List *pDoneQueue)
Sorts and adds commands to the RF driver internal command queue.
void(* RF_ClientCallback)(RF_Handle h, RF_ClientEvent event, void *arg)
Handles events related to a driver instance.
Definition: RF.h:1472
RF driver configuration parameters.
Definition: RF.h:1497
rfc_CMD_RADIO_SETUP_PA_t common_pa
Radio setup command for BLE and IEEE modes with High Gain PA.
Definition: RF.h:1145
uint32_t startTime
Start time window in RAT Time for radio access.
Definition: RF.h:1651
RF_Callback volatile pCb
Definition: RF.h:1530
RF_RatCallback callback
Callback function to be invoked upon a capture event (optional).
Definition: RF.h:1766
Use RAT user channel 2.
Definition: RF.h:1665
This file contains snippets to be used in the TI Driver s documentation *******************************************************************************The Display driver is designed abstract to operations &considerations specific to a given output method *******************************************************************************< TABLE >< TR align="center">< TH > Display Driver Interface</TH >< TH > Implementations</TH ></TR >< TR align="center">< TD > ref Display h</TD >< TD > ref DisplayHost h n ref DisplayUart h</TD ></TR ></TABLE > *******************************************************************************< TABLE >< TR align="center">< TH > Display Driver Interface</TH >< TH > Implementations</TH ></TR >< TR align="center">< TD > ref Display h</TD >< TD > ref DisplayDogm1286 h n ref DisplayHost h n ref DisplayExt h n ref DisplayUart h</TD ></TR ></TABLE > *******************************************************************************The NoRTOS framework module is provided to enable use of drivers without an underlying operating system The module provides interfaces used by drivers to perform block register interrupts and more NoRTOS module documentation and usage can be a ref driver_function_table function table
Definition: doxygen_drivers.txt:74
RF_InfoType
Selects the entry of interest in RF_getInfo().
Definition: RF.h:1373
RF_Stat RF_setTxPower(RF_Handle h, RF_TxPowerTable_Value value)
Updates the transmit power configuration of the RF core.
uint16_t nPowerUpDurationMargin
Definition: RF.h:1510
Configure RAT_CHANNEL[x] to interface with RAT_GPO[1].
Definition: RF.h:1740
The RF core has been powered up the radio setup has been finished.
Definition: RF.h:1181
RF_ClientEvent
Client-related RF driver events.
Definition: RF.h:1180
Definition: List.h:131
RF_Stat
Status codes for various RF driver functions.
Definition: RF.h:1109
rfc_CMD_PROP_RADIO_SETUP_PA_t prop_pa
Radio setup command for PROPRIETARY mode on 2.4 GHz with High Gain PA.
Definition: RF.h:1147
uint8_t rfMode
Specifies which PHY modes should be activated. Must be set to RF_MODE_MULTIPLE for dual-mode operatio...
Definition: RF.h:1079
RF_Priority priority
Intra client priority.
Definition: RF.h:1638
void(* RF_Callback)(RF_Handle h, RF_CmdHandle ch, RF_EventMask e)
Handles events related to RF command execution.
Definition: RF.h:1440
RF_EventMask RF_pendCmd(RF_Handle h, RF_CmdHandle ch, RF_EventMask bmEvent)
Synchronizes the calling task to an RF operation command ch and returns accumulated event flags...
Configure RAT_CHANNEL[x] to interface with RAT_GPO[7].
Definition: RF.h:1746
RF_ClientEventMask nClientEventMask
Definition: RF.h:1520
Selects the RTC update signal source.
Definition: RF.h:1674
RF_RatCaptureSource
Selects the source signal for RF_ratCapture().
Definition: RF.h:1673
RF schedule map entry structure.
Definition: RF.h:1399
RF_CmdHandle RF_postCmd(RF_Handle h, RF_Op *pOp, RF_Priority ePri, RF_Callback pCb, RF_EventMask bmEvent)
Appends RF operation commands to the driver&#39;s command queue and returns a command handle...
Command finished with success.
Definition: RF.h:1116
RF_EventMask RF_runScheduleCmd(RF_Handle h, RF_Op *pOp, RF_ScheduleCmdParams *pSchParams, RF_Callback pCb, RF_EventMask bmEvent)
Runs synchronously a (chain of) RF operation(s) for dual or single-mode.
Configure RAT_CHANNEL[x] to interface with RAT_GPO[2].
Definition: RF.h:1741
uint32_t allowDelay
Definition: RF.h:1538
Command not executed because RF driver is busy.
Definition: RF.h:1110
Highest priority. Only use this for urgent commands.
Definition: RF.h:1096
RF_EventMask rfifg
Definition: RF.h:1535
Definition: RF.h:1528
RF_Stat RF_runImmediateCmd(RF_Handle h, uint32_t *pCmdStruct)
Send any Immediate command.
High-power PA.
Definition: RF.h:1050
Definition: RF.h:1676
void RF_RatConfigCompare_init(RF_RatConfigCompare *channelConfig)
Initialize the configuration structure to be used to set up a RAT compare event.
RF_RatHandle channel
RF_RatHandle identifies the channel to be allocated.
Definition: RF.h:1755
Sets the output high independently of any RAT events.
Definition: RF.h:1727
uint64_t RF_EventMask
Data type for events during command execution.
Definition: RF.h:1125
uint32_t RF_ClientEventMask
Event mask for combining RF_ClientEvent event flags in RF_Params::nClientEventMask.
Definition: RF.h:1240
uint32_t nPowerUpDuration
Definition: RF.h:1501
Command successfully scheduled for execution.
Definition: RF.h:1117
uint8_t swiPriority
Priority for SWIs belong to the RF driver.
Definition: RF.h:1551
Provide the client to client switching times.
Definition: RF.h:1379
RF_TxPowerTable_Value RF_getTxPower(RF_Handle h)
Returns the currently configured transmit power configuration.
void RF_close(RF_Handle h)
Close client connection to RF driver.
Use RAT user channel 0.
Definition: RF.h:1663
Definition: RF.h:1573
Definition: RF.h:1182
Cmd is found in the pool but was already ended.
Definition: RF.h:1114
RF_RatOutputMode
Selects the mode of the RAT_GPO[x] for RF_ratCompare() or RF_ratCapture().
Definition: RF.h:1721
uint8_t volatile flags
Definition: RF.h:1541
rfc_CMD_PROP_RADIO_DIV_SETUP_t prop_div
Radio setup command for PROPRIETARY mode on Sub-1 Ghz.
Definition: RF.h:1142
List_Elem _elem
Definition: RF.h:1529
Use RAT user channel 1.
Definition: RF.h:1664
uint32_t RF_getCurrentTime(void)
Return current radio timer value.
Signals the client that the RF driver is about to switch over from another client.
Definition: RF.h:1186
RF_GlobalEventMask globalEventMask
Event mask which the globalCallback is invoked upon.
Definition: RF.h:1554
Selects the Generic event of Event Fabric as source.
Definition: RF.h:1675
Stores output parameters for RF_getInfo().
Definition: RF.h:1387
RF_Object * RF_Handle
A handle that is returned by to RF_open().
Definition: RF.h:1357
uint32_t RF_GlobalEventMask
Event mask for combining RF_GlobalEvent event flags in RFCC26XX_HWAttrsV2::globalEventMask.
Definition: RF.h:1245
void(* RF_GlobalCallback)(RF_Handle h, RF_GlobalEvent event, void *arg)
Handles global events as part of PHY configuration.
Definition: RF.h:1487
RF_Handle pClient
Pointer to client object.
Definition: RF.h:1401
RF_CmdHandle ch
Definition: RF.h:1539
RF_Priority ePri
Definition: RF.h:1540
Provide the client list.
Definition: RF.h:1378
void(* RF_RatCallback)(RF_Handle h, RF_RatHandle rh, RF_EventMask e, uint32_t compareCaptureTime)
Handles events related to the Radio Timer (RAT).
Definition: RF.h:1455
#define RF_NUM_SCHEDULE_ACCESS_ENTRIES
Number of access request entries.
Definition: RF.h:951
RAT related IO parameter structure.
Definition: RF.h:1776
RF_CmdHandle ch
Command handle.
Definition: RF.h:1400
RF_EventMask RF_runCmd(RF_Handle h, RF_Op *pOp, RF_Priority ePri, RF_Callback pCb, RF_EventMask bmEvent)
Runs synchronously an RF operation command or a chain of commands and returns the termination reason...
int8_t RF_TxPowerTable_findPowerLevel(RF_TxPowerTable_Entry table[], RF_TxPowerTable_Value value)
Retrieves a power level in dBm for a given power configuration value.
Configure RAT_CHANNEL[x] to interface with RAT_GPO[3].
Definition: RF.h:1742
RF_Priority priority
Priority of the command or access request.
Definition: RF.h:1404
rfc_radioOp_t RF_Op
Base type for all radio operation commands.
Definition: RF.h:1067
Definition: RF.h:1692
Default priority. Use this in single-client applications.
Definition: RF.h:1098
RF_ratCapture parameter structure.
Definition: RF.h:1753
int8_t RF_getRssi(RF_Handle h)
Get RSSI value.
bool bRadioState
Current RF core power state (RF_GET_RADIO_STATE).
Definition: RF.h:1390
RF_RatOutputSelect select
The signal which shall be connected to the GPO.
Definition: RF.h:1778
Definition: RF.h:1563
uint32_t endTime
Definition: RF.h:1537
Definition: List.h:126
uint32_t duration
Radio access duration in RAT Ticks requested by the client.
Definition: RF.h:1650
Definition: RF.h:1564
Definition: RF.h:1575
RF_RatCaptureSource source
Configuration of the event source to cause a capture event.
Definition: RF.h:1756
Definition: RF.h:1628
void RF_yield(RF_Handle h)
Signal that radio client is not going to issue more commands in a while.
RF_RatCaptureRepetition repeat
Configuration of the channel to be used in single or repeated mode.
Definition: RF.h:1758
void RF_RatConfigOutput_init(RF_RatConfigOutput *ioConfig)
Initialize the configuration structure to be used to set up a RAT IO.
#define RF_NUM_SCHEDULE_COMMAND_ENTRIES
Number of scheduled command entries.
Definition: RF.h:952
uint32_t startTime
Start time (in RAT tick) of the command or access request.
Definition: RF.h:1402
uint32_t endTime
End time in RAT Ticks for the radio command.
Definition: RF.h:1637
Rearm the channel after each capture events.
Definition: RF.h:1704
RF_GlobalCallback globalCallback
Pointer to a callback function serving client independent events listed in RF_GlobalEvent.
Definition: RF.h:1553
Definition: RF.h:1629
Definition: RF.h:1679
Create a bitmask showing available RAT channels.
Definition: RF.h:1375
RF_Stat RF_flushCmd(RF_Handle h, RF_CmdHandle ch, uint8_t mode)
Abort/stop/cancel command and any subsequent commands in command queue.
RF_Stat RF_cancelCmd(RF_Handle h, RF_CmdHandle ch, uint8_t mode)
Abort/stop/cancel single command in command queue.
Definition: RF.h:1636
Configure RAT_CHANNEL[x] to interface with RAT_GPO[4].
Definition: RF.h:1743
RF_Callback pPowerCb
Definition: RF.h:1505
RF_RatCaptureMode
Selects the mode of RF_ratCapture().
Definition: RF.h:1689
int16_t RF_CmdHandle
Command handle that is returned by RF_postCmd().
Definition: RF.h:1259
RF_ClientCallback pClientEventCb
Definition: RF.h:1517
Definition: RF.h:1572
Definition: RF.h:1565
Definition: RF.h:1574
RF_ScheduleStatus
Describes the location within the pend queue where the new command was inserted by the scheduler...
Definition: RF.h:1570
uint16_t availRatCh
Available RAT channels (RF_GET_AVAIL_RAT_CH).
Definition: RF.h:1389
RF_TxPowerTable_PAType
Selects a power amplifier path in a TX power value.
Definition: RF.h:1048
Configure RAT_CHANNEL[x] to interface with RAT_GPO[6].
Definition: RF.h:1745
rfc_CMD_BLE5_RADIO_SETUP_PA_t ble5_pa
Radio setup command for BLE5 mode with High Gain PA.
Definition: RF.h:1146
uint32_t timeout
Definition: RF.h:1768
RF_RatOutputSelect
Selects GPO to be used with RF_ratCompare() or RF_ratCapture().
Definition: RF.h:1739
RF_Op * RF_getCmdOp(RF_Handle h, RF_CmdHandle cmdHnd)
Get command structure pointer.
uint32_t startTime
Definition: RF.h:1536
General error specifier.
Definition: RF.h:1115
RF_Conflict RF_defaultConflictPolicy(RF_Cmd *pCmdBg, RF_Cmd *pCmdFg, List_List *pPendQueue, List_List *pDoneQueue)
Makes a final decision when a conflict in run-time is identified.
uint32_t endTime
End time (in RAT tick) of the command or access request.
Definition: RF.h:1403
int8_t power
Definition: RF.h:1035
RF_ScheduleStatus(* RF_SubmitHook)(RF_Cmd *pCmdNew, RF_Cmd *pCmdBg, RF_Cmd *pCmdFg, List_List *pPendQueue, List_List *pDoneQueue)
Handles the queue sorting algorithm when a new command is submitted to the driver from any of the act...
Definition: RF.h:1598
Free the channel after the first capture event.
Definition: RF.h:1703
Rising edge of the selected source will trigger a capture event.
Definition: RF.h:1690
int8_t RF_RatHandle
RAT handle that is returned by RF_ratCompare() or RF_ratCapture().
Definition: RF.h:1368
RF_RatHandle RF_ratCapture(RF_Handle rfHandle, RF_RatConfigCapture *channelConfig, RF_RatConfigOutput *ioConfig)
Setup a Radio Timer (RAT) channel in capture mode.
RF request access parameter struct.
Definition: RF.h:1649
RF_Stat RF_getInfo(RF_Handle h, RF_InfoType type, RF_InfoVal *pValue)
Get value for some RF driver parameters.
Command finished with an error.
Definition: RF.h:1112
Provide a timetable of all scheduled commands.
Definition: RF.h:1377
RF_Conflict
Controls the behavior of the state machine of the RF driver when a conflict is identified run-time be...
Definition: RF.h:1561
RF_Priority
Scheduling priority of RF operation commands.
Definition: RF.h:1095
RF_RatOutputMode mode
The mode the GPO should operate in.
Definition: RF.h:1777
Function was called with an invalid parameter.
Definition: RF.h:1113
RF_AllowDelay
Controls the behavior of the RF_scheduleCmd() API.
Definition: RF.h:1627
TX power configuration entry in a TX power table.
Definition: RF.h:1033
High priority. Use this for time-critical commands in synchronous protocols.
Definition: RF.h:1097
void RF_RatConfigCapture_init(RF_RatConfigCapture *channelConfig)
Initialize the configuration structure to be used to set up a RAT capture event.
A unified type for radio setup commands of different PHYs.
Definition: RF.h:1136
RF_RatHandle RF_ratCompare(RF_Handle rfHandle, RF_RatConfigCompare *channelConfig, RF_RatConfigOutput *ioConfig)
Setup a Radio Timer (RAT) channel in compare mode.
RF_TxPowerTable_Value value
PA hardware configuration for that power level.
Definition: RF.h:1038
RF_Op * pOp
Definition: RF.h:1531
uint32_t nInactivityTimeout
Definition: RF.h:1498
RF schedule map structure.
Definition: RF.h:1410
RF_ratCompare parameter structure.
Definition: RF.h:1765
RF_EventMask pastifg
Definition: RF.h:1534
RF_TxPowerTable_Value RF_TxPowerTable_findValue(RF_TxPowerTable_Entry table[], int8_t powerLevel)
Retrieves a power configuration value for a given power level in dBm.
Generates a one-clock period width pulse.
Definition: RF.h:1722
RF_SubmitHook submitHook
Function hook implements the scheduling policy to be executed at the time of RF_scheduleCmd API call...
Definition: RF.h:1620
RF_RatSelectChannel
Select the preferred RAT channel through the configuration of RF_ratCompare() or RF_ratCapture().
Definition: RF.h:1661
rfc_CMD_PROP_RADIO_DIV_SETUP_PA_t prop_div_pa
Radio setup command for PROPRIETARY mode on Sub-1 Ghz with High Gain PA.
Definition: RF.h:1148
Sets the output high on a RAT event.
Definition: RF.h:1723
Falling edge of the selected source will trigger a capture event.
Definition: RF.h:1691
Inverts the polarity of the output.
Definition: RF.h:1725
Chose the first available channel.
Definition: RF.h:1662
RF_RatHandle channel
RF_RatHandle identifies the channel to be allocated.
Definition: RF.h:1767
bool xoscHfAlwaysNeeded
Indicate that the XOSC HF should be turned on by the power driver.
Definition: RF.h:1552
RF_Stat RF_requestAccess(RF_Handle h, RF_AccessParams *pParams)
Request radio access.
RF_ConflictHook conflictHook
Function hook implements the runtime conflict resolution, if any identified at the start time of next...
Definition: RF.h:1621
RF_Stat RF_runDirectCmd(RF_Handle h, uint32_t cmd)
Send any Direct command.
void RF_ScheduleCmdParams_init(RF_ScheduleCmdParams *pSchParams)
Initialize the configuration structure to default values to be used with the RF_scheduleCmd() API...
Definition: RF.h:1231
RF_Stat RF_ratDisableChannel(RF_Handle rfHandle, RF_RatHandle ratHandle)
Disable a RAT channel.
RF scheduler policy.
Definition: RF.h:1619
Definition: RF.h:1227
Retrieve a command handle of the current command.
Definition: RF.h:1374
Specifies a RF core firmware configuration.
Definition: RF.h:1078
RF_Object * pClient
Definition: RF.h:1532
rfc_command_t commandId
Definition: RF.h:1137
RF_Handle RF_open(RF_Object *pObj, RF_Mode *pRfMode, RF_RadioSetup *pRadioSetup, RF_Params *params)
Creates a a new client instance of the RF driver.
RF_RatCaptureRepetition
Selects the repetition of RF_ratCapture().
Definition: RF.h:1702
rfc_CMD_PROP_RADIO_SETUP_t prop
Radio setup command for PROPRIETARY mode on 2.4 GHz.
Definition: RF.h:1141
rfc_CMD_BLE5_RADIO_SETUP_t ble5
Radio setup command for BLE5 mode.
Definition: RF.h:1140
PA configuration value for a certain power level.
Definition: RF.h:1003
RF_RatCallback callback
Callback function to be invoked upon a capture event (optional).
Definition: RF.h:1754
Configure RAT_CHANNEL[x] to interface with RAT_GPO[5].
Definition: RF.h:1744
Function finished with success.
Definition: RF.h:1118
RF_Callback pErrCb
Definition: RF.h:1508
Sets the output low on a RAT event.
Definition: RF.h:1724
RF_CmdHandle RF_scheduleCmd(RF_Handle h, RF_Op *pOp, RF_ScheduleCmdParams *pSchParams, RF_Callback pCb, RF_EventMask bmEvent)
Schedule an RF operation (chain) to the command queue.
Sets the output low independently of any RAT events.
Definition: RF.h:1726
RF_GlobalEvent
Global RF driver events.
Definition: RF.h:1226
RF_Stat RF_control(RF_Handle h, int8_t ctrl, void *args)
Set RF control parameters.
uint8_t hwiPriority
Priority for HWIs belong to the RF driver.
Definition: RF.h:1550
uint16_t nPhySwitchingDurationMargin
An additional safety margin to be used to calculate when conflicts shall be evaluated run-time...
Definition: RF.h:1515
void RF_Params_init(RF_Params *params)
Function to initialize the RF_Params struct to its defaults.
RF_EventMask bmEvent
Definition: RF.h:1533
Stores the client&#39;s internal configuration and states.
Linked List interface for use in drivers.
Show the current RF core power state. 0: Radio OFF, 1: Radio ON.
Definition: RF.h:1376
RF_Priority priority
Access priority.
Definition: RF.h:1652
void * pScheduleMap
Pointer to scheduling map (RF_GET_SCHEDULE_MAP).
Definition: RF.h:1393
RF_Conflict(* RF_ConflictHook)(RF_Cmd *pCmdBg, RF_Cmd *pCmdFg, List_List *pPendQueue, List_List *pDoneQueue)
Defines the conflict resolution in runtime.
Definition: RF.h:1612
Default PA.
Definition: RF.h:1049
© Copyright 1995-2021, Texas Instruments Incorporated. All rights reserved.
Trademarks | Privacy policy | Terms of use | Terms of sale