Difference between revisions of "OCEOSmp/blank"
(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));