OCEOSmp/blank

Semaphores

oceos_sem_create()

Header File
semaphore.h

Description
This function creates a semaphore.

Prototype

/**
 * Create a counting semaphore
 *
 * @param sem_id            SEMAPHORE ID (from 0 to 62)
 * @param max_permits       number of max permits allowed for this SEMAPHORE, 1 to 4095
 * @param count_permits     starting number of permits available 0 to 4095
 * @param pending_q_size    MAX Number of tasks on SEMAPHORE pending queue 1 to 253
 * @param use_timeout       if TRUE, directive oceos_sem_wait_restart_timeout can be used
 *
 * @return  OCEOS_SUCCESS
 *          ERR_SYS_FIXED_CORRUPT       System Fixed area corrupt
 *          ERR_WRONG_CPU_CORE          Executing directive on wrong CPU
 *          ERR_WRONG_PHASE             Called before oceos_init() is done
 *          ERR_TOO_MANY                MAX number of SEMAPHOREs already created
 *          ERR_ID_INVALID              SEMAPHORE ID outside allowed range 0 to 62
 *          ERR_ID_WRONG                SEMAPHORE ID >= number of SEMAPHOREs
 *          ERR_SM_ALREADY_ALLOCATED    SEMAPHORE ID already used
 *          ERR_SM_MAX_PERMIT_WRONG     MAX permits outside allowed range 1 to 4095
 *          ERR_SM_COUNT_PERMIT_WRONG   Count permits outside allowed range 0 to 4095
 *          ERR_SM_COUNT_PERMIT_INVALID Count permits is greater than MAX permits for this SEMAPHORE
 *          ERR_SM_PENQ_SIZE_WRONG      SEMAPHORE pending queue size outside allowed range 1 to 253
 *          ERR_SM_TA_MAX_NUM_REACHED   Number of timed actions exceeds MAX allowed 255,
 *                                      each task on SEMAPHORE pending queue is timed action
 */
S32_t oceos_sem_create(
    sem_t sem_id,         // counting semaphore ID (MAX 63)
    U16_t max_permits,    // max number of permits (MAX 4095)
    U16_t count_permits,  // initial number of permits (MAX 4095)
    U8_t  pending_q_size, // max number of pending queue jobs (MAX 253)
    BOOLE_t use_timeout   // whether timeout is used in oceos_sem_wait_restart_timeout
);

Parameters

Parameter	Description
sem_id	Semaphore ID to be created (from 0 to 62)
max_permits	number of max permits allowed for this semaphore, 1 to 4095
count_permits	starting number of permits available 0 to 4095
pending_q_size	Maximum Number of tasks on SEMAPHORE pending queue 1 to 253
use_timeout	if TRUE, directive oceos_sem_wait_restart_timeout can be used

Returns
This function returns an S32_t with a value of OCEOS_SUCCESS (zero) or return code bits set as defined in the table below.

ERR_SYS_FIXED_CORRUPT	System Fixed area corrupt
ERR_WRONG_CPU_CORE	Executing directive on wrong CPU
ERR_WRONG_PHASE	Called before oceos_init() is done
ERR_TOO_MANY	MAX number of SEMAPHOREs already created
ERR_ID_INVALID	SEMAPHORE ID outside allowed range 0 to 62
ERR_ID_WRONG	SEMAPHORE ID >= number of SEMAPHOREs
ERR_SM_ALREADY_ALLOCATED	SEMAPHORE ID already used
ERR_SM_MAX_PERMIT_WRONG	MAX permits outside allowed range 1 to 4095
ERR_SM_COUNT_PERMIT_WRONG	Count permits outside allowed range 0 to 4095
ERR_SM_COUNT_PERMIT_INVALID	Count permits is greater than MAX permits for this SEMAPHORE
ERR_SM_PENQ_SIZE_WRONG	SEMAPHORE pending queue size outside allowed range 1 to 253
ERR_SM_TA_MAX_NUM_REACHED	Number of timed actions exceeds MAX allowed 255

Example Usage

S32_t status, param;
...
// Create semaphore called s_audi with max permits of 1000, starting permits of zero, max of 10 tasks on pending queue, and no timeouts 
status = oceos_sem_create(s_audi, 1000, 0, 10, FALSE);

oceos_sem_signal()

Header File
semaphore.h

Description
This function signals a semaphore, increments its count and transfers pending jobs to the ready queue.

Prototype

/**
 * Signals a semaphore, increments and transfers pending jobs to ready queue
 *
 * @param sem_id counting SEM ID
 *
 * @return  OCEOS_SUCCESS
 *          WARN_JOB_NOT_GUARDED
 *
 *          ERR_SYS_FIXED_CORRUPT       System Fixed area corrupt
 *          ERR_SYS_DYN_CORRUPT         System Dynamic area corrupt
 *          ERR_WRONG_PHASE             Directive was called before OCEOS initialisation is finished
 *          ERR_ID_INVALID              SEM ID outside allowed range 0 to 62
 *          ERR_ID_WRONG                SEM ID >= number of SEMs
 *          ERR_SYS_BUSY                Failed to grab SEM guard
 *          ERR_TOO_MANY                SEM max permits count already reached
 *          ERR_SM_JOB_ID_WRONG         Job ID of the task on SEM pending queue is wrong
 *          ERR_TA_NOT_FOUND            Timed action index to be removed for job not found
 *          ERR_TA_START_FAILED         Timed action re-start failed after job remove from timed action queue
 */
S32_t oceos_sem_signal(
    sem_t sem_id // counting SEM ID
);

Parameters

Parameter	Description
sem_id	U32_t value of semaphore to be signalled (incremented)

Returns
This function returns an S32_t with a value of OCEOS_SUCCESS (zero) or return code bits set as defined in the table below.

WARN_JOB_NOT_GUARDED	job not guarded, application should check system log
ERR_SYS_FIXED_CORRUPT	System Fixed area corrupt
ERR_SYS_DYN_CORRUPT	System Dynamic area corrupt
ERR_WRONG_PHASE	Directive was called before OCEOS initialisation is finished
ERR_ID_INVALID	SEM ID outside allowed range 0 to 62
ERR_ID_WRONG	SEM ID >= number of SEMs
ERR_SYS_BUSY	Failed to grab SEM guard
ERR_TOO_MANY	SEM max permits count already reached
ERR_SM_JOB_ID_WRONG	Job ID of the task on SEM pending queue is wrong
ERR_TA_NOT_FOUND	Timed action index to be removed for job not found
ERR_TA_START_FAILED	Timed action re-start failed after job remove from timed action queue

Example Usage

S32_t status;
...
// Signal s_audi semaphore (increment its count)
status = oceos_sem_signal(s_audi);

Next Section

oceos_sem_wait_continue()

Header File
semaphore.h

Description
This function decrements the available permits of a sempahore otherwise returns an unsuccessful status code.

Prototype

/**
 * Wait on semaphore,
 * decrement the number of available permits for semaphore,
 * if no permits continue and task should handle unsuccessful result
 *
 * @param sem_id SEM ID
 *
 * @return  OCEOS_SUCCESS
 *          ERR_SYS_FIXED_CORRUPT       System Fixed area corrupt
 *          ERR_SYS_DYN_CORRUPT         System Dynamic area corrupt
 *          ERR_WRONG_PHASE             Directive was called before OCEOS initialisation is finished
 *          ERR_ID_INVALID              SEM ID outside allowed range 0 to 62
 *          ERR_ID_WRONG                SEM ID >= number of SEMs
 *          ERR_SYS_BUSY                Failed to grab SEM guard
 *          ERR_SM_NOT_AVAILABLE        No more permits available for this SEM
 */
S32_t oceos_sem_wait_continue(
    sem_t sem_id // counting SEM ID
);

Parameters

Parameter	Description
sem_id	U32_t value of semaphore to be decremented

Returns
This function returns an S32_t with a value of OCEOS_SUCCESS (zero) or return code bits set as defined in the table below.

ERR_SYS_FIXED_CORRUPT	System Fixed area corrupt
ERR_SYS_DYN_CORRUPT	System Dynamic area corrupt
ERR_WRONG_PHASE	Directive was called before OCEOS initialisation is finished
ERR_ID_INVALID	SEM ID outside allowed range 0 to 62
ERR_ID_WRONG	SEM ID >= number of SEMs
ERR_SYS_BUSY	Failed to grab SEM guard
ERR_SM_NOT_AVAILABLE	No more permits available for this SEM

Example Usage

S32_t status;
...
// Decrement available permits on semaphore s_1
status = oceos_sem_wait_continue(s_1);

oceos_sem_wait_restart()

Header File
semaphore.h

Description
This function decrements the available permits of a sempahore and if none available, the job is put on the pending queue.

Prototype

/**
 * Waits on semaphore,
 * if fail, put job on pending queue and exit task
 *
 * @param sem_id SEM ID
 *
 * @return  OCEOS_SUCCESS
 *          ERR_SYS_FIXED_CORRUPT       System Fixed area corrupt
 *          ERR_SYS_DYN_CORRUPT         System Dynamic area corrupt
 *          ERR_WRONG_PHASE             Directive was called before OCEOS initialisation is finished
 *          ERR_ID_INVALID              SEM ID outside allowed range 0 to 62
 *          ERR_ID_WRONG                SEM ID >= number of SEMs
 *          ERR_SYS_BUSY                Failed to grab SEM guard
 *          ERR_SM_J_START_FROM_TIMOUT  Task started from timeout already, SEM no permits available second time
 *          ERR_FAILED                  Should never return this
 */
S32_t oceos_sem_wait_restart(
    sem_t sem_id  // counting SEM ID
);

Parameters

Parameter	Description
sem_id	U32_t value of semaphore to be decremented

Returns
This function returns an S32_t with a value of OCEOS_SUCCESS (zero) or return code bits set as defined in the table below.

ERR_SYS_FIXED_CORRUPT	System Fixed area corrupt
ERR_SYS_DYN_CORRUPT	System Dynamic area corrupt
ERR_WRONG_PHASE	Directive was called before OCEOS initialisation is finished
ERR_ID_INVALID	SEM ID outside allowed range 0 to 62
ERR_ID_WRONG	SEM ID >= number of SEMs
ERR_SYS_BUSY	Failed to grab SEM guard
ERR_SM_J_START_FROM_TIMOUT	Task started from timeout already, SEM no permits available second time
ERR_FAILED	Should never return this

Example Usage

S32_t status;
...
// Decrement available permits on semaphore s_1 otherwise job is put on pending queue
status = oceos_sem_wait_restart(s_1);

oceos_sem_wait_restart_timeout()

Header File
semaphore.h

Description
This function decrements the available permits of a sempahore and if none available, the job is put on the pending queue with a timeout enabled. The job is restarted either when a permit is available to be decremented or when the timeout has expired. In order to use this directive, semaphore must be created with flag use_timeout is set to TRUE.

Prototype

/**
 * Waits on semaphore,
 * if fail, put job on pending queue with optional timeout.
 * In order to use this directive, semaphore must be created with
 * flag use_timeout is set to TRUE
 *
 * @param sem_id         SEM ID
 * @param U64_t timeout  Restart time if no permits, 0 => ignore
 *
 * @return  OCEOS_SUCCESS
 *          ERR_SYS_FIXED_CORRUPT       System Fixed area corrupt
 *          ERR_SYS_DYN_CORRUPT         System Dynamic area corrupt
 *          ERR_WRONG_PHASE             Directive was called before OCEOS initialisation is finished
 *          ERR_TA_NOT_INIT             Timed action intialisation is not done and tried to be used; or SEM created without timeouts
 *          ERR_ID_INVALID              SEM ID outside allowed range 0 to 62
 *          ERR_ID_WRONG                SEM ID >= number of SEMs
 *          ERR_SYS_BUSY                Failed to grab SEM guard
 *          ERR_SM_J_START_FROM_TIMOUT  Task started from timeout already, SEM no permits available second time
 *          ERR_TOO_MANY                SEM pending queue is full
 *          ERR_FAILED                  Should never return this
 */
S32_t oceos_sem_wait_restart_timeout(
    sem_t sem_id, // counting SEM ID
    U64_t timeout // timeout, restart time if no permits, 0 => ignore
);

Parameters

Parameter	Description
sem_id	U32_t value of semaphore to be decremented
U64_t timeout in time units. A value of 0 causes timeout to be ignored.

Returns
This function returns an S32_t with a value of OCEOS_SUCCESS (zero) or return code bits set as defined in the table below.

ERR_SYS_FIXED_CORRUPT	System Fixed area corrupt
ERR_SYS_DYN_CORRUPT	System Dynamic area corrupt
ERR_WRONG_PHASE	Directive was called before OCEOS initialisation is finished
ERR_TA_NOT_INIT	Timed action intialisation is not done and tried to be used; or SEM created without timeouts
ERR_ID_INVALID	SEM ID outside allowed range 0 to 62
ERR_ID_WRONG	SEM ID >= number of SEMs
ERR_SYS_BUSY	Failed to grab SEM guard
ERR_SM_J_START_FROM_TIMOUT	Task started from timeout already, SEM no permits available second time
ERR_TOO_MANY	SEM pending queue is full
ERR_FAILED	Should never return this

Example Usage

S32_t status;
...
// Decrement available permits on semaphore s_1 otherwise job is put on pending queue with timeout of 10,000 time units (usually usecs)
status = oceos_sem_wait_restart_timeout(s_1);

oceos_sem_get_value()

Header File
semaphore.h

Description
This function returns the number of available permits for the specified semaphore.

Prototype

/**
 * Returns number of available permits
 * for SEM ID
 *
 * @param sem_id        SEM id
 * @param s_permits     pointer to permits count holder
 *
 * @return  OCEOS_SUCCESS
 *          ERR_SYS_FIXED_CORRUPT       System Fixed area corrupt
 *          ERR_SYS_DYN_CORRUPT         System Dynamic area corrupt
 *          ERR_WRONG_PHASE             Directive was called before OCEOS initialisation is finished
 *          ERR_ID_INVALID              SEM ID outside allowed range 0 to 62
 *          ERR_ID_WRONG                SEM ID >= number of SEMs
 *          ERR_SM_DATA_BAD             Data holder pointer is null
 */
S32_t oceos_sem_get_value(
    sem_t sem_id,    // counting SEM ID
    U32_t *s_permits // pointer to permits count holder
);

Parameters

Parameter	Description
sem_id	U32_t value of semaphore whose permit count is required
s_permits	U32_t pointer to permits count holder

Returns
This function returns an S32_t with a value of OCEOS_SUCCESS (zero) or return code bits set as defined in the table below.

ERR_SYS_FIXED_CORRUPT	System Fixed area corrupt
ERR_SYS_DYN_CORRUPT	System Dynamic area corrupt
ERR_WRONG_PHASE	Directive was called before OCEOS initialisation is finished
ERR_ID_INVALID	SEM ID outside allowed range 0 to 62
ERR_ID_WRONG	SEM ID >= number of SEMs
ERR_SM_DATA_BAD	Data holder pointer is null

Example Usage

S32_t status, permit_count;
...
// Get the available permits for semaphore s_1
status = oceos_sem_get_value(s_1, &permit_count);

oceos_sem_penq_get_size()

Header File
semaphore.h

Description
This function returns the number of jobs on the specified semaphore pending queue.

Prototype

/**
 * Returns number of jobs on semaphore pending queue
 * for semaphore ID
 *
 * @param sem_id    SEM id
 * @param s_size    pointer to pending queue size holder
 *
 * @return  OCEOS_SUCCESS
 *          ERR_SYS_FIXED_CORRUPT       System Fixed area corrupt
 *          ERR_SYS_DYN_CORRUPT         System Dynamic area corrupt
 *          ERR_WRONG_PHASE             Directive was called before OCEOS initialisation is finished
 *          ERR_ID_INVALID              SEM ID outside allowed range 0 to 62
 *          ERR_ID_WRONG                SEM ID >= number of SEMs
 *          ERR_SM_DATA_BAD             Data holder pointer is null
 */
S32_t oceos_sem_penq_get_size(
    sem_t sem_id,   // counting SEM ID
    U32_t *s_size   // pointer to pending queue size holder
);

Parameters

Parameter	Description
sem_id	U32_t value of semaphore whose permit count is required
s_size	U32_t pointer to pending queue jobs count holder

Returns
This function returns an S32_t with a value of OCEOS_SUCCESS (zero) or return code bits set as defined in the table below.

ERR_SYS_FIXED_CORRUPT	System Fixed area corrupt
ERR_SYS_DYN_CORRUPT	System Dynamic area corrupt
ERR_WRONG_PHASE	Directive was called before OCEOS initialisation is finished
ERR_ID_INVALID	SEM ID outside allowed range 0 to 62
ERR_ID_WRONG	SEM ID >= number of SEMs
ERR_SM_DATA_BAD	Data holder pointer is null

Example Usage

S32_t status, job_count;
...
// Get the available permits for semaphore s_1
status = oceos_sem_penq_get_size(s_1, &job_count);

blank_function()

Header File
header.h

Description
This function does xyz...

Prototype

S32_t oceosmp_blank(
    U32_t param
);

Parameters

Parameter	Description
param	parameter to function

Returns
This function returns an S32_t with a value of OCEOS_SUCCESS (zero) or return code bits set as defined in the table below.

Error bit  !! Description

Example Usage

S32_t status, param;
...
// Do xyz
status = oceosmp_blank(param));