module ti.sysbios.ipc.Semaphore

Semaphore Manager

C synopsis
XDCscript usage
XDCspec declarations
Individual elements
Additional documentation

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

XDCspec summary sourced in ti/sysbios/ipc/Semaphore.xdc

module Semaphore { ...

// inherits xdc.runtime.IModule

instance: ...

C synopsis target-domain

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

module-wide constants & types

typedef enum Semaphore_Mode// Types of semaphores {

Semaphore_Mode_COUNTING// Counting semaphore,

Semaphore_Mode_BINARY// Binary Semaphore

} Semaphore_Mode;

module-wide config parameters

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.ipc.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;

module-wide built-ins

Types_ModuleId Semaphore_Module_id// Get this module's unique id( );

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

IHeap_Handle Semaphore_Module_heap// 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// Set the diagnostics mask for this module( Bits16 mask );

per-instance object types

typedef struct Semaphore_Object// Opaque internal representation of an instance object Semaphore_Object;

typedef Semaphore_Object *Semaphore_Handle// Client reference to an instance object;

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

Semaphore_Handle Semaphore_handle// Convert this instance structure pointer into an instance handle( Semaphore_Struct *structP );

Semaphore_Struct *Semaphore_struct// Convert this instance handle into an instance structure pointer( Semaphore_Handle handle );

per-instance config parameters

typedef struct Semaphore_Params// Instance config-params structure {

IInstance_Params *instance;

Event_Handle event// event if using Events. Default is null;

UInt eventId// eventId if using Events. Default is 1;

Semaphore_Mode mode// Semaphore mode. Default is COUNTING;

} Semaphore_Params;

Void Semaphore_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation( Semaphore_Params *params );

per-instance creation

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_construct// Initialize a new instance object inside the provided structure( Semaphore_Struct *structP, Int count, const Semaphore_Params *params );

per-instance deletion

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

per-instance functions

Int Semaphore_getCount// Get current semaphore count( Semaphore_Handle handle );

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

per-instance built-ins

Int Semaphore_Object_count// The number of statically-created instance objects( );

Semaphore_Handle Semaphore_Object_get// The handle of the i-th statically-created instance object (array == NULL)( Semaphore_Object *array, Int i );

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

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

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

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

String Semaphore_Handle_name// The name of this instance object( Semaphore_Handle handle );

XDCscript usage meta-domain

var Semaphore = xdc.useModule('ti.sysbios.ipc.Semaphore');

module-wide constants & types

values of type Semaphore.Mode// Types of semaphores

const Semaphore.Mode_COUNTING// Counting semaphore;

const Semaphore.Mode_BINARY// Binary Semaphore;

var obj = new Semaphore.BasicView// ;

obj.label = String ...

obj.event = String ...

obj.eventId = String ...

obj.mode = String ...

obj.count = Int ...

obj.pendedTasks = String[] ...

module-wide config parameters

Semaphore.A_badContext// Asserted when pend is called with non-zero timeout from other than a Task context = Assert.Desc {

msg: "A_badContext: bad calling context. Must be called from a Task."

};

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 = Assert.Desc {

msg: "A_invTimeout: Can't use BIOS_EVENT_ACQUIRED with this Semaphore."

};

Semaphore.A_noEvents// Generated by create if supportsEvents is false and an ti.sysbios.ipc.Event object is passed to create = Assert.Desc {

msg: "A_noEvents: The Event.supportsEvents flag is disabled."

};

Semaphore.LM_pend// Logged on calls to Semaphore_pend() = Log.EventDesc {

mask: Diags.USER1 | Diags.USER2,

msg: "LM_pend: sem: 0x%x, count: %d, timeout: %d"

};

Semaphore.LM_post// Logged on calls to Semaphore_post() = Log.EventDesc {

mask: Diags.USER1 | Diags.USER2,

msg: "LM_post: sem: 0x%x, count: %d"

};

Semaphore.supportsEvents// Support Semaphores with Events? Default is false = Bool false;

Semaphore.common$// Common module configuration parameters = Types.Common$ undefined;

Semaphore.rovViewInfo// = ViewInfo.Instance ViewInfo.create;

per-instance config parameters

var params = new Semaphore.Params// Instance config-params object;

params.event// event if using Events. Default is null = Event.Handle null;

params.eventId// eventId if using Events. Default is 1 = UInt 1;

params.mode// Semaphore mode. Default is COUNTING = Semaphore.Mode Semaphore.Mode_COUNTING;

per-instance creation

var inst = Semaphore.create// Create an instance-object( Int count, params );

XDCspec declarations sourced in ti/sysbios/ipc/Semaphore.xdc

package ti.sysbios.ipc;

module Semaphore {

module-wide constants & types

enum Mode// Types of semaphores {

Mode_COUNTING// Counting semaphore,

Mode_BINARY// Binary Semaphore

};

metaonly struct BasicView// {

String label;

String event;

String eventId;

String mode;

Int count;

String pendedTasks[];

};

module-wide config parameters

config Assert.Id A_badContext// Asserted when pend is called with non-zero timeout from other than a Task context = {

msg: "A_badContext: bad calling context. Must be called from a Task."

};

config Assert.Id A_invTimeout// Generated by pend if BIOS_EVENT_ACQUIRED timeout is used with a Semaphore that has not been configured with an Event object = {

msg: "A_invTimeout: Can't use BIOS_EVENT_ACQUIRED with this Semaphore."

};

config Assert.Id A_noEvents// Generated by create if supportsEvents is false and an ti.sysbios.ipc.Event object is passed to create = {

msg: "A_noEvents: The Event.supportsEvents flag is disabled."

};

config Log.Event LM_pend// Logged on calls to Semaphore_pend() = {

mask: Diags.USER1 | Diags.USER2,

msg: "LM_pend: sem: 0x%x, count: %d, timeout: %d"

};

config Log.Event LM_post// Logged on calls to Semaphore_post() = {

mask: Diags.USER1 | Diags.USER2,

msg: "LM_post: sem: 0x%x, count: %d"

};

config Bool supportsEvents// Support Semaphores with Events? Default is false = false;

metaonly config Types.Common$ common$// Common module configuration parameters;

metaonly config ViewInfo.Instance rovViewInfo// = ViewInfo.create;

instance:

per-instance config parameters

config Event.Handle event// event if using Events. Default is null = null;

config UInt eventId// eventId if using Events. Default is 1 = 1;

config Semaphore.Mode mode// Semaphore mode. Default is COUNTING = Semaphore.Mode_COUNTING;

per-instance creation

create// Create an instance-object( Int count );

per-instance functions

Int getCount// Get current semaphore count( );

Bool pend// Wait for a semaphore( UInt timeout );

Void post// Signal a semaphore( );

Void registerEvent// Register an Event Object with a semaphore( Event.Handle event, UInt eventId );

}

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