Difference between revisions of "OCEOSmp/blank"

From wiki
Jump to navigation Jump to search
(Created page with "== Next Section == ===<span style="color:#0000ff">blank_function()</span>=== <blockquote style="border-left-style: none;"> <span style="color:#1b7ac2">'''Header File'''</span...")
 
Line 1: Line 1:
== Semaphores ==
===<span style="color:#0000ff">oceos_sem_create()</span>===
<blockquote style="border-left-style: none;">
<span style="color:#1b7ac2">'''Header File'''</span><br>
'''''semaphore.h'''''<br>
<span style="color:#1b7ac2">'''Description'''</span><br>
This function creates a semaphore.
<span style="color:#1b7ac2">'''Prototype'''</span><br>
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>
<span style="color:#1b7ac2">'''Parameters'''</span><br>
{| class="wikitable"
|-
! 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
|}
<span style="color:#1b7ac2">'''Returns'''</span><br>
This function returns an S32_t with a value of OCEOS_SUCCESS (zero) or return code bits set as defined in the table below.
{| class="wikitable"
|-
| 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
|}
<span style="color:#1b7ac2">'''Example Usage'''</span><br>
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>
===<span style="color:#0000ff">oceos_sem_signal()</span>===
<blockquote style="border-left-style: none;">
<span style="color:#1b7ac2">'''Header File'''</span><br>
'''''semaphore.h'''''<br>
<span style="color:#1b7ac2">'''Description'''</span><br>
This function signals a semaphore, increments its count and transfers pending jobs to the ready queue.
<span style="color:#1b7ac2">'''Prototype'''</span><br>
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>
<span style="color:#1b7ac2">'''Parameters'''</span><br>
{| class="wikitable"
|-
! Parameter !! Description
|-
| sem_id || U32_t value of semaphore to be signalled (incremented)
|}
<span style="color:#1b7ac2">'''Returns'''</span><br>
This function returns an S32_t with a value of OCEOS_SUCCESS (zero) or return code bits set as defined in the table below.
{| class="wikitable"
|-
| WARN_JOB_NOT_GUARDED        || job not guarded (TBD elaborate)
|-
| 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
|}
<span style="color:#1b7ac2">'''Example Usage'''</span><br>
<syntaxhighlight lang="C">
S32_t status;
...
// Signal s_audi semaphore (increment its count)
status = oceos_sem_signal(s_audi);
</syntaxhighlight>
</blockquote>
== Next Section ==
== Next Section ==


Line 39: Line 219:
</syntaxhighlight>
</syntaxhighlight>
</blockquote>
</blockquote>
[[Category:backup]]

Revision as of 13:18, 30 April 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 (TBD elaborate)
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

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