Detailed Description

RF core driver for the CC13xx/CC26xx device family.

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

#include

The RF driver provides access to the radio core on the CC13xx/CC26xx 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.

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's guide. Key features are:

Synchronous execution of direct and immediate radio commands,
Synchronous and asynchronous execution of radio operation commands,
Various event hooks to interact with RF commands and the RF driver,
Automatic power management,
Preemptive scheduler for RF operations of different RF driver instances,
Convenient access to the radio timer.

Setup and configuration

The RF driver can be configured at 4 different places:

In the build configuration by chosing either the single-client or multi-client driver version.
At compile-time by setting hardware and software interrupt priorities in the board support file.
During run-time initialization by setting RF_Params when calling RF_open().
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 either against a RFCC26XX_singleMode or RFCC26XX_multiMode prebuilt library. When using the single-client driver, RF_SINGLEMODE has to be defined globally in the build configuration. 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 existance of a global RFCC26XX_HWAttrs object. This is usually defined in the board support file, for example CC1310_LAUNCHXL.c, but when developing on custom boards, it might be kept anywhere in the application. By default, the priorities are set to the lowest possible value:

const RFCC26XX_HWAttrs RFCC26XX_hwAttrs = {
    .hwiCpe0Priority = INT_PRI_LEVEL7,         // lowest
    .hwiHwPriority   = INT_PRI_LEVEL1,         // highest
    .swiCpe0Priority =  0,                     // lowest
    .swiHwPriority   =  Swi.numPriorities - 1, // highest
};

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:

Direct commands
Immediate commands
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:

Asynchronous: RF_postCmd() and RF_pendCmd()
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:

Command-specific events, documented for each radio operation command. An example is the RF_EventRxEntryDone for the CMD_PROP_RX.
Generic events, defined for all radio operations and originating on the RF core. These are for instance RF_EventCmdDone and RF_EventLastCmdDone. Both events indicate the termination of one or more RF operations.
Generic events, defined for all radio operations and originating in the RF driver, for instance RF_EventCmdCancelled.

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
Power-down on inactivity
Deferred dispatching of commands with absolute timing

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 or a CMD_FS command, the driver updates its internal cache with the new settings.

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 uncertainity 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:

Automatic power-down by setting the parameter RF_Params::nInactivityTimeout. The RF core will then start a timer after the last command in the queue has completed. The default timeout is "forever" and this feature is disabled.
Manual power-down by calling RF_yield(). The client should do this whenever it knows that no further radio operation will be executed for a couple of milliseconds.

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:

cmd.startTrigger.triggerType is set to TRIG_ABSTIME
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.
There is enough time to run a full power cycle before cmd.startTime is due. That includes:
- the power-down time (fixed value, 1 ms) if the RF core is already powered up,
- the measured power-up duration or the value specified by RF_Params::nPowerUpDuration,
- the power-up safety margin RF_Params::nPowerUpDurationMargin (the default is 282 microseconds).

If one of the conditions are not fullfilled, 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
schParams_ble.priority  = RF_PriorityNormal;
schParams_ble.endTime   = 0;
schParams_prop.priority = RF_PriorityNormal;
schParams_prop.endTime  = 0;
// 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 advertizer command
RF_scheduleCmd(rfHandle_ble, (RF_Op*)&RF_cmdBleAdv, &schParams_ble, &ble_callback,
             (RF_EventLastCmdDone | RF_EventRxEntryDone | RF_EventTxEntryDone));

Get dual mode schedule map including timing and priority information for access requests and commands.

RF_ScheduleMap rfSheduleMap;
RF_InfoVal     rfGetInfoVal;
// Get schedule map
rfGetInfoVal.pScheduleMap = &rfScheduleMap;
RF_getInfo(NULL, RF_GET_SCHEDULE_MAP, &rfGetInfoVal);
// RF_scheduleMap includes the following information:
// (RF_NUM_SCHEDULE_ACCESS_ENTRIES (default = 2)) entries of access request information
// (RF_NUM_SCHEDULE_COMMAND_ENTRIES (default = 3)) entries of radio command information
// Each entry has the type of RF_ScheduleMapElement.

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

For defining absolute triggers in radio operation commands, one often needs to know the current time. This can be achieved with the function RF_getCurrentTime(). When the RF core is not up and running and the radio timer is disabled, this function can still return a previse value:

uint32_t rfTime = RF_getCurrentTime();

#include <stdint.h>
#include <stdbool.h>
#include <ti/drivers/dpl/ClockP.h>
#include <ti/drivers/dpl/SemaphoreP.h>
#include <ti/devices/DeviceFamily.h>

Go to the source code of this file.

Data Structures
struct	RF_Mode
	Specifies a RF core firmware configuration. More...

union	RF_RadioSetup
	A unified type for radio setup commands of different PHYs. More...

struct	RFCC26XX_HWAttrs
	RF Hardware attributes. 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_ScheduleCmdParams
	RF schedule command parameter struct RF schedule command parameters are used with the RF_scheduleCmd() call. More...

struct	RF_AccessParams
	RF request access parameter struct RF request access command parameters are used with the RF_requestAccess() call. More...

Macros
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_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 cancelled before it was started. More...

#define	RF_EventCmdAborted 0x2000000000000000
	Aprubt 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...

#define	RF_EventRadioFree 0x0080000000000000
	Radio available to use. 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_RAT_RTC_ERR_TOL_VAL 3
	Control code used by RF_control to set max error tolerence for RAT/RTC. More...

#define	RF_CTRL_SET_POWER_MGMT 4
	Control code used by RF_control to set power management. More...

#define	RF_CTRL_SET_HWI_PRIORITY 5
	Control code used by RF_control to set the hardware interrupt priority level of the RF driver. More...

#define	RF_CTRL_SET_SWI_PRIORITY 6
	Control code used by RF_control to set the software interrupt priority level of the RF driver. More...

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_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 errata SWRA521. More...

#define	RF_NUM_SCHEDULE_MAP_ENTRIES 5
	Number of schedule map entries. This is the sum of access request and scheduled command entries. More...

#define	RF_NUM_SCHEDULE_ACCESS_ENTRIES 2
	Number of access request entries. More...

#define	RF_NUM_SCHEDULE_COMMAND_ENTRIES (RF_NUM_SCHEDULE_MAP_ENTRIES - RF_NUM_SCHEDULE_ACCESS_ENTRIES)
	Number of scheduled command entries. More...

#define	RF_SCH_CMD_EXECUTION_TIME_UNKNOWN 0
	For unknown execution time for RF scheduler. 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 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 void(*	RF_Callback) (RF_Handle h, RF_CmdHandle ch, RF_EventMask e)
	Handles events related to RF command execution. More...

typedef void(*	RF_ClientCallback) (RF_Handle h, RF_ClientEvent event, void *arg)
	Handles events related to a driver instance. More...

Enumerations
enum	RF_Priority { RF_PriorityHighest = 2, RF_PriorityHigh = 1, RF_PriorityNormal = 0 }
	Scheduling priority of RF operation commands. 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 = 0x00000001, RF_ClientEventRadioFree = 0x00000002, RF_ClientEventSwitchClientEntered = 0x00000004 }
	Client-related RF driver events. More...

enum	RF_InfoType { RF_GET_CURR_CMD, RF_GET_AVAIL_RAT_CH, RF_GET_RADIO_STATE, RF_GET_SCHEDULE_MAP }
	Selects the entry of interest in RF_getInfo(). More...

Functions
RF_Handle	RF_open (RF_Object pObj, RF_Mode pRfMode, RF_RadioSetup pOpSetup, 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_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...

int8_t	RF_ratCompare (RF_Handle h, rfc_CMD_SET_RAT_CMP_t *pCmdStruct, uint32_t compareTime, RF_Callback pRatCb)
	Setup RAT compare, and callback when compare matches. Note radio needs to be on for RAT to operate. If radio is off, this API returns RF_ALLOC_ERROR. More...

int8_t	RF_ratCapture (RF_Handle h, uint16_t config, RF_Callback pRatCb)
	Setup RAT capture, and callback when capture event happens. Note radio needs to be on for RAT to operate. If radio is off, this API returns RF_ALLOC_ERROR. More...

RF_Stat	RF_ratHwOutput (RF_Handle h, uint16_t config)
	Setup RAT HW output. Note radio needs to be on for RAT to operate. If radio is off, this API returns RF_ALLOC_ERROR. More...

RF_Stat	RF_ratDisableChannel (RF_Handle h, int8_t ratChannelNum)
	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...

Macro Definition Documentation

§ RF_EventCmdDone

#define RF_EventCmdDone (1<<0)

A radio operation command in a chain finished.

§ RF_EventLastCmdDone

#define RF_EventLastCmdDone (1<<1)

A stand-alone radio operation command or the last radio operation command in a chain finished.

§ RF_EventFGCmdDone

#define RF_EventFGCmdDone (1<<2)

A IEEE-mode radio operation command in a chain finished.

§ RF_EventLastFGCmdDone

#define RF_EventLastFGCmdDone (1<<3)

A stand-alone IEEE-mode radio operation command or the last command in a chain finished.

§ RF_EventTxDone

#define RF_EventTxDone (1<<4)

Packet transmitted.

§ RF_EventTXAck

#define RF_EventTXAck (1<<5)

ACK packet transmitted.

§ RF_EventTxCtrl

#define RF_EventTxCtrl (1<<6)

Control packet transmitted.

§ RF_EventTxCtrlAck

#define RF_EventTxCtrlAck (1<<7)

Acknowledgement received on a transmitted control packet.

§ RF_EventTxCtrlAckAck

#define RF_EventTxCtrlAckAck (1<<8)

Acknowledgement received on a transmitted control packet, and acknowledgement transmitted for that packet.

§ RF_EventTxRetrans

#define RF_EventTxRetrans (1<<9)

Packet retransmitted.

§ RF_EventTxEntryDone

#define RF_EventTxEntryDone (1<<10)

Tx queue data entry state changed to Finished.

§ RF_EventTxBufferChange

#define RF_EventTxBufferChange (1<<11)

A buffer change is complete.

§ RF_EventRxOk

#define RF_EventRxOk (1<<16)

Packet received with CRC OK, payload, and not to be ignored.

§ RF_EventRxNOk

#define RF_EventRxNOk (1<<17)

Packet received with CRC error.

§ RF_EventRxIgnored

#define RF_EventRxIgnored (1<<18)

Packet received with CRC OK, but to be ignored.

§ RF_EventRxEmpty

#define RF_EventRxEmpty (1<<19)

Packet received with CRC OK, not to be ignored, no payload.

§ RF_EventRxCtrl

#define RF_EventRxCtrl (1<<20)

Control packet received with CRC OK, not to be ignored.

§ RF_EventRxCtrlAck

#define RF_EventRxCtrlAck (1<<21)

Control packet received with CRC OK, not to be ignored, then ACK sent.

§ RF_EventRxBufFull

#define RF_EventRxBufFull (1<<22)

Packet received that did not fit in the Rx queue.

§ RF_EventRxEntryDone

#define RF_EventRxEntryDone (1<<23)

Rx queue data entry changing state to Finished.

§ RF_EventDataWritten

#define RF_EventDataWritten (1<<24)

Data written to partial read Rx buffer.

§ RF_EventNDataWritten

#define RF_EventNDataWritten (1<<25)

Specified number of bytes written to partial read Rx buffer.

§ RF_EventRxAborted

#define RF_EventRxAborted (1<<26)

Packet reception stopped before packet was done.

§ RF_EventRxCollisionDetected

#define RF_EventRxCollisionDetected (1<<27)

A collision was indicated during packet reception.

§ RF_EventModulesUnlocked

#define RF_EventModulesUnlocked (1<<29)

As part of the boot process, the CM0 has opened access to RF core modules and memories.

§ RF_EventInternalError

#define RF_EventInternalError (uint32_t)(1<<31)

Internal error observed.

§ RF_EventMdmSoft

#define RF_EventMdmSoft 0x0000002000000000

Synchronization word detected (MDMSOFT interrupt flag)

§ RF_EventCmdCancelled

#define RF_EventCmdCancelled 0x1000000000000000

Command cancelled before it was started.

§ RF_EventCmdAborted

#define RF_EventCmdAborted 0x2000000000000000

Aprubt command termination caused by RF_cancelCmd() or RF_flushCmd().

§ RF_EventCmdStopped

#define RF_EventCmdStopped 0x4000000000000000

Graceful command termination caused by RF_cancelCmd() or RF_flushCmd().

§ RF_EventRatCh

#define RF_EventRatCh 0x0800000000000000

A user-programmable RAT channel triggered an event.

§ RF_EventPowerUp

#define RF_EventPowerUp 0x0400000000000000

RF power up event.

Deprecated:: This event is deprecated. Use RF_ClientEventPowerUpFinished instead.

§ RF_EventError

#define RF_EventError 0x0200000000000000

Event flag used for error callback functions to indicate an error. See RF_Params::pErrCb.

§ RF_EventCmdPreempted

#define RF_EventCmdPreempted 0x0100000000000000

Command preempted by another command with higher priority. Applies only to multi-client applications.

§ RF_EventRadioFree

#define RF_EventRadioFree 0x0080000000000000

Radio available to use.

Deprecated:: Event is deprecated. Use RF_ClientEventRadioFree instead.

§ RF_CTRL_SET_INACTIVITY_TIMEOUT

#define RF_CTRL_SET_INACTIVITY_TIMEOUT 0

Control code used by RF_control to set inactivity timeout.

Setting this control allows RF to power down the radio upon completion of a radio command after a specified timeout period (in us) With this control code arg is a pointer to the timeout variable and returns RF_StatSuccess.

§ RF_CTRL_UPDATE_SETUP_CMD

#define RF_CTRL_UPDATE_SETUP_CMD 1

Control code used by RF_control to update setup command.

Setting this control notifies RF that the setup command is to be updated, so that RF will take proper actions when executing the next setup command. Note the updated setup command will take effect in the next power up cycle when RF executes the setup command. Prior to updating the setup command, user should make sure all pending commands have completed.

§ RF_CTRL_SET_POWERUP_DURATION_MARGIN

#define RF_CTRL_SET_POWERUP_DURATION_MARGIN 2

Control code used by RF_control to set powerup duration margin.

Setting this control updates the powerup duration margin. Default is RF_DEFAULT_POWER_UP_MARGIN.

§ RF_CTRL_SET_RAT_RTC_ERR_TOL_VAL

#define RF_CTRL_SET_RAT_RTC_ERR_TOL_VAL 3

Control code used by RF_control to set max error tolerence for RAT/RTC.

Setting this control updates the error tol for how frequently the CMD_RAT_SYNC_STOP is sent. Default is RF_DEFAULT_RAT_RTC_ERR_TOL_IN_US (5 us) Client is recommeneded to change this setting before sending any commands.

§ RF_CTRL_SET_POWER_MGMT

#define RF_CTRL_SET_POWER_MGMT 4

Control code used by RF_control to set power management.

Setting this control configures RF driver to enable or disable power management. By default power management is enabled. If disabled, once RF core wakes up, RF driver will not go to standby and will not power down RF core. To configure power management, use this control to pass a parameter value of 0 to disable power management, and pass a parameter value of 1 to re-enable power management. This control is valid for dual-mode code only. Setting this control when using single-mode code has no effect (power management always enabled).

§ RF_CTRL_SET_HWI_PRIORITY

#define RF_CTRL_SET_HWI_PRIORITY 5

Control code used by RF_control to set the hardware interrupt priority level of the RF driver.

This control code sets the hardware interrupt priority level that is used by the RF driver. Valid values are INT_PRI_LEVEL1 (highest) until INT_PRI_LEVEL7 (lowest). The default interrupt priority is set in the board support file. The default value is -1 which means "lowest possible priority".

When using the TI-RTOS kernel, INT_PRI_LEVEL0 is reserved for zero-latency interrupts and must not be used.

Execute this control code only while the RF core is powered down and the RF driver command queue is empty. This is usually the case after calling RF_open(). Changing the interrupt priority level while the RF driver is active will result in RF_StatBusyError being returned.

Example:

#include DeviceFamily_constructPath(driverlib/interrupt.h)
int32_t hwiPriority = INT_PRI_LEVEL5;
RF_control(rfHandle, RF_CTRL_SET_HWI_PRIORITY, &hwiPriority);

§ RF_CTRL_SET_SWI_PRIORITY

#define RF_CTRL_SET_SWI_PRIORITY 6

Control code used by RF_control to set the software interrupt priority level of the RF driver.

This control code sets the software interrupt priority level that is used by the RF driver. Valid values are integers starting at 0 (lowest) until Swi_numPriorities - 1 (highest). The default interrupt priority is set in the board support file. The default value is 0 which means means "lowest possible priority".

Execute this control code only while the RF core is powered down and the RF driver command queue is empty. This is usually the case after calling RF_open(). Changing the interrupt priority level while the RF driver is active will result in RF_StatBusyError being returned.

Example:

#include <ti/sysbios/knl/Swi.h>
// Set highest possible priority
uint32_t swiPriority = ~0;
RF_control(rfHandle, RF_CTRL_SET_SWI_PRIORITY, &swiPriority);

§ RF_GET_RSSI_ERROR_VAL

#define RF_GET_RSSI_ERROR_VAL (-128)

Error return value for RF_getRssi()

§ RF_CMDHANDLE_FLUSH_ALL

#define RF_CMDHANDLE_FLUSH_ALL (-1)

RF command handle to flush all RF commands.

§ RF_ALLOC_ERROR

#define RF_ALLOC_ERROR (-2)

RF command or RAT channel allocation error.

§ RF_SCHEDULE_CMD_ERROR

#define RF_SCHEDULE_CMD_ERROR (-3)

RF command schedule error.

§ RF_ERROR_INVALID_RFMODE

#define RF_ERROR_INVALID_RFMODE (-256)

Invalid RF_Mode. Used in error callback.

§ RF_ERROR_CMDFS_SYNTH_PROG

#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 errata SWRA521.

§ RF_NUM_SCHEDULE_MAP_ENTRIES

#define RF_NUM_SCHEDULE_MAP_ENTRIES 5

Number of schedule map entries. This is the sum of access request and scheduled command entries.

§ RF_NUM_SCHEDULE_ACCESS_ENTRIES

#define RF_NUM_SCHEDULE_ACCESS_ENTRIES 2

Number of access request entries.

§ RF_NUM_SCHEDULE_COMMAND_ENTRIES

#define RF_NUM_SCHEDULE_COMMAND_ENTRIES (RF_NUM_SCHEDULE_MAP_ENTRIES - RF_NUM_SCHEDULE_ACCESS_ENTRIES)

Number of scheduled command entries.

§ RF_SCH_CMD_EXECUTION_TIME_UNKNOWN

#define RF_SCH_CMD_EXECUTION_TIME_UNKNOWN 0

For unknown execution time for RF scheduler.

Typedef Documentation

§ RF_Op

typedef rfc_radioOp_t RF_Op

Base type for all radio operation commands.

All radio operation commands share a common part. That includes the command id, a status field, chaining properties and a start trigger. Whenever an RF operation command is used with the RF driver, it needs to be casted to an RF_Op.

More information about RF operation commands can be found in the Proprietary RF User's Guide.

See also: RF_runCmd(), RF_postCmd(), RF_pendCmd()

§ RF_EventMask

typedef uint64_t RF_EventMask

Data type for events during command execution.

Possible event flags are listed in RF_Core_Events and RF_Driver_Events.

§ RF_ClientEventMask

typedef uint32_t RF_ClientEventMask

Event mask for combining RF_ClientEvent event flags in RF_Params::nClientEventMask.

§ RF_CmdHandle

typedef int16_t RF_CmdHandle

Command handle that is returned by RF_postCmd().

A command handle is an integer number greater equals zero and identifies a command container in the RF driver's internal command queue. A client can dispatch a command with RF_postCmd() and use the command handle later on to make the RF driver interact with the command.

A negative value has either a special meaning or indicates an error.

See also: RF_pendCmd(), RF_flushCmd(), RF_cancelCmd(), RF_ALLOC_ERROR, RF_CMDHANDLE_FLUSH_ALL

§ RF_Handle

typedef RF_Object* RF_Handle

A handle that is returned by to RF_open().

RF_Handle is used for further RF client interaction with the RF driver. An invalid handle has the value NULL.

§ RF_Callback

typedef void(* RF_Callback) (RF_Handle h, RF_CmdHandle ch, RF_EventMask e)

Handles events related to RF command execution.

RF command callbacks notify the application of any events happening during RF command execution. Events may either refer to RF core interrupts (RF_Core_Events) or may be generated by the RF driver (RF_Driver_Events).

RF command callbacks are set up as parameter to RF_postCmd() or RF_runCmd() and provide:

the relevant driver client handle h which was returned by RF_open(),
the relevant radio operation command handle ch,
an event mask e containing the occured events.

RF command callbacks are executed in Software Interrupt (SWI) context and must not perform any blocking operation. The priority is configurable via RFCC26XX_HWAttrs in the board file or RF_CTRL_SET_SWI_PRIORITY in RF_control().

The RF_Callback function type is also used for signalling power events and errors. These are set in RF_Params::pPowerCb and RF_Params::pErrCb respectively. In case of a power event, ch can be ignored and e has RF_EventPowerUp set. In case of an error callback, ch contains an error code instead of a command handle and e has the RF_EventError flag set.

Note: Error and power callbacks will be replaced by RF_ClientCallback in future releases.

§ RF_ClientCallback

typedef void(* RF_ClientCallback) (RF_Handle h, RF_ClientEvent event, void *arg)

Handles events related to a driver instance.

The RF driver produces additional events that are not directly related to the execution of a certain command, but happen during general RF driver operations. This includes power-up events, client switching events and others.

A client callback provides the following arguments:

the relevant driver client handle h which was returned by RF_open(),
an event identifier event,
an optional argument arg depending on the event.

RF client callbacks are executed in Software Interrupt (SWI) context and must not perform any blocking operation. The priority is configurable via RFCC26XX_HWAttrs in the board file or RF_CTRL_SET_SWI_PRIORITY in RF_control().

Enumeration Type Documentation

§ RF_Priority

enum RF_Priority

Scheduling priority of RF operation commands.

When multiple RF driver instances are used at the same time, commands from different clients may overlap. If an RF operation with a higher priority than the currently running operation is scheduled by RF_scheduleCmd(), then the running operation is interrupted.

In single-client applications, RF_PriorityNormal should be used.

Enumerator
RF_PriorityHighest	Highest priority. Only use this for urgent commands.
RF_PriorityHigh	High priority. Use this for time-critical commands in synchronous protocols.
RF_PriorityNormal	Default priority. Use this in single-client applications.

§ RF_Stat

enum RF_Stat

Status codes for various RF driver functions.

RF_Stat is reported as return value for RF driver functions which execute direct and immediate commands. Such commands are executed by RF_runDirectCmd() and RF_runImmediateCmd() in the first place, but also by some convenience functions like RF_cancelCmd(), RF_flushCmd(), RF_getInfo() and others.

Enumerator
RF_StatBusyError	Command not executed because RF driver is busy.
RF_StatRadioInactiveError	Command not executed because RF core is powered down.
RF_StatCmdDoneError	Command finished with an error.
RF_StatInvalidParamsError	Function was called with an invalid parameter.
RF_StatCmdEnded	Cmd is found in the pool but was already ended.
RF_StatError	General error specifier.
RF_StatCmdDoneSuccess	Command finished with success.
RF_StatCmdSch	Command successfully scheduled for execution.
RF_StatSuccess	Function finished with success.

§ RF_ClientEvent

enum RF_ClientEvent

Client-related RF driver events.

Events originating in the RF driver but not directly related to a specific radio command, are called client events. Clients may subscribe to these events by specifying a callback function RF_Params::pClientEventCb. Events are activated by specifying a bitmask RF_Params::nClientEventMask. The callback is called separately for every event providing an optional argument.

void onClientEvent(RF_Handle h, RF_ClientEvent event, void* arg)
{
    switch (event)
    {
    case RF_ClientEventPowerUpFinished:
        // Set output port
        break;
    default:
        // Unsubscribed events must not be issued.
        assert(false);
    }
}
RF_Params params;
params.pClientEventCb = &onClientEvent;
params.nClientEventMask = RF_ClientEventPowerUpFinished;
RF_open(...);

Enumerator
RF_ClientEventPowerUpFinished	The RF core has been powered up the radio setup has been finished.
RF_ClientEventRadioFree	Radio becomes free after a command has been preempted by a high-priority command of another client. This event is only triggered on a client that has been preempted. Clients may use this event to retry running their low-priority RF operation.
RF_ClientEventSwitchClientEntered	Signals the client that the RF driver is about to switch over from another client.

§ RF_InfoType

enum RF_InfoType

Selects the entry of interest in RF_getInfo().

Enumerator
RF_GET_CURR_CMD	Retrieve a command handle of the current command.
RF_GET_AVAIL_RAT_CH	Create a bitmask showing available RAT channels.
RF_GET_RADIO_STATE	Show the current RF core power state. 0: Radio OFF, 1: Radio ON.
RF_GET_SCHEDULE_MAP	Provide a timetable of all scheduled commands.

Function Documentation

§ RF_open()

RF_Handle RF_open	(	RF_Object *	pObj,
		RF_Mode *	pRfMode,
		RF_RadioSetup *	pOpSetup,
		RF_Params *	params
	)

Creates a a new client instance of the RF driver.

This function initializes an RF driver client instance using pObj as storage. It does not power up the RF core. Once the client starts the first RF opweration command later in the application, the RF core is powered up and set into a PHY mode specified by pRfMode. The chosen PHY is then configured by a radio setup command pOpSetup. Whenever the RF core is powered up, the RF driver re-executes the radio setup command pOpSetup. Additional driver behaviour may be set by an optional params.

// Define parameters
RF_Params rfParams;
rfParams.nInactivityTimeout = 4;
RF_Params_init(&rfParams);
rfParams.nInactivityTimeout = 1701; // microseconds
RF_Handle rfHandle = RF_open(&rfObject, &RF_prop, (RF_RadioSetup*)&RF_cmdPropRadioDivSetup, &rfParams);

Note: Calling context : Task

Parameters

pObj	Pointer to a RF_Object that will hold the state for this RF client. The object must be in persistent and writeable memory.
pRfMode	Pointer to a RF_Mode struct holding PHY information
pOpSetup	Pointer to the radio setup command used for this client. This is re-executed by the RF Driver on each power-up.
params	Pointer to an RF_Params object with the desired driver configuration. A NULL pointer results in the default configuration being loaded.

Returns: A handle for further RF driver calls on success. Otherwise NULL.

§ RF_close()

void RF_close ( RF_Handle h )

Close client connection to RF driver.

Allows a RF client (high-level driver or application) to close its connection to the RF driver.

Note: Calling context : Task

Parameters

h	Handle previously returned by RF_open()

§ RF_getCurrentTime()

uint32_t RF_getCurrentTime ( void )

Return current radio timer value.

If the radio is powered returns the current radio timer value, if not returns a conservative estimate of the current radio timer value

Note: Calling context : Task/SWI/HWI

Returns: Current radio timer value

§ RF_postCmd()

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.

The RF operation pOp may either represent a single operation or may be the first operation in a chain. If the command queue is empty, the pCmd is dispatched immediately. If there are other operations pending, then pCmd is processed after all other commands have been finished. The RF operation command must be compatible to the RF_Mode selected by RF_open(), e.g. proprietary commands can only be used when the RF core is configured for proprietary mode.

The returned command handle is an identifier that can be used to control command execution later on, for instance with RF_pendCmd() or RF_cancelCmd(). It is a 16 Bit signed integer value, incremented on every new command. If the RF driver runs out of command containers, RF_ALLOC_ERROR is returned.

The priority ePri is only relevant in multi-client applications where commands of distinct clients may interrupt each other. Only commands started by RF_scheduleCmd() can preempt running commands. RF_postCmd() or RF_runCmd() do never interrupt a running command. In single-client applications, ePri is ignored and should be set to RF_PriorityNormal.

A callback function pCb might be specified to get notified about events during command execution. Events are subscribed by the bit mask bmEvent. Valid event flags are specified in RF_Core_Events and RF_Driver_Events. If no callback is set, RF_pendCmd() can be used to synchronize the current task to command execution. For this it is necessary to subscribe all relevant events. The termination events RF_EventLastCmdDone, RF_EventCmdCancelled, RF_EventCmdAborted and RF_EventCmdStopped are always implicitly subscribed.

The following limitations apply to the execution of command chains:

If TRIG_ABSTIME is used as a start trigger for the first command, TRIG_REL_FIRST_START can not be used for any other command. This is because the RF driver may insert a frequency-select command (CMD_FS) at the front of the chain when it performs an automatic power-up.
Having more than one CMD_FS in a chain may lead to unexpected behavior. If a chain contains a CMD_FS and the command can be reached by iterating over the pNextOp field, then RF driver will always update the cached CMD_FS with the new settings. On the next automatic power-up, the RF driver will use the updated frequency.

Note: Calling context : Task/SWI

See also: RF_pendCmd(), RF_runCmd(), RF_scheduleCmd(), RF_RF_cancelCmd(), RF_flushCmd(), RF_getCmdOp()

Parameters

h	Driver handle previously returned by RF_open()
pOp	Pointer to the RF operation command.
ePri	Priority of this RF command (used for arbitration in multi-client systems)
pCb	Callback function called during command execution and upon completion. If RF_postCmd() fails, no callback is made.
bmEvent	Bitmask of events that will trigger the callback or that can be pended on.

Returns: A handle to the RF command. Return value of RF_ALLOC_ERROR indicates error.

§ RF_scheduleCmd()

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.

Schedule an RF_Op to the RF command queue of the client with handle h.
The command can be the first in a chain of RF operations or a standalone RF operation. If a chain of operations are posted they are treated atomically, i.e. either all or none of the chained operations are run.
All operations must be posted in strictly increasing chronological order. Function returns immediately.

Limitations apply to the operations posted:

The operation must be in the set supported in the chosen radio mode when RF_open() was called
Only a subset of radio operations are supported
Only some of the trigger modes are supported with potential power saving (TRIG_NOW, TRIG_ABSTIME)

Note: Calling context : Task/SWI

Parameters

h	Handle previously returned by RF_open()
pOp	Pointer to the RF_Op. Must normally be in persistent and writeable memory
pSchParams	Pointer to the schdule command parameter structure
pCb	Callback function called upon command completion (and some other events). If RF_scheduleCmd() fails no callback is made
bmEvent	Bitmask of events that will trigger the callback.

Returns: A handle to the RF command. Return value of RF_ALLOC_ERROR indicates error.

§ RF_pendCmd()

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.

After having dispatched an RF operation represented by ch with RF_postCmd(), the command is running in parallel on the RF core. Thus, it might be desirable to synchronize the calling task to the execution of the command. With RF_pendCmd(), the application can block until one of the events specified in bmEvent occurs or until the command finishes. The function consumes and returns all accumulated event flags that occured during execution if they have been previously subscribed by RF_postCmd(). Possible events are specified in RF_Core_Events and RF_Driver_Events. The termination events RF_EventLastCmdDone, RF_EventCmdCancelled, RF_EventCmdAborted and RF_EventCmdStopped are always implicitly subscribed and can not be masked.

RF_pendCmd() may be called multiple times for the same command.

If RF_pendCmd() is called for a command handle representing a finished command, then only the RF_EventLastCmdDone flag is returned, regardless of how the command finished.

If the command has also a callback set, the callback is executed before RF_pendCmd() returns.

Example:

// Dispatch a command to the RF driver's command queue
RF_CmdHandle ch = RF_postCmd(driver, (RF_Op*)&CMD_PROP_RX, RF_PriorityNormal, NULL, RF_EventRxEntryDone);
assert(ch != RF_ALLOC_ERROR);
bool finished = false;
while (finished == false)
{
    // Synchronize to events during command execution.
    uint32_t events = RF_pendCmd(driver, ch, RF_EventRxEntryDone);
    // Check events that happen during execution
    if (events & RF_EventRxEntryDone)
    {
        // Process packet
    }
    if (events & (RF_EventLastCmdDone | RF_EventCmdStopped | RF_EventCmdAborted | RF_EventCmdCancelled))
    {
        finished = true;
    }
    // ...
}

Note: Calling context : Task

Parameters

h	Driver handle previously returned by RF_open()
ch	Command handle previously returned by RF_postCmd().
bmEvent	Bitmask of events that make RF_pendCmd() return. Termination events are always implicitly subscribed.

Returns: Event flags accumulated during command execution.

See also: RF_postCmd()

§ RF_runCmd()

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.

This function appends an RF operation command or a chain of commands to the RF driver's command queue and then waits for it to complete. A command is completed if one of the termination events RF_EventLastCmdDone, RF_EventCmdCancelled, RF_EventCmdAborted, RF_EventCmdStopped occured.

This function is a combination of RF_postCmd() and RF_pendCmd(). All options and limitations for RF_postCmd() apply here as well.

An application should always ensure that the command completed in the expected way and with an expected status code.

Note: Calling context : Task

Parameters

h	Driver handle previously returned by RF_open()
pOp	Pointer to the RF operation command.
ePri	Priority of this RF command (used for arbitration in multi-client systems)
pCb	Callback function called during command execution and upon completion. If RF_runCmd() fails, no callback is made.
bmEvent	Bitmask of events that will trigger the callback or that can be pended on.

Returns: The relevant termination event.

See also: RF_postCmd(), RF_pendCmd(), RF_cancelCmd(), RF_flushCmd()

§ RF_runScheduleCmd()

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.

Allows a (chain of) operation(s) to be scheduled to the command queue and then waits for it to complete.
A command is completed if one of the RF_EventLastCmdDone, RF_EventCmdCancelled, RF_EventCmdAborted, RF_EventCmdStopped occured.

Note: Calling context : Task; Only one call to RF_pendCmd() or RF_runScheduleCmd() can be made at a time for each client

Parameters

h	Handle previously returned by RF_open()
pOp	Pointer to the RF_Op. Must normally be in persistent and writeable memory
pSchParams	Pointer to the schdule command parameter structure
pCb	Callback function called upon command completion (and some other events). If RF_runScheduleCmd() fails, no callback is made.
bmEvent	Bitmask of events that will trigger the callback.

Returns: The relevant commmand completed event.

§ RF_cancelCmd()

RF_Stat RF_cancelCmd	(	RF_Handle	h,
		RF_CmdHandle	ch,
		uint8_t	mode
	)

Abort/stop/cancel single command in command queue.

If command is running, aborts/stops it and posts callback for the aborted/stopped command.
If command has not yet run, cancels it it and posts callback for the cancelled command.
If command has already run or been aborted/stopped/cancelled, has no effect.
If RF_cancelCmd is called from a Swi context with same or higher priority than RF Driver Swi, when the RF core is powered OFF -> the cancel callback will be delayed until the next power-up cycle.

Note: Calling context : Task/SWI

Parameters

h	Handle previously returned by RF_open()
ch	Command handle previously returned by RF_postCmd().
mode	1: Stop gracefully, 0: abort abruptly

Returns: RF_Stat indicates if command was successfully completed

§ RF_flushCmd()

RF_Stat RF_flushCmd	(	RF_Handle	h,
		RF_CmdHandle	ch,
		uint8_t	mode
	)

Abort/stop/cancel command and any subsequent commands in command queue.

If command is running, aborts/stops it and then cancels all later commands in queue.
If command has not yet run, cancels it and all later commands in queue.
If command has already run or been aborted/stopped/cancelled, has no effect.
The callbacks for all cancelled commands are issued in chronological order.
If RF_flushCmd is called from a Swi context with same or higher priority than RF Driver Swi, when the RF core is powered OFF -> the cancel callback will be delayed until the next power-up cycle.

Note: Calling context : Task/SWI

Parameters

h	Handle previously returned by RF_open()
ch	Command handle previously returned by RF_postCmd().
mode	1: Stop gracefully, 0: abort abruptly

Returns: RF_Stat indicates if command was successfully completed

§ RF_runImmediateCmd()

RF_Stat RF_runImmediateCmd	(	RF_Handle	h,
		uint32_t *	pCmdStruct
	)

Send any Immediate command.

Immediate Comamnd is send to RDBELL, if radio is active and the RF_Handle points to the current client.
In other appropriate RF_Stat values are returned.

Note: Calling context : Task/SWI/HWI

Parameters

h	Handle previously returned by RF_open()
pCmdStruct	Pointer to the immediate command structure

Returns: RF_Stat indicates if command was successfully completed

§ RF_runDirectCmd()

RF_Stat RF_runDirectCmd	(	RF_Handle	h,
		uint32_t	cmd
	)

Send any Direct command.

Direct Comamnd value is send to RDBELL immediately, if radio is active and the RF_Handle point to the current client.
In other appropriate RF_Stat values are returned.

Note: Calling context : Task/SWI/HWI

Parameters

h	Handle previously returned by RF_open()
cmd	Direct command value.

Returns: RF_Stat indicates if command was successfully completed.

§ RF_yield()

void RF_yield ( RF_Handle h )

Signal that radio client is not going to issue more commands in a while.

Hint to RF driver that, irrespective of inactivity timeout, no new further commands will be issued for a while and thus the radio can be powered down at the earliest convenience.

Note: Calling context : Task

Parameters

h	Handle previously returned by RF_open()

§ RF_Params_init()

void RF_Params_init ( RF_Params * params )

Function to initialize the RF_Params struct to its defaults.

Parameters

params An pointer to RF_Params structure for initialization

Defaults values are: nInactivityTimeout = BIOS_WAIT_FOREVER nPowerUpDuration = RF_DEFAULT_POWER_UP_TIME bPowerUpXOSC = true

§ RF_getInfo()

RF_Stat RF_getInfo	(	RF_Handle	h,
		RF_InfoType	type,
		RF_InfoVal *	pValue
	)

Get value for some RF driver parameters.

Note: Calling context : Task/SWI/HWI

Parameters

h	Handle previously returned by RF_open()
type	Request value paramter defined by RF_InfoType
pValue	Pointer to return parameter values specified by RF_InfoVal

Returns: RF_Stat indicates if command was successfully completed

§ RF_getRssi()

int8_t RF_getRssi ( RF_Handle h )

Get RSSI value.

Note: Calling context : Task/SWI/HWI

Parameters

h	Handle previously returned by RF_open()

Returns: RSSI value. Return value of RF_GET_RSSI_ERROR_VAL indicates error case.

§ RF_getCmdOp()

RF_Op* RF_getCmdOp	(	RF_Handle	h,
		RF_CmdHandle	cmdHnd
	)

Get command structure pointer.

Note: Calling context : Task/SWI/HWI

Parameters

h	Handle previously returned by RF_open()
cmdHnd	Command handle returned by RF_postCmd()

Returns: Pointer to the command structure.

§ RF_ratCompare()

int8_t RF_ratCompare	(	RF_Handle	h,
		rfc_CMD_SET_RAT_CMP_t *	pCmdStruct,
		uint32_t	compareTime,
		RF_Callback	pRatCb
	)

Setup RAT compare, and callback when compare matches. Note radio needs to be on for RAT to operate. If radio is off, this API returns RF_ALLOC_ERROR.

Note: Calling context : Task/SWI

Parameters

h	Handle previously returned by RF_open()
pCmdStruct	Pointer to the RAT compare command structure.
compareTime	Compare time in RAT ticks
pRatCb	Callback function when capture event happens

Returns: Allocated RAT channel. Returned value RF_ALLOC_ERROR indicates error.

§ RF_ratCapture()

int8_t RF_ratCapture	(	RF_Handle	h,
		uint16_t	config,
		RF_Callback	pRatCb
	)

Setup RAT capture, and callback when capture event happens. Note radio needs to be on for RAT to operate. If radio is off, this API returns RF_ALLOC_ERROR.

Note: Calling context : Task/SWI

Parameters

h	Handle previously returned by RF_open()
config	Config field of RAT capture command structure
pRatCb	Callback function when capture event happens

Returns: Allocated RAT channel. Returned value RF_ALLOC_ERROR indicates error.

§ RF_ratHwOutput()

RF_Stat RF_ratHwOutput	(	RF_Handle	h,
		uint16_t	config
	)

Setup RAT HW output. Note radio needs to be on for RAT to operate. If radio is off, this API returns RF_ALLOC_ERROR.

Note: Calling context : Task/SWI

Parameters

h	Handle previously returned by RF_open()
config	Config field of RAT HW output command structure

Returns: RF_Stat indicates if command was successfully completed

§ RF_ratDisableChannel()

RF_Stat RF_ratDisableChannel	(	RF_Handle	h,
		int8_t	ratChannelNum
	)

Disable a RAT channel.

Note: Calling context : Task/SWI

Parameters

h	Handle previously returned by RF_open()
ratChannelNum	RAT channel number to be disabled

Returns: RF_Stat indicates if command was successfully completed.

§ RF_control()

RF_Stat RF_control	(	RF_Handle	h,
		int8_t	ctrl,
		void *	args
	)

Set RF control parameters.

Note: Calling context : Task

Parameters

h	Handle previously returned by RF_open()
ctrl	Control codes
args	Pointer to control arguments

Returns: RF_Stat indicates if API call was successfully completed.

§ RF_requestAccess()

RF_Stat RF_requestAccess	(	RF_Handle	h,
		RF_AccessParams *	pParams
	)

Request radio access.

Scope:

Only suppports request access which start immediately.
The RF_AccessParams duration should be less than a pre-defined value RF_REQ_ACCESS_MAX_DUR_US in RFCC26XX_multiMode.c.
The RF_AccessParams priority should be set RF_PriorityHighest.
Single request for a client at anytime.
Command from different client are blocked untill the radio access period is completed.

Note: Calling context : Task

Parameters

h	Handle previously returned by RF_open()
pParams	Pointer to RF_AccessRequest parameters

Returns: RF_Stat indicates if API call was successfully completed.

Detailed Description

Setup and configuration

Build configuration

Board configuration

Initialization

Run-time configuration

Command execution

Event callbacks

Power management

Lazy power-up and radio setup caching

Power-down on inactivity

Deferred dispatching of commands with absolute timing

Preemptive scheduling of RF commands in multi-client applications

Convenience features

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

§ RF_EventCmdDone

§ RF_EventLastCmdDone

§ RF_EventFGCmdDone

§ RF_EventLastFGCmdDone

§ RF_EventTxDone

§ RF_EventTXAck

§ RF_EventTxCtrl

§ RF_EventTxCtrlAck

§ RF_EventTxCtrlAckAck

§ RF_EventTxRetrans

§ RF_EventTxEntryDone

§ RF_EventTxBufferChange

§ RF_EventRxOk

§ RF_EventRxNOk

§ RF_EventRxIgnored

§ RF_EventRxEmpty

§ RF_EventRxCtrl

§ RF_EventRxCtrlAck

§ RF_EventRxBufFull

§ RF_EventRxEntryDone

§ RF_EventDataWritten

§ RF_EventNDataWritten

§ RF_EventRxAborted

§ RF_EventRxCollisionDetected

§ RF_EventModulesUnlocked

§ RF_EventInternalError

§ RF_EventMdmSoft

§ RF_EventCmdCancelled

§ RF_EventCmdAborted

§ RF_EventCmdStopped

§ RF_EventRatCh

§ RF_EventPowerUp

§ RF_EventError

§ RF_EventCmdPreempted

§ RF_EventRadioFree

§ RF_CTRL_SET_INACTIVITY_TIMEOUT

§ RF_CTRL_UPDATE_SETUP_CMD

§ RF_CTRL_SET_POWERUP_DURATION_MARGIN

§ RF_CTRL_SET_RAT_RTC_ERR_TOL_VAL

§ RF_CTRL_SET_POWER_MGMT

§ RF_CTRL_SET_HWI_PRIORITY

§ RF_CTRL_SET_SWI_PRIORITY

§ RF_GET_RSSI_ERROR_VAL

§ RF_CMDHANDLE_FLUSH_ALL

§ RF_ALLOC_ERROR

§ RF_SCHEDULE_CMD_ERROR

§ RF_ERROR_INVALID_RFMODE

§ RF_ERROR_CMDFS_SYNTH_PROG

§ RF_NUM_SCHEDULE_MAP_ENTRIES

§ RF_NUM_SCHEDULE_ACCESS_ENTRIES

§ RF_NUM_SCHEDULE_COMMAND_ENTRIES

§ RF_SCH_CMD_EXECUTION_TIME_UNKNOWN

Typedef Documentation

§ RF_Op

§ RF_EventMask

§ RF_ClientEventMask

§ RF_CmdHandle

§ RF_Handle

§ RF_Callback

§ RF_ClientCallback