module ti.sysbios.gates.GateMutexPri

Mutex Gate with priority inheritance

GateMutexPri is a mutex gate (it can only be held by one thread at a time) which implements priority inheritance in order to prevent priority inversion. Priority inversion occurs when a high priority task has its priority effectively 'inverted' because it is waiting on a gate held by a low priority task. [ more ... ]
 C synopsis target-domain sourced in ti/sysbios/gates/GateMutexPri.xdc
DETAILS
GateMutexPri is a mutex gate (it can only be held by one thread at a time) which implements priority inheritance in order to prevent priority inversion. Priority inversion occurs when a high priority task has its priority effectively 'inverted' because it is waiting on a gate held by a low priority task.
When multiple tasks wait on this gate, they will receive the gate in order of priority (higher priority tasks will receive the gate first). This is because the queue of tasks waiting on a GateMutexPri is sorted by priority, not FIFO.

### Problem: Priority Inversion

The following example demonstrates priority inversion. A system has three tasks, Low, Med, and High, each with the priority suggested by its name. Task Low runs first and acquires the gate. Task High is scheduled and preempts Low. Task High tries to acquire the gate, and waits on it. Next, task Med is scheduled and preempts task Low. Now task High must wait for both task Med and task Low to finish before it can continue. In this situation, task Low has in effect lowered task High's priority to that of Low.

### Solution: Priority Inheritance

To guard against priority inversion, GateMutexPri implements priority inheritance: when task High tries to acquire a gate that is owned by task Low, task Low's priority will be temporarily raised to that of High, as long as High is waiting on the gate. Task High will "donate" its priority to task Low. When multiple tasks wait on the gate, the gate owner will receive the highest priority of any of the tasks waiting on the gate.

### Caveats

Priority inheritance is not a complete guard against priority inversion. Tasks only donate priority on the call to gate, so if a task has its priority raised while waiting on a gate, that priority will not carry through to the gate owner. This can occur in situations involving multiple gates. A system has four tasks: VeryLow, Low, Med, and High, each with the priority suggested by its name. Task VeryLow runs first and acquires gate A. Task Low runs next and acquires gate B, then waits on gate A. Task High runs and waits on gate B. Task High has donated its priority to task Low, but Low is blocked on VeryLow, so priority inversion occurs despite the use of the gate. The solution to this problem is to design around it. If gate A may be needed by a high-priority, time-critical task, then it should be a design rule that no task holds this gate for a long time, or blocks while holding this gate.

### Miscellaneous

Calls to enter() may block, so this gate can only be used in the task context. GateMutexPri is non-deterministic on calls to gate because it keeps the queue of waiting tasks sorted by priority.

### Calling Context

Function Hwi Swi Task Main Startup
Params_init Y Y Y Y Y
query Y Y Y Y Y
construct Y Y Y Y N
create N* N* Y Y N
delete N* N* Y Y N
destruct Y Y Y Y N
enter N N Y Y** N
leave N N Y Y** N
Definitions:
• Hwi: API is callable from a Hwi thread.
• Swi: API is callable from a Swi thread.
• Task: API is callable from a Task thread.
• Main: API is callable during any of these phases:
• In your module startup after this module is started (e.g. GateMutexPri_Module_startupDone() returns TRUE).
• During xdc.runtime.Startup.lastFxns.
• During main().
• During BIOS.startupFxns.
• Startup: API is callable during any of these phases:
• During xdc.runtime.Startup.firstFxns.
• In your module startup before this module is started (e.g. GateMutexPri_Module_startupDone() returns FALSE).
• *: Assuming blocking Heap is used for creation.
• **: Must be used in enter/leave pairs.

 const GateMutexPri_Q_BLOCKING

Blocking quality

 C synopsis target-domain
#define GateMutexPri_Q_BLOCKING (Int)1

DETAILS
Gates with this "quality" may cause the calling thread to block; i.e., suspend execution until another thread leaves the gate.

 const GateMutexPri_Q_PREEMPTING

Preempting quality

 C synopsis target-domain
#define GateMutexPri_Q_PREEMPTING (Int)2

DETAILS
Gates with this "quality" allow other threads to preempt the thread that has already entered the gate.

 config GateMutexPri_A_badContext  // module-wide

Assert when GateMutexPri_enter() is not called from correct context. GateMutexPri_enter() can only be called from main() or Task context (not Hwi or Swi)

 C synopsis target-domain
extern const Assert_Id GateMutexPri_A_badContext;

DETAILS
Common causes and workarounds for hitting this Assert:
- Calling printf() from a Hwi or Swi thread.
• Use xdc.runtime.System_printf (with SysMin) instead.
- Calling System_printf() from a Hwi or Swi thread when using SysStd.
- Calling Memory_alloc() from a Hwi or Swi thread.
• Use a different Heap manager

 GateMutexPri_query()  // module-wide

Runtime test for a particular gate quality

 C synopsis target-domain
Bool GateMutexPri_query(Int qual);

ARGUMENTS
qual — constant describing a quality
RETURNS
Returns TRUE if the gate has the given quality, and FALSE otherwise, which includes the case when the gate does not recognize the constant describing the quality.
 Module-Wide Built-Ins

 C synopsis target-domain
Types_ModuleId GateMutexPri_Module_id();
// Get this module's unique id

Bool GateMutexPri_Module_startupDone();
// Test if this module has completed startup

IHeap_Handle GateMutexPri_Module_heap();
// The heap from which this module allocates memory

Bool GateMutexPri_Module_hasMask();
// Test whether this module has a diagnostics mask

Bits16 GateMutexPri_Module_getMask();
// Returns the diagnostics mask for this module

Void GateMutexPri_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
 Instance Object Types

 C synopsis target-domain
typedef struct GateMutexPri_Object GateMutexPri_Object;
// Opaque internal representation of an instance object

typedef GateMutexPri_Object *GateMutexPri_Handle;
// Client reference to an instance object

typedef struct GateMutexPri_Struct GateMutexPri_Struct;
// Opaque client structure large enough to hold an instance object

GateMutexPri_Handle GateMutexPri_handle(GateMutexPri_Struct *structP);
// Convert this instance structure pointer into an instance handle

GateMutexPri_Struct *GateMutexPri_struct(GateMutexPri_Handle handle);
// Convert this instance handle into an instance structure pointer
 Instance Config Parameters

 C synopsis target-domain
typedef struct GateMutexPri_Params {
// Instance config-params structure
IInstance_Params *instance;
// Common per-instance configs
} GateMutexPri_Params;

Void GateMutexPri_Params_init(GateMutexPri_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
 Instance Creation

 C synopsis target-domain
GateMutexPri_Handle GateMutexPri_create(const GateMutexPri_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle

Void GateMutexPri_construct(GateMutexPri_Struct *structP, const GateMutexPri_Params *params);
// Initialize a new instance object inside the provided structure
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
 Instance Deletion

 C synopsis target-domain
Void GateMutexPri_delete(GateMutexPri_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL

Void GateMutexPri_destruct(GateMutexPri_Struct *structP);
// Finalize the instance object inside the provided structure

 GateMutexPri_enter()  // instance

Enter this gate

 C synopsis target-domain
IArg GateMutexPri_enter(GateMutexPri_Handle handle);

ARGUMENTS
handle — handle of a previously-created GateMutexPri instance object
DETAILS
Each gate provider can implement mutual exclusion using different algorithms; e.g., disabling all scheduling, disabling the scheduling of all threads below a specified "priority level", suspending the caller when the gate has been entered by another thread and re-enabling it when the the other thread leaves the gate. However, in all cases, after this method returns that caller has exclusive access to the data protected by this gate.
A thread may reenter a gate without blocking or failing.
RETURNS
Returns a "key" that is used to leave this gate; this value is used to restore thread preemption to the state that existed just prior to entering this gate.

 GateMutexPri_leave()  // instance

Leave this gate

 C synopsis target-domain
Void GateMutexPri_leave(GateMutexPri_Handle handle, IArg key);

ARGUMENTS
handle — handle of a previously-created GateMutexPri instance object
key — the value returned by a matching call to enter
DETAILS
This method is only called by threads that have previously entered this gate via enter. After this method returns, the caller must not access the data structure protected by this gate (unless the caller has entered the gate more than once and other calls to leave remain to balance the number of previous calls to enter).
 Instance Convertors

 C synopsis target-domain
IGateProvider_Handle GateMutexPri_Handle_upCast(GateMutexPri_Handle handle);
// unconditionally move one level up the inheritance hierarchy

GateMutexPri_Handle GateMutexPri_Handle_downCast(IGateProvider_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
 Instance Built-Ins

 C synopsis target-domain
Int GateMutexPri_Object_count();
// The number of statically-created instance objects

GateMutexPri_Handle GateMutexPri_Object_get(GateMutexPri_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)

GateMutexPri_Handle GateMutexPri_Object_first();
// The handle of the first dynamically-created instance object, or NULL

GateMutexPri_Handle GateMutexPri_Object_next(GateMutexPri_Handle handle);
// The handle of the next dynamically-created instance object, or NULL

IHeap_Handle GateMutexPri_Object_heap();
// The heap used to allocate dynamically-created instance objects

Types_Label *GateMutexPri_Handle_label(GateMutexPri_Handle handle, Types_Label *buf);
// The label associated with this instance object

String GateMutexPri_Handle_name(GateMutexPri_Handle handle);
// The name of this instance object

 XDCscript usage meta-domain sourced in ti/sysbios/gates/GateMutexPri.xdc
var GateMutexPri = xdc.useModule('ti.sysbios.gates.GateMutexPri');
module-wide constants & types
module-wide config parameters
msg: "A_badContext: bad calling context. See GateMutexPri API doc for details."
};

module-wide functions
per-instance config parameters
var params = new GateMutexPri.Params// Instance config-params object;
per-instance creation
var inst = GateMutexPri.create// Create an instance-object(params);

 const GateMutexPri.Q_BLOCKING

Blocking quality

 XDCscript usage meta-domain
const GateMutexPri.Q_BLOCKING = 1;

DETAILS
Gates with this "quality" may cause the calling thread to block; i.e., suspend execution until another thread leaves the gate.
C SYNOPSIS

 const GateMutexPri.Q_PREEMPTING

Preempting quality

 XDCscript usage meta-domain
const GateMutexPri.Q_PREEMPTING = 2;

DETAILS
Gates with this "quality" allow other threads to preempt the thread that has already entered the gate.
C SYNOPSIS

 config GateMutexPri.A_badContext  // module-wide

Assert when GateMutexPri_enter() is not called from correct context. GateMutexPri_enter() can only be called from main() or Task context (not Hwi or Swi)

 XDCscript usage meta-domain
GateMutexPri.A_badContext = Assert.Desc {
msg: "A_badContext: bad calling context. See GateMutexPri API doc for details."
};

DETAILS
Common causes and workarounds for hitting this Assert:
- Calling printf() from a Hwi or Swi thread.
• Use xdc.runtime.System_printf (with SysMin) instead.
- Calling System_printf() from a Hwi or Swi thread when using SysStd.
- Calling Memory_alloc() from a Hwi or Swi thread.
• Use a different Heap manager
C SYNOPSIS

 metaonly config GateMutexPri.common\$  // module-wide

Common module configuration parameters

 XDCscript usage meta-domain
GateMutexPri.common\$ = Types.Common\$ undefined;

DETAILS
All modules have this configuration parameter. Its name contains the '\$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.

 metaonly GateMutexPri.queryMeta()  // module-wide

Configuration time test for a particular gate quality

 XDCscript usage meta-domain
GateMutexPri.queryMeta(Int qual) returns Bool

ARGUMENTS
qual — constant describing a quality
RETURNS
Returns TRUE if the gate has the given quality, and FALSE otherwise, which includes the case when the gate does not recognize the constant describing the quality.
 Instance Config Parameters

 XDCscript usage meta-domain
var params = new GateMutexPri.Params;
// Instance config-params object
 Instance Creation

 XDCscript usage meta-domain
var params = new GateMutexPri.Params;
// Allocate instance config-params
params.config =   ...
// Assign individual configs

var inst = GateMutexPri.create(params);
// Create an instance-object
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
generated on Thu, 01 Mar 2012 16:58:02 GMT