The Semaphore manager makes available a set of functions that manipulate
semaphore objects. Semaphores can be used for task synchronization and
mutual exclusion.
Semaphores can be counting semaphores or binary semaphores. Counting
semaphores keep track of the number of times the semaphore has been posted
with post(). This is useful, for example, if you have a group of resources
that are shared between tasks. Such tasks might call pend() to see if a
resource is available before using one.
Binary semaphores can have only two states: available (count = 1) and
unavailable (count = 0). They can be used to share a single resource
between
tasks. They can also be used for a basic signaling mechanism, where the
semaphore can be posted multiple times. Binary semaphores do not keep track
of the count; they simply track whether the semaphore has been posted
or not.
The Mailbox module uses a counting semaphore internally to manage the
count of free (or full) mailbox elements. Another example of a counting
semaphore is an ISR that might fill multiple buffers of data for
consumption by a task. After filling each buffer, the ISR puts the buffer on
a queue and calls post(). The task waiting for the data calls pend(), which
simply decrements the semaphore count and returns or blocks if the count is
0. The semaphore count thus tracks the number of full buffers available for
the task.
pend() is used to wait for a semaphore. The timeout parameter allows the
task to wait until a timeout, wait indefinitely, or not wait at all. The
return value is used to indicate if the semaphore was signaled successfully.
post() is used to signal a semaphore. If a task is waiting for the
semaphore, post() removes the task from the semaphore queue and puts it on
the ready queue. If no tasks are waiting, post() simply increments the
semaphore count and returns. For a binary semaphore the count is always
set to one.
enum Semaphore_Mode |
|
Semaphore types
typedef enum Semaphore_Mode {
Semaphore_Mode_COUNTING,
// Counting (FIFO)
Semaphore_Mode_BINARY,
// Binary (FIFO)
Semaphore_Mode_COUNTING_PRIORITY,
// Counting (priority-based)
Semaphore_Mode_BINARY_PRIORITY
// Binary (priority-based)
} Semaphore_Mode;
DETAILS
These enumerations specify the type of semaphore.
Tasks wait for the semaphore in FIFO order unless the PRIORITY
option is chosen.
For PRIORITY semaphores, the pending task will be
inserted in the waiting list before the first task that has
lower priority. This ensures that tasks of equal priority will
pend in FIFO order.
WARNING
PRIORITY semaphores have a potential to increase the interrupt
latency in the system since interrupts are disabled while the list of
tasks waiting on the semaphore is scanned for the proper insertion
point. This is typically about a dozen instructions per waiting task.
For example, if you have 10 tasks of higher priority waiting, then all
10 will be checked with interrupts disabled before the new task is
entered onto the list.
config Semaphore_A_badContext // module-wide |
|
Assert raised if an operation is invalid in the current calling context
extern const Assert_Id Semaphore_A_badContext;
DETAILS
Asserted when
pend is called with non-zero timeout from
other than a Task context.
config Semaphore_A_noEvents // module-wide |
|
Assert raised if application uses Event but it's not supported
DETAILS
This assertion is triggered by
create if
supportsEvents is false and an
ti.sysbios.knl.Event
object is passed to
create.
config Semaphore_A_overflow // module-wide |
|
Assert raised if the semaphore count is incremented past 65535
DETAILS
Asserted when Semaphore_post() has been called when the 16 bit
semaphore count is at its maxmium value of 65535.
config Semaphore_A_pendTaskDisabled // module-wide |
|
Asserted in Sempahore_pend()
extern const Assert_Id Semaphore_A_pendTaskDisabled;
DETAILS
Assert raised if Semaphore_pend() is called with the Task or
Swi scheduler disabled.
config Semaphore_LM_pend // module-wide |
|
Logged on calls to Semaphore_pend()
config Semaphore_LM_post // module-wide |
|
Logged on calls to Semaphore_post()
config Semaphore_supportsEvents // module-wide |
|
Support Semaphores with Events?
extern const Bool Semaphore_supportsEvents;
DETAILS
The default for this parameter is false.
config Semaphore_supportsPriority // module-wide |
|
Support Task priority pend queuing?
extern const Bool Semaphore_supportsPriority;
DETAILS
The default for this parameter is true.
Module-Wide Built-Ins |
|
// Get this module's unique id
Bool Semaphore_Module_startupDone();
// Test if this module has completed startup
// The heap from which this module allocates memory
Bool Semaphore_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Semaphore_Module_getMask();
// Returns the diagnostics mask for this module
Void Semaphore_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types |
|
typedef struct Semaphore_Object Semaphore_Object;
// Opaque internal representation of an instance object
// Client reference to an instance object
typedef struct Semaphore_Struct Semaphore_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 Semaphore_Params {
// Instance config-params structure
// Common per-instance configs
// Event instance to use if non-NULL
UInt eventId;
// eventId if using Events
// Semaphore mode
} Semaphore_Params;
// Initialize this config-params structure with supplier-specified defaults before instance creation
config Semaphore_Params.event // instance |
|
Event instance to use if non-NULL
DETAILS
The default value of this parameter is null. If event is non-null:
- Event_post(sem->event, sem->eventId) will be invoked when
Semaphore_post() is called.
- Event_pend(sem->event, 0, sem->eventId, timeout) will be
invoked when Semaphore_pend() is called.
config Semaphore_Params.eventId // instance |
|
eventId if using Events
DETAILS
The default for this parameters is 1.
config Semaphore_Params.mode // instance |
|
Semaphore mode
DETAILS
When mode is BINARY, the semaphore has only two states, available
and unavailable. When mode is COUNTING, the semaphore keeps track of
number of times a semaphore is posted.
The default for this parameter is COUNTING.
Runtime Instance Creation |
|
// Allocate and initialize a new instance object and return its handle
// Initialize a new instance object inside the provided structure
ARGUMENTS
count
initial semaphore count
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)
DETAILS
This function creates a new Semaphore object which is initialized to
count.
Instance Deletion |
|
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
// Finalize the instance object inside the provided structure
Semaphore_getCount() // instance |
|
Get current semaphore count
ARGUMENTS
handle
handle of a previously-created Semaphore instance object
RETURNS
current semaphore count
DETAILS
This function returns the current value of the semaphore specified by
the handle.
Semaphore_pend() // instance |
|
Wait for a semaphore
ARGUMENTS
handle
handle of a previously-created Semaphore instance object
timeout
return after this many system time units
RETURNS
TRUE if successful, FALSE if timeout
DETAILS
If the semaphore count is greater than zero (available), this function
decrements the count and returns TRUE. If the semaphore count is zero
(unavailable), this function suspends execution of the current task
until post() is called or the timeout expires.
A timeout value of
BIOS_WAIT_FOREVER causes
the task to wait indefinitely for its semaphore to be posted.
A timeout value of
BIOS_NO_WAIT
causes Semaphore_pend to return immediately.
Semaphore_post() // instance |
|
Signal a semaphore
ARGUMENTS
handle
handle of a previously-created Semaphore instance object
DETAILS
Readies the first task waiting for the semaphore. If no task is
waiting, this function simply increments the semaphore count and
returns. In the case of a binary semaphore, the count has a
maximum value of one.
Semaphore_registerEvent() // instance |
|
Register an Event Object with a semaphore
ARGUMENTS
handle
handle of a previously-created Semaphore instance object
event
Ptr to Event Object
eventId
Event ID
DETAILS
Ordinarily, an Event object and eventId are configured at
Semaphore create time.
This API is provided so that Semaphore-using middleware
can support implicit Event posting without having to be
retrofitted.
After the Event object and eventId are registered with the
Semaphore:
Event_post(event, eventId) will be invoked when
Semaphore_post(sem) is called.
Event_pend(event, eventId, 0, timeout) will be invoked when
Semaphore_pend(sem, timeout) is called.
Semaphore_reset() // instance |
|
Reset semaphore count
ARGUMENTS
handle
handle of a previously-created Semaphore instance object
count
semaphore count
DETAILS
Resets the semaphore count to count.
No task switch occurs when calling SEM_reset.
CONSTRAINTS
count must be greater than or equal to 0.
No tasks should be waiting on the semaphore when
Semaphore_reset is called.
Semaphore_reset cannot be called by a Hwi or a Swi.
Instance Built-Ins |
|
Int Semaphore_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
enum Semaphore.Mode |
|
Semaphore types
values of type Semaphore.Mode
const Semaphore.Mode_COUNTING;
// Counting (FIFO)
const Semaphore.Mode_BINARY;
// Binary (FIFO)
const Semaphore.Mode_COUNTING_PRIORITY;
// Counting (priority-based)
const Semaphore.Mode_BINARY_PRIORITY;
// Binary (priority-based)
DETAILS
These enumerations specify the type of semaphore.
Tasks wait for the semaphore in FIFO order unless the PRIORITY
option is chosen.
For PRIORITY semaphores, the pending task will be
inserted in the waiting list before the first task that has
lower priority. This ensures that tasks of equal priority will
pend in FIFO order.
WARNING
PRIORITY semaphores have a potential to increase the interrupt
latency in the system since interrupts are disabled while the list of
tasks waiting on the semaphore is scanned for the proper insertion
point. This is typically about a dozen instructions per waiting task.
For example, if you have 10 tasks of higher priority waiting, then all
10 will be checked with interrupts disabled before the new task is
entered onto the list.
C SYNOPSIS
config Semaphore.A_badContext // module-wide |
|
Assert raised if an operation is invalid in the current calling context
msg: "A_badContext: bad calling context. Must be called from a Task."
};
DETAILS
Asserted when
pend is called with non-zero timeout from
other than a Task context.
C SYNOPSIS
config Semaphore.A_noEvents // module-wide |
|
Assert raised if application uses Event but it's not supported
msg: "A_noEvents: The Event.supportsEvents flag is disabled."
};
DETAILS
This assertion is triggered by
create if
supportsEvents is false and an
ti.sysbios.knl.Event
object is passed to
create.
C SYNOPSIS
config Semaphore.A_overflow // module-wide |
|
Assert raised if the semaphore count is incremented past 65535
msg: "A_overflow: Count has exceeded 65535 and rolled over."
};
DETAILS
Asserted when Semaphore_post() has been called when the 16 bit
semaphore count is at its maxmium value of 65535.
C SYNOPSIS
config Semaphore.A_pendTaskDisabled // module-wide |
|
Asserted in Sempahore_pend()
msg: "A_pendTaskDisabled: Cannot call Semaphore_pend() while the Task or Swi scheduler is disabled."
};
DETAILS
Assert raised if Semaphore_pend() is called with the Task or
Swi scheduler disabled.
C SYNOPSIS
config Semaphore.LM_pend // module-wide |
|
Logged on calls to Semaphore_pend()
msg: "LM_pend: sem: 0x%x, count: %d, timeout: %d"
};
C SYNOPSIS
config Semaphore.LM_post // module-wide |
|
Logged on calls to Semaphore_post()
msg: "LM_post: sem: 0x%x, count: %d"
};
C SYNOPSIS
config Semaphore.supportsEvents // module-wide |
|
Support Semaphores with Events?
Semaphore.supportsEvents = Bool false;
DETAILS
The default for this parameter is false.
C SYNOPSIS
config Semaphore.supportsPriority // module-wide |
|
Support Task priority pend queuing?
Semaphore.supportsPriority = Bool true;
DETAILS
The default for this parameter is true.
C SYNOPSIS
metaonly config Semaphore.common$ // module-wide |
|
Common module configuration parameters
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.
Instance Config Parameters |
|
var params = new Semaphore.Params;
// Instance config-params object
// Event instance to use if non-NULL
params.eventId = UInt 1;
// eventId if using Events
// Semaphore mode
config Semaphore.Params.event // instance |
|
Event instance to use if non-NULL
var params = new Semaphore.Params;
...
DETAILS
The default value of this parameter is null. If event is non-null:
- Event_post(sem->event, sem->eventId) will be invoked when
Semaphore_post() is called.
- Event_pend(sem->event, 0, sem->eventId, timeout) will be
invoked when Semaphore_pend() is called.
C SYNOPSIS
config Semaphore.Params.eventId // instance |
|
eventId if using Events
var params = new Semaphore.Params;
...
params.eventId = UInt 1;
DETAILS
The default for this parameters is 1.
C SYNOPSIS
config Semaphore.Params.mode // instance |
|
Semaphore mode
var params = new Semaphore.Params;
...
DETAILS
When mode is BINARY, the semaphore has only two states, available
and unavailable. When mode is COUNTING, the semaphore keeps track of
number of times a semaphore is posted.
The default for this parameter is COUNTING.
C SYNOPSIS
Static Instance Creation |
|
var params =
new Semaphore.
Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = Semaphore.create(Int count, params);
// Create an instance-object
ARGUMENTS
count
initial semaphore count
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)
DETAILS
This function creates a new Semaphore object which is initialized to
count.