OCEOS/oceos inter-task communication/semaphore

Semaphore

Semaphore Introduction

A counting semaphore has an integer value that is always greater than or equal to zero. This value is set initially when the semaphore is created and is modified by atomic wait and signal operations.
Each counting semaphore has a pending jobs queue of jobs waiting for the semaphore value to become greater than zero.
Unlike a mutex, which must become available after a finite number of cycles, a counting semaphore may remain unavailable, i.e. at value zero, indefinitely unless a timeout has been specified.

When a wait operation is performed the semaphore value is decremented unless the semaphore is already zero and an appropriate status code returned.

Unlike many other OS, the job that performs the wait operation does not block if the semaphore value is zero. Instead OCEOS provides three options for the wait operation:

• In the oceos_sem_wait_continue() option if the semaphore value is 0 it remains unchanged and an appropriate status code is returned, the job continues taking this returned value into account.
• In the oceos_sem_wait_restart() or oceos_sem_wait_restart_timeout() option if the semaphore is zero the job terminates and restarts from its beginning when the semaphore is signaled or the timeout occurs.
• A job that was restarted as a result of a timeout does not terminate if it comes to oceos_sem_wait_restart_timeout() and the semaphore is still zero, an appropriate status is returned and the job continues taking this into account.

When the semaphore is signaled, its value is incremented, and any jobs on its pending jobs queue are transferred to the ready queue and also removed from the timed jobs queue if present.

The pending jobs queue order of jobs with the same priority is preserved in this transfer. The scheduler is then activated and may pre-empt the current executing job.

Note

If timeouts are used with data queues the hardware specific timer initialization and handling must be set up by the developer please see here.

Semaphore Configuration

User must define NUMBER_OF_SEMAPHORES. If NUMBER_OF_SEMAPHORES is zero, semaphores are not used. The example can be found in OCEOS demo projects.
User must create defined number of semaphores before calling oceos_init_finish()

    #define NUMBER_OF_SEMAPHORES 2
    /*
     * Create the application configuration structure
     */
    struct application_configuration           app_config = {0};
   app_config.number_of_counting_semaphores = NUMBER_OF_SEMAPHORES;

API Functions

API Functions

Directive	Description	main	task	IRQ handler
oceos_sem_create()	Create semaphore	*
oceos_sem_signal()	Signals a semaphore		*	*
oceos_sem_wait_continue()	Wait on semaphore		*
oceos_sem_wait_restart()	Wait on semaphore		*
oceos_sem_wait_restart_timeout()	Wait on semaphore		*
oceos_sem_get_value()	Returns number of available permits		*	*
oceos_sem_penq_get_size()	Returns number of jobs on semaphore pending queue		*	*
oceos_sem_reset()	Restore permits to original value and frees tasks on pending queue		*	*

oceos_sem_create()

Header File
semaphore.h

Description

Prototype

Parameters

Parameter	Description

Returns
This function returns enum DIRECTIVE_STATUS.

enum DIRECTIVE_STATUS	Description
INCORRECT_STATE	If system Meta pointer is NULL or Init pointer is NULL or Start up phase check fail or Fixed data checksum failed (check log)
INVALID_NAME	If Start Sentinel for fixed area is corrupt or Start Sentinel for dynamic area is corrupt
INVALID_NUMBER	If Configuration and actual parameters do not match (In configuration file was defined 5 tasks, but created less)
SUCCESSFUL	If All OK

Example Usage

oceos_sem_signal()

Header File
semaphore.h

Description

Prototype

Parameters

Parameter	Description

Returns
This function returns enum DIRECTIVE_STATUS.

enum DIRECTIVE_STATUS	Description
INCORRECT_STATE	If system Meta pointer is NULL or Init pointer is NULL or Start up phase check fail or Fixed data checksum failed (check log)
INVALID_NAME	If Start Sentinel for fixed area is corrupt or Start Sentinel for dynamic area is corrupt
INVALID_NUMBER	If Configuration and actual parameters do not match (In configuration file was defined 5 tasks, but created less)
SUCCESSFUL	If All OK

Example Usage

oceos_sem_wait_continue()

Header File
semaphore.h

Description

Prototype

Parameters

Parameter	Description

Returns
This function returns enum DIRECTIVE_STATUS.

enum DIRECTIVE_STATUS	Description
INCORRECT_STATE	If system Meta pointer is NULL or Init pointer is NULL or Start up phase check fail or Fixed data checksum failed (check log)
INVALID_NAME	If Start Sentinel for fixed area is corrupt or Start Sentinel for dynamic area is corrupt
INVALID_NUMBER	If Configuration and actual parameters do not match (In configuration file was defined 5 tasks, but created less)
SUCCESSFUL	If All OK

Example Usage

oceos_sem_wait_restart()

Header File
semaphore.h

Description

Prototype

Parameters

Parameter	Description

Returns
This function returns enum DIRECTIVE_STATUS.

enum DIRECTIVE_STATUS	Description
INCORRECT_STATE	If system Meta pointer is NULL or Init pointer is NULL or Start up phase check fail or Fixed data checksum failed (check log)
INVALID_NAME	If Start Sentinel for fixed area is corrupt or Start Sentinel for dynamic area is corrupt
INVALID_NUMBER	If Configuration and actual parameters do not match (In configuration file was defined 5 tasks, but created less)
SUCCESSFUL	If All OK

Example Usage

oceos_sem_wait_restart_timeout()

Header File
semaphore.h

Description

Prototype

Parameters

Parameter	Description

Returns
This function returns enum DIRECTIVE_STATUS.

enum DIRECTIVE_STATUS	Description
INCORRECT_STATE	If system Meta pointer is NULL or Init pointer is NULL or Start up phase check fail or Fixed data checksum failed (check log)
INVALID_NAME	If Start Sentinel for fixed area is corrupt or Start Sentinel for dynamic area is corrupt
INVALID_NUMBER	If Configuration and actual parameters do not match (In configuration file was defined 5 tasks, but created less)
SUCCESSFUL	If All OK

Example Usage

oceos_sem_get_value()

Header File
semaphore.h

Description

Prototype

Parameters

Parameter	Description

Returns
This function returns enum DIRECTIVE_STATUS.

enum DIRECTIVE_STATUS	Description
INCORRECT_STATE	If system Meta pointer is NULL or Init pointer is NULL or Start up phase check fail or Fixed data checksum failed (check log)
INVALID_NAME	If Start Sentinel for fixed area is corrupt or Start Sentinel for dynamic area is corrupt
INVALID_NUMBER	If Configuration and actual parameters do not match (In configuration file was defined 5 tasks, but created less)
SUCCESSFUL	If All OK

Example Usage

oceos_sem_penq_get_size()

Header File
semaphore.h

Description

Prototype

Parameters

Parameter	Description

Returns
This function returns enum DIRECTIVE_STATUS.

enum DIRECTIVE_STATUS	Description
INCORRECT_STATE	If system Meta pointer is NULL or Init pointer is NULL or Start up phase check fail or Fixed data checksum failed (check log)
INVALID_NAME	If Start Sentinel for fixed area is corrupt or Start Sentinel for dynamic area is corrupt
INVALID_NUMBER	If Configuration and actual parameters do not match (In configuration file was defined 5 tasks, but created less)
SUCCESSFUL	If All OK

Example Usage

oceos_sem_reset()

Header File
semaphore.h

Description

Prototype

Parameters

Parameter	Description

Returns
This function returns enum DIRECTIVE_STATUS.

enum DIRECTIVE_STATUS	Description
INCORRECT_STATE	If system Meta pointer is NULL or Init pointer is NULL or Start up phase check fail or Fixed data checksum failed (check log)
INVALID_NAME	If Start Sentinel for fixed area is corrupt or Start Sentinel for dynamic area is corrupt
INVALID_NUMBER	If Configuration and actual parameters do not match (In configuration file was defined 5 tasks, but created less)
SUCCESSFUL	If All OK

Example Usage