System States and Scheduling Policies

A DMM policy tells the scheduler which stack has priority in a certain application state and whether submitted RF commands can be deferred or not. From the policy, the scheduler can deduce a how scheduling conflicts shall be resolved. A set of policies is called a policy table. Each table entry represents a comprehensive system state and consists of the following parameters:

  • role of each stack in this entry
  • possible states of each stack encoded as flags and OR’ed together
  • stack priorities in the current system state
  • timing constraints of RF commands in the current system state

During a comprehensive system state, a stack might have multiple possible states. For instance, while the BLE stack is in connected state with a high priority, a Sub-1 GHz connection might be in idle state or transmit state or might receive an acknowledgment. That is why a flag type is used for stack states.

Creating A Policy Table

Each application or system wishing to use the DMM must create a policy table that will be used by used by the DMM to make scheduling decisions.

The policy table is entry structure defined by DMMPolicy_PolicyTableEntry in dmm_policy.h. An application will usually define multiple system states and initialize a policy table array.

A shell of a policy table could be created like so:

DMMPolicy_PolicyTableEntry samplePolicyTable[] = {
    // Todo: Define DMM states here
};

Choosing A Stack Role

For each policy table entry, the application developer must choose a stack role. The DMMPolicy_StackRole enum defines available stack roles. For example for WSN and BLE the stack role array is initialized like this:

{DMMPolicy_StackRole_BlePeripheral, DMMPolicy_StackRole_WsnNode},

Note

Only BLE, TI 15.4 Sensor and WSN Node are supported at this time. Creating new stack role is not supported. However, two roles are available for use with custom stacks that do not fit any of the pre-defined roles. These roles are DMMPolicy_StackRole_reserved1 and DMMPolicy_StackRole_reserved2.

Creating a DMM State

A DMM state is a combination of each protocol stack state. There can be multiple states of a protocol stack that map to a given DMM state. It is the combinations of protocol stack states that define a DMM state. This state combination must be mapped to a 32-bit bitmask in the stackStateBitMask[] field. For example, a when the BLE-Stack is advertising and the WSN Node is in either sleeping, TX or ACK state could be defined below as a DMM state as below:

{(DMMPOLICY_STACKSTATE_BLEPERIPH_ADV) , (DMMPOLICY_STACKSTATE_WSNNODE_SLEEPING | DMMPOLICY_STACKSTATE_WSNNODE_TX | DMMPOLICY_STACKSTATE_WSNNODE_ACK)},

Each DMM state has a policy assigned to each stack when that state is active. A policy is a structure that contains timing and priority information. It also contains the operation state of the stack policy. An example DMMPolicy_Policy array is shown below:, specifying the following policy:

  • BLE-stack is low priority and has no critical timing.
  • The WSN Node is high priority and has critical timing.
  • Both stack policies is active.
{DMMPOLICY_PRIORITY_LOW, DMMPOLICY_TIME_NONE_CRITICAL, DMMPOLICY_NOT_PAUSED, //BLE SP Stack
 DMMPOLICY_PRIORITY_HIGH, DMMPOLICY_TIME_CRITICAL, DMMPOLICY_NOT_PAUSED}  //WSN NODE Stack

If one of the stacks were to be temporarily paused when transitioning into this state, DMMPOLICY_NOT_PAUSED would be replaced with DMMPOLICY_PAUSED for that particular stack. When the active DMM policy transitions to one where any of the stacks is set to be paused, the DMM policy manager will invoke the user registered callback to notify the application that it should pause operation.

Note

The offset into both stackStateBitMask[] and DMMPolicy_Policy[] is controlled by the stackRole enumeration. Each state must contain a mapping of stack role to policy and stateBitMask.

The complete DMM state entry discussed above is defined as

{
  {DMMPolicy_StackRole_BlePeripheral, DMMPolicy_StackRole_WsnNode},
  {(DMMPOLICY_STACKSTATE_BLEPERIPH_ADV) , (DMMPOLICY_STACKSTATE_WSNNODE_SLEEPING | DMMPOLICY_STACKSTATE_WSNNODE_TX | DMMPOLICY_STACKSTATE_WSNNODE_ACK)},
  {DMMPOLICY_PRIORITY_LOW, DMMPOLICY_TIME_NONE_CRITICAL, DMMPOLICY_NOT_PAUSED //BLE SP Stack
   DMMPOLICY_PRIORITY_HIGH, DMMPOLICY_TIME_CRITICAL, DMMPOLICY_NOT_PAUSED} //WSN NODE Stack
},

A DMM state structure should be created for every possible combination of stack states that will be encountered by the application. The state structure defines the policy that is used when the DMM state is active. Each entry must be added to the DMMPolicy_PolicyTableEntry.

Initializing the Policy Table

Once the policy table has been defined, it must be initialized and passed to the DMM. This is done through five steps:

  • Initialize the policy module
  • Initialize the parameter structure used to open the module to a known default state
  • Modify the necessary policy parameters as needed
  • Open the policy module by passing in the parameter struct
  • Register policy callbacks as needed

This initialization is generally performed in the main function before the RTOS is started to prevent any stacks from running commands before the policy module is initialized. Refer to the DMM sample application’s main.c for an example of how to initialize a the policy module.

Furthermore, the sample policy table that defines the DMM states for WSN Node + BLE-Stack can be found in dmm_policy_blesp_wsnnode.[c,h].

Setting the State of the Stack

Since the DMM does not hook directly into the stack, it relies on each stack’s high level application to inform the policy module of any changes in the stack. Such stack changes are usually signaled to the high level application via a message, callback, or event.

Whenever the application is signaled that the stack has changed state, the application should immediately notify the DMM of the new stack state using the DMMPolicy_updateStackState() API.

Registering Policy Callbacks

In order for the application to know when its DMM policy is changed into a paused state, the user has to register callbacks functions with the DMM policy manager. The application callbacks are registered using the DMMPolicy_registerAppCbs() API.

Note

The application callbacks should be registered at an early stage for each affected stack.

Sample Policies

There is a number of sample policies that is provided by TI alongside the DMM examples. While the given combinations and relative priorities can be tweaked by the application developer, this policy should serve as a starting point when developing a DMM application. The sample policies are designed for their respective example and it is recommended to read the related README.html file found inside the example project.

As an example, the dmm_154sensor_remote_display sample policy showcases the Pause Policy feature. It is recommended to read the associated README.html file found in the example project to understand how this feature is used in the application.

The tables below define the sample policy for the dmm_154sensor_remote_display example.

Table 15. State 0: BLE Advertising, TI 15.4 Sensor is uninitialized
Stack Role BLE Peripheral TI 15.4 Sensor
Stack State(s) Advertising Uninitialized
Policy High Priority, Time Critical, Policy Not Paused Low Priority, Not Time Critical, Policy Not Paused
Table 16. State 1: BLE Connected or Advertising, TI 15.4 Sensor is commissioning
Stack Role BLE Peripheral TI 15.4 Sensor
Stack State(s) Advertising + Connected Commissioning
Policy Low Priority, Not Time Critical, Policy Paused High Priority, Not Time Critical, Policy Not Paused
Table 17. State 2: BLE Connected or Advertising, TI 15.4 Sensor connected
Stack Role BLE Peripheral TI 15.4 Sensor
Stack State(s) Advertising + Connected Connected
Policy Low Priority, Not Time Critical, Policy Not Paused High Priority, Not Time Critical, Policy Not Paused
Table 18. State 3: BLE Connecting, TI 15.4 Sensor is in any state
Stack Role BLE Peripheral TI 15.4 Sensor
Stack State(s) Connecting Any
Policy High Priority, Time Critical, Policy Not Paused Low Priority, Not Time Critical, Policy Not Paused
Table 19. Default: Assume TI 15.4 Sensor restriction
Stack Role BLE Peripheral TI 15.4 Sensor
Stack State(s) Any Any
Policy High Priority, Time Critical, Policy Not Paused Low Priority, Not Time Critical, Policy Not Paused

Additional sample policies are available and can be found in the DMM source directory found in the SimpleLink CC13x2 / 26x2 SDK: <SDK INSTALL DIRECTORY>/source/ti/dmm/dmm_policy_*.[c/h].