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