OCEOSmp/blank
Jump to navigation
Jump to search
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));