DMM Policy Interface

Dual Mode Policy Manager.

The DMMPolicy interface provides a service to for the stack applications to update the stack states, which is then used to make scheduling decisions

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_updateStackState: Update the policy used by DMMSch for scheduling RF commands from stack A and B

An example of a policy table (define in a use case specific policy header, such as dmm_policy_blesp_wsnnode.h)

// The supported stack states bit map for BLE Simple Peripheral
#define DMMPOLICY_STACKSTATE_BLEPERIPH_ADV          0x00000001 // State for BLE Simple Peripheral when trying to connect
#define DMMPOLICY_STACKSTATE_BLEPERIPH_CONNECTING   0x00000002 // State for BLE Simple Peripheral when connect
#define DMMPOLICY_STACKSTATE_BLEPERIPH_CONNECTED    0x00000004 // State for BLE Simple Peripheral when connect
#define DMMPOLICY_STACKSTATE_BLEPERIPH_ANY          0xFFFFFFFF // Allow any policy

// The supported stack states bit map for Wsn Node
#define DMMPOLICY_STACKSTATE_WSNNODE_SLEEPING   0x00000001 // State for Wsn Node when sleeping
#define DMMPOLICY_STACKSTATE_WSNNODE_TX         0x00000002 // State for Wsn Node when transmitting
#define DMMPOLICY_STACKSTATE_WSNNODE_ACK        0x00000004 // State for Wsn Node when waiting for Ack
#define DMMPOLICY_STACKSTATE_WSNNODE_ANY        0xFFFFFFFF // Allow any policy

// The policy table for the BLE Simple Peripheral and WSN Node use case
DMMPolicy_policyTableEntry_t DMMPolicy_wsnNodeBleSpPolicyTable[] = {
//State 1: BleSp connectable advertisements and Wsn Node TX or Ack: BleSp  = Low Priority | Time None Critical, WsnNode = High Priority | Time Critical
    {
      {DMMPolicy_StackType_BlePeripheral, DMMPolicy_StackType_WsnNode},
      {(DMMPOLICY_STACKSTATE_BLEPERIPH_ADV) , (DMMPOLICY_STACKSTATE_WSNNODE_SLEEPING | DMMPOLICY_STACKSTATE_WSNNODE_TX | DMMPOLICY_STACKSTATE_WSNNODE_ACK)},
      {DMMPOLICY_PRIORITY_LOW, DMMPOLICY_TIME_NONE_CRITICAL, //BLE SP Stack
       DMMPOLICY_PRIORITY_HIGH, DMMPOLICY_TIME_CRITICAL} //WSN NODE Stack
    },
//State 2: BleSp connecting or connected and Wsn Node Tx: BleSp  = High Priority | Time Critical, WsnNode = Low Priority | Time Critical
    {
      {DMMPolicy_StackType_BlePeripheral, DMMPolicy_StackType_WsnNode},
      {(DMMPOLICY_STACKSTATE_BLEPERIPH_CONNECTING | DMMPOLICY_STACKSTATE_BLEPERIPH_CONNECTED) , (DMMPOLICY_STACKSTATE_WSNNODE_TX)},
      {DMMPOLICY_PRIORITY_HIGH, DMMPOLICY_TIME_CRITICAL, //BLE SP Stack
       DMMPOLICY_PRIORITY_LOW, DMMPOLICY_TIME_NONE_CRITICAL} //WSN NODE Stack
    },
//State 2: BleSp connecting or connected and Wsn Node Tx: BleSp  = High Priority | Time Critical, WsnNode = Low Priority | Time Critical
    {
      {DMMPolicy_StackType_BlePeripheral, DMMPolicy_StackType_WsnNode},
      {(DMMPOLICY_STACKSTATE_BLEPERIPH_CONNECTING | DMMPOLICY_STACKSTATE_BLEPERIPH_CONNECTED) , (DMMPOLICY_STACKSTATE_WSNNODE_ACK)},
      {DMMPOLICY_PRIORITY_HIGH, DMMPOLICY_TIME_CRITICAL, //BLE SP Stack
       DMMPOLICY_PRIORITY_LOW, DMMPOLICY_TIME_NONE_CRITICAL} //WSN NODE Stack
    },
//Default State: If matching state is not found default to: BleSp  = High Priority | Time Critical, WsnNode = Low Priority | none Time Critical
    {
      {DMMPolicy_StackType_BlePeripheral, DMMPolicy_StackType_WsnNode},
      {DMMPOLICY_STACKSTATE_BLEPERIPH_ANY, DMMPOLICY_STACKSTATE_WSNNODE_ANY},
      {DMMPOLICY_PRIORITY_HIGH, DMMPOLICY_TIME_CRITICAL, //BLE SP Stack
      DMMPOLICY_PRIORITY_LOW, DMMPOLICY_TIME_NONE_CRITICAL} //WSN NODE Stack
    },
};

// The policy table size for the BLE Simple Peripheral and WSN Node use case
uint32_t DMMPolicy_wsnNodeBleSpPolicyTableSize = (sizeof(DMMPolicy_wsnNodeBleSpPolicyTable) / sizeof(DMMPolicy_policyTableEntry_t));

Defines

DMMPOLICY_NUM_STACKS

number of stacks supported by this policy manager

DMMPOLICY_PRIORITY_LOW

stack priotiy

DMMPOLICY_PRIORITY_HIGH

DMMPOLICY_TIME_NONE_CRITICAL

stack timing

DMMPOLICY_TIME_CRITICAL

Enums

enum DMMPolicy_StackType

the stack types supported

Values:

DMMPolicy_StackType_invalid = 0

invalid stack type

DMMPolicy_StackType_BlePeripheral

stack type for a BLE Simple Peripheral

DMMPolicy_StackType_WsnNode

stack type for an EasyLink Wireless Sensor Network Node

enum DMMPolicy_Status

Status codes for various DMM Policy functions.

RF_Stat is reported as return value for DMM Policy functions.

Values:

DMMPolicy_StatusError

Error.

DMMPolicy_StatusNoPolicyError

Error with policy table.

DMMPolicy_StatusParamError

Parameter Error.

DMMPolicy_StatusSuccess

Function finished with success.

Functions

void DMMPolicy_Params_init(DMMPolicy_Params * params)

Function to initialize the DMMPolicy_Params struct to its defaults.

Defaults values are:

Parameters

• params: An pointer to RF_Params structure for initialization

void DMMPolicy_init(void)

Function that initializes the DMMPolicy module.

DMMPolicy_Status DMMPolicy_open(DMMPolicy_Params * params)

Function to open the DMMPolicy module.

Return

DMMPolicy_Stat status

Parameters

• params: An pointer to RF_Params structure for initialization

DMMPolicy_Status DMMPolicy_updateStackState(DMMPolicy_StackType stackType, uint32_t newState)

Updates the policy used to make scheduling decisions.

Return

DMMPolicy_Stat status

Parameters

• stackType: The stack type that has changed state
• newState: The state the stack has changed to

struct DMMPolicy_Policy

#include <dmm_policy.h>

Structure used to decide the policy for a particular stack state.

Public Members

RF_Priority priority

0 being highest priority

uint16_t timingConstrant

0=Time critical and cannot be changed, 0xFFFF=No timing constraint, 1-0xFFFE timing constraint in ms units

struct DMMPolicy_PolicyTableEntry

#include <dmm_policy.h>

policy table entry

Public Members

DMMPolicy_StackType DMMPolicy_PolicyTableEntry::stackType[2]

uint32_t DMMPolicy_PolicyTableEntry::stackStateBitMask[2]

DMMPolicy_Policy DMMPolicy_PolicyTableEntry::policy[2]

struct DMMPolicy_Params

#include <dmm_policy.h>

RF parameter struct DMM Scheduler parameters are used with the DMMPolicy_open() and DMMPolicy_Params_init() call.

Public Members

DMMPolicy_PolicyTableEntry* policyTable

policy table to be used for the DMM use case

uint32_t numPolicyTableEntries

entries in policy table