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. When the semaphore becomes available but no task is pending on it, the events specified will be sent to the task registered by this function. A task can overwrite its own registration without first invoking semEvStop( ) or specifying the ALLOW_OVERWRITE option.

The option parameter is used for 3 user options: - Specify if the events are to be sent only once or every time the semaphore is free until semEvStop( ) is called. The option

EVENTS_SEND_ONCE (0x1)

tells the semaphore to send the events one time only. - Specify if another task can register itself while the current task is still registered. If so, the current task registration is overwritten without any warning. The option

EVENTS_ALLOW_OVERWRITE (0x2)

allows subsequent registrations to overwrite the current one. - Specify if events are to be sent at the time of the registration in the case the semaphore is free. The option

EVENTS_SEND_IF_FREE (0x4)

tells the registration process to send events if the semaphore is free. If none of these options are to be used, the option

EVENTS_OPTIONS_NONE

has to be passed to the options parameter.

WARNING

This routine cannot be called from interrupt level.

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.

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