Difference between revisions of "OCEOSmp/blank"

From wiki
Jump to navigation Jump to search
Line 177: Line 177:
</syntaxhighlight>
</syntaxhighlight>
</blockquote>
</blockquote>
== Next Section ==


===<span style="color:#0000ff">oceos_sem_wait_continue()</span>===
===<span style="color:#0000ff">oceos_sem_wait_continue()</span>===
Line 609: Line 607:
</syntaxhighlight>
</syntaxhighlight>
</blockquote>
</blockquote>
== Next Section ==


===<span style="color:#0000ff">blank_function()</span>===
===<span style="color:#0000ff">blank_function()</span>===

Revision as of 10:53, 1 May 2024

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

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

oceos_sem_reset()

Header File
semaphore.h

Description
This function restores the permits to the original semaphore initial value and removes any jobs from the pending queue.

Prototype

/**
 * Restore permits to original value and
 * remove jobs from pending queue
 *
 * @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_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_reset(
    sem_t sem_id   // counting SEM ID
);

Parameters

Parameter Description
sem_id U32_t value of semaphore to be reset

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_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;
...
// Reset semaphore s_1
status = oceos_sem_reset(s_1);

Next Section

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