Semaphore Creation and Use

In most cases, VxWorks provides a single, uniform interface for semaphore control—instead of defining a full set of semaphore control routines specific to each type of semaphore. The exceptions to this rule are as follows:

■ The creation routines, which are specific to each semaphore type.

■ The give and take routines for read/write semaphores, which support read and write modes for each operation.

■ The scalable and inline variants of the give and take routines for binary and mutex semaphores, which provide optimized alternatives to the standard routines.

Table 7-1 lists the semaphore control routines. Table 7-2 lists the options that can be used with the scalable and inline routines. For general information about the scalable and inline routines, see Scalable and Inline Semaphore Take and Give Routines, p.122.

NOTE: The semaphores described here are for use with UP and SMP

configurations of VxWorks. The optional product VxMP provides semaphores that can be used in an asymmetric multiprocessor (AMP) system, in the VxWorks kernel (but not in UP or SMP systems). For more information, see

31. Shared-Memory Objects: VxMP.

Table 7-1 Semaphore Control Routines

Routine Description

semBInitialize( ) Initializes a pre-allocated binary semaphore. See Static Instantiation of Semaphores, p.121.

semCInitialize( ) Initializes a pre-allocated counting semaphore. See Static Instantiation of Semaphores, p.121.

semRWInitialize( ) Initializes a pre-allocated read/write semaphore. See Static Instantiation of Semaphores, p.121.

semBCreate( ) Allocates and initializes a binary semaphore.

semMCreate( ) Allocates and initializes a mutual-exclusion semaphore.

semCCreate( ) Allocates and initializes a counting semaphore.

semRWCreate( ) Allocates and initializes a read/write semaphore.

semDelete( ) Terminates and frees a semaphore (all types).

semTake( ) Takes a binary, mutual-exclusion, or counting semaphore, or a read/write semaphore in write mode.

semRTake( ) Takes a read/write semaphore in read mode.

semWTake( ) Takes a read/write semaphore in write mode.

semBTakeScalable( ) Takes a binary semaphore (with scalable functionality).

semMTakeScalable(

)

Takes a mutual-exclusion semaphore (with scalable functionality).

semBTake_inline( ) Takes a binary semaphore (with scalable functionality).

semMTake_inline( ) Takes a mutual-exclusion semaphore (with scalable functionality). Implemented as an inline function.

semGive( ) Gives a binary, mutual-exclusion, or counting semaphore.

semRWGive( ) Gives a read/write semaphore.

semMGiveForce( ) Gives a mutual-exclusion semaphore without restrictions.

Intended for debugging purposes only.

semRWGiveForce( ) Gives a read-write semaphore without restrictions.

Intended for debugging purposes only.

semBGiveScalable( ) Gives a binary semaphore (with scalable functionality).

semMGiveScalable( ) Gives a mutual-exclusion semaphore (with scalable functionality).

semBGive_inline( ) Gives a binary semaphore (with scalable functionality).

Implemented as an inline function.

semMGive_inline( ) Gives a mutual-exclusion semaphore (with scalable functionality). Implemented as an inline function.

semFlush( ) Unblocks all tasks that are waiting for a binary or counting semaphore.

semExchange( ) Provides for an atomic give and exchange of semaphores in SMP systems.

Table 7-1 Semaphore Control Routines (cont’d)

Routine Description

7 Intertask and Interprocess Communication 7.6 Semaphores

The creation routines return a semaphore ID that serves as a handle on the semaphore during subsequent use by the other semaphore-control routines. When a semaphore is created, the queue type is specified. Tasks pending on a semaphore can be queued in priority order (SEM_Q_PRIORITY) or in first-in first-out order (SEM_Q_FIFO).

Options for Scalable and Inline Semaphore Routines

Table 7-2 lists the options that can be used with the scalable and inline routines. For general information about scalable and inline routines, see Scalable and Inline Semaphore Take and Give Routines, p.122.

! ^WARNING: The semDelete( ) call terminates a semaphore and deallocates all associated memory. Take care when deleting semaphores, particularly those used for mutual exclusion, to avoid deleting a semaphore that another task still requires.

Do not delete a semaphore unless the same task first succeeds in taking it.

Table 7-2 Scalable and Inline Semaphore Options

Routine Description

SEM_NO_ID_VALIDATE No object validation is performed on a semaphore.

SEM_NO_ERROR_CHECK Error checking code is not executed. This includes tests for interrupt restriction, task validation of owners selected from the pend queue, and ownership validation for mutex semaphores.

SEM_NO_EVENT_SEND Do not send VxWorks events, even if a task has registered to receive event notification on this semaphore.

SEM_NO_SYSTEM_VIEWER Do not send System Viewer events. This applies only when semaphores are uncontested. If it is necessary to pend on a take call or to unpend a task on a give call, System Viewer events are sent. This differs from calls to the semLib APIs which send events for all invocations as well as second events when pending (or unpending).

SEM_NO_RECURSE Do not perform recursion checks (applies only to mutex semaphores only) whether semaphores are contested or not. It is important that this is used consistently during any single thread of execution.

! ^CAUTION: The options listed in Table 7-2 must not be used when semaphores are created. Errors are generated if they are used.

then the object is initialized. Semaphores (and other VxWorks objects) can also be statically instantiated—which means that their memory is allocated for the object at compile time—and the object is then initialized at runtime.

For general information about static instantiation, see 4.7 Static Instantiation of Kernel Objects, p.61. For information about static instantiation of semaphores, see 4.7.5 Static Instantiation Of Semaphores, p.64.

Scalable and Inline Semaphore Take and Give Routines

In addition to the standard semaphore give and take routines, VxWorks provides scalable and inline of variants for use with binary and mutex semaphores. These routines provide the following advantages:

■ Performance improvements for both UP and SMP configurations of VxWorks based on either—or both—scalable options and inline use.

■ Additional performance improvements for SMP over standard routines even if just inline variants are used, because they provide optimizations for uncontested take and give operations in an SMP system.

The scalable routines are designed for use with lightly contested resources when performance is of greater significance than features of the standard routines that provide for their robustness (such as various forms of error checking). Several options are available for de-selecting operational features that would normally be conducted for any given take or give operation.

The inline variants of the take and give routines provide the same options as the scalable routines, but also avoid the overhead associated with a function call. As with any inline code, repeated use adds to system footprint. If an application makes numerous calls to a routine for which there is an inline variant, either a wrapper should be created for the inline routine, or the scalable variant should be used instead.

The scalable and inline of variants are listed in Table 7-1; and the options for the scalable and inline routines are listed in Table 7-2). Note that in order to use these routines, you must include the h/inline/semLibInline.h header file.