module ti.sysbios.knl.Semaphore

Semaphore Manager

C synopsis
Individual elements
XDCscript usage
Individual elements

The Semaphore manager makes available a set of functions that manipulate semaphore objects. Semaphores can be used for task synchronization and mutual exclusion. [ more ... ]

C synopsis target-domain sourced in ti/sysbios/knl/Semaphore.xdc

#include <ti/sysbios/knl/Semaphore.h>

Functions
Void	Semaphore_construct// Initialize a new instance object inside the provided structure(Semaphore_Struct structP, Int count, const Semaphore_Params params);
Semaphore_Handle	Semaphore_create// Allocate and initialize a new instance object and return its handle(Int count, const Semaphore_Params params, Error_Block eb);
Void	Semaphore_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(Semaphore_Handle *handleP);
Void	Semaphore_destruct// Finalize the instance object inside the provided structure(Semaphore_Struct *structP);
Int	Semaphore_getCount// Get current semaphore count(Semaphore_Handle handle);
Void	Semaphore_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(Semaphore_Params *params);
Bool	Semaphore_pend// Wait for a semaphore(Semaphore_Handle handle, UInt timeout);
Void	Semaphore_post// Signal a semaphore(Semaphore_Handle handle);
Void	Semaphore_registerEvent// Register an Event Object with a semaphore(Semaphore_Handle handle, Event_Handle event, UInt eventId);
Void	Semaphore_reset// Reset semaphore count(Semaphore_Handle handle, Int count);
Functions common to all target instances
	Semaphore_handle// Convert this instance structure pointer into an instance handle, Semaphore_Handle_label// The label associated with this instance object, Semaphore_Handle_name// The name of this instance object, Semaphore_Object_count// The number of statically-created instance objects, Semaphore_Object_first// The handle of the first dynamically-created instance object, or NULL, Semaphore_Object_get// The handle of the i-th statically-created instance object (array == NULL), Semaphore_Object_heap// The heap used to allocate dynamically-created instance objects, Semaphore_Object_next// The handle of the next dynamically-created instance object, or NULL, Semaphore_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
	Semaphore_Module_getMask// Returns the diagnostics mask for this module, Semaphore_Module_hasMask// Test whether this module has a diagnostics mask, Semaphore_Module_heap// The heap from which this module allocates memory, Semaphore_Module_id// Get this module's unique id, Semaphore_Module_setMask// Set the diagnostics mask for this module, Semaphore_Module_startupDone// Test if this module has completed startup
Typedefs
typedef Semaphore_Object *	Semaphore_Handle// Client reference to an instance object;
typedef enum	Semaphore_Mode// Types of semaphores ...
typedef struct	Semaphore_Object// Opaque internal representation of an instance object Semaphore_Object;
typedef struct	Semaphore_Params// Instance config-params structure ...
typedef struct	Semaphore_Struct// Opaque client structure large enough to hold an instance object Semaphore_Struct;
Constants
extern const Assert_Id	Semaphore_A_badContext// Asserted when pend is called with non-zero timeout from other than a Task context;
extern const Assert_Id	Semaphore_A_invTimeout// Generated by pend if BIOS_EVENT_ACQUIRED timeout is used with a Semaphore that has not been configured with an Event object;
extern const Assert_Id	Semaphore_A_noEvents// Generated by create if supportsEvents is false and an ti.sysbios.knl.Event object is passed to create;
extern const Log_Event	Semaphore_LM_pend// Logged on calls to Semaphore_pend();
extern const Log_Event	Semaphore_LM_post// Logged on calls to Semaphore_post();
extern const Bool	Semaphore_supportsEvents// Support Semaphores with Events? Default is false;

DETAILS

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.

Calling Context

Function	Hwi	Swi	Task	Main	Startup
Params_init	Y	Y	Y	Y	Y
construct	N	N	Y	Y	N
create	N	N	Y	Y	N
delete	N	N	Y	Y	N
destruct	N	N	Y	Y	N
getCount	Y	Y	Y	Y	Y
pend	N	N	Y	N	N
post	Y	Y	Y	Y	N
registerEvent	N	N	Y	Y	Y
reset	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. Semaphore_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. Semaphore_Module_startupDone() returns FALSE).

enum Semaphore_Mode