VxWorks API Reference : OS Libraries

semEvLib

NAME

semEvLib - VxWorks events support for semaphores

ROUTINES

semEvStart( ) - start event notification process for a semaphore
semEvStop( ) - stop event notification process for a semaphore

DESCRIPTION

This library is an extension to eventLib, the events library. Its purpose is to support events for semaphores.

The functions in this library are used to control registration of tasks on a semaphore. The routine semEvStart( ) registers a task and starts the notification process. The function semEvStop( ) un-registers the task, which stops the notification mechanism.

When a task is registered and the semaphore becomes available, the events specified are sent to that task. However, if a semTake( ) is to be done afterwards, there is no guarantee that the semaphore will still be available.

INCLUDE FILES

semEvLib.h

SEE ALSO

eventLib, semLib, VxWorks Programmer's Guide: Basic OS

---

OS Libraries : Routines

semEvStart( )

NAME

semEvStart( ) - start event notification process for a semaphore

SYNOPSIS

STATUS semEvStart
    (
    SEM_ID semId,             /* semaphore on which to register events */
    UINT32 events,            /* 32 possible events to register */
    UINT8  options            /* event-related semaphore options */
    )

DESCRIPTION

This routine turns on the event notification process for a given semaphore, registering the calling task on that semaphore. When the semaphore becomes available but no task is pending on it, the events specified will be sent to the registered task. A task can always overwrite its own registration.

The option parameter is used for 3 user options:

• Specify if the events are to be sent only once or every time the semaphore
becomes free until semEvStop( ) is called.
• Specify if another task can subsequently register itself while the calling
task is still registered. If so specified, the existing task registration will be overwritten without any warning.
• Specify if events are to be sent at the time of the registration in the
case the semaphore is free.

Here are the respective values to be used to form the options field:

EVENTS_SEND_ONCE (0x1)

The semaphore will send the events only once.

EVENTS_ALLOW_OVERWRITE (0x2)

Allows subsequent registrations from other tasks to overwrite the current one.

EVENTS_SEND_IF_FREE (0x4)

The registration process will send events if the semaphore is free at the time semEvStart( ) is called.

EVENTS_OPTIONS_NONE

Must be passed to the options parameter if none of the other three options are used.

WARNING

This routine cannot be called from interrupt level.

WARNING

Task preemption can allow a semDelete to be performed between the calls to semEvStart and eventReceive. This will prevent the task from ever receiving the events wanted from the semaphore.

RETURNS

OK on success, or ERROR.

ERRNO

S_objLib_OBJ_ID_ERROR

The semaphore ID is invalid.

S_eventLib_ALREADY_REGISTERED

A task is already registered on the semaphore.

S_intLib_NOT_ISR_CALLABLE

Routine has been called from interrupt level.

S_eventLib_EVENTSEND_FAILED

User chose to send events right away and that operation failed.

S_eventLib_ZERO_EVENTS

User passed in a value of zero to the events parameter.

SEE ALSO

semEvLib, eventLib, semLib, semEvStop( )

---

OS Libraries : Routines

semEvStop( )

NAME

semEvStop( ) - stop event notification process for a semaphore

SYNOPSIS

STATUS semEvStop
    (
    SEM_ID semId
    )

DESCRIPTION

This routine turns off the event notification process for a given semaphore. It thus allows another task to register itself for event notification on that particular semaphore. It has to be called from the task that is already registered on that particular semaphore.

RETURNS

OK on success, or ERROR.

ERRNO

S_objLib_OBJ_ID_ERROR

The semaphore ID is invalid.

S_intLib_NOT_ISR_CALLABLE

Routine has been called at interrupt level.

S_eventLib_TASK_NOT_REGISTERED

Routine has not been called by the registered task.

SEE ALSO

semEvLib, eventLib, semLib, semEvStart( )