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 ... ]
#include <ti/sysbios/gates/GateMutexPri.h>
Functions |
Void | |
| |
Void | |
Void | |
Void | |
Functions common to all IGateProvider modules |
Bool | |
Functions common to all target instances |
|
GateMutexPri_handle// Convert this instance structure pointer into an instance handle,
GateMutexPri_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure,
GateMutexPri_Handle_label// The label associated with this instance object,
GateMutexPri_Handle_name// The name of this instance object,
GateMutexPri_Handle_upCast// unconditionally move one level up the inheritance hierarchy,
GateMutexPri_Object_count// The number of statically-created instance objects,
GateMutexPri_Object_first// The handle of the first dynamically-created instance object, or NULL,
GateMutexPri_Object_get// The handle of the i-th statically-created instance object (array == NULL),
GateMutexPri_Object_heap// The heap used to allocate dynamically-created instance objects,
GateMutexPri_Object_next// The handle of the next dynamically-created instance object, or NULL,
GateMutexPri_struct// Convert this instance handle into an instance structure pointer
|
Functions common to all target modules |
|
|
Defines |
#define | |
#define | |
Typedefs |
| |
typedef struct | |
typedef struct | |
typedef struct | |
Constants |
| |
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
#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
#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)
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
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 |
|
// Get this module's unique id
Bool GateMutexPri_Module_startupDone();
// Test if this module has completed startup
// 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 |
|
typedef struct GateMutexPri_Object GateMutexPri_Object;
// Opaque internal representation of an instance object
// Client reference to an instance object
typedef struct GateMutexPri_Struct GateMutexPri_Struct;
// Opaque client structure large enough to hold an instance object
// Convert this instance structure pointer into an instance handle
// Convert this instance handle into an instance structure pointer
Instance Config Parameters |
|
typedef struct GateMutexPri_Params {
// Instance config-params structure
// Common per-instance configs
} GateMutexPri_Params;
// Initialize this config-params structure with supplier-specified defaults before instance creation
Instance Creation |
|
// Allocate and initialize a new instance object and return its handle
// 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 |
|
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
// Finalize the instance object inside the provided structure
Instance Convertors |
|
// unconditionally move one level up the inheritance hierarchy
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins |
|
Int GateMutexPri_Object_count();
// The number of statically-created instance objects
// The handle of the i-th statically-created instance object (array == NULL)
// The handle of the first dynamically-created instance object, or NULL
// The handle of the next dynamically-created instance object, or NULL
// The heap used to allocate dynamically-created instance objects
// The label associated with this instance object
// The name of this instance object
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
per-instance creation
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
metaonly struct GateMutexPri.BasicView |
|
XDCscript usage |
meta-domain |
var obj = new GateMutexPri.BasicView;
obj.status = String ...
obj.label = String ...
obj.mutexCnt = UInt ...
obj.owner = String ...
obj.ownerOrigPri = Int ...
obj.ownerCurrPri = Int ...
metaonly struct GateMutexPri.DetailedView |
|
XDCscript usage |
meta-domain |
var obj = new GateMutexPri.DetailedView;
obj.status = String ...
obj.label = String ...
obj.mutexCnt = UInt ...
obj.owner = String ...
obj.ownerOrigPri = Int ...
obj.ownerCurrPri = Int ...
obj.pendedTasks = String[] ...
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 |
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 |
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 config GateMutexPri.rovViewInfo // module-wide |
|
XDCscript usage |
meta-domain |
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, 03 Feb 2011 19:01:32 GMT