OCEOS/oceos inter-task communication/semaphore

From wiki
Jump to navigation Jump to search

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
Create a counting semaphore. If use_timeout = TRUE, timed actions must be initialized, please see here

Prototype

enum DIRECTIVE_STATUS   oceos_sem_create(
    sem_t sem_id,              // counting semaphore ID (0 to 62)
    U16_t max_permits,         // max number of permits (1 to 4094)
    U16_t count_permits,       // initial number of permits (1 to 4094)
    U16_t  pending_q_size,     // max number of pending queue jobs (1 to 255)
    BOOLE_t use_timeout        // whether timeout is used
);

Parameters

Parameter Description
sem_id Counting semaphore ID (0 to 62)
max_permits Max number of permits (1 to 4094)
count_permits Initial number of permits (1 to 4094)
pending_q_size Max number of pending queue jobs (1 to 254)
use_timeout Specify if timeout are required, so oceos_sem_wait_restart_timeout() can be used

Returns
This function returns enum DIRECTIVE_STATUS.

enum DIRECTIVE_STATUS Description
NOT_CONFIGURED System Meta pointer is NULL or corrupt
INCORRECT_STATE Init Meta pointer is NULL
INVALID_ID Semaphore id is not OK
INVALID_NUMBER max_permits or count_permits or pending_q_size is not OK
TOO_MANY max_permits > count_permits
INVALID_SIZE pending_q_size is zero
SUCCESSFUL OK

Example Usage

enum SEM_NAME{
    s_tesla,
    s_audi
}; 
enum DIRECTIVE_STATUS status;
status |= oceos_sem_create(s_tesla, 5, 5, 127, FALSE);
if(SUCCESSFUL != status) {
  // Handle ERROR
}

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

Retrieved from ‘https://wiki.ocetechnology.com/mediawiki/index.php?title=OCEOS/oceos_inter-task_communication/semaphore&oldid=1238’