RFCC26X2.h

Go to the documentation of this file.

/*
 * Copyright (c) 2016-2020, Texas Instruments Incorporated
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * *  Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * *  Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * *  Neither the name of Texas Instruments Incorporated nor the names of
 *    its contributors may be used to endorse or promote products derived
 *    from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
/*!****************************************************************************
@file   RFCC26X2.h
@brief  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:

@code
#include <ti/drivers/rf/RF.h>
@endcode

<hr>
@anchor rf_overview
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
<a href='../../proprietary-rf/technical-reference-manual.html'><b>Technical
Reference Manual</b></a> or the
<a href='../../proprietary-rf/proprietary-rf-users-guide.html'><b>Proprietary
RF User Guide</b></a>.

<b>Key features are:</b>

@li @ref rf_command_execution "Synchronous execution of direct and immediate radio commands"
@li @ref rf_command_execution "Synchronous and asynchronous execution of radio operation commands"
@li Various @ref rf_event_callbacks "event hooks" to interact with RF commands and the RF driver
@li Automatic @ref rf_power_management "power management"
@li @ref rf_scheduling "Preemptive scheduler for RF operations" of different RF driver instances
@li Convenient @ref rf_rat "Access to the radio timer" (RAT)
@li @ref rf_tx_power "Programming the TX power level"

@anchor rf_setup_and_configuration
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 is
usually defined in the board support file, for example `CC2652RB_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:

@code
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
};
@endcode


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:

@code
RF_Params rfParams;
RF_Params_init(&rfParams);
rfParams.nInactivityTimeout = 2000;

RF_Handle rfHandle = RF_open(&rfObject, &RF_prop,
        (RF_RadioSetup*)&RF_cmdPropRadioDivSetup, &rfParams);
@endcode

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 @ref RF_CTRL are available.
Example:

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

<hr>
@anchor rf_command_execution
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.

@code
#include <ti/devices/${DEVICE_FAMILY}/driverlib/rf_common_cmd.h>

RF_Stat status = RF_runDirectCmd(rfHandle, CMD_ABORT);
assert(status == RF_StatCmdDoneSuccess);
@endcode

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.

@code
#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.
@endcode

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:

@code
// 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.
@endcode

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:

@code
uint8_t abortGraceful = 1;

// Abort a single command
RF_cancelCmd(rfHandle, rxCommandHandle, abortGraceful);

// Abort anything
RF_flushCmd(rfHandle, RF_CMDHANDLE_FLUSH_ALL, abortGraceful);
@endcode

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.

<hr>
@anchor rf_event_callbacks
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.

@sa @ref RF_Core_Events, @ref 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:

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

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 @ref rf_setup_and_configuration "Setup and configuration" for more details.

<hr>
@anchor rf_power_management
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 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:

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

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:

   - 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 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.

<hr>
@anchor rf_scheduling
Preemptive scheduling of RF commands in multi-client applications
=================================================================

Schedule BLE and proprietary radio commands.

@code
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));

@endcode

<hr>
@anchor rf_rat
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():

@code
uint32_t now = RF_getCurrentTime();
@endcode

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():

@code
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);
}
@endcode

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

@code
#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);
}
@endcode

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

@code
// 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);
@endcode

<hr>
@anchor rf_tx_power
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:
@code
RF_TxPowerTable_Entry txPowerTable[] = {
    { .power = 11,  .value = { 0x1233, RF_TxPowerTable_DefaultPA }},
    { .power = 13,  .value = { 0x1234, RF_TxPowerTable_DefaultPA }},
    // ...
    RF_TxPowerTable_TERMINATION_ENTRY
};
@endcode

@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:
@code
// 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);
@endcode

The current configured power level for a client can be retrieved by #RF_getTxPower().
@code
// Get the current configured power level.
int8_t power = RF_TxPowerTable_findPowerLevel(txPowerTable, RF_getTxPower(h));
@endcode

<hr>
@anchor rf_convenience_features
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`:

@code
int8_t rssi = RF_getRssi(rfHandle);
assert (rssi != RF_GET_RSSI_ERROR_VAL); // Could not read the RSSI
@endcode

<hr>
 ******************************************************************************
 */

//*****************************************************************************
//
//
//*****************************************************************************

#ifndef ti_drivers_rfcc26x2__include
#define ti_drivers_rfcc26x2__include

#ifdef __cplusplus
extern "C" {
#endif

#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 DeviceFamily_constructPath(driverlib/rf_common_cmd.h)
#include DeviceFamily_constructPath(driverlib/rf_prop_cmd.h)
#include DeviceFamily_constructPath(driverlib/rf_ble_cmd.h)

#define   RF_EventCmdDone             (1 << 0)   
#define   RF_EventLastCmdDone         (1 << 1)   
#define   RF_EventFGCmdDone           (1 << 2)   
#define   RF_EventLastFGCmdDone       (1 << 3)   
#define   RF_EventTxDone              (1 << 4)   
#define   RF_EventTXAck               (1 << 5)   
#define   RF_EventTxCtrl              (1 << 6)   
#define   RF_EventTxCtrlAck           (1 << 7)   
#define   RF_EventTxCtrlAckAck        (1 << 8)   
#define   RF_EventTxRetrans           (1 << 9)   
#define   RF_EventTxEntryDone         (1 << 10)  
#define   RF_EventTxBufferChange      (1 << 11)  
#define   RF_EventPaChanged           (1 << 14)  
#define   RF_EventSamplesEntryDone    (1 << 15)  
#define   RF_EventRxOk                (1 << 16)  
#define   RF_EventRxNOk               (1 << 17)  
#define   RF_EventRxIgnored           (1 << 18)  
#define   RF_EventRxEmpty             (1 << 19)  
#define   RF_EventRxCtrl              (1 << 20)  
#define   RF_EventRxCtrlAck           (1 << 21)  
#define   RF_EventRxBufFull           (1 << 22)  
#define   RF_EventRxEntryDone         (1 << 23)  
#define   RF_EventDataWritten         (1 << 24)  
#define   RF_EventNDataWritten        (1 << 25)  
#define   RF_EventRxAborted           (1 << 26)  
#define   RF_EventRxCollisionDetected (1 << 27)  
#define   RF_EventModulesUnlocked     (1 << 29)  
#define   RF_EventInternalError       (uint32_t)(1 << 31) 
#define   RF_EventMdmSoft             0x0000002000000000  

#define   RF_EventCmdCancelled        0x1000000000000000  
#define   RF_EventCmdAborted          0x2000000000000000  
#define   RF_EventCmdStopped          0x4000000000000000  
#define   RF_EventRatCh               0x0800000000000000  
#define   RF_EventPowerUp             0x0400000000000000  
#define   RF_EventError               0x0200000000000000  
#define   RF_EventCmdPreempted        0x0100000000000000  

#define RF_CTRL_SET_INACTIVITY_TIMEOUT            0

#define RF_CTRL_UPDATE_SETUP_CMD                  1

#define RF_CTRL_SET_POWERUP_DURATION_MARGIN       2

#define RF_CTRL_SET_PHYSWITCHING_DURATION_MARGIN  3

#define RF_CTRL_SET_RAT_RTC_ERR_TOL_VAL           4

#define RF_CTRL_SET_POWER_MGMT                    5

#define RF_CTRL_SET_HWI_PRIORITY                  6

#define RF_CTRL_SET_SWI_PRIORITY                  7

#define RF_CTRL_SET_AVAILABLE_RAT_CHANNELS_MASK   8

#define RF_CTRL_COEX_CONTROL  9

#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 }


#define RF_GET_RSSI_ERROR_VAL                   (-128)   
#define RF_CMDHANDLE_FLUSH_ALL                  (-1)     
#define RF_ALLOC_ERROR                          (-2)     
#define RF_SCHEDULE_CMD_ERROR                   (-3)     
#define RF_ERROR_RAT_PROG                       (-255)   
#define RF_ERROR_INVALID_RFMODE                 (-256)   
#define RF_ERROR_CMDFS_SYNTH_PROG               (-257)   

#define RF_NUM_SCHEDULE_ACCESS_ENTRIES          2        
#define RF_NUM_SCHEDULE_COMMAND_ENTRIES         8        
#define RF_NUM_SCHEDULE_MAP_ENTRIES             (RF_NUM_SCHEDULE_ACCESS_ENTRIES + RF_NUM_SCHEDULE_COMMAND_ENTRIES) 
#define RF_SCH_MAP_CURRENT_CMD_OFFSET           RF_NUM_SCHEDULE_ACCESS_ENTRIES      
#define RF_SCH_MAP_PENDING_CMD_OFFSET           (RF_SCH_MAP_CURRENT_CMD_OFFSET + 2) 

#define RF_ABORT_PREEMPTION                     (1<<2)   
#define RF_ABORT_GRACEFULLY                     (1<<0)   

#define RF_SCH_CMD_EXECUTION_TIME_UNKNOWN       0        

#define RF_RAT_ANY_CHANNEL                      (-1)     
#define RF_RAT_TICKS_PER_US                     4        

#define RF_LODIVIDER_MASK                       0x7F     


#define RF_STACK_ID_DEFAULT                     0x00000000  
#define RF_STACK_ID_154                         0x8000F154  
#define RF_STACK_ID_BLE                         0x8000FB1E  
#define RF_STACK_ID_EASYLINK                    0x8000FEA2  
#define RF_STACK_ID_THREAD                      0x8000FEAD  
#define RF_STACK_ID_TOF                         0x8000F00F  
#define RF_STACK_ID_CUSTOM                      0x0000FC00  

#define RF_convertUsToRatTicks(microseconds) \
    ((microseconds) * (RF_RAT_TICKS_PER_US))

#define RF_convertMsToRatTicks(milliseconds) \
    ((milliseconds) * 1000 * (RF_RAT_TICKS_PER_US))

#define RF_convertRatTicksToUs(ticks) \
    ((ticks) / (RF_RAT_TICKS_PER_US))

#define RF_convertRatTicksToMs(ticks) \
    ((ticks) / (1000 * (RF_RAT_TICKS_PER_US)))


typedef struct {
    uint32_t rawValue:22;      
    uint32_t __dummy:9;
    uint32_t paType:1;         
} RF_TxPowerTable_Value;

typedef struct
{
    int8_t power;                 

    RF_TxPowerTable_Value value;  
} __attribute__((packed)) RF_TxPowerTable_Entry;


typedef enum {
    RF_TxPowerTable_DefaultPA = 0, 
    RF_TxPowerTable_HighPA = 1,    
} RF_TxPowerTable_PAType;


typedef rfc_radioOp_t RF_Op;


typedef struct {
    uint8_t rfMode;             
    void (*cpePatchFxn)(void);  
    void (*mcePatchFxn)(void);  
    void (*rfePatchFxn)(void);  
} RF_Mode;

typedef enum {
    RF_PriorityHighest = 2, 
    RF_PriorityHigh    = 1, 
    RF_PriorityNormal  = 0, 
} RF_Priority;

typedef enum {
    RF_PriorityCoexDefault  = 0,  
    RF_PriorityCoexLow      = 1,  
    RF_PriorityCoexHigh     = 2,  
} RF_PriorityCoex;

typedef enum {
    RF_RequestCoexDefault     = 0, 
    RF_RequestCoexAssertRx    = 1, 
    RF_RequestCoexNoAssertRx  = 2, 
} RF_RequestCoex;

typedef struct {
    RF_PriorityCoex   priority;   
    RF_RequestCoex    request;    
} RF_CoexOverride;

typedef struct {
    RF_CoexOverride    bleInitiator;
    RF_CoexOverride    bleConnected;
    RF_CoexOverride    bleBroadcaster;
    RF_CoexOverride    bleObserver;
} RF_CoexOverride_BLEUseCases;

typedef enum {
    RF_StatBusyError,          
    RF_StatRadioInactiveError, 
    RF_StatCmdDoneError,       
    RF_StatInvalidParamsError, 
    RF_StatCmdEnded,           
    RF_StatError   = 0x80,     
    RF_StatCmdDoneSuccess,     
    RF_StatCmdSch,             
    RF_StatSuccess             
} RF_Stat;

typedef uint64_t RF_EventMask;

typedef union {
    rfc_command_t                      commandId;   
    rfc_CMD_RADIO_SETUP_t              common;      
    rfc_CMD_BLE5_RADIO_SETUP_t         ble5;        
    rfc_CMD_PROP_RADIO_SETUP_t         prop;        
    rfc_CMD_PROP_RADIO_DIV_SETUP_t     prop_div;    
    rfc_CMD_RADIO_SETUP_PA_t           common_pa;   
    rfc_CMD_BLE5_RADIO_SETUP_PA_t      ble5_pa;     
    rfc_CMD_PROP_RADIO_SETUP_PA_t      prop_pa;     
    rfc_CMD_PROP_RADIO_DIV_SETUP_PA_t  prop_div_pa; 
} RF_RadioSetup;

typedef enum {
    RF_ClientEventPowerUpFinished     = (1 << 0),   
    RF_ClientEventRadioFree           = (1 << 1),   

    RF_ClientEventSwitchClientEntered = (1 << 2)    
} RF_ClientEvent;

typedef enum {
    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_GlobalEvent;


typedef uint32_t RF_ClientEventMask;

typedef uint32_t RF_GlobalEventMask;

typedef int16_t RF_CmdHandle;

typedef struct RF_ObjectMultiMode RF_Object;

struct RF_ObjectMultiMode{
    struct {
        uint32_t            nInactivityTimeout;          
        RF_Mode*            pRfMode;                     
        RF_RadioSetup*      pRadioSetup;                 
        uint32_t            nPhySwitchingDuration;       
        uint32_t            nPowerUpDuration;            
        bool                bMeasurePowerUpDuration;     
        bool                bUpdateSetup;                
        uint16_t            nPowerUpDurationMargin;      
        void*               pPowerCb;                    
        void*               pErrCb;                      
        void*               pClientEventCb;              
        RF_ClientEventMask  nClientEventMask;            
        uint16_t            nPhySwitchingDurationMargin; 
        uint32_t            nID;                         
    } clientConfig;
    struct {
        struct {
            rfc_CMD_FS_t        cmdFs;              
        } mode_state;                               
        SemaphoreP_Struct       semSync;            
        RF_EventMask volatile   eventSync;          
        void*                   pCbSync;            
        RF_EventMask            unpendCause;        
        ClockP_Struct           clkReqAccess;       
        bool                    bYielded;           
    } state;
};

typedef RF_Object* RF_Handle;


typedef int8_t RF_RatHandle;

typedef enum {
    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,                 
} RF_InfoType;

typedef union {
    RF_CmdHandle ch;                              
    uint16_t     availRatCh;                      
    bool         bRadioState;                     
    RF_Handle    pClientList[2];                  
    uint32_t     phySwitchingTimeInUs[2];         
    void         *pScheduleMap;                   
} RF_InfoVal;

typedef struct {
    RF_CmdHandle ch;                               
    RF_Handle    pClient;                          
    uint32_t     startTime;                        
    uint32_t     endTime;                          
    RF_Priority  priority;                         
} RF_ScheduleMapElement;

typedef struct {
    RF_ScheduleMapElement  accessMap[RF_NUM_SCHEDULE_ACCESS_ENTRIES];    
    RF_ScheduleMapElement  commandMap[RF_NUM_SCHEDULE_COMMAND_ENTRIES];  
} RF_ScheduleMap;

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

typedef void (*RF_RatCallback)(RF_Handle h, RF_RatHandle rh, RF_EventMask e, uint32_t compareCaptureTime);

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

typedef void (*RF_GlobalCallback)(RF_Handle h, RF_GlobalEvent event, void* arg);

typedef struct {
    uint32_t            nInactivityTimeout;      

    uint32_t            nPowerUpDuration;        

    RF_Callback         pPowerCb;                

    RF_Callback         pErrCb;                  

    uint16_t            nPowerUpDurationMargin;  

    uint16_t            nPhySwitchingDurationMargin; 

    RF_ClientCallback   pClientEventCb;          

    RF_ClientEventMask  nClientEventMask;        

    uint32_t            nID;                     
} RF_Params;

typedef enum {
    RF_StartNotSpecified = 0,
    RF_StartAbs          = 1,
} RF_StartType;

typedef enum {
    RF_EndNotSpecified = 0,
    RF_EndAbs          = 1,
    RF_EndRel          = 2,
    RF_EndInfinit      = 3,
 } RF_EndType;

/* RF command. */
typedef struct RF_Cmd_s RF_Cmd;

/* RF command . */
struct RF_Cmd_s {
    List_Elem            _elem;       /* Pointer to next and previous elements. */
    RF_Callback volatile pCb;         /* Pointer to callback function */
    RF_Op*               pOp;         /* Pointer to (chain of) RF operations(s) */
    RF_Object*           pClient;     /* Pointer to client */
    RF_EventMask         bmEvent;     /* Enable mask for interrupts from the command */
    RF_EventMask         pastifg;     /* Accumulated value of events happened within a command chain */
    RF_EventMask         rfifg;       /* Return value for callback 0:31 - RF_CPE0_INT, 32:63 - RF_HW_INT */
    RF_CmdHandle         ch;          /* Command handle */
    RF_Priority          ePri;        /* Priority of RF command */
    uint8_t volatile     flags;       /* [0: Aborted, 1: Stopped, 2: canceled] */
    uint32_t             startTime;   /* Command start time (in RAT ticks) */
    RF_StartType         startType;   /* Command start time type */
    uint32_t             allowDelay;  /* Delay allowed if the start time cannot be met. */
    uint32_t             endTime;     /* Command end time (in RAT ticks) */
    RF_EndType           endType;     /* Command end type */
    uint32_t             duration;    /* Command duration (in RAT ticks) */
    uint32_t             activityInfo; /* General value supported by user */
    RF_PriorityCoex      coexPriority; /* Command priority to use for coexistence request. */
    RF_RequestCoex       coexRequest; /* Command REQUEST line behavior to use for coexistence request. */
};

typedef struct {
    uint8_t             hwiPriority;        
    uint8_t             swiPriority;        
    bool                xoscHfAlwaysNeeded; 
    RF_GlobalCallback   globalCallback;     
    RF_GlobalEventMask  globalEventMask;    
} RFCC26XX_HWAttrsV2;

typedef enum
{
    RF_ExecuteActionNone             = 0,  
    RF_ExecuteActionRejectIncoming   = 1,  
    RF_ExecuteActionAbortOngoing     = 2,  
} RF_ExecuteAction;

typedef enum
{
    RF_ScheduleStatusError   = -3,
    RF_ScheduleStatusNone    = 0,
    RF_ScheduleStatusTop     = 1,
    RF_ScheduleStatusMiddle  = 2,
    RF_ScheduleStatusTail    = 4,
    RF_ScheduleStatusPreempt = 8
} RF_ScheduleStatus;

typedef RF_ScheduleStatus (*RF_SubmitHook)(RF_Cmd* pCmdNew, RF_Cmd* pCmdBg, RF_Cmd* pCmdFg, List_List* pPendQueue, List_List* pDoneQueue);

typedef RF_ExecuteAction (*RF_ExecuteHook)(RF_Cmd* pCmdBg, RF_Cmd* pCmdFg, List_List* pPendQueue, List_List* pDoneQueue, bool bConflict, RF_Cmd* conflictCmd);

typedef struct {
  RF_SubmitHook   submitHook;   
  RF_ExecuteHook  executeHook; 
} RFCC26XX_SchedulerPolicy;

typedef enum {
    RF_AllowDelayNone = 0,
    RF_AllowDelayAny  = UINT32_MAX
} RF_AllowDelay;

/* @brief RF schedule command parameter struct
 *
 * RF schedule command parameters are used with the RF_scheduleCmd() call.
 */
typedef struct {
    uint32_t            startTime;          
    RF_StartType        startType;          
    uint32_t            allowDelay;         
   uint32_t            endTime;             
   RF_EndType          endType;             
   uint32_t            duration;            
   uint32_t            activityInfo;        
   RF_PriorityCoex     coexPriority;        
   RF_RequestCoex      coexRequest;         
} RF_ScheduleCmdParams;

typedef struct {
    uint32_t            duration;           
    uint32_t            startTime;          
    RF_Priority         priority;           
} RF_AccessParams;

typedef enum {
    RF_RatChannelAny = -1,                  
    RF_RatChannel0   =  0,                  
    RF_RatChannel1   =  1,                  
    RF_RatChannel2   =  2,                  
} RF_RatSelectChannel;

typedef enum {
      RF_RatCaptureSourceRtcUpdate    = 20, 
      RF_RatCaptureSourceEventGeneric = 21, 
      RF_RatCaptureSourceRfcGpi0      = 22, 
      RF_RatCaptureSourceRfcGpi1      = 23  
} RF_RatCaptureSource;

typedef enum {
    RF_RatCaptureModeRising       = 0,      
    RF_RatCaptureModeFalling      = 1,      
    RF_RatCaptureModeBoth         = 2       
} RF_RatCaptureMode;

typedef enum {
    RF_RatCaptureSingle           = 0,      
    RF_RatCaptureRepeat           = 1       
} RF_RatCaptureRepetition;

typedef enum {
    RF_RatOutputModePulse         = 0,      
    RF_RatOutputModeSet           = 1,      
    RF_RatOutputModeClear         = 2,      
    RF_RatOutputModeToggle        = 3,      
    RF_RatOutputModeAlwaysZero    = 4,      
    RF_RatOutputModeAlwaysOne     = 5,      
} RF_RatOutputMode;

typedef enum {
    RF_RatOutputSelectRatGpo1     = 1,      
    RF_RatOutputSelectRatGpo2     = 2,      
    RF_RatOutputSelectRatGpo3     = 3,      
    RF_RatOutputSelectRatGpo4     = 4,      
    RF_RatOutputSelectRatGpo5     = 5,      
    RF_RatOutputSelectRatGpo6     = 6,      
    RF_RatOutputSelectRatGpo7     = 7,      
} RF_RatOutputSelect;

typedef struct {
    RF_RatCallback            callback;         
    RF_RatHandle              channel;          
    RF_RatCaptureSource       source;           
    RF_RatCaptureMode         captureMode;      
    RF_RatCaptureRepetition   repeat;           
} RF_RatConfigCapture;

typedef struct {
    RF_RatCallback            callback;         
    RF_RatHandle              channel;          
    uint32_t                  timeout;          
} RF_RatConfigCompare;

typedef struct {
    RF_RatOutputMode          mode;            
    RF_RatOutputSelect        select;          
} RF_RatConfigOutput;

extern RF_Handle RF_open(RF_Object *pObj, RF_Mode *pRfMode, RF_RadioSetup *pRadioSetup, RF_Params *params);

extern void RF_close(RF_Handle h);

extern uint32_t RF_getCurrentTime(void);

extern RF_CmdHandle RF_postCmd(RF_Handle h, RF_Op *pOp, RF_Priority ePri, RF_Callback pCb, RF_EventMask bmEvent);

extern RF_ScheduleStatus RF_defaultSubmitPolicy(RF_Cmd* pCmdNew, RF_Cmd* pCmdBg, RF_Cmd* pCmdFg, List_List* pPendQueue, List_List* pDoneQueue);

extern RF_ExecuteAction RF_defaultExecutionPolicy(RF_Cmd* pCmdBg, RF_Cmd* pCmdFg, List_List* pPendQueue, List_List* pDoneQueue, bool bConflict, RF_Cmd* conflictCmd);


extern void RF_ScheduleCmdParams_init(RF_ScheduleCmdParams *pSchParams);

extern RF_CmdHandle RF_scheduleCmd(RF_Handle h, RF_Op *pOp, RF_ScheduleCmdParams *pSchParams, RF_Callback pCb, RF_EventMask bmEvent);

extern RF_EventMask RF_pendCmd(RF_Handle h, RF_CmdHandle ch, RF_EventMask bmEvent);

extern RF_EventMask RF_runCmd(RF_Handle h, RF_Op *pOp, RF_Priority ePri, RF_Callback pCb, RF_EventMask bmEvent);

extern RF_EventMask RF_runScheduleCmd(RF_Handle h, RF_Op *pOp, RF_ScheduleCmdParams *pSchParams, RF_Callback pCb, RF_EventMask bmEvent);

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

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

extern RF_Stat RF_runImmediateCmd(RF_Handle h, uint32_t *pCmdStruct);

extern RF_Stat RF_runDirectCmd(RF_Handle h, uint32_t cmd);

extern void RF_yield(RF_Handle h);

extern void RF_Params_init(RF_Params *params);

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

extern int8_t RF_getRssi(RF_Handle h);

extern RF_Op* RF_getCmdOp(RF_Handle h, RF_CmdHandle cmdHnd);

extern void RF_RatConfigCompare_init(RF_RatConfigCompare* channelConfig);

extern void RF_RatConfigCapture_init(RF_RatConfigCapture* channelConfig);

extern void RF_RatConfigOutput_init(RF_RatConfigOutput* ioConfig);

extern RF_RatHandle RF_ratCompare(RF_Handle rfHandle, RF_RatConfigCompare* channelConfig, RF_RatConfigOutput* ioConfig);

extern RF_RatHandle RF_ratCapture(RF_Handle rfHandle, RF_RatConfigCapture* channelConfig, RF_RatConfigOutput* ioConfig);

extern RF_Stat RF_ratDisableChannel(RF_Handle rfHandle, RF_RatHandle ratHandle);

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

extern RF_Stat RF_requestAccess(RF_Handle h, RF_AccessParams *pParams);

extern RF_TxPowerTable_Value RF_getTxPower(RF_Handle h);

extern RF_Stat RF_setTxPower(RF_Handle h, RF_TxPowerTable_Value value);

extern int8_t RF_TxPowerTable_findPowerLevel(RF_TxPowerTable_Entry table[], RF_TxPowerTable_Value value);

extern RF_TxPowerTable_Value RF_TxPowerTable_findValue(RF_TxPowerTable_Entry table[], int8_t powerLevel);


extern void RF_enableHPOSCTemperatureCompensation(void);

#ifdef __cplusplus
}
#endif

#endif /* ti_drivers_rfcc26x2__include */

//*****************************************************************************
//
//
//*****************************************************************************