Detailed Description

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

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

Go to the source code of this file.

Classes
struct	DMMSch_Params
	RF parameter struct DMM Scheduler parameters are used with the DMMSch_open() and DMMSch_Params_init() call. More...

Macros
#define	CONFLICT_FLUSH_ALL 1
	Define to flush all commands. More...


#define	xDMM_DEBUG_LOGGING
	DMM Debug Logging. More...

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

Typedefs
typedef void(*	DMMSch_PreemptionCb) (DMMPolicy_StackRole stackRolePreempted)
	Defines the preemption callback. More...

Enumerations
enum	DMM_ConflictStatus { DMM_NoConflict = 0, DMM_ConflictWithPrev, DMM_ConflictWithNext, DMM_ConfictWithBoth }
	DMM Conflict struct DMM Conflict Status. More...

Functions
void	DMMSch_Params_init (DMMSch_Params *params)
	Function to initialize the DMMSch_Params struct to its defaults. More...

void	DMMSch_init (void)
	Function that initializes the DMMSch module. More...

void	DMMSch_registerPreemptionCb (DMMSch_PreemptionCb dmmSchPreemptionCb)
	allows policy manager to register a callback on command preemption More...

void	DMMSch_open (DMMSch_Params *params)
	Function to open the DMMSch module. More...

void	DMMSch_registerClient (Task_Handle *pTaskHndl, DMMPolicy_StackRole StackRole)
	Register an DMM Scheduler client. More...

RF_Handle	DMMSch_rfOpen (RF_Object pObj, RF_Mode pRfMode, RF_RadioSetup pOpSetup, RF_Params params)
	Intercepts calls from a stack to RF_postCmd (re-mapped to DMMSch_rfOpen), The DMMSch module uses this to tie. More...

RF_CmdHandle	DMMSch_rfPostCmd (RF_Handle h, RF_Op *pOp, RF_Priority ePri, RF_Callback pCb, RF_EventMask bmEvent)
	Handles calls from a stack to RF_postCmd (re-mapped to DMMSch_postCmd), adjusts timing as necessary and schedules then accordingly with RF_scheduleCmd. More...

RF_CmdHandle	DMMSch_rfScheduleCmd (RF_Handle h, RF_Op pOp, RF_ScheduleCmdParams pSchParams, RF_Callback pCb, RF_EventMask bmEvent)
	Handles calls from a stack to RF_scheduleCmd (re-mapped to DMMSch_scheduleCmd), adjusts timing as necessary and schedules then accordingly with RF_scheduleCmd. More...

RF_EventMask	DMMSch_rfRunCmd (RF_Handle h, RF_Op *pOp, RF_Priority ePri, RF_Callback pCb, RF_EventMask bmEvent)
	Handles calls from a stack to RF_runCmd (re-mapped to DMMSch_runCmd), adjusts timing as necessary and schedules then accordingly with RF_scheduleCmd. More...

RF_EventMask	DMMSch_rfRunScheduleCmd (RF_Handle h, RF_Op pOp, RF_ScheduleCmdParams pSchParams, RF_Callback pCb, RF_EventMask bmEvent)
	Handles calls from a stack to RF_runScheduleCmd (re-mapped to DMMSch_runScheduleCmd), adjusts timing as necessary and schedules then accordingly with RF_scheduleCmd. More...

RF_Stat	DMMSch_rfCancelCmd (RF_Handle h, RF_CmdHandle ch, uint8_t mode)
	Abort/stop/cancel single command in command queue. More...

RF_Stat	DMMSch_rfFlushCmd (RF_Handle h, RF_CmdHandle ch, uint8_t mode)
	Abort/stop/cancel command and any subsequent commands in command queue. More...

RF_Stat	DMMSch_rfRunImmediateCmd (RF_Handle h, uint32_t *pCmdStruct)
	Send any Immediate command. More...

RF_Stat	DMMSch_rfRunDirectCmd (RF_Handle h, uint32_t cmd)
	Send any Direct command. More...

bool	DMMSch_setBlockModeOn (DMMPolicy_StackRole stackRole)
	Turn on Block mode. More...

bool	DMMSch_setBlockModeOff (DMMPolicy_StackRole stackRole)
	Turn off Block mode. More...

bool	DMMSch_getBlockModeStatus (DMMPolicy_StackRole stackRole)
	Get Block mode status. More...

RF_Stat	DMMSch_rfRequestAccess (RF_Handle h, RF_AccessParams *pParams)
	Request access RF API that should not be used in DMM

Macro Definition Documentation

§ CONFLICT_FLUSH_ALL

#define CONFLICT_FLUSH_ALL 1

Define to flush all commands.

Default option to flush all commands for a specific client for a conflict

§ xDMM_DEBUG_LOGGING

#define xDMM_DEBUG_LOGGING

DMM Debug Logging.

Debugging for internal use only.

Typedef Documentation

§ DMMSch_PreemptionCb

typedef void(* DMMSch_PreemptionCb) (DMMPolicy_StackRole stackRolePreempted)

Defines the preemption callback.

The function is invoked when a preemption occurs in DMM Scheduler.

The arguments are:

stackRolePreempted stack role for command was preempted.

Enumeration Type Documentation

§ DMM_ConflictStatus

enum DMM_ConflictStatus

DMM Conflict struct DMM Conflict Status.

Enumerator
DMM_NoConflict	used to define where there is no conflict in commands.
DMM_ConflictWithPrev	used to define where there is a conflict with the previous command.
DMM_ConflictWithNext	used to define where there is a conflict with the next command.
DMM_ConfictWithBoth	used to define where there is a conflict with both previous and next command.

Function Documentation

§ DMMSch_getBlockModeStatus()

bool DMMSch_getBlockModeStatus ( DMMPolicy_StackRole stackRole )

Get Block mode status.

Parameters

stackRole stack role associated with Task handle

Returns: true: Block Mode is On, False: Block Mode is Off

§ DMMSch_init()

void DMMSch_init ( void )

Function that initializes the DMMSch module.

§ DMMSch_open()

void DMMSch_open ( DMMSch_Params * params )

Function to open the DMMSch module.

Parameters

params An pointer to RF_Params structure for initialization

§ DMMSch_Params_init()

void DMMSch_Params_init ( DMMSch_Params * params )

Function to initialize the DMMSch_Params struct to its defaults.

Parameters

params An pointer to RF_Params structure for initialization

Defaults values are:

§ DMMSch_registerClient()

void DMMSch_registerClient	(	Task_Handle *	pTaskHndl,
		DMMPolicy_StackRole	StackRole
	)

Register an DMM Scheduler client.

Parameters

pTaskHndl	Task handle that the stack is running in, used to map the RF Client handle to a stack role
StackRole	stack role associated with Task handle

§ DMMSch_registerPreemptionCb()

void DMMSch_registerPreemptionCb ( DMMSch_PreemptionCb dmmSchPreemptionCb )

allows policy manager to register a callback on command preemption

Parameters

dmmSchPreemptionCb callback to register

§ DMMSch_rfCancelCmd()

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

Abort/stop/cancel single command in command queue.

If command is running, aborts/stops it and posts callback for the aborted/stopped command.
If command has not yet run, cancels it it and posts callback for the cancelled command.
If command has already run or been aborted/stopped/cancelled, has no effect.
If RF_cancelCmd is called from a Swi context with same or higher priority than RF Driver Swi, when the RF core is powered OFF -> the cancel callback will be delayed until the next power-up cycle.

Note: Calling context : Task/SWI

Parameters

h	Handle previously returned by RF_open()
ch	Command handle previously returned by RF_postCmd().
mode	1: Stop gracefully, 0: abort abruptly

Returns: RF_Stat indicates if command was successfully completed

§ DMMSch_rfFlushCmd()

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

Abort/stop/cancel command and any subsequent commands in command queue.

If command is running, aborts/stops it and then cancels all later commands in queue.
If command has not yet run, cancels it and all later commands in queue.
If command has already run or been aborted/stopped/cancelled, has no effect.
The callbacks for all cancelled commands are issued in chronological order.
If RF_flushCmd is called from a Swi context with same or higher priority than RF Driver Swi, when the RF core is powered OFF -> the cancel callback will be delayed until the next power-up cycle.

Note: Calling context : Task/SWI

Parameters

h	Handle previously returned by RF_open()
ch	Command handle previously returned by RF_postCmd().
mode	1: Stop gracefully, 0: abort abruptly

Returns: RF_Stat indicates if command was successfully completed

§ DMMSch_rfOpen()

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

Intercepts calls from a stack to RF_postCmd (re-mapped to DMMSch_rfOpen), The DMMSch module uses this to tie.

Parameters

pObj	pointer to RF Object
pRfMode	pointer to RF Mode
pOpSetup	pointer to Radio Setup
params	pointer to RF params

Returns: An pointer to RF_Params structure for initialization

§ DMMSch_rfPostCmd()

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

Handles calls from a stack to RF_postCmd (re-mapped to DMMSch_postCmd), adjusts timing as necessary and schedules then accordingly with RF_scheduleCmd.

See also: RF_pendCmd(), RF_runCmd(), RF_scheduleCmd(), RF_RF_cancelCmd(), RF_flushCmd(), RF_getCmdOp()

Parameters

h	Driver handle previously returned by RF_open()
pOp	Pointer to the RF operation command.
ePri	Priority of this RF command (used for arbitration in multi-client systems)
pCb	Callback function called during command execution and upon completion. If RF_postCmd() fails, no callback is made.
bmEvent	Bitmask of events that will trigger the callback or that can be pended on.

Returns: A handle to the RF command. Return value of RF_ALLOC_ERROR indicates error.

§ DMMSch_rfRunCmd()

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

Handles calls from a stack to RF_runCmd (re-mapped to DMMSch_runCmd), adjusts timing as necessary and schedules then accordingly with RF_scheduleCmd.

Parameters

h	Driver handle previously returned by RF_open()
pOp	Pointer to the RF operation command.
ePri	Priority of this RF command (used for arbitration in multi-client systems)
pCb	Callback function called during command execution and upon completion. If RF_runCmd() fails, no callback is made.
bmEvent	Bitmask of events that will trigger the callback or that can be pended on.

Returns: The relevant termination event.

§ DMMSch_rfRunDirectCmd()

RF_Stat DMMSch_rfRunDirectCmd	(	RF_Handle	h,
		uint32_t	cmd
	)

Send any Direct command.

Direct Comamnd value is send to RDBELL immediately, if radio is active and the RF_Handle point to the current client.
In other appropriate RF_Stat values are returned.

Note: Calling context : Task/SWI/HWI

Parameters

h	Handle previously returned by RF_open()
cmd	Direct command value.

Returns: RF_Stat indicates if command was successfully completed.

§ DMMSch_rfRunImmediateCmd()

RF_Stat DMMSch_rfRunImmediateCmd	(	RF_Handle	h,
		uint32_t *	pCmdStruct
	)

Send any Immediate command.

Immediate Comamnd is send to RDBELL, if radio is active and the RF_Handle points to the current client.
In other appropriate RF_Stat values are returned.

Note: Calling context : Task/SWI/HWI

Parameters

h	Handle previously returned by RF_open()
pCmdStruct	Pointer to the immediate command structure

Returns: RF_Stat indicates if command was successfully completed

§ DMMSch_rfRunScheduleCmd()

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

Handles calls from a stack to RF_runScheduleCmd (re-mapped to DMMSch_runScheduleCmd), adjusts timing as necessary and schedules then accordingly with RF_scheduleCmd.

Parameters

h	Handle previously returned by RF_open()
pOp	Pointer to the RF_Op. Must normally be in persistent and writeable memory
pSchParams	Pointer to the schdule command parameter structure
pCb	Callback function called upon command completion (and some other events). If RF_runScheduleCmd() fails, no callback is made.
bmEvent	Bitmask of events that will trigger the callback.

Returns: The relevant command completed event.

§ DMMSch_rfScheduleCmd()

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

Handles calls from a stack to RF_scheduleCmd (re-mapped to DMMSch_scheduleCmd), adjusts timing as necessary and schedules then accordingly with RF_scheduleCmd.

Parameters

h	Handle previously returned by RF_open()
pOp	Pointer to the RF_Op. Must normally be in persistent and writeable memory
pSchParams	Pointer to the schedule command parameter structure
pCb	Callback function called upon command completion (and some other events). If RF_scheduleCmd() fails no callback is made
bmEvent	Bitmask of events that will trigger the callback.

Returns: A handle to the RF command. Return value of RF_ALLOC_ERROR indicates error.

§ DMMSch_setBlockModeOff()

bool DMMSch_setBlockModeOff ( DMMPolicy_StackRole stackRole )

Turn off Block mode.

Parameters

stackRole stack role associated with Task handle

Returns: true: success, false: the stack role cannot be found

§ DMMSch_setBlockModeOn()

bool DMMSch_setBlockModeOn ( DMMPolicy_StackRole stackRole )

Turn on Block mode.

Parameters

stackRole stack role associated with Task handle

Returns: true: success, false: the stack role cannot be found

Detailed Description

DMMSch API

Classes

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

§ CONFLICT_FLUSH_ALL

§ xDMM_DEBUG_LOGGING

Typedef Documentation

§ DMMSch_PreemptionCb

Enumeration Type Documentation

§ DMM_ConflictStatus

Function Documentation

§ DMMSch_getBlockModeStatus()

§ DMMSch_init()

§ DMMSch_open()

§ DMMSch_Params_init()

§ DMMSch_registerClient()

§ DMMSch_registerPreemptionCb()

§ DMMSch_rfCancelCmd()

§ DMMSch_rfFlushCmd()

§ DMMSch_rfOpen()

§ DMMSch_rfPostCmd()

§ DMMSch_rfRunCmd()

§ DMMSch_rfRunDirectCmd()

§ DMMSch_rfRunImmediateCmd()

§ DMMSch_rfRunScheduleCmd()

§ DMMSch_rfScheduleCmd()

§ DMMSch_setBlockModeOff()

§ DMMSch_setBlockModeOn()