rflib
Data Structures | Macros | Typedefs | Enumerations | Functions
RFCC26X2.h File Reference

Detailed Description

Radio Frequency (RF) Core Driver for the CC13X2 and CC26X2 device family.

To use the RF driver, ensure that the correct driver library for your device is linked in and include the top-level header file as follows:

#include <ti/drivers/rf/RF.h>

Overview

The RF driver provides access to the radio core on the CC13x2/CC26x2 device family. It offers a high-level interface for command execution and to the radio timer (RAT). The RF driver ensures the lowest possible power consumption by providing automatic power management that is fully transparent for the application.

Note
This document describes the features and usage of the RF driver API. For a detailed explanation of the RF core, please refer to the Technical Reference Manual or the Proprietary RF User Guide.

Key features are:

Setup and configuration

The RF driver can be configured at 4 different places:

  1. In the build configuration by choosing either the single-client or multi-client driver version.
  2. At compile-time by setting hardware and software interrupt priorities in the board support file.
  3. During run-time initialization by setting RF_Params when calling RF_open().
  4. At run-time via RF_control().

Build configuration

The RF driver comes in two versions: single-client and multi-client. The single-client version allows only one driver instance to access the RF core at a time. The multi-client driver version allows concurrent access to the RF core with different RF settings. The multi-client driver has a slightly larger footprint and is not needed for many proprietary applications. The driver version can be selected in the build configuration by linking against a RFCC26X2_multiMode pre-built library. The multi-client driver is the default configuration in the SimpleLink SDKs.

Board configuration

The RF driver handles RF core hardware interrupts and uses software interrupts for its internal state machine. For managing the interrupt priorities, it expects the existence of a global RFCC26XX_HWAttrsV2 object. This object is configured in SysConfig and defined in the generated file ti_drivers_config.c. By default, the priorities are set to the lowest possible value:

const RFCC26XX_HWAttrsV2 RFCC26XX_hwAttrs = {
.hwiPriority = INT_PRI_LEVEL7, // Lowest HWI priority: INT_PRI_LEVEL7
// Highest HWI priority: INT_PRI_LEVEL1
.swiPriority = 0, // Lowest SWI priority: 0
// Highest SWI priority: Swi.numPriorities - 1
.xoscHfAlwaysNeeded = true // Power driver always starts XOSC-HF: true
// RF driver will request XOSC-HF if needed: false
};

Initialization

When initiating an RF driver instance, the function RF_open() accepts a pointer to a RF_Params object which might set several driver parameters. In addition, it expects an RF_Mode object and a setup command which is usually generated by SmartRF Studio:

RF_Params rfParams;
RF_Params_init(&rfParams);
rfParams.nInactivityTimeout = 2000;
RF_Handle rfHandle = RF_open(&rfObject, &RF_prop,
(RF_RadioSetup*)&RF_cmdPropRadioDivSetup, &rfParams);

The function RF_open() returns a driver handle that is used for accessing the correct driver instance. Please note that the first RF operation command before an RX or TX operation command must be a CMD_FS to set the synthesizer frequency. The RF driver caches both, the pointer to the setup command and the physical CMD_FS for automatic power management.

Run-time configuration

While a driver instance is opened, it can be re-configured with the function RF_control(). Various configuration parameters RF_CTRL are available. Example:

uint32_t timeoutUs = 2000;
RF_control(rfHandle, RF_CTRL_SET_INACTIVITY_TIMEOUT, &timeoutUs);

Command execution

The RF core supports 3 different kinds of commands:

  1. Direct commands
  2. Immediate commands
  3. Radio operation commands

Direct and immediate commands are dispatched via RF_runDirectCmd() and RF_runImmediateCmd() respectively. These functions block until the command has completed and return a status code of the type RF_Stat when done.

#include <ti/devices/${DEVICE_FAMILY}/driverlib/rf_common_cmd.h>
RF_Stat status = RF_runDirectCmd(rfHandle, CMD_ABORT);
assert(status == RF_StatCmdDoneSuccess);

Radio operation commands are potentially long-running commands and support different triggers as well as conditional execution. Only one command can be executed at a time, but the RF driver provides an internal queue that stores commands until the RF core is free. Two interfaces are provided for radio operation commands:

  1. Asynchronous: RF_postCmd() and RF_pendCmd()
  2. Synchronous: RF_runCmd()

The asynchronous function RF_postCmd() posts a radio operation into the driver's internal command queue and returns a command handle of the type RF_CmdHandle which is an index in the command queue. The command is dispatched as soon as the RF core has completed any previous radio operation command.

#include <ti/devices/${DEVICE_FAMILY}/driverlib/rf_common_cmd.h>
RF_Callback callback = NULL;
RF_EventMask subscribedEvents = 0;
RF_CmdHandle rxCommandHandle = RF_postCmd(rfHandle, (RF_Op*)&RF_cmdRx,
RF_PriorityNormal, callback, subscribedEvents);
assert(rxCommandHandle != RF_ALLOC_ERROR); // The command queue is full.

Command execution happens in background. The calling task may proceed with other work or execute direct and immediate commands to interact with the posted radio operation. But beware that the posted command might not have started, yet. By calling the function RF_pendCmd() and subscribing events of the type RF_EventMask, it is possible to re-synchronize to a posted command:

// RF_EventRxEntryDone must have been subscribed in RF_postCmd().
RF_EventMask events = RF_pendCmd(rfHandle, rxCommandHandle,
RF_EventRxEntryDone);
// Program proceeds after RF_EventRxEntryDone or after a termination event.

The function RF_runCmd() is a combination of both, RF_postCmd() and RF_pendCmd() and allows synchronous execution.

A pending or already running command might be aborted at any time by calling the function RF_cancelCmd() or RF_flushCmd(). These functions take command handles as parameters, but can also just abort anything in the RF driver's queue:

uint8_t abortGraceful = 1;
// Abort a single command
RF_cancelCmd(rfHandle, rxCommandHandle, abortGraceful);
// Abort anything
RF_flushCmd(rfHandle, RF_CMDHANDLE_FLUSH_ALL, abortGraceful);

When aborting a command, the return value of RF_runCmd() or RF_pendCmd() will contain the termination reason in form of event flags. If the command is in the RF driver queue, but has not yet start, the RF_EventCmdCancelled event is raised.

Event callbacks

The RF core generates multiple interrupts during command execution. The RF driver maps these interrupts 1:1 to callback events of the type RF_EventMask. Hence, it is unnecessary to implement own interrupt handlers. Callback events are divided into 3 groups:

See also
RF_Core_Events, RF_Driver_Events.

How callback events are subscribed was shown in the previous section. The following snippet shows a typical event handler callback for a proprietary RX operation:

void rxCallback(RF_Handle handle, RF_CmdHandle command, RF_EventMask events)
{
if (events & RF_EventRxEntryDone)
{
Semaphore_post(rxPacketSemaphore);
}
if (events & RF_EventLastCmdDone)
{
// ...
}
}

In addition, the RF driver can generate error and power-up events that do not relate directly to the execution of a radio command. Such events can be subscribed by specifying the callback function pointers RF_Params::pErrCb and RF_Params::pPowerCb.

All callback functions run in software interrupt (SWI) context. Therefore, only a minimum amount of code should be executed. When using absolute timed commands with tight timing constraints, then it is recommended to set the RF driver SWIs to a high priority. See Setup and configuration for more details.

Power management

The RF core is a hardware peripheral and can be switched on and off. The RF driver handles that automatically and provides the following power optimization features:

Lazy power-up and radio setup caching

The RF core optimizes the power consumption by enabling the RF core as late as possible. For instance does RF_open() not power up the RF core immediately. Instead, it waits until the first radio operation command is dispatched by RF_postCmd() or RF_runCmd().

The function RF_open() takes a radio setup command as parameter and expects a CMD_FS command to follow. The pointer to the radio setup command and the whole CMD_FS command are cached internally in the RF driver. They will be used for every proceeding power-up procedure. Whenever the client re-runs a setup command, the driver updates its internal cache with the new settings. RF driver also caches the first CMD_FS from the list of done commands. Please refer RF_postCmd() for limitations of command chains.

By default, the RF driver measures the time that it needs for the power-up procedure and uses that as an estimate for the next power cycle. On the CC13x0/CC26x0 devices, power-up takes usually 1.6 ms. Automatic measurement can be suppressed by specifying a custom power-up time with RF_Params::nPowerUpDuration. In addition, the client might set RF_Params::nPowerUpDurationMargin to cover any uncertainty when doing automatic measurements. This is necessary in applications with a high hardware interrupt load which can delay the RF driver's internal state machine execution.

Power-down on inactivity

Whenever a radio operation completes and there is no other radio operation in the queue, the RF core might be powered down. There are two options in the RF driver:

During the power-down procedure the RF driver stops the radio timer and saves a synchronization timestamp for the next power-up. This keeps the radio timer virtually in sync with the RTC even though it is not running all the time. The synchronization is done in hardware.

Deferred dispatching of commands with absolute timing

When dispatching a radio operation command with an absolute start trigger that is ahead in the future, the RF driver defers the execution and powers the RF core down until the command is due. It does that only, when:

  1. cmd.startTrigger.triggerType is set to TRIG_ABSTIME
  2. The difference between RF_getCurrentTime() and cmd.startTime is at not more than 3/4 of a full RAT cycle. Otherwise the driver assumes that cmd.startTime is in the past.
  3. There is enough time to run a full power cycle before cmd.startTime is due. That includes:

If one of the conditions are not fulfilled, the RF core is kept up and running and the command is dispatched immediately. This ensures, that the command will execute on-time and not miss the configured start trigger.

Preemptive scheduling of RF commands in multi-client applications

Schedule BLE and proprietary radio commands.

RF_Object rfObject_ble;
RF_Object rfObject_prop;
RF_Handle rfHandle_ble, rfHandle_prop;
RF_Params rfParams_ble, rfParams_prop;
RF_ScheduleCmdParams schParams_ble, schParams_prop;
RF_Mode rfMode_ble =
{
.rfMode = RF_MODE_MULTIPLE, // rfMode for dual mode
.cpePatchFxn = &rf_patch_cpe_ble,
.mcePatchFxn = 0,
.rfePatchFxn = &rf_patch_rfe_ble,
};
RF_Mode rfMode_prop =
{
.rfMode = RF_MODE_MULTIPLE, // rfMode for dual mode
.cpePatchFxn = &rf_patch_cpe_genfsk,
.mcePatchFxn = 0,
.rfePatchFxn = 0,
};
// Init RF and specify non-default parameters
RF_Params_init(&rfParams_ble);
rfParams_ble.nInactivityTimeout = 200; // 200us
RF_Params_init(&rfParams_prop);
rfParams_prop.nInactivityTimeout = 200; // 200us
// Configure RF schedule command parameters directly.
schParams_ble.priority = RF_PriorityNormal;
schParams_ble.endTime = 0;
schParams_ble.allowDelay = RF_AllowDelayAny;
// Alternatively, use the helper function to configure the default behavior
RF_ScheduleCmdParams_init(&schParams_prop);
// Open BLE and proprietary RF handles
rfHandle_ble = RF_open(rfObj_ble, &rfMode_ble, (RF_RadioSetup*)&RF_cmdRadioSetup, &rfParams_ble);
rfHandle_prop = RF_open(rfObj_prop, &rfMode_prop, (RF_RadioSetup*)&RF_cmdPropRadioDivSetup, &rfParams_prop);
// Run a proprietary Fs command
RF_runCmd(rfHandle_pro, (RF_Op*)&RF_cmdFs, RF_PriorityNormal, NULL, NULL);
// Schedule a proprietary RX command
RF_scheduleCmd(rfHandle_pro, (RF_Op*)&RF_cmdPropRx, &schParams_prop, &prop_callback, RF_EventRxOk);
// Schedule a BLE advertiser command
RF_scheduleCmd(rfHandle_ble, (RF_Op*)&RF_cmdBleAdv, &schParams_ble, &ble_callback,
(RF_EventLastCmdDone | RF_EventRxEntryDone | RF_EventTxEntryDone));

Accessing the Radio Timer (RAT)

The Radio Timer on the RF core is an independent 32 bit timer running at a tick rate of 4 ticks per microsecond. It is only physically active while the RF core is on. But because the RF driver resynchronizes the RAT to the RTC on every power-up, it appears to the application as the timer is always running. The RAT accuracy depends on the system HF clock while the RF core is active and on the LF clock while the RF core is powered down.

The current RAT time stamp can be obtained by RF_getCurrentTime():

uint32_t now = RF_getCurrentTime();

The RAT has 8 independent channels that can be set up in capture and compare mode by RF_ratCapture() and RF_ratCompare() respectively. Three of these channels are accessible by the RF driver. Each channel may be connected to physical hardware signals for input and output or may trigger a callback function.

In order to allocate a RAT channel and trigger a callback function at a certain time stamp, use RF_ratCompare():

RF_Handle rfDriver;
RF_RatConfigCompare config;
RF_RatConfigCompare_init(&config);
config.callback = &onRatTriggered;
config.channel = RF_RatChannelAny;
config.timeout = RF_getCurrentTime() + RF_convertMsToRatTicks(1701);
RF_RatHandle ratHandle = RF_ratCompare(rfDriver, &config, nullptr);
assert(ratHandle != RF_ALLOC_ERROR);
void onRatTriggered(RF_Handle h, RF_RatHandle rh, RF_EventMask e, uint32_t compareCaptureTime)
{
if (e & RF_EventError)
{
// RF driver failed to trigger the callback on time.
}
printf("RAT has triggered at %u.", compareCaptureTime);
// Trigger precisely with the same period again
config.timeout = compareCaptureTime + RF_convertMsToRatTicks(1701);
ratHandle = RF_ratCompare(rfDriver, &config, nullptr);
assert(ratHandle != RF_ALLOC_ERROR);
}

The RAT may be used to capture a time stamp on an edge of a physical pin. This can be achieved with RF_ratCapture().

#include <ti/drivers/pin/PINCC26XX.h>
// Map IO 26 to RFC_GPI0
PINCC26XX_setMux(pinHandle, IOID_26, PINCC26XX_MUX_RFC_GPI0);
RF_Handle rfDriver;
RF_RatConfigCapture config;
RF_RatConfigCapture_init(&config);
config.callback = &onSignalTriggered;
config.channel = RF_RatChannelAny;
config.source = RF_RatCaptureSourceRfcGpi0;
config.captureMode = RF_RatCaptureModeRising;
config.repeat = RF_RatCaptureRepeat;
RF_RatHandle ratHandle = RF_ratCapture(rfDriver, &config, nullptr);
assert(ratHandle != RF_ALLOC_ERROR);
void onSignalTriggered(RF_Handle h, RF_RatHandle rh, RF_EventMask e, uint32_t compareCaptureTime)
{
if (e & RF_EventError)
{
// An internal error has occurred
}
printf("Rising edge detected on IO 26 at %u.", compareCaptureTime);
}

In both cases, the RAT may generate an output signal when being triggered. The signal can be routed to a physical IO pin:

// Generate a pulse on an internal RAT output signal
RF_RatConfigOutput output;
RF_RatConfigOutput_init(&output);
output.mode = RF_RatOutputModePulse;
output.select = RF_RatOutputSelectRatGpo3;
RF_ratCompare(...);
// Map RatGpo3 to one of four intermediate doorbell signals.
// This has to be done in the override list in order to take permanent effect.
// The override list can be found in the RF settings .c file exported from
// SmartRF Studio.
// Attention: This will change the default mapping of the PA and LNA signal as well.
#include <ti/devices/[DEVICE_FAMILY]/inc/hw_rfc_dbell.h>
static uint32_t pOverrides[] =
{
HW_REG_OVERRIDE(0x1110, RFC_DBELL_SYSGPOCTL_GPOCTL2_RATGPO3),
// ...
}
// Finally, route the intermediate doorbell signal to a physical pin.
#include <ti/drivers/pin/PINCC26XX.h>
PINCC26XX_setMux(pinHandle, IOID_17, PINCC26XX_MUX_RFC_GPO2);

Programming the TX power level

The application can program a TX power level for each RF client with the function RF_setTxPower(). The new value takes immediate effect if the RF core is up and running. Otherwise, it is stored in the RF driver client configuration.

TX power may be stored in a lookup table in ascending order. This table is usually generated and exported from SmartRF Studio together with the rest of the PHY configuration. A typical power table my look as follows:

RF_TxPowerTable_Entry txPowerTable[] = {
{ .power = 11, .value = { 0x1233, RF_TxPowerTable_DefaultPA }},
{ .power = 13, .value = { 0x1234, RF_TxPowerTable_DefaultPA }},
// ...
RF_TxPowerTable_TERMINATION_ENTRY
};
Note
Some devices offer a high-power PA in addition to the default PA. A client must not mix configuration values in the same power table and must not hop from a default PA configuration to a high-power PA configuration unless it can guarantee that the RF setup command is re-executed in between.

Given this power table format, the application may program a new power level in multiple ways. It can use convenience functions to search a certain power level in the power table or may access the table index-based:

// Set a certain power level. Search a matching level.
RF_setTxPower(h, RF_TxPowerTable_findValue(txPowerTable, 17));
// Set a certain power level with a known level.
RF_setTxPower(h, txPowerTable[3].value);
// Set a certain power without using a human readable level.
RF_setTxPower(h, value);
// Set maximum power. Search the value.
RF_setTxPower(h, RF_TxPowerTable_findValue(txPowerTable, RF_TxPowerTable_MAX_DBM));
// Set minimum power without searching.
RF_setTxPower(h, txPowerTable[0].value);
// Set minimum power. Search the value.
RF_setTxPower(h, RF_TxPowerTable_findValue(txPowerTable, RF_TxPowerTable_MIN_DBM));
// Set maximum power without searching.
int32_t lastIndex = sizeof(txPowerTable) / sizeof(RF_TxPowerTable_Entry) - 2;
RF_setTxPower(h, txPowerTable[lastIndex].value);

The current configured power level for a client can be retrieved by RF_getTxPower().

// Get the current configured power level.
int8_t power = RF_TxPowerTable_findPowerLevel(txPowerTable, RF_getTxPower(h));

Temperature Compensation

The RF driver improves the accuracy of XOSC_HF by performing temperature dependent compensation. This is commonly done in the BAW/SIP devices where the compensation parameters are already available inside the package.

When temperature compensation is enabled, RF_enableHPOSCTemperatureCompensation() is called during the board initialization(in Board_init()). This function enables the RF driver to update HPOSC_OVERRIDE with the correct frequency offset according to the ambient temperature at radio setup.

// Enable RF Temperature Compensation
status = RF_enableHPOSCTemperatureCompensation(void)

The RF driver also subscribes to a temperature notification event that triggers for 3 degree Celsius change in temperature. At every 3 degree Celsius change in temperature, it updates the RF core with the new frequency offset and re-subscribes to the temperature notification with updated thresholds.

Warning
At the moment, temperature compensation is only supported on BAW or SIP device variants.

Error Handling

When temperature compensation is enabled, but HPOSC_OVERRIDE is not found, then RF_open() returns a NULL handle.

RF_enableHPOSCTemperatureCompensation() returns RF_StatInvalidParamsError if the temperature notification fails to register.

When the temperature notification fails to register, a global callback can be executed by subscribing to the event RF_GlobalEventTempNotifyFail defined in RF_GlobalEvent.

Note
The RF_Handle in the global callback function will belong to the current active client and this client is not causing the failure, since neither the temperature event nor the failure is client specific.

Convenience features

The RF driver simplifies often needed tasks and provides additional functions. For instance, it can read the RSSI while the RF core is in RX mode using the function :tidrivers_api:RF_getRssi:

int8_t rssi = RF_getRssi(rfHandle);
assert (rssi != RF_GET_RSSI_ERROR_VAL); // Could not read the RSSI
#include <stdint.h>
#include <stdbool.h>
#include <ti/drivers/dpl/ClockP.h>
#include <ti/drivers/dpl/SemaphoreP.h>
#include <ti/drivers/utils/List.h>
#include <ti/devices/DeviceFamily.h>
#include <ti/devices/cc13x2_26x2/ driverlib/rf_common_cmd.h>
#include <ti/devices/cc13x2_26x2/ driverlib/rf_prop_cmd.h>
#include <ti/devices/cc13x2_26x2/ driverlib/rf_ble_cmd.h>
Include dependency graph for RFCC26X2.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  RF_TxPowerTable_Value
 PA configuration value for a certain power level. More...
 
struct  RF_TxPowerTable_Entry
 TX power configuration entry in a TX power table. More...
 
struct  RF_Mode
 Specifies a RF core firmware configuration. More...
 
struct  RF_CoexOverride
 Runtime coexistence override parameters. More...
 
struct  RF_CoexOverride_BLEUseCases
 Coexistence override settings for BLE5 application scenarios. More...
 
union  RF_RadioSetup
 A unified type for radio setup commands of different PHYs. More...
 
union  RF_InfoVal
 Stores output parameters for RF_getInfo(). More...
 
struct  RF_ScheduleMapElement
 RF schedule map entry structure. More...
 
struct  RF_ScheduleMap
 RF schedule map structure. More...
 
struct  RF_Params
 RF driver configuration parameters. More...
 
struct  RF_Cmd_s
 
struct  RFCC26XX_HWAttrsV2
 RF Hardware attributes. More...
 
struct  RFCC26XX_SchedulerPolicy
 RF scheduler policy. More...
 
struct  RF_ScheduleCmdParams
 
struct  RF_AccessParams
 RF request access parameter struct. More...
 
struct  RF_RatConfigCapture
 RF_ratCapture parameter structure. More...
 
struct  RF_RatConfigCompare
 RF_ratCompare parameter structure. More...
 
struct  RF_RatConfigOutput
 RAT related IO parameter structure. More...
 

Macros

#define RF_convertUsToRatTicks(microseconds)   ((microseconds) * (RF_RAT_TICKS_PER_US))
 Converts a duration given in microseconds into radio timer (RAT) ticks. More...
 
#define RF_convertMsToRatTicks(milliseconds)   ((milliseconds) * 1000 * (RF_RAT_TICKS_PER_US))
 Converts a duration given in milliseconds into radio timer (RAT) ticks. More...
 
#define RF_convertRatTicksToUs(ticks)   ((ticks) / (RF_RAT_TICKS_PER_US))
 Converts a duration given in radio timer (RAT) ticks into microseconds. More...
 
#define RF_convertRatTicksToMs(ticks)   ((ticks) / (1000 * (RF_RAT_TICKS_PER_US)))
 Converts a duration given in radio timer (RAT) ticks into milliseconds. More...
 
RF Core Events

Events originating on the RF core and caused during command execution. They are aliases for the corresponding interrupt flags. RF Core Events are command-specific and are explained in the Technical Reference Manual.

See also
RF_postCmd(), RF_pendCmd(), RF_runCmd()
#define RF_EventCmdDone   (1 << 0)
 A radio operation command in a chain finished. More...
 
#define RF_EventLastCmdDone   (1 << 1)
 A stand-alone radio operation command or the last radio operation command in a chain finished. More...
 
#define RF_EventFGCmdDone   (1 << 2)
 A IEEE-mode radio operation command in a chain finished. More...
 
#define RF_EventLastFGCmdDone   (1 << 3)
 A stand-alone IEEE-mode radio operation command or the last command in a chain finished. More...
 
#define RF_EventTxDone   (1 << 4)
 Packet transmitted. More...
 
#define RF_EventTXAck   (1 << 5)
 ACK packet transmitted. More...
 
#define RF_EventTxCtrl   (1 << 6)
 Control packet transmitted. More...
 
#define RF_EventTxCtrlAck   (1 << 7)
 Acknowledgement received on a transmitted control packet. More...
 
#define RF_EventTxCtrlAckAck   (1 << 8)
 Acknowledgement received on a transmitted control packet, and acknowledgement transmitted for that packet. More...
 
#define RF_EventTxRetrans   (1 << 9)
 Packet retransmitted. More...
 
#define RF_EventTxEntryDone   (1 << 10)
 Tx queue data entry state changed to Finished. More...
 
#define RF_EventTxBufferChange   (1 << 11)
 A buffer change is complete. More...
 
#define RF_EventPaChanged   (1 << 14)
 The PA was reconfigured on the fly. More...
 
#define RF_EventSamplesEntryDone   (1 << 15)
 CTE data has been copied, only valid if autocopy feature is enabled. More...
 
#define RF_EventRxOk   (1 << 16)
 Packet received with CRC OK, payload, and not to be ignored. More...
 
#define RF_EventRxNOk   (1 << 17)
 Packet received with CRC error. More...
 
#define RF_EventRxIgnored   (1 << 18)
 Packet received with CRC OK, but to be ignored. More...
 
#define RF_EventRxEmpty   (1 << 19)
 Packet received with CRC OK, not to be ignored, no payload. More...
 
#define RF_EventRxCtrl   (1 << 20)
 Control packet received with CRC OK, not to be ignored. More...
 
#define RF_EventRxCtrlAck   (1 << 21)
 Control packet received with CRC OK, not to be ignored, then ACK sent. More...
 
#define RF_EventRxBufFull   (1 << 22)
 Packet received that did not fit in the Rx queue. More...
 
#define RF_EventRxEntryDone   (1 << 23)
 Rx queue data entry changing state to Finished. More...
 
#define RF_EventDataWritten   (1 << 24)
 Data written to partial read Rx buffer. More...
 
#define RF_EventNDataWritten   (1 << 25)
 Specified number of bytes written to partial read Rx buffer. More...
 
#define RF_EventRxAborted   (1 << 26)
 Packet reception stopped before packet was done. More...
 
#define RF_EventRxCollisionDetected   (1 << 27)
 A collision was indicated during packet reception. More...
 
#define RF_EventModulesUnlocked   (1 << 29)
 As part of the boot process, the CM0 has opened access to RF core modules and memories. More...
 
#define RF_EventInternalError   (uint32_t)(1 << 31)
 Internal error observed. More...
 
#define RF_EventMdmSoft   0x0000002000000000
 Synchronization word detected (MDMSOFT interrupt flag) More...
 
RF Driver Events

Event flags generated by the RF Driver.

#define RF_EventCmdCancelled   0x1000000000000000
 Command canceled before it was started. More...
 
#define RF_EventCmdAborted   0x2000000000000000
 Abrupt command termination caused by RF_cancelCmd() or RF_flushCmd(). More...
 
#define RF_EventCmdStopped   0x4000000000000000
 Graceful command termination caused by RF_cancelCmd() or RF_flushCmd(). More...
 
#define RF_EventRatCh   0x0800000000000000
 A user-programmable RAT channel triggered an event. More...
 
#define RF_EventPowerUp   0x0400000000000000
 RF power up event. More...
 
#define RF_EventError   0x0200000000000000
 Event flag used for error callback functions to indicate an error. See RF_Params::pErrCb. More...
 
#define RF_EventCmdPreempted   0x0100000000000000
 Command preempted by another command with higher priority. Applies only to multi-client applications. More...
 
Control codes for driver configuration

Control codes are used in RF_control().

#define RF_CTRL_SET_INACTIVITY_TIMEOUT   0
 Control code used by RF_control to set inactivity timeout. More...
 
#define RF_CTRL_UPDATE_SETUP_CMD   1
 Control code used by RF_control to update setup command. More...
 
#define RF_CTRL_SET_POWERUP_DURATION_MARGIN   2
 Control code used by RF_control to set powerup duration margin. More...
 
#define RF_CTRL_SET_PHYSWITCHING_DURATION_MARGIN   3
 Control code used by RF_control to set the phy switching margin. More...
 
#define RF_CTRL_SET_RAT_RTC_ERR_TOL_VAL   4
 Control code used by RF_control to set max error tolerance for RAT/RTC. More...
 
#define RF_CTRL_SET_POWER_MGMT   5
 Control code used by RF_control to set power management. More...
 
#define RF_CTRL_SET_HWI_PRIORITY   6
 Control code used by RF_control to set the hardware interrupt priority level of the RF driver. More...
 
#define RF_CTRL_SET_SWI_PRIORITY   7
 Control code used by RF_control to set the software interrupt priority level of the RF driver. More...
 
#define RF_CTRL_SET_AVAILABLE_RAT_CHANNELS_MASK   8
 Control code used by RF_control to mask the available RAT channels manually. More...
 
#define RF_CTRL_COEX_CONTROL   9
 Control code used by RF_control to enable or disable the coexistence feature at runtime. More...
 
TX Power Table defines
#define RF_TxPowerTable_MIN_DBM   -128
 
#define RF_TxPowerTable_MAX_DBM   126
 
#define RF_TxPowerTable_INVALID_DBM   127
 
#define RF_TxPowerTable_INVALID_VALUE   0x3fffff
 
#define RF_TxPowerTable_TERMINATION_ENTRY   { .power = RF_TxPowerTable_INVALID_DBM, .value = { .rawValue = RF_TxPowerTable_INVALID_VALUE, .paType = RF_TxPowerTable_DefaultPA } }
 
#define RF_TxPowerTable_DEFAULT_PA_ENTRY(bias, gain, boost, coefficient)   { .rawValue = ((bias) << 0) | ((gain) << 6) | ((boost) << 8) | ((coefficient) << 9), .paType = RF_TxPowerTable_DefaultPA }
 
#define RF_TxPowerTable_HIGH_PA_ENTRY(bias, ibboost, boost, coefficient, ldotrim)   { .rawValue = ((bias) << 0) | ((ibboost) << 6) | ((boost) << 8) | ((coefficient) << 9) | ((ldotrim) << 16), .paType = RF_TxPowerTable_HighPA }
 
Other defines
#define RF_GET_RSSI_ERROR_VAL   (-128)
 Error return value for RF_getRssi() More...
 
#define RF_CMDHANDLE_FLUSH_ALL   (-1)
 RF command handle to flush all RF commands. More...
 
#define RF_ALLOC_ERROR   (-2)
 RF command or RAT channel allocation error. More...
 
#define RF_SCHEDULE_CMD_ERROR   (-3)
 RF command schedule error. More...
 
#define RF_ERROR_RAT_PROG   (-255)
 A rat channel could not be programmed. More...
 
#define RF_ERROR_INVALID_RFMODE   (-256)
 Invalid RF_Mode. Used in error callback. More...
 
#define RF_ERROR_CMDFS_SYNTH_PROG   (-257)
 Synthesizer error with CMD_FS. Used in error callback. If this error occurred in error callback, user needs to resend CMD_FS to recover. See the device's errata for more details. More...
 
#define RF_NUM_SCHEDULE_ACCESS_ENTRIES   2
 Number of access request entries. More...
 
#define RF_NUM_SCHEDULE_COMMAND_ENTRIES   8
 Number of scheduled command entries. More...
 
#define RF_NUM_SCHEDULE_MAP_ENTRIES   (RF_NUM_SCHEDULE_ACCESS_ENTRIES + RF_NUM_SCHEDULE_COMMAND_ENTRIES)
 Number of schedule map entries. This is the sum of access request and scheduled command entries. More...
 
#define RF_SCH_MAP_CURRENT_CMD_OFFSET   RF_NUM_SCHEDULE_ACCESS_ENTRIES
 Offset of the current command entry in the schedule map. More...
 
#define RF_SCH_MAP_PENDING_CMD_OFFSET   (RF_SCH_MAP_CURRENT_CMD_OFFSET + 2)
 Offset of the first pending command entry in the schedule map. More...
 
#define RF_ABORT_PREEMPTION   (1<<2)
 Used with RF_cancelCmd() to provoke subscription to RadioFreeCallback. More...
 
#define RF_ABORT_GRACEFULLY   (1<<0)
 Used with RF_cancelCmd() for graceful command termination. More...
 
#define RF_SCH_CMD_EXECUTION_TIME_UNKNOWN   0
 For unknown execution time for RF scheduler. More...
 
#define RF_RAT_ANY_CHANNEL   (-1)
 To be used within the channel configuration structure. Allocate any of the available channels. More...
 
#define RF_RAT_TICKS_PER_US   4
 Radio timer (RAT) ticks per microsecond. More...
 
#define RF_LODIVIDER_MASK   0x7F
 Mask to be used to determine the effective value of the setup command's loDivider field. More...
 
Stack ID defines

Reserved values to identify which stack owns an RF_Handle h (stored as h->clientConfig.nID)

#define RF_STACK_ID_DEFAULT   0x00000000
 No value is set. More...
 
#define RF_STACK_ID_154   0x8000F154
 ID for TI 15.4 Stack. More...
 
#define RF_STACK_ID_BLE   0x8000FB1E
 ID for TI BLE Stack. More...
 
#define RF_STACK_ID_EASYLINK   0x8000FEA2
 ID for TI EasyLink Stack. More...
 
#define RF_STACK_ID_THREAD   0x8000FEAD
 ID for TI Thread Stack. More...
 
#define RF_STACK_ID_TOF   0x8000F00F
 ID for TI TOF Stack. More...
 
#define RF_STACK_ID_CUSTOM   0x0000FC00
 ID for Custom Stack. More...
 

Typedefs

typedef rfc_radioOp_t RF_Op
 Base type for all radio operation commands. More...
 
typedef uint64_t RF_EventMask
 Data type for events during command execution. More...
 
typedef uint32_t RF_ClientEventMask
 Event mask for combining RF_ClientEvent event flags in RF_Params::nClientEventMask. More...
 
typedef uint32_t RF_GlobalEventMask
 Event mask for combining RF_GlobalEvent event flags in RFCC26XX_HWAttrsV2::globalEventMask. More...
 
typedef int16_t RF_CmdHandle
 Command handle that is returned by RF_postCmd(). More...
 
typedef RF_Object * RF_Handle
 A handle that is returned by to RF_open(). More...
 
typedef int8_t RF_RatHandle
 RAT handle that is returned by RF_ratCompare() or RF_ratCapture(). More...
 
typedef void(* RF_Callback) (RF_Handle h, RF_CmdHandle ch, RF_EventMask e)
 Handles events related to RF command execution. More...
 
typedef void(* RF_RatCallback) (RF_Handle h, RF_RatHandle rh, RF_EventMask e, uint32_t compareCaptureTime)
 Handles events related to the Radio Timer (RAT). More...
 
typedef void(* RF_ClientCallback) (RF_Handle h, RF_ClientEvent event, void *arg)
 Handles events related to a driver instance. More...
 
typedef void(* RF_GlobalCallback) (RF_Handle h, RF_GlobalEvent event, void *arg)
 Handles global events as part of PHY configuration. More...
 
typedef struct RF_Cmd_s RF_Cmd
 
typedef 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 active clients. More...
 
typedef RF_ExecuteAction(* RF_ExecuteHook) (RF_Cmd *pCmdBg, RF_Cmd *pCmdFg, List_List *pPendQueue, List_List *pDoneQueue, bool bConflict, RF_Cmd *conflictCmd)
 Defines the execution and conflict resolution hook at runtime. More...
 

Enumerations

enum  RF_TxPowerTable_PAType { RF_TxPowerTable_DefaultPA = 0, RF_TxPowerTable_HighPA = 1 }
 Selects a power amplifier path in a TX power value. More...
 
enum  RF_Priority { RF_PriorityHighest = 2, RF_PriorityHigh = 1, RF_PriorityNormal = 0 }
 Scheduling priority of RF operation commands. More...
 
enum  RF_PriorityCoex { RF_PriorityCoexDefault = 0, RF_PriorityCoexLow = 1, RF_PriorityCoexHigh = 2 }
 Priority level for coexistence priority signal. More...
 
enum  RF_RequestCoex { RF_RequestCoexDefault = 0, RF_RequestCoexAssertRx = 1, RF_RequestCoexNoAssertRx = 2 }
 Behavior for coexistence request signal. More...
 
enum  RF_Stat {
  RF_StatBusyError, RF_StatRadioInactiveError, RF_StatCmdDoneError, RF_StatInvalidParamsError,
  RF_StatCmdEnded, RF_StatError = 0x80, RF_StatCmdDoneSuccess, RF_StatCmdSch,
  RF_StatSuccess
}
 Status codes for various RF driver functions. More...
 
enum  RF_ClientEvent { RF_ClientEventPowerUpFinished = (1 << 0), RF_ClientEventRadioFree = (1 << 1), RF_ClientEventSwitchClientEntered = (1 << 2) }
 Client-related RF driver events. More...
 
enum  RF_GlobalEvent {
  RF_GlobalEventRadioSetup = (1 << 0), RF_GlobalEventRadioPowerDown = (1 << 1), RF_GlobalEventInit = (1 << 2), RF_GlobalEventCmdStart = (1 << 3),
  RF_GlobalEventCmdStop = (1 << 4), RF_GlobalEventCoexControl = (1 << 5), RF_GlobalEventTempNotifyFail = (1 << 6)
}
 Global RF driver events. More...
 
enum  RF_InfoType {
  RF_GET_CURR_CMD, RF_GET_AVAIL_RAT_CH, RF_GET_RADIO_STATE, RF_GET_SCHEDULE_MAP,
  RF_GET_CLIENT_LIST, RF_GET_CLIENT_SWITCHING_TIME
}
 Selects the entry of interest in RF_getInfo(). More...
 
enum  RF_StartType { RF_StartNotSpecified = 0, RF_StartAbs = 1 }
 Controls the behavior of the RF_scheduleCmd() API. More...
 
enum  RF_EndType { RF_EndNotSpecified = 0, RF_EndAbs = 1, RF_EndRel = 2, RF_EndInfinit = 3 }
 Controls the behavior of the RF_scheduleCmd() API. More...
 
enum  RF_ExecuteAction { RF_ExecuteActionNone = 0, RF_ExecuteActionRejectIncoming = 1, RF_ExecuteActionAbortOngoing = 2 }
 Controls the behavior of the state machine of the RF driver when a conflict is identified run-time between the commands waiting on the pend queue and the commands being actively executed by the radio. More...
 
enum  RF_ScheduleStatus {
  RF_ScheduleStatusError = -3, RF_ScheduleStatusNone = 0, RF_ScheduleStatusTop = 1, RF_ScheduleStatusMiddle = 2,
  RF_ScheduleStatusTail = 4, RF_ScheduleStatusPreempt = 8
}
 Describes the location within the pend queue where the new command was inserted by the scheduler. More...
 
enum  RF_AllowDelay { RF_AllowDelayNone = 0, RF_AllowDelayAny = UINT32_MAX }
 Controls the behavior of the RF_scheduleCmd() API. More...
 
enum  RF_RatSelectChannel { RF_RatChannelAny = -1, RF_RatChannel0 = 0, RF_RatChannel1 = 1, RF_RatChannel2 = 2 }
 Select the preferred RAT channel through the configuration of RF_ratCompare() or RF_ratCapture(). More...
 
enum  RF_RatCaptureSource { RF_RatCaptureSourceRtcUpdate = 20, RF_RatCaptureSourceEventGeneric = 21, RF_RatCaptureSourceRfcGpi0 = 22, RF_RatCaptureSourceRfcGpi1 = 23 }
 Selects the source signal for RF_ratCapture(). More...
 
enum  RF_RatCaptureMode { RF_RatCaptureModeRising = 0, RF_RatCaptureModeFalling = 1, RF_RatCaptureModeBoth = 2 }
 Selects the mode of RF_ratCapture(). More...
 
enum  RF_RatCaptureRepetition { RF_RatCaptureSingle = 0, RF_RatCaptureRepeat = 1 }
 Selects the repetition of RF_ratCapture(). More...
 
enum  RF_RatOutputMode {
  RF_RatOutputModePulse = 0, RF_RatOutputModeSet = 1, RF_RatOutputModeClear = 2, RF_RatOutputModeToggle = 3,
  RF_RatOutputModeAlwaysZero = 4, RF_RatOutputModeAlwaysOne = 5
}
 Selects the mode of the RAT_GPO[x] for RF_ratCompare() or RF_ratCapture(). More...
 
enum  RF_RatOutputSelect {
  RF_RatOutputSelectRatGpo1 = 1, RF_RatOutputSelectRatGpo2 = 2, RF_RatOutputSelectRatGpo3 = 3, RF_RatOutputSelectRatGpo4 = 4,
  RF_RatOutputSelectRatGpo5 = 5, RF_RatOutputSelectRatGpo6 = 6, RF_RatOutputSelectRatGpo7 = 7
}
 Selects GPO to be used with RF_ratCompare() or RF_ratCapture(). More...
 

Functions

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. More...
 
void RF_close (RF_Handle h)
 Close client connection to RF driver. More...
 
uint32_t RF_getCurrentTime (void)
 Return current radio timer value. More...
 
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's command queue and returns a command handle. More...
 
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. More...
 
RF_ExecuteAction RF_defaultExecutionPolicy (RF_Cmd *pCmdBg, RF_Cmd *pCmdFg, List_List *pPendQueue, List_List *pDoneQueue, bool bConflict, RF_Cmd *conflictCmd)
 Makes a final decision before dispatching a scheduled command. More...
 
void RF_ScheduleCmdParams_init (RF_ScheduleCmdParams *pSchParams)
 Initialize the configuration structure to default values to be used with the RF_scheduleCmd() API. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
RF_Stat RF_cancelCmd (RF_Handle h, RF_CmdHandle ch, uint8_t mode)
 Abort/stop/cancel single command in command queue. More...
 
RF_Stat RF_flushCmd (RF_Handle h, RF_CmdHandle ch, uint8_t mode)
 Abort/stop/cancel command and any subsequent commands in command queue. More...
 
RF_Stat RF_runImmediateCmd (RF_Handle h, uint32_t *pCmdStruct)
 Send any Immediate command.
More...
 
RF_Stat RF_runDirectCmd (RF_Handle h, uint32_t cmd)
 Send any Direct command.
More...
 
void RF_yield (RF_Handle h)
 Signal that radio client is not going to issue more commands in a while.
More...
 
void RF_Params_init (RF_Params *params)
 Function to initialize the RF_Params struct to its defaults. More...
 
RF_Stat RF_getInfo (RF_Handle h, RF_InfoType type, RF_InfoVal *pValue)
 Get value for some RF driver parameters.
More...
 
int8_t RF_getRssi (RF_Handle h)
 Get RSSI value. More...
 
RF_Op * RF_getCmdOp (RF_Handle h, RF_CmdHandle cmdHnd)
 Get command structure pointer. More...
 
void RF_RatConfigCompare_init (RF_RatConfigCompare *channelConfig)
 Initialize the configuration structure to be used to set up a RAT compare event. More...
 
void RF_RatConfigCapture_init (RF_RatConfigCapture *channelConfig)
 Initialize the configuration structure to be used to set up a RAT capture event. More...
 
void RF_RatConfigOutput_init (RF_RatConfigOutput *ioConfig)
 Initialize the configuration structure to be used to set up a RAT IO. More...
 
RF_RatHandle RF_ratCompare (RF_Handle rfHandle, RF_RatConfigCompare *channelConfig, RF_RatConfigOutput *ioConfig)
 Setup a Radio Timer (RAT) channel in compare mode. More...
 
RF_RatHandle RF_ratCapture (RF_Handle rfHandle, RF_RatConfigCapture *channelConfig, RF_RatConfigOutput *ioConfig)
 Setup a Radio Timer (RAT) channel in capture mode. More...
 
RF_Stat RF_ratDisableChannel (RF_Handle rfHandle, RF_RatHandle ratHandle)
 Disable a RAT channel. More...
 
RF_Stat RF_control (RF_Handle h, int8_t ctrl, void *args)
 Set RF control parameters. More...
 
RF_Stat RF_requestAccess (RF_Handle h, RF_AccessParams *pParams)
 Request radio access.
More...
 
RF_TxPowerTable_Value RF_getTxPower (RF_Handle h)
 Returns the currently configured transmit power configuration. More...
 
RF_Stat RF_setTxPower (RF_Handle h, RF_TxPowerTable_Value value)
 Updates the transmit power configuration of the RF core. More...
 
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. More...
 
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. More...
 
RF_Stat RF_enableHPOSCTemperatureCompensation (void)
 Enables temperature monitoring and temperature based drift compensation. More...
 
© Copyright 1995-2021, Texas Instruments Incorporated. All rights reserved.
Trademarks | Privacy policy | Terms of use | Terms of sale