VxWorks Reference Manual : Libraries
semMLib - mutual-exclusion semaphore library
semMCreate( ) - create and initialize a mutual-exclusion semaphore
semMGiveForce( ) - give a mutual-exclusion semaphore without restrictions
This library provides the interface to VxWorks mutual-exclusion semaphores. Mutual-exclusion semaphores offer convenient options suited for situations requiring mutually exclusive access to resources. Typical applications include sharing devices and protecting data structures. Mutual-exclusion semaphores are used by many higher-level VxWorks facilities.
The mutual-exclusion semaphore is a specialized version of the binary semaphore, designed to address issues inherent in mutual exclusion, such as recursive access to resources, priority inversion, and deletion safety. The fundamental behavior of the mutual-exclusion semaphore is identical to the binary semaphore (see the manual entry for semBLib), except for the following restrictions:
- It can only be used for mutual exclusion.
- It can only be given by the task that took it.
- It may not be taken or given from interrupt level.
- The semFlush( ) operation is illegal.These last two operations have no meaning in mutual-exclusion situations.
A special feature of the mutual-exclusion semaphore is that it may be taken "recursively," i.e., it can be taken more than once by the task that owns it before finally being released. Recursion is useful for a set of routines that need mutually exclusive access to a resource, but may need to call each other.
Recursion is possible because the system keeps track of which task currently owns a mutual-exclusion semaphore. Before being released, a mutual-exclusion semaphore taken recursively must be given the same number of times it has been taken; this is tracked by means of a count which is incremented with each semTake( ) and decremented with each semGive( ).
The example below illustrates recursive use of a mutual-exclusion semaphore. Function A requires access to a resource which it acquires by taking semM; function A may also need to call function B, which also requires semM:
SEM_ID semM; semM = semMCreate (...); funcA () { semTake (semM, WAIT_FOREVER); ... funcB (); ... semGive (semM); } funcB () { semTake (semM, WAIT_FOREVER); ... semGive (semM); }
If the option SEM_INVERSION_SAFE is selected, the library adopts a priority-inheritance protocol to resolve potential occurrences of "priority inversion," a problem stemming from the use semaphores for mutual exclusion. Priority inversion arises when a higher-priority task is forced to wait an indefinite period of time for the completion of a lower-priority task.
Consider the following scenario: T1, T2, and T3 are tasks of high, medium, and low priority, respectively. T3 has acquired some resource by taking its associated semaphore. When T1 preempts T3 and contends for the resource by taking the same semaphore, it becomes blocked. If we could be assured that T1 would be blocked no longer than the time it normally takes T3 to finish with the resource, the situation would not be problematic. However, the low-priority task is vulnerable to preemption by medium-priority tasks; a preempting task, T2, could inhibit T3 from relinquishing the resource. This condition could persist, blocking T1 for an indefinite period of time.
The priority-inheritance protocol solves the problem of priority inversion by elevating the priority of T3 to the priority of T1 during the time T1 is blocked on T3. This protects T3, and indirectly T1, from preemption by T2. Stated more generally, the priority-inheritance protocol assures that a task which owns a resource will execute at the priority of the highest priority task blocked on that resource. Once the task priority has been elevated, it remains at the higher level until all mutual-exclusion semaphores that the task owns are released; then the task returns to its normal, or standard, priority. Hence, the "inheriting" task is protected from preemption by any intermediate-priority tasks.
The priority-inheritance protocol also takes into consideration a task's ownership of more than one mutual-exclusion semaphore at a time. Such a task will execute at the priority of the highest priority task blocked on any of its owned resources. The task will return to its normal priority only after relinquishing all of its mutual-exclusion semaphores that have the inversion-safety option enabled.
The semDelete( ) call terminates a semaphore and deallocates any associated memory. The deletion of a semaphore unblocks tasks pended on that semaphore; the routines which were pended return ERROR. Take special care when deleting mutual-exclusion semaphores to avoid deleting a semaphore out from under a task that already owns (has taken) that semaphore. Applications should adopt the protocol of only deleting semaphores that the deleting task owns.
If the option SEM_DELETE_SAFE is selected, the task owning the semaphore will be protected from deletion as long as it owns the semaphore. This solves another problem endemic to mutual exclusion. Deleting a task executing in a critical region can be catastrophic. The resource could be left in a corrupted state and the semaphore guarding the resource would be unavailable, effectively shutting off all access to the resource.
As discussed in taskLib, the primitives taskSafe( ) and taskUnsafe( ) offer one solution, but as this type of protection goes hand in hand with mutual exclusion, the mutual-exclusion semaphore provides the option SEM_DELETE_SAFE, which enables an implicit taskSafe( ) with each semTake( ), and a taskUnsafe( ) with each semGive( ). This convenience is also more efficient, as the resulting code requires fewer entrances to the kernel.
There is no mechanism to give back or reclaim semaphores automatically when tasks are suspended or deleted. Such a mechanism, though desirable, is not currently feasible. Without explicit knowledge of the state of the guarded resource or region, reckless automatic reclamation of a semaphore could leave the resource in a partial state. Thus if a task ceases execution unexpectedly, as with a bus error, currently owned semaphores will not be given back, effectively leaving a resource permanently unavailable. The SEM_DELETE_SAFE option partially protects an application, to the extent that unexpected deletions will be deferred until the resource is released.
Because the priority of a task which has been elevated by the taking of a mutual-exclusion semaphore remains at the higher priority until all mutexes held by that task are released, unbounded priority inversion situations can result when nested mutexes are involved. If nested mutexes are required, consider the following alternatives:
- 1.
- Avoid overlapping critical regions.
- 2.
- Adjust priorities of tasks so that there are no tasks at intermediate priority levels.
- 3.
- Adjust priorities of tasks so that priority inheritance protocol is not needed.
- 4.
- Manually implement a static priority ceiling protocol using a non-inversion-save mutex. This involves setting all blockers on a mutex to the ceiling priority, then taking the mutex. After semGive, set the priorities back to the base priority. Note that this implementation reduces the queue to a fifo queue.
semLib.h
semMLib, semLib, semBLib, semCLib, VxWorks Programmer's Guide: Basic OS
semMCreate( ) - create and initialize a mutual-exclusion semaphore
SEM_ID semMCreate ( int options /* mutex semaphore options */ )
This routine allocates and initializes a mutual-exclusion semaphore. The semaphore state is initialized to full.
Semaphore options include the following:
- SEM_Q_PRIORITY (0x1)
- Queue pended tasks on the basis of their priority.
- SEM_Q_FIFO (0x0)
- Queue pended tasks on a first-in-first-out basis.
- SEM_DELETE_SAFE (0x4)
- Protect a task that owns the semaphore from unexpected deletion. This option enables an implicit taskSafe( ) for each semTake( ), and an implicit taskUnsafe( ) for each semGive( ).
- SEM_INVERSION_SAFE (0x8)
- Protect the system from priority inversion. With this option, the task owning the semaphore will execute at the highest priority of the tasks pended on the semaphore, if it is higher than its current priority. This option must be accompanied by the SEM_Q_PRIORITY queuing mode.
The semaphore ID, or NULL if memory cannot be allocated.
semMLib, semLib, semBLib, taskSafe( ), taskUnsafe( )
semMGiveForce( ) - give a mutual-exclusion semaphore without restrictions
STATUS semMGiveForce ( SEM_ID semId /* semaphore ID to give */ )
This routine gives a mutual-exclusion semaphore, regardless of semaphore ownership. It is intended as a debugging aid only.
The routine is particularly useful when a task dies while holding some mutual-exclusion semaphore, because the semaphore can be resurrected. The routine will give the semaphore to the next task in the pend queue or make the semaphore full if no tasks are pending. In effect, execution will continue as if the task owning the semaphore had actually given the semaphore.
This routine should be used only as a debugging aid, when the condition of the semaphore is known.
OK, or ERROR if the semaphore ID is invalid.