dmm_policy.h

Go to the documentation of this file.

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

 @file dmm_policy.h

 @brief dmm policy Header

 Group: WCS LPC
 $Target Device: DEVICES $

 ******************************************************************************
 $License: TISD 2019 $
 ******************************************************************************
 $Release Name: PACKAGE NAME $
 $Release Date: PACKAGE RELEASE DATE $
 *****************************************************************************/
/*!****************************************************************************
 *  @file       dmm_policy.h
 *
 *  @brief      Dual Mode Policy Manager
 *
 *  The DMMPolicy interface provides a service to for the stack applications to
 *  update the priority of the stack activities, which is then used to make scheduling decisions.
 *
 *  # Fields in the Policy Table #
 *  .state: the name of the application state
 *  .weight: amount of adjusted priority for stack activities specified in .appliedActivity
 *  .timingConstraint: reserved for future usage
 *  .pause: whether or not the specified stack's application is paused during the state
 *  .appliedActivity: Specified the activities of which priority is/are adjusted by .weight
 *    - Final Priority = GPT (Stack level priority) +  weight (Application Level)
 *  .balancedMode: Switch the .weight value between the two stacks based on the time information specified
 *
 *  # Usage #
 *
 *  To use the DMMPolicy module to set the scheduling policy, the application
 *  calls the following APIs:
 *    - DMMPolicy_init(): Initialize the DMMPolicy module/task.
 *    - DMMPolicy_Params_init():  Initialize a DMMPolicy_Params structure
 *      with default values.  Then change the parameters from non-default
 *      values as needed.
 *    - DMMPolicy_open():  Open an instance of the DMMPolicy module,
 *      passing the initialized parameters.
 *    - Stack A/B application - DMMPolicy_updateApplicationState: Update the application state.
 *                              The Policy Manager finds the matching policy that is used
 *                              when scheduling RF commands from stack A and B.
 *
 *   An example of a policy table (define in ti_dmm_application_policy.c, which is generated by SysConfig)
 *
 *   \code
 * DMMPolicy_Policy DMMPolicy_ApplicationPolicy[] = {
 *   // DMM Policy 0
 *   {
 *       // BLE Peripheral Policy
 *       .appState[BLE_STACK_POLICY_IDX] = {
 *           .state = DMMPOLICY_BLE_OAD,
 *           .weight = 25,
 *           .timingConstraint = DMMPOLICY_TIME_RESERVED,
 *           .pause = DMMPOLICY_NOT_PAUSED,
 *           .appliedActivity =  DMMPOLICY_APPLIED_ACTIVITY_BLE_CONNECTION,
 *            (note: the priority of BLE connection event is increased by .weight (25) during BLE_OAD)
 *       },
 *       // 15.4 Collector Policy
 *       .appState[TI154_STACK_POLICY_IDX] = {
 *           .state = ANY,
 *            .weight = 0,
 *            .timingConstraint = DMMPOLICY_TIME_RESERVED,
 *            .pause = DMMPOLICY_PAUSED,
 *            .appliedActivity =  DMMPOLICY_APPLIED_ACTIVITY_NONE,
 *        },
 *        //Balanced Mode Policy
 *        .balancedMode = DMMPOLICY_BALANCED_NONE,
 *    },
 *    // DMM Policy 1
 *    {
 *        // BLE Peripheral Policy
 *        .appState[BLE_STACK_POLICY_IDX] = {
 *            .state = DMMPOLICY_BLE_HIGH_BANDWIDTH,
 *            .weight = 25,
 *            .timingConstraint = DMMPOLICY_TIME_RESERVED,
 *            .pause = DMMPOLICY_NOT_PAUSED,
 *            .appliedActivity =  DMMPOLICY_APPLIED_ACTIVITY_BLE_CONNECTION,
 *             (note: the priority of BLE connection event is increased by .weight (25) during BLE_HIGH_BANDWIDTH)
 *        },
 *        // 15.4 Collector Policy
 *        .appState[TI154_STACK_POLICY_IDX] = {
 *            .state = ANY,
 *            .weight = 0,
 *            .timingConstraint = DMMPOLICY_TIME_RESERVED,
 *            .pause = DMMPOLICY_NOT_PAUSED,
 *            .appliedActivity =  DMMPOLICY_APPLIED_ACTIVITY_NONE,
 *        },
 *        //Balanced Mode Policy
 *        .balancedMode = DMMPOLICY_BALANCED_NONE,
 *    },
 *    // DMM Policy 2 (The last policy indicates the default priority of the two stacks)
 *    {
 *        // BLE Peripheral Policy
 *        .appState[BLE_STACK_POLICY_IDX] = {
 *            .state = ANY,
 *            .weight = 0,
 *            .timingConstraint = DMMPOLICY_TIME_RESERVED,
 *            .pause = DMMPOLICY_NOT_PAUSED,
 *            .appliedActivity =  DMMPOLICY_APPLIED_ACTIVITY_NONE,
 *        },
 *        // 15.4 Collector Policy
 *        .appState[TI154_STACK_POLICY_IDX] = {
 *            .state = ANY,
 *            .weight = 1,
 *            .timingConstraint = DMMPOLICY_TIME_RESERVED,
 *            .pause = DMMPOLICY_NOT_PAUSED,
 *            .appliedActivity =  DMMPOLICY_APPLIED_ACTIVITY_NONE,
 *        },
 *        //Balanced Mode Policy
 *        .balancedMode = DMMPOLICY_BALANCED_NONE,
 *    },
 *};
 *
 *DMMPolicy_PolicyTable DMMPolicy_ApplicationPolicyTable = {
 *    //Stack Roles
 *    .stackRole[BLE_STACK_POLICY_IDX] = DMMPolicy_StackRole_BlePeripheral,
 *    .stackRole[TI154_STACK_POLICY_IDX] = DMMPolicy_StackRole_154Sensor,
 *    //Policy table
 *    .policy = DMMPolicy_ApplicationPolicy,
 *    // Index Table for future use
 *    .indexTable = NULL,
 *};
 *
 * //! \brief The application policy table size
 * uint32_t DMMPolicy_ApplicationPolicySize = (sizeof(DMMPolicy_ApplicationPolicy) / sizeof(DMMPolicy_Policy));
 *
 *   \endcode
 *
 *********************************************************************************/

#ifndef DMMPolicy_H_
#define DMMPolicy_H_

#ifdef __cplusplus
extern "C" {
#endif

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


#define BLE_STACK_POLICY_IDX       0    


#define DMMPOLICY_NUM_STACKS    2       

#define DMMPOLICY_PRIORITY_LOW     0    
#define DMMPOLICY_PRIORITY_HIGH    1    

#define DMMPOLICY_TIME_NONE_CRITICAL    0   
#define DMMPOLICY_TIME_CRITICAL         1   
#define DMMPOLICY_TIME_RESERVED         1   

#define DMMPOLICY_NOT_PAUSED            0           
#define DMMPOLICY_PAUSED                0x0001      
#define DMMPOLICY_SCHEDULE_BLOCKED      0x0002      

#define DMMPOLICY_BALANCED_NONE             0       

#define DMMPOLICY_BALANCED_TIME_BM_1               0x80000000                                                                           
#define DMMPOLICY_BALANCED_TIME_MODE_1(onMin, offMax)     (DMMPOLICY_BALANCED_TIME_BM_1 | (onMin & 0xFFF) | ((offMax & 0xFFF) << 12))   
#define DMMPOLICY_BALANCED_TIME_MODE_1_ON_MIN(RatioTime)     (RatioTime & 0xFFF)                                                        
#define DMMPOLICY_BALANCED_TIME_MODE_1_OFF_MAX(RatioTime)     ((RatioTime & 0xFFF000) >> 12)                                            

#define DMMPOLICY_APPLIED_ACTIVITY_NONE                     0           
#define DMMPOLICY_APPLIED_ACTIVITY_ALL                      0xFFFF      
#define DMMPOLICY_APPLIED_ACTIVITY_BLE_CONNECTION           0x0001      
#define DMMPOLICY_APPLIED_ACTIVITY_BLE_LINK_EST             0x0002      
#define DMMPOLICY_APPLIED_ACTIVITY_BLE_BROADCASTING         0x0004      
#define DMMPOLICY_APPLIED_ACTIVITY_BLE_OBSERVING            0x0008      

#define DMMPOLICY_APPLIED_ACTIVITY_154_DATA                 0x0001      
#define DMMPOLICY_APPLIED_ACTIVITY_154_LINK_EST             0x0002      
#define DMMPOLICY_APPLIED_ACTIVITY_154_TX_BEACON            0x0004      
#define DMMPOLICY_APPLIED_ACTIVITY_154_RX_BEACON            0x0008      
#define DMMPOLICY_APPLIED_ACTIVITY_154_FH                   0x0010      
#define DMMPOLICY_APPLIED_ACTIVITY_154_SCAN                 0x0020      
#define DMMPOLICY_APPLIED_ACTIVITY_154_RXON                 0x0040      

#define DMMPOLICY_APPLIED_ACTIVITY_WSN_RETRANSMIT           0x0001      
#define DMMPOLICY_APPLIED_ACTIVITY_WSN_TRANSMIT             0x0002      
#define DMMPOLICY_APPLIED_ACTIVITY_WSN_RECEIVE              0x0004      


#define PRIORITY_NUM                              3         

#define DMMPolicy_updateStackState DMMPolicy_updateApplicationState

#define DMM_PRIORITY_MAX_LIMIT                    250       
#define DMM_PRIORITY_MAX_CHANGE_LIMIT             185       

#define DMM_GLOBAL_PRIORITY(activity, level, weight) {(activity << 16 | level), weight} 

typedef enum
{
    DMMPolicy_StackRole_invalid = 0,            
    DMMPolicy_StackRole_BlePeripheral,          
    DMMPolicy_StackRole_WsnNode,                
    DMMPolicy_StackRole_154Sensor,              
    DMMPolicy_StackRole_154Collector,           
    DMMPolicy_StackRole_ZigbeeEndDevice,        
    DMMPolicy_StackRole_ZigbeeRouter,           
    DMMPolicy_StackRole_ZigbeeCoordinator,      
    DMMPolicy_StackRole_custom1,                
    DMMPolicy_StackRole_custom2,                
} DMMPolicy_StackRole;

typedef struct
{
    uint32_t     state;                         
    uint8_t      weight;                        
    uint16_t     timingConstraint;              
    uint32_t     appliedActivity;               
    uint16_t     pause;                         
} DMMPolicy_State;

typedef struct
{
    DMMPolicy_State appState[DMMPOLICY_NUM_STACKS];     
    uint32_t        balancedMode;                       
} DMMPolicy_Policy;

typedef struct
{
    uint8_t *CmdIndex;          
    uint8_t tableSize;          
}DMMPolicy_StackCmdIndexTable;

typedef struct
{
    DMMPolicy_StackRole stackRole[DMMPOLICY_NUM_STACKS];    
    DMMPolicy_Policy* policy;                               
    DMMPolicy_StackCmdIndexTable *indexTable;               
} DMMPolicy_PolicyTable;

typedef struct {
    uint32_t activity;          
    uint16_t globalPriority;    
} StackActivity;

typedef enum
{
    DMM_StackPNormal =0,        
    DMM_StackPHigh,             
    DMM_StackPUrgent,           
} PriorityDef;

typedef struct {
    StackActivity *globalTableArray;    
    uint8_t tableSize;                  
    DMMPolicy_StackRole stackRole;      
} GlobalTable;

typedef struct {
    uint32_t stackID;           
    uint8_t currentWeight;      
    uint8_t defaultPriority;    
} DMMPolicy_CurrentInfo;

typedef struct {
    DMMPolicy_PolicyTable policyTable;                                  
    uint32_t numPolicyTableEntries;                                     
    GlobalTable *globalPriorityTable;                                   
    DMMPolicy_CurrentInfo  policyCurrentInfo[DMMPOLICY_NUM_STACKS];     
} DMMPolicy_Params;

typedef enum {
    DMMPolicy_StatusError,          
    DMMPolicy_StatusNoPolicyError,  
    DMMPolicy_StatusParamError,     
    DMMPolicy_StatusSuccess         
} DMMPolicy_Status;

typedef void (*DMMPolicy_appPauseCb_t)(uint16_t pause);

typedef struct
{
    DMMPolicy_appPauseCb_t appPauseCb;      
} DMMPolicy_AppCbs_t;

extern void DMMPolicy_Params_init(DMMPolicy_Params *params);

extern void DMMPolicy_registerAppCbs(DMMPolicy_AppCbs_t AppCbs, DMMPolicy_StackRole StackRole);

extern void DMMPolicy_init(void);

extern DMMPolicy_Status DMMPolicy_open(DMMPolicy_Params *params);

extern DMMPolicy_Status DMMPolicy_updateApplicationState(DMMPolicy_StackRole StackRole, uint32_t newState);

extern uint16_t DMMPolicy_getGlobalPriority (uint32_t activity, uint32_t stackID);

extern uint8_t DMMPolicy_getDefaultPriority (uint32_t stackID);

extern void DMMPolicy_setStackID (uint32_t stackID, DMMPolicy_StackRole StackRole);

extern uint16_t DMMPolicy_getPauseValue (uint32_t stackID);

extern uint16_t DMMPolicy_getTimeConstraintValue (uint32_t stackID);

extern bool DMMPolicy_getGPTStatus (void);

bool DMMPolicy_setBlockModeOn(DMMPolicy_StackRole StackRole);

bool DMMPolicy_setBlockModeOff(DMMPolicy_StackRole StackRole);

bool DMMPolicy_getBlockModeStatus(DMMPolicy_StackRole StackRole);

#ifdef __cplusplus
}
#endif

#endif /* DMMPolicy_H_ */