RF.h

Go to the documentation of this file.

/*
 * Copyright (c) 2016-2018, 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.
 */
#ifndef ti_drivers_rf__include
#define ti_drivers_rf__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_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_RAT_RTC_ERR_TOL_VAL           3

#define RF_CTRL_SET_POWER_MGMT                    4

#define RF_CTRL_SET_HWI_PRIORITY                  5

#define RF_CTRL_SET_SWI_PRIORITY                  6

#define RF_CTRL_SET_AVAILABLE_RAT_CHANNELS_MASK   7

#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_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_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;    

#if (DeviceFamily_PARENT == DeviceFamily_PARENT_CC13X2_CC26X2)
    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; 
#endif
} 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_GlobalEvent;


typedef uint32_t RF_ClientEventMask;

typedef uint32_t RF_GlobalEventMask;

typedef int16_t RF_CmdHandle;

#if defined (RF_SINGLEMODE)
  typedef struct RF_ObjectSingleMode  RF_Object;
#else
  typedef struct RF_ObjectMultiMode   RF_Object;
#endif

/*  Definition of the RF_Object structure for single-mode applications.
 *  It is applicable with the single-mode RF driver through the #RF_Object common type.
 */
struct RF_ObjectSingleMode{
    struct {
        uint32_t               nInactivityTimeout;      
        RF_Mode*               pRfMode;                 
        RF_RadioSetup*         pRadioSetup;             
        uint32_t               nPowerUpDuration;        
        bool                   bMeasurePowerUpDuration; 
        bool                   bUpdateSetup;            
        uint16_t               nPowerUpDurationMargin;  
        void*                  pPowerCb;                
        void*                  pErrCb;                  
    } clientConfig;
    struct {
        struct {
            rfc_CMD_FS_t        cmdFs;               
        } mode_state;                                
        SemaphoreP_Struct       semSync;             
        RF_EventMask volatile   eventSync;           
        void*                   pCbSync;             
        RF_EventMask            unpendCause;         
        bool                    bYielded;            
    } state;
};

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

    RF_ClientCallback   pClientEventCb;          

    RF_ClientEventMask  nClientEventMask;        
} RF_Params;

/* 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 */
    uint32_t             startTime;   /* Command start time (in RAT ticks) */
    uint32_t             endTime;     /* Command end time (in RAT ticks) */
    uint32_t             allowDelay;  /* Delay allowed if the start time cannot be met. */
    RF_CmdHandle         ch;          /* Command handle */
    RF_Priority          ePri;        /* Priority of RF command */
    uint8_t volatile     flags;       /* [0: Aborted, 1: Stopped, 2: cancelled] */
};

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

typedef enum
{
    RF_ConflictNone   = 0,
    RF_ConflictReject = 1,
    RF_ConflictAbort  = 2,
} RF_Conflict;

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_Conflict (*RF_ConflictHook)(RF_Cmd* pCmdBg, RF_Cmd* pCmdFg, List_List* pPendQueue, List_List* pDoneQueue);

typedef struct {
  RF_SubmitHook   submitHook;   
  RF_ConflictHook conflictHook; 
} 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            endTime;            
    RF_Priority         priority;           
    uint32_t            allowDelay;         
} 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_Conflict RF_defaultConflictPolicy(RF_Cmd* pCmdBg, RF_Cmd* pCmdFg, List_List* pPendQueue, List_List* pDoneQueue);


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


#ifdef __cplusplus
}
#endif

#endif /* ti_drivers_rf__include */