dmm_scheduler.h

Go to the documentation of this file.

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

 @file dmm_scheduler.h

 @brief Dual Mode Manager Scheduler

 Group: WCS LPC
 $Target Device: DEVICES $

 ******************************************************************************
 $License: TISD 2019 $
 ******************************************************************************
 $Release Name: PACKAGE NAME $
 $Release Date: PACKAGE RELEASE DATE $
 *****************************************************************************/
/*!****************************************************************************
 *  @file       dmm_scheduler.h
 *
 *  @brief      Dual Mode Manager Scheduler
 *  
 *  DMM enables devices to run multiple wireless protocol stacks concurrently. 
 *  The DMMSch is to enable concurrent operation of multiple stacks with minimized conflicts 
 *  so that it does not cause significant performance degradation.  
 *  The DMMSch uses Application Level, Stack Level information, and Global Priority Table (GPT) when scheduling a command. 
 *  Stack Level information (provided by stack) is embedded in each RF command and it includes:
 *  - Start Type, Start Time, AllowDelay, Priority, Activity, etc.  
 *  Application Level information (provided by User via the Policy Table) includes:
 *  - Application State Name, Weight, AppliedActivity, Pause, etc.   
 *  Global Priority Table (GPT)
 *  - GPT defines relative priorities of the two stacks
 *  The DMMSch uses Start Type, Start Time, and AllowDelay (Stack Level Information) when scheduling a RF command
 *  and tries to avoid a conflict by delaying the command if allowed. 
 *  When a command conflicts with another (during scheduling or execution), 
 *  The DMMSch selects one command over the other based on the final priority of two commands as below:
 *  Final Priority = GPT (Stack level priority) +  weight (Application Level) 
 * 
 *  # DMMSch API #
 *
 *  To use the DMMSch module to schedule a tacks RF commands, the application
 *  calls the following APIs:
 *    - DMMSch_init(): Initialize the DMMSch module/task.
 *    - DMMSch_Params_init():  Initialize a DMMSch_Params structure
 *      with default values.  Then change the parameters from non-default
 *      values as needed.
 *    - DMMSch_open():  Open an instance of the DMMSch module,
 *      passing the initialized parameters.
 *    - Stack A application - DMMSch_registerClient: Passes Task_Handle and StackRole so 
 *                            DMMSch can map the Task_Handle to the stack role 
 *    - Stack A application - Rf_open -> DMMSch_rfOpen: DMMSch overwrites the RF_Mode and 
 *                            rf patches for multi-mode operation, maps RF Handle to the stack ID,
 *                            assigns phySwitchingTime for DMM operation. 
 *                            From this point, Task_Handle, StackRole, and Stack ID are all related. 
 *    - Stack B application - DMMSch_registerClient: Passes Task_Handle and StackRole so 
 *                            DMMSch can map the Task_Handle to the stack role 
 *    - Stack B application - Rf_open -> DMMSch_rfOpen: Rf_open -> DMMSch_rfOpen: DMMSch overwrites the RF_Mode and 
 *                            rf patches for multi-mode operation, maps RF Handle to the stack ID,
 *                            assigns phySwitchingTime for DMM operation. 
 *                            From this point, Task_Handle, StackRole, and Stack ID are all related. 
 *    - Stack A application - RF_scheduleCmd -> DMMSch_rfScheduleCmd: DMMSch adjusted timing based on policy
 *    - Stack B application - RF_scheduleCmd -> DMMSch_rfScheduleCmd: DMMSch adjusted timing based on policy
 *
 *
 ********************************************************************************/

#ifndef DMMSch_H_
#define DMMSch_H_

#ifdef __cplusplus
extern "C" {
#endif

#include "stdint.h"

#include <ti/drivers/rf/RF.h>
#include <ti/sysbios/knl/Task.h>

#include "dmm_policy.h"


#define xDMM_DEBUG_LOGGING

#ifdef DMM_DEBUG_LOGGING
#include <xdc/runtime/Log.h>
#define DMM_dbgLog0(str)                     Log_info0(str)
#define DMM_dbgLog1(str, a0)                 Log_info1(str, a0)
#define DMM_dbgLog2(str, a0, a1)             Log_info2(str, a0, a1)
#define DMM_dbgLog3(str, a0, a1, a2)         Log_info3(str, a0, a1, a2)
#define DMM_dbgLog4(str, a0, a1, a2, a3)     Log_info4(str, a0, a1, a2, a3)
#define DMM_dbgLog5(str, a0, a1, a2, a3, a4) Log_info5(str, a0, a1, a2, a3, a4)
#else
#define DMM_dbgLog0(str)
#define DMM_dbgLog1(str, a0)
#define DMM_dbgLog2(str, a0, a1)
#define DMM_dbgLog3(str, a0, a1, a2)
#define DMM_dbgLog4(str, a0, a1, a2, a3)
#define DMM_dbgLog5(str, a0, a1, a2, a3, a4)
#endif

typedef struct {
    DMMPolicy_StackRole stackRoles[DMMPOLICY_NUM_STACKS];       
    DMMPolicy_StackCmdIndexTable *indexTable;                   
} DMMSch_Params;

typedef enum
{
    DMM_NoConflict  = 0,        
    DMM_ConflictWithPrev,       
    DMM_ConflictWithNext,       
    DMM_ConfictWithBoth,        
} DMM_ConflictStatus;

#define CONFLICT_FLUSH_ALL       1

typedef void (*DMMSch_PreemptionCb)(DMMPolicy_StackRole stackRolePreempted);

extern void DMMSch_Params_init(DMMSch_Params *params);

extern void DMMSch_init(void);

extern void DMMSch_registerPreemptionCb(DMMSch_PreemptionCb dmmSchPreemptionCb);

extern void DMMSch_open(DMMSch_Params *params);

extern void DMMSch_registerClient(Task_Handle* pTaskHndl, DMMPolicy_StackRole StackRole);

extern RF_Handle DMMSch_rfOpen(RF_Object *pObj, RF_Mode *pRfMode, RF_RadioSetup *pOpSetup, RF_Params *params);

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

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

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

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

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

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

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

extern RF_Stat DMMSch_rfRunDirectCmd(RF_Handle h, uint32_t cmd);


extern bool DMMSch_setBlockModeOn(DMMPolicy_StackRole stackRole);

extern bool DMMSch_setBlockModeOff(DMMPolicy_StackRole stackRole);

extern bool DMMSch_getBlockModeStatus(DMMPolicy_StackRole stackRole);

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

#ifdef __cplusplus
}
#endif

#endif /* DMMSch_H_ */