Difference between revisions of "OCEOSmp/blank"

From wiki
Jump to navigation Jump to search
 
(37 intermediate revisions by the same user not shown)
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, 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
|}
<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 ==


===<span style="color:#0000ff">oceos_sem_wait_continue()</span>===
===<span style="color:#0000ff">blank_function()</span>===
<blockquote style="border-left-style: none;">
<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 decrements the available permits of a sempahore otherwise returns an unsuccessful status code.
<span style="color:#1b7ac2">'''Prototype'''</span><br>
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>
<span style="color:#1b7ac2">'''Parameters'''</span><br>
{| class="wikitable"
|-
! Parameter !! Description
|-
| sem_id || U32_t value of semaphore to be decremented
|}
<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_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
|}
<span style="color:#1b7ac2">'''Example Usage'''</span><br>
<syntaxhighlight lang="C">
S32_t status;
...
// Decrement available permits on semaphore s_1
status = oceos_sem_wait_continue(s_1);
</syntaxhighlight>
</blockquote>
===<span style="color:#0000ff">oceos_sem_wait_restart()</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 decrements the available permits of a sempahore and if none available, the job is put on the pending queue.
<span style="color:#1b7ac2">'''Prototype'''</span><br>
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>
<span style="color:#1b7ac2">'''Parameters'''</span><br>
{| class="wikitable"
|-
! Parameter !! Description
|-
| sem_id || U32_t value of semaphore to be decremented
|}
<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_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
|}
<span style="color:#1b7ac2">'''Example Usage'''</span><br>
<syntaxhighlight lang="C">
S32_t status;
...
// Decrement available permits on semaphore s_1 otherwise job is put on pending queue
status = oceos_sem_wait_restart(s_1);
</syntaxhighlight>
</blockquote>
===<span style="color:#0000ff">oceos_sem_wait_restart_timeout()</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 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.
<span style="color:#1b7ac2">'''Prototype'''</span><br>
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>
<span style="color:#1b7ac2">'''Parameters'''</span><br>
{| class="wikitable"
|-
! Parameter !! Description
|-
| sem_id || U32_t value of semaphore to be decremented
|-
| timeout | U64_t timeout in time units. A value of 0 causes timeout to be ignored.
|}
<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_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
|}
<span style="color:#1b7ac2">'''Example Usage'''</span><br>
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>
===<span style="color:#0000ff">oceos_sem_get_value()</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 returns the number of available permits for the specified semaphore.
<span style="color:#1b7ac2">'''Prototype'''</span><br>
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>
<span style="color:#1b7ac2">'''Parameters'''</span><br>
{| class="wikitable"
|-
! Parameter !! Description
|-
| sem_id || U32_t value of semaphore whose permit count is required
|-
| s_permits || U32_t pointer to permits count holder
|}
<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_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
|}
<span style="color:#1b7ac2">'''Example Usage'''</span><br>
<syntaxhighlight lang="C">
S32_t status, permit_count;
...
// Get the available permits for semaphore s_1
status = oceos_sem_get_value(s_1, &permit_count);
</syntaxhighlight>
</blockquote>
===<span style="color:#0000ff">oceos_sem_penq_get_size()</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 returns the number of jobs on the specified semaphore pending queue.
<span style="color:#1b7ac2">'''Prototype'''</span><br>
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>
<span style="color:#1b7ac2">'''Parameters'''</span><br>
{| class="wikitable"
|-
! 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
|}
<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_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
|}
<span style="color:#1b7ac2">'''Example Usage'''</span><br>
<syntaxhighlight lang="C">
S32_t status, job_count;
...
// Get the available permits for semaphore s_1
status = oceos_sem_penq_get_size(s_1, &job_count);
</syntaxhighlight>
</blockquote>
===<span style="color:#0000ff">blank_function()</span>===
<blockquote style="border-left-style: none;">
<span style="color:#1b7ac2">'''Header File'''</span><br>
<span style="color:#1b7ac2">'''Header File'''</span><br>
'''''header.h'''''<br>
'''''header.h'''''<br>
Line 555: Line 20:
{| class="wikitable"
{| class="wikitable"
|-
|-
! Parameter !! Description
! Parameter || Description
|-
|-
| param || parameter to function
| param || parameter to function
Line 563: Line 28:
{| class="wikitable"
{| class="wikitable"
|-
|-
| Error bit  !! Description
! Error bit  !! Description
|-
| Error_name|| description
|-
|}
|}


Line 575: Line 43:
</syntaxhighlight>
</syntaxhighlight>
</blockquote>
</blockquote>


[[Category:backup]]
[[Category:backup]]

Latest revision as of 16:56, 3 May 2024

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
Error_name description

Example Usage

S32_t status, param;
...
// Do xyz
status = oceosmp_blank(param));
Retrieved from ‘https://wiki.ocetechnology.com/mediawiki/index.php?title=OCEOSmp/blank&oldid=1702’