OCEOSmp/directive reference
Introduction
To be added
Directives
Initialisation directives
oceos_init()
Header File
initialisation.h
Description
Initialises OCEOS and must be the first directive used.Initialises the OCEOS system meta data using the information supplied in the application configuration and prepares for creation of tasks etc.
The values provided in the application configuration are checked as much as possible before being used.
The system log also is created here.
This function sets up sysMetaPtr and init_meta_ptr and must have completed successfully before tasks etc. can be created.
It disables interrupts and leaves them disabled, they will be re-enabled to the previous level after all tasks etc. have been created and oceos_init_finish() has completed successfully.
Prototype
/** * Initialises OCEOS and must be the first directive used. * * Initialises the OCEOS system meta data using the information supplied in * the application configuration and prepares for creation of tasks etc. * * The values provided in the application configuration are checked as much * as possible before being used. * * The system log also is created here. * * This function sets up sysMetaPtr and init_meta_ptr and must have completed * successfully before tasks etc. can be created. * * It disables interrupts and leaves them disabled, they will be re-enabled to * the previous level after all tasks etc. have been created and * oceos_init_finish() has completed successfully. * * @param app_config Pointer to configuration struct * @return SUCCESSFUL All OK * WARN_LOG_SIZE_DEFAULT Warning, log size is set to default value of 64 entries * WARN_NO_ERROR_FUNCTION Warning, user defined function for ERROR handling is not provided * ERR_CPU_FIRST_CORE_INVALID Start CPU not in a range of available cores for this target; or greater than end CPU * ERR_CPU_LAST_CORE_INVALID Last CPU not in a range of available cores for this target * ERR_NOT_START_CPU_CORE Executing oceos_init on wrong CPU * ERR_STACK_START_MISALIGNED Stack start address is not set by user misaligned * ERR_STACK_PER_CORE_INVALID Stack per CPU size is zero, or not 8byte aligned, or less then min require * ERR_LOG_ADDR_MISALIGNED Log start address is not 8 byte aligned * ERR_FIX_ADDR_MISALIGNED Fixed area start address is not 8 byte aligned * ERR_DYN_ADDR_MISALIGNED Dynamic area start address is not 8 byte aligned * ERR_CPU_CORE_RANGE_WRONG CPU cores in use exceed available CPUs on the SoC * ERR_STACK_SPACE_WRONG Current CPU SP is not within user provided stack range * ERR_LOG_SIZE_INVALID Log size outside expected range * ERR_CS_LOG_SIZE_INVALID Context switch log size invalid * ERR_TASK_NUMBER_INVALID Number of tasks invalid * ERR_MUTEX_NUMBER_INVALID Number of mutexes invalid * ERR_RWMUTEX_NUMBER_INVALID Number of rwmutexes invalid * ERR_SEM_NUMBER_INVALID Number of semaphores invalid * ERR_DATAQ_NUMBER_INVALID Number of datqs invalid * ERR_TIMED_ACTIONS_NUMBER_INVALID Number of timed actions invalid * ERR_OVERLAP_STACK Overlap stack end address with (two overlap areas are set) * ERR_OVERLAP_LOG Overlap log with (two overlap areas are set) * ERR_OVERLAP_FIXED Overlap fixed area with (two overlap areas are set) * ERR_OVERLAP_DYNAMIC Overlap dynamic area with (two overlap areas are set) * ERR_FIXED_MEMORY_FAILED Fixed area memory write fail * ERR_DYNAMIC_MEMORY_FAILED Dynamic area memory write fail * ERR_TIMER_ADDR_INVALID Timer address not provided by user (null). SPARC only * ERR_SYS_TIMER_INDEX_INVALID System timer index of subtimer invalid; SPARC only; Subtimers start from index 1; Need index of subtimer plus one in front * ERR_PERIPHERAL_CLOCK_INVALID System peripheral code invalid * */ S32_t oceos_init( const struct application_configuration app_config );Parameters
Parameter Description app_config Pointer to configuration struct. struct application_configuration defined in basic_structs.h 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 WARN_LOG_SIZE_DEFAULT Warning, log size is set to default value of 64 entries WARN_NO_ERROR_FUNCTION Warning, user defined function for ERROR handling is not provided ERR_CPU_FIRST_CORE_INVALID Start CPU not in a range of available cores for this target; or greater than end CPU ERR_CPU_LAST_CORE_INVALID Last CPU not in a range of available cores for this target ERR_NOT_START_CPU_CORE Executing oceos_init on wrong CPU ERR_STACK_START_MISALIGNED Stack start address is not set by user misaligned ERR_STACK_PER_CORE_INVALID Stack per CPU size is zero, or not 8byte aligned, or less then min require ERR_LOG_ADDR_MISALIGNED Log start address is not 8 byte aligned ERR_FIX_ADDR_MISALIGNED Fixed area start address is not 8 byte aligned ERR_DYN_ADDR_MISALIGNED Dynamic area start address is not 8 byte aligned ERR_CPU_CORE_RANGE_WRONG CPU cores in use exceed available CPUs on the SoC ERR_STACK_SPACE_WRONG Current CPU SP is not within user provided stack range ERR_LOG_SIZE_INVALID Log size outside expected range ERR_CS_LOG_SIZE_INVALID Context switch log size invalid ERR_TASK_NUMBER_INVALID Number of tasks invalid ERR_MUTEX_NUMBER_INVALID Number of mutexes invalid ERR_RWMUTEX_NUMBER_INVALID Number of rwmutexes invalid ERR_SEM_NUMBER_INVALID Number of semaphores invalid ERR_DATAQ_NUMBER_INVALID Number of datqs invalid ERR_TIMED_ACTIONS_NUMBER_INVALID Number of timed actions invalid ERR_OVERLAP_STACK Overlap stack end address with (two overlap areas are set) ERR_OVERLAP_LOG Overlap log with (two overlap areas are set) ERR_OVERLAP_FIXED Overlap fixed area with (two overlap areas are set) ERR_OVERLAP_DYNAMIC Overlap dynamic area with (two overlap areas are set) ERR_FIXED_MEMORY_FAILED Fixed area memory write fail ERR_DYNAMIC_MEMORY_FAILED Dynamic area memory write fail ERR_TIMER_ADDR_INVALID Timer address not provided by user (null). SPARC only ERR_SYS_TIMER_INDEX_INVALID System timer index of subtimer invalid; SPARC only; Subtimers start from index 1; Need index of subtimer plus one in front ERR_PERIPHERAL_CLOCK_INVALID System peripheral code invalid Example Usage
/* * Create the application configuration structure */ struct application_configuration app_config = {0}; /* * Fill in the application parameters */ app_config.log_address = (log_t)log_data; // required app_config.fixed_data_address = (adrs_t)fixed_data; // required app_config.dynamic_data_address = (adrs_t)dynamic_data; // required app_config.stack_start_address = start_stack_array[OCEOS_START_CPU_INDEX];// OCEOSMP_STACK_START_ADDRESS; app_config.stack_size_per_cpu = (U32_t)&__oceos_stack_size_per_cpu; // OCEOSMP_STACK_LOW_BOUND_ADDRESS; app_config.system_error_function = oceosmp_on_error; // NULL => ignore app_config.log_full_function = oceosmp_on_full_log; // NULL => ignore // used in setting up system log and fixed data array app_config.log_number_of_entries = NUMBER_OF_LOG_ENTRIES; // 0 => use default app_config.number_of_tasks = NUMBER_OF_TASKS; // >= 1 app_config.number_of_mutexes = NUMBER_OF_MUTEXES; app_config.number_of_rwmutexes = NUMBER_OF_RWMUTEXES; app_config.number_of_counting_semaphores = NUMBER_OF_SEMAPHORES; app_config.number_of_data_queues = NUMBER_OF_DATAQS; /** * FOR SPARC TARGET ONLY. */ app_config.sys_time_timer_index = SYS_TIME_TIMER_INDEX; // 0 => invalid index /** * FOR SPARC TARGET ONLY. * Not Used for ARM. Always Nested */ app_config.interrupt_nesting_enabled = TRUE; // TRUE => single vector app_config.oceos_cpu_switch_int_number = OCEOS_CPU_INTER_COM_INT_NUMBER; // User should provide SGI ID (0-15) app_config.timed_actions_queue_size = NUMBER_OF_ACTION_ENTRIES; app_config.CS_log_entries_base2 = CS_LOG_DEF_ENTRIES_BASE2; /** * Set starting index of CPU that will be used by OCEOSMP */ app_config.oceos_cpu_start_index = OCEOS_START_CPU_INDEX; /** * Set last index of CPU that will be used by OCEOSMP */ app_config.oceos_cpu_last_index = OCEOS_LAST_CPU_INDEX; /* * Set system/peripheral clock used to initialise system timer */ app_config.soc_peripheral_clck = BSP_SYSFREQ * 1000 * 1000; // initialise OCEOSMP S32_t status; status = oceos_init(app_config); if (OCEOS_SUCCESS > status) { oceosmp_print("\n oceos_init failure\n\r"); return 0; } else { return 1; } // else
oceos_init_finish()
Header File
initialisation.h
Description
Finalizes the fixed data array after all tasks etc. have been createdAll information needed to start OCEOS can be found in the fixed data area when oceos_init_finish() has completed.
Once all tasks etc. have been created oceos_init_finish() checks the accumulated information against the application configuration data stored in the fixed meta structure.
oceos_init_finish also calculates the size of the dynamic data area and checks it does not overlap with the system stack, the system log, or the fixed data, and if all ok sets up pointers to the various dynamic area components in the fixed data.
It then adds an XOR checksum to the fixed data area, and checks that this is followed by FILLER, which it replaces with the end sentinel.
On successful completion it restores the interrupt level to its value before oceos_init() was called, otherwise interrupts remain disabled.
Prototype
/** * Finalizes the fixed data array after all tasks etc. have been created * * All information needed to start OCEOS can be found in the fixed data area * when oceos_init_finish() has completed. * * Once all tasks etc. have been created oceos_init_finish() checks the * accumulated information against the application configuration data * stored in the fixed meta structure. * * oceos_init_finish also calculates the size of the dynamic data area and * checks it does not overlap with the system stack, the system log, or the * fixed data, and if all ok sets up pointers to the various dynamic area * components in the fixed data. * * It then adds an XOR checksum to the fixed data area, and checks that this * is followed by FILLER, which it replaces with the end sentinel. * * On successful completion it restores the interrupt level to its value * before oceos_init() was called, otherwise interrupts remain disabled. * * @return OCEOS_SUCCESS All OK * ERR_SYS_FIXED_CORRUPT System Meta data is NULL or corrupt * ERR_SYS_DYN_CORRUPT System Dynamic area corrupt * ERR_WRONG_CPU_CORE Executing directive on wrong CPU * ERR_WRONG_PHASE Called before oceos_init() * ERR_TASKS_INCOMPLETE Created wrong number of tasks * ERR_MUTEX_INCOMPLETE Created wrong number of mutexes * ERR_RWMUTEX_INCOMPLETE Created wrong number of rwmutexes * ERR_SEM_INCOMPLETE Created wrong number of semaphores * ERR_DATAQ_INCOMPLETE Created wrong number of dataqs * ERR_TASK_MAX_ID_INVALID Task's max id invalid * ERR_MUTEX_MAX_ID_INVALID Mutexe's max id invalid * ERR_RWMUTEX_MAX_ID_INVALID Rwmutexe's max id invalid * ERR_SEM_MAX_ID_INVALID Semaphore's max id invalid * ERR_DATAQ_MAX_ID_INVALID Dataq's max id invalid * ERR_TOTAL_JOBS_NUMBER_WRONG Wrong number of total jobs created * ERR_ORDER_ARRAY_PTR_INVALID Order array pointer is NULL or mis-aligned * ERR_FIXED_AREA_TOO_SMALL Not enough space for fixed data area */ S32_t oceos_init_finish(void);Parameters
There are no input parameters to this 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 ERR_SYS_FIXED_CORRUPT System Meta data is NULL or corrupt ERR_SYS_DYN_CORRUPT System Dynamic area corrupt ERR_WRONG_CPU_CORE Executing directive on wrong CPU ERR_WRONG_PHASE Called before oceos_init() ERR_TASKS_INCOMPLETE Created wrong number of tasks ERR_MUTEX_INCOMPLETE Created wrong number of mutexes ERR_RWMUTEX_INCOMPLETE Created wrong number of rwmutexes ERR_SEM_INCOMPLETE Created wrong number of semaphores ERR_DATAQ_INCOMPLETE Created wrong number of dataqs ERR_TASK_MAX_ID_INVALID Task's max id invalid ERR_MUTEX_MAX_ID_INVALID Mutexe's max id invalid ERR_RWMUTEX_MAX_ID_INVALID Rwmutexe's max id invalid ERR_SEM_MAX_ID_INVALID Semaphore's max id invalid ERR_DATAQ_MAX_ID_INVALID Dataq's max id invalid ERR_TOTAL_JOBS_NUMBER_WRONG Wrong number of total jobs created ERR_ORDER_ARRAY_PTR_INVALID Order array pointer is NULL or mis-aligned ERR_FIXED_AREA_TOO_SMALL Not enough space for fixed data area Example Usage
/* * Finish initialising OCEOS and setting up the fixed data */ status = oceos_init_finish(); if(OCEOS_SUCCESS > status){ // LOG oceosmp_print("\nAbandoning, problem ending OCEOS initialisation\n\r"); return -1; } // if
oceos_start()
Header File
initialisation.h
Description
Starts OCEOS scheduling.
Create dynamic OCEOS structures and start scheduling.
This function should only be called once and only after oceos_init() and oceos_init_finish() have been called successfully.
Normally this function does not return.
If a problem is detected the function terminates and returns an appropriate DIRECTIVE_STATUS code, with interrupts disabled.Prototype
/** * Starts OCEOS scheduling * * Create dynamic OCEOS structures and start scheduling * * This function should only be called once * and only after oceos_init() * and oceos_init_finish() have * been called successfully. * Normally this function does not return. * If a problem is detected the function * terminates and returns an appropriate * DIRECTIVE_STATUS code, with interrupts disabled. * * @param fixed_array_ptr Pointer to fixed data array * @param start_task Task ID * @param data_ptr Pointer to data to be passed to the task * @return OCEOSMP_EXIT OCEOSMP return from scheduling and exit * ERR_SYS_FIXED_CORRUPT Fixed area pointer is null or bad sentinel * ERR_FIXED_AREA_SIZE_WRONG Fixed area size is zero * ERR_FIXED_AREA_END_SENTINEL_BAD Fixed data end sentinel corrupt * ERR_FIXED_AREA_BAD_XOR Fixed area bad checksum or checksum mis-match * ERR_INIT_NOT_DONE oceos_start() called without initialisation * ERR_DYN_AREA_PTR_BAD Dynamic area pointer invalid in sysMetaPtr * ERR_INT_HANDLER_BAD IRQ controller pointer provided by BCC is NULL;or OCEOS handler is not set * ERR_DYN_JOB_PTR_BAD Job array pointer is NULL * ERR_FIXED_TASK_PTR_BAD Tasks array pointer is NULL * ERR_JOB_COUNT_WRONG Total job count inconsistent * ERR_DYN_MUTEX_PTR_BAD Mutex dynamic pointer is NULL * ERR_DYN_LOCK_PTR_BAD Mutex lock array pointer is NULL * ERR_DYN_RWMUTEX_PTR_BAD Rwmutex dynamic pointer is NULL * ERR_DYN_RWLOCK_PTR_BAD Rwmutex lock array pointer is NULL * ERR_FIXED_SEM_PTR_BAD Semaphore fixed pointer is NULL * ERR_DYN_SEM_PTR_BAD Semaphore dynamic pointer is NULL * ERR_SEM_PEND_PTR_BAD Semaphore pending queue pointer is NULL * ERR_FIXED_DATAQ_PTR_BAD Dataq fixed pointer is NULL * ERR_DYN_DATAQ_PTR_BAD Dataq dynamic pointer is NULL * ERR_DATAQ_PEND_PTR_BAD Dataq pending queue pointer is NULL * ERR_DATAQ_DATA_PTR_BAD Dataq data pointer is NULL * ERR_CPU_INT_NUMBER_INVALID SPARC only.IRQ number for CPU inter-comunication invalid(zero or used by timer) * ERR_REGISTER_CPU_IRQ_FAILED SPARC only. Failed to set CPU IRQ handler in BCC * ERR_CPU_STACK_INVALID Current CPU stack not within specified range * ERR_CPU_PRIORITY_STACK_INVALID Per CPU priority stack invalid * ERR_LOG_AREA_END_SENTINEL_BAD Log area end sentinel override * ERR_TA_CONFIG_PTR_BAD SPARC only; Timed action configuration data pointer is NULL * ERR_TA_TIMER_INDEX_INVALID SPARC only; Timed action sub-timer index in timer unit is invalid * ERR_TA_IRQ_NUMBER_INVALID SPARC only; Timer action timer IRQ number is invalid * ERR_TA_BCC_IRQ_REGISTER_FAILED SPARC only; Timed action timer IRQ handler failed to register */ S32_t oceos_start( const U32_t * const fixed_array_ptr,// pointer to fixed data array const U32_t start_task, // taskID void * const data_ptr // pointer to data to be passed to task );Parameters
Parameter Description fixed_array_ptr Pointer to fixed data array start_task Task ID data_ptr Pointer to data to be passed to the task 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 ERR_SYS_FIXED_CORRUPT Fixed area pointer is null or bad sentinel ERR_FIXED_AREA_SIZE_WRONG Fixed area size is zero ERR_FIXED_AREA_END_SENTINEL_BAD Fixed data end sentinel corrupt ERR_FIXED_AREA_BAD_XOR Fixed area bad checksum or checksum mis-match ERR_INIT_NOT_DONE oceos_start() called without initialisation ERR_DYN_AREA_PTR_BAD Dynamic area pointer invalid in sysMetaPtr ERR_INT_HANDLER_BAD IRQ controller pointer provided by BCC is NULL;or OCEOS handler is not set ERR_DYN_JOB_PTR_BAD Job array pointer is NULL ERR_FIXED_TASK_PTR_BAD Tasks array pointer is NULL ERR_JOB_COUNT_WRONG Total job count inconsistent ERR_DYN_MUTEX_PTR_BAD Mutex dynamic pointer is NULL ERR_DYN_LOCK_PTR_BAD Mutex lock array pointer is NULL ERR_DYN_RWMUTEX_PTR_BAD Rwmutex dynamic pointer is NULL ERR_DYN_RWLOCK_PTR_BAD Rwmutex lock array pointer is NULL ERR_FIXED_SEM_PTR_BAD Semaphore fixed pointer is NULL ERR_DYN_SEM_PTR_BAD Semaphore dynamic pointer is NULL ERR_SEM_PEND_PTR_BAD Semaphore pending queue pointer is NULL ERR_FIXED_DATAQ_PTR_BAD Dataq fixed pointer is NULL ERR_DYN_DATAQ_PTR_BAD Dataq dynamic pointer is NULL ERR_DATAQ_PEND_PTR_BAD Dataq pending queue pointer is NULL ERR_DATAQ_DATA_PTR_BAD Dataq data pointer is NULL ERR_CPU_INT_NUMBER_INVALID SPARC only.IRQ number for CPU inter-comunication invalid(zero or used by timer) ERR_REGISTER_CPU_IRQ_FAILED SPARC only. Failed to set CPU IRQ handler in BCC ERR_CPU_STACK_INVALID Current CPU stack not within specified range ERR_CPU_PRIORITY_STACK_INVALID Per CPU priority stack invalid ERR_LOG_AREA_END_SENTINEL_BAD Log area end sentinel override ERR_TA_CONFIG_PTR_BAD SPARC only; Timed action configuration data pointer is NULL ERR_TA_TIMER_INDEX_INVALID SPARC only; Timed action sub-timer index in timer unit is invalid ERR_TA_IRQ_NUMBER_INVALID SPARC only; Timer action timer IRQ number is invalid ERR_TA_BCC_IRQ_REGISTER_FAILED SPARC only; Timed action timer IRQ handler failed to register Example Usage
/* Sample Task names - all here start with t_ to help avoid name confusion */ enum TASK_NAME{ t_tom, // will have task ID 0 t_dick, // will have task ID 1 }; extern U32_t fixed_data[]; ... S32_t status; status = oceos_start(fixed_data, t_tom, NULL);
oceos_exit()
Header File
initialisation.h
Description
Ends scheduling and exit from oceos_start(). No task can be started after this.
OCEOS will exit when the current job ends.
An idle task in an endless loop should check that scheduling is enabled.Prototype
/** * Ends scheduling and exit from oceos_start. * No task can be started after this. * OCEOS will exit when the current job ends. * An idle task in an endless loop should check that scheduling is enabled. * * @return OCEOS_SUCCESS * ERR_SYS_FIXED_CORRUPT System Fixed area corrupt * ERR_WRONG_PHASE Called before scheduling started */ S32_t oceos_exit(void);Parameters
There are no input parameters to this 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 ERR_SYS_FIXED_CORRUPT System Fixed area corrupt ERR_WRONG_PHASE Called before scheduling started Example Usage
// Exit OCEOS oceos_exit();
oceos_CPU_sleep()
Header File
initialisation.h
Description
Puts CPU in sleep mode.
User must to be sure that interrupts are enabled.Prototype
/** * Puts CPU in sleep mode. * User must to be sure that interrupts are enabled. * * @return OCEOS_SUCCESS */ S32_t oceos_CPU_sleep(void);Parameters
There are no input parameters to this function.Returns
This function returns an S32_t with a value of OCEOS_SUCCESS (zero).Example Usage
// Put CPU to sleep oceos_CPU_sleep();
oceosmp_cpu_disable()
Header File
initialisation.h
Description
This function ends execution of all tasks running on particular CPU and removes the CPU from scheduling.Prototype
/** * Ends execution of all tasks running on particular CPU and removes this CPU from scheduling. * @param cpu_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 CPU ID outside allowed range 0 to 254 * ERR_ID_WRONG CPU ID >= number of available CPUs * ERR_CPU_ALREADY_DISABLED CPU already disabled */ S32_t oceosmp_cpu_disable( U32_t cpu_id );Parameters
Parameter Description cpu_id ID of CPU core to be disabled. 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 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 CPU ID outside allowed range 0 to 254 ERR_ID_WRONG CPU ID >= number of available CPUs ERR_CPU_ALREADY_DISABLED CPU already disabled Example Usage
S32_t status, faulty_cpu; ... // Disable faulty CPU core status = oceosmp_cpu_disable(faulty_cpu));
oceosmp_cpu_enable()
Header File
initialisation.h
Description
This function adds a disabled CPU core to the OCEOSmp scheduler. It should only be called after scheduling has startedPrototype
/** * Adds disabled CPU to OCEOSmp scheduler * * N.B. This function should only be called after scheduling has started * * @param cpu_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 CPU ID outside allowed range 0 to 254 * ERR_ID_WRONG CPU ID >= number of available CPUs; or the same as currently running * ERR_CPU_ALREADY_ENABLED CPU already enabled */ S32_t oceosmp_cpu_enable( U32_t cpu_id );Parameters
Parameter Description cpu_id ID of CPU core to be enabled. 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 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 CPU ID outside allowed range 0 to 254 ERR_ID_WRONG CPU ID >= number of available CPUs; or the same as currently running ERR_CPU_ALREADY_ENABLED CPU already enabled Example Usage
S32_t status, good_cpu; ... // Enable CPU core status = oceosmp_cpu_enable(good_cpu));
oceosmp_cpu_terminate()
Header File
initialisation.h
Description
This function removes a CPU core from the OCEOSmp scheduler and marks it so it cannot be restarted. It puts CPU to sleep with interrupts disabled. It should only be called after scheduling has started.Prototype
/** * Removes CPU from OCEOSMP scheduler and terminates, cannot be restarted. * Puts CPU to sleep with interrupts disabled * * N.B. This function should only be called after scheduling has started * Steps: * 1. Set terminate flag on this CPU; * 2. Trigger software interrupt to transfer execution to IRQ handler; * 3. Check flag and if set => put CPU to sleep in while loop with interrupts disabled; * 4. Set MAX priority on this CPU priority stack; * 5. Remove CPU from scheduling; * 6. Clean up all the tasks by calling task terminate function and free up all the * preempted jobs by this CPU; * * @param cpu_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 CPU ID outside allowed range 0 to 254 * ERR_ID_WRONG CPU ID >= number of available CPUs; or the same as currently running * ERR_CPU_ALREADY_TERMINATED CPU already terminated */ S32_t oceosmp_cpu_terminate( U32_t cpu_id );Parameters
Parameter Description cpu_id ID of CPU core to be terminated. 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 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 CPU ID outside allowed range 0 to 254 ERR_ID_WRONG CPU ID >= number of available CPUs; or the same as currently running ERR_CPU_ALREADY_TERMINATED CPU already terminated Example Usage
S32_t status, faulty_cpu; ... // Terminate CPU core status = oceosmp_cpu_terminate(faulty_cpu));
Task directives
| Directive | Description | main | task | IRQ handler |
| oceos_task_create() | Create Task | * | ||
| oceos_task_start() | Start Task | * | * | |
| oceos_task_timed_start() | Schedule a task to start execution at a given system time | * | * | |
| oceos_task_disable() | Disable Task | * | * | |
| oceos_task_enable() | Enable Task | * | * | |
| oceos_task_self() | Returns the task ID of the currently executing task | * | * | |
| oceos_task_get_priority() | Get priority of a task | * | * | |
| oceos_task_get_status() | Get status of a task | * | * | |
| oceos_task_kill() | Directive to terminate current task | * | * | |
| oceos_task_get_info() | Get task information | * | * | |
| oceosmp_task_kill() | Directive to terminate current task | * | * |
Task data structures
Header File
tasks.h
Description
The following data structures are used by some of the task directives.Data structures
/** * A pointer to this structure is passed to oceos_task_create(). * The structure is first initialised according to a tasks's parameters, * and is not used again after the task is created and may then be discarded. */ struct task_descriptor { void (*function_start)(void*); // name of task start function void (*function_end)(void*); // optional, NULL or task end function U32_t task_id; // 0 to 254, usually an enum U32_t task_jobs_max; // 1 to 15, max concurrent 'jobs' U32_t task_priority; // 1 (highest) to 254 (lowest) U32_t task_threshold; // >=1, <= task_priority (higher or same priority) U32_t task_turned_on_initially; // 0: disabled initially, else enabled U32_t time_deadline_microsecs; // start request to finish, 0 to ignore U32_t time_min_interval_microsecs; // between start requests, 0 to ignore U32_t uses_cpu_affinity; // 0: not restricted, else core restricted U32_t uses_cpu_affinity_core_id;// core ID to which restricted if affinity used }__attribute__ ((aligned (8))); /** * Task info used with oceos_task_get_info */ struct task_info { U64_t time_max_delay; // maximum time job is waiting on ready queue before becoming active U64_t time_max_finish; // maximum time to finish job execution after starting U64_t time_max_exec; // maximum time spent executing U64_t time_total_exec; // total CPU time used by this task U64_t time_min_gap_starts; // minimum time between job creations, can be reset U64_t time_min_gap_finish_start; // minimum time between job ending and new job creation, can be reset U64_t time_last_start; // time of most recent job creation U64_t time_last_finish; // time of most recent job finish unsigned int jobs_current_max :16; // maximum number of current jobs for this task, no roll over, can be reset unsigned int jobs_total :16; // number of times this task was started, no roll-over, can be reset U32_t jobs_current; // Number of task instances currently in use by oceos U32_t preempt_max; // maximum times any job was pre-empted, no roll-over, can be reset }__attribute__ ((aligned (8))); /* A task's status is returned as below if queried */ enum TASK_STATUS { TASK_DISABLED, // cannot be scheduled, and no current jobs TASK_ENABLED, // can be scheduled, but no current jobs TASK_INVALID, // task does not exist };oceos_task_create()
Header File
tasks.h
Description
Create a task. Can only be use before OCEOS starts. Stores the task information in the OCEOS fixed data area. This directive populates the data structures for a task. It should be called after oceos_init() and before oceos_init_finish().
It must be called for each task otherwise oceos_start() will return an error.Prototype
/** * Create a task using a task descriptor structure * * Can only be used in Initialisation Phase. * * A task has twelve constant parameters set when the task is created. * Rather than setting a list of these parameters the named fields of a * task_descriptor structure are set and a pointer to it passed here. * * The task_descriptor structure fields are described above. * Once the task has been created the structure can be discarded. * * To create a task: * set up a task_descriptor structure, * set its fields to the parameter values for the task, * pass a pointer to the structure to this directive. * * The structure is checked for validity by oceos_task_create and its * information used to set the task details in the OCEOS fixed data area. * * @param struct task_descriptor * fields give task characteristics * * @return OCEOS_SUCCESS No errors or warnings * WARN_NO_END_FUNCTION Warning, no end task function specified * * 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 tasks already created * ERR_ID_INVALID Task ID outside allowed range 0 to 254 * ERR_ID_WRONG Task ID outside >= number of tasks * ERR_T_ALREADY_ALLOCATED Task ID already in use * ERR_T_PRIORITY_INVALID Task priority outside allowed range 1 to 254 * ERR_THRESHOLD_INVALID Task threshold outside range 1 to 254 * ERR_THRESHOLD_WRONG Task threshold higher priority than task priority * ERR_JOBS_MAX_INVALID Job number outside range 1 to 15 * ERR_JOBS_TOO_MANY System capacity exceeded * ERR_AFFINITY_WRONG CPU core specified is outside chosen range * ERR_START_FUNCTION_BAD Task start function address either NULL or misaligned */ S32_t oceos_task_create( const struct task_descriptor * const task_description_ptr );Parameters
Parameter Description struct task_descriptor * Pointer to task descriptor which contains task attributes 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 WARN_NO_END_FUNCTION Warning, no end task function specified 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 tasks already created ERR_ID_INVALID Task ID outside allowed range 0 to 254 ERR_ID_WRONG Task ID outside >= number of tasks ERR_T_ALREADY_ALLOCATED Task ID already in use ERR_T_PRIORITY_INVALID Task priority outside allowed range 1 to 254 ERR_THRESHOLD_INVALID Task threshold outside range 1 to 254 ERR_THRESHOLD_WRONG Task threshold higher priority than task priority ERR_JOBS_MAX_INVALID Job number outside range 1 to 15 ERR_JOBS_TOO_MANY System capacity exceeded ERR_AFFINITY_WRONG CPU core specified is outside chosen range ERR_START_FUNCTION_BAD Task start function address either NULL or misaligned Example Usage
/* Sample Task names - all here start with t_ to help avoid name confusion */ enum TASK_NAME{ t_0, t_1, t_2 }; /* * APPLICATION FUNCTION DECLARATIONS */ void fun0(void *); void fun1(void *); void fun2(void *); void end_function(void *); const struct task_descriptor tasks_data[NUMBER_OF_TASKS] = { {fun0, end_function, t_0, 2, 10, 8, TASK_ENABLED, 0, 0, 0, 0}, {fun1, end_function, t_1, 2, 10, 8, TASK_ENABLED, 0, 0, 0, 0}, {fun2, end_function, t_2, 2, 10, 8, TASK_ENABLED, 0, 0, 0, 0} }; S32_t status; ... // create tasks (names are defined in the application header) for (i=0; i<NUMBER_OF_TASKS; i++){ if ( oceos_task_create(&tasks_data[i]) != OCEOS_SUCCESS ){ oceosmp_print("\nFailed to create task\n\r"); return -i; } }oceos_task_start()
Header File
tasks.h
Description
This function starts an instance of a task. An instance of a task is called a job in OCEOS terminology.Prototype
/** * Starting a task involves three main stages * 1 setting up a job * finding a free job entry if available * setting up this entry including passing it the data void * * * 2 placing the job on readyQ * * 3 doing a context switch * This function should only be called after OCEOS is initialised * and the dynamic task and job structures set up * * When used from an interrupt handler, * the context switch is only done * after all nested interrupts have unwound * * @param task_id Task ID must be in range 0 to 254 * @param ptr Pointer to task data * @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 Task ID is invalid * ERR_ID_WRONG Task ID is wrong * ERR_START_TASK_DISABLED Starting task is disabled * ERR_TOO_MANY There is no free job * ERR_SYS_BUSY Failed to grab the lock */ S32_t oceos_task_start( const U32_t task_id, // task ID, must be in range 0 to 254 void * const ptr // pointer to data );Parameters
Parameter Description task_id U32_t with Task ID in range 0 to 254. ptr void * pointer to task data 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 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 Task ID is invalid ERR_ID_WRONG Task ID is wrong ERR_START_TASK_DISABLED Starting task is disabled ERR_TOO_MANY There is no free job ERR_SYS_BUSY Failed to grab the lock Example Usage
S32_t status; void *ptr; ... // Start instance of task T_1 passing pointer ptr status = oceos_task_start(t_1,ptr);oceos_task_timed_start()
Header File
tasks.h
Description
This function schedules a task to start execution at a given system time.Prototype
/** * Schedule a task to start execution at a given system time * * The before and after offsets define a window around the selected time * in which the task may be started. * * If the current system time is before the start window a job is created * and a corresponding action put on the timed action queue. * * If the current system time is within the time window for starting the task, * it is started immediately. * * If the current system time is after the window, an error is reported. * * Times are in microseconds. * * This function should only be called after OCEOS is initialised * and the dynamic task and job structures set up * * @param taskID Task ID must be in range 0 to 254 * @param ptr Pointer to data * @param start_time System time at which job should start * @param before Forward tolerance for time * @param after Backward tolerance for time * @param return_job_id Return job_id to the user, to remove this job from timed action if needed * * @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 Task ID invalid * ERR_ID_WRONG Task ID is wrong * ERR_TA_NOT_INIT Timed action inialisation is not done and tried to be used * ERR_START_TASK_DISABLED Starting task is disabled * ERR_TOO_MANY There is no free job * ERR_TOO_LATE Starting task is too late(out of time frame) * ERR_SYS_BUSY Failed to grab the lock * ERR_TA_Q_FULL Timed action queue is full * ERR_TA_START_FAILED Timed action execute failed; See log */ S32_t oceos_task_timed_start( const U32_t task_id, // task ID, must be in range 0 to 254 void * const ptr, // pointer to data const U64_t start_time, // system time at which job should start const U32_t before, // forward tolerance for time const U32_t after, // backward tolerance for time U32_t * return_job_id // return job_id to the user, to remove this job from timed action if needed );Parameters
Parameter Description taskID U32_t task ID must be in range 0 to 254 ptr void * pointer to data start_time U64_t system time at which job should start before U32_t forward tolerance for time after U32_t backward tolerance for time return_job_id U32_t return job_id to the user, to remove this job from timed action if needed 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 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 Task ID invalid ERR_ID_WRONG Task ID is wrong ERR_TA_NOT_INIT Timed action inialisation is not done and tried to be used ERR_START_TASK_DISABLED Starting task is disabled ERR_TOO_MANY There is no free job ERR_TOO_LATE Starting task is too late(out of time frame) ERR_SYS_BUSY Failed to grab the lock ERR_TA_Q_FULL Timed action queue is full ERR_TA_START_FAILED Timed action execute failed; See log Example Usage
S32_t status; U32_t job_id; U64_t cur_sys_time; ... cur_sys_time = oceos_time_sys_get64(); // Start task 10,000 microseconds (us) from now and advise if started more than 1,000 us before or 2,000 us after. status = oceos_task_timed_start(t_2, ptr, cur_sys_time + 10000, 1000, 2000, &job_id);oceos_task_disable()
Header File
initialisation.h
Description
This function disables a task and removes any current pending jobs from the readyQ.Prototype
/** * Disable a task and remove any current pending jobs on readyQ. * * A disabled task's jobs will not be put into execution nor put on readyQ. * * Note that where execution of a task has already commenced, * disabling the task will not prevent it from completing. * * This function should only be called after OCEOS is initialised * and the dynamic task and job structures set up * * @param taskID Task ID must be in range 0 to 254 * @return: OCEOS_SUCCESS * WARN_ALREADY_DISABLED Task already disabled * WARN_SEM_PEND_REMOVE_FAILED Failed to remove job from semaphore pending queue * WARN_DQ_PEND_REMOVE_FAILED Failed to remove job from dataq pending queue * * ERR_SYS_FIXED_CORRUPT System Fixed area corrupt * ERR_SYS_DYN_CORRUPT System Dynamic area corrupt * ERR_WRONG_PHASE Directive was called before OCEOS init is finished * ERR_ID_INVALID Task ID is invalid * ERR_ID_WRONG Task ID is wrong * ERR_SYS_BUSY Failed to grab the lock */ S32_t oceos_task_disable( const U32_t task_id // task ID, must be in range 0 to 254 );Parameters
Parameter Description taskID U32_t task ID must be in range 0 to 254 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 WARN_ALREADY_DISABLED Task already disabled WARN_SEM_PEND_REMOVE_FAILED Failed to remove job from semaphore pending queue WARN_DQ_PEND_REMOVE_FAILED Failed to remove job from dataq pending queue ERR_SYS_FIXED_CORRUPT System Fixed area corrupt ERR_SYS_DYN_CORRUPT System Dynamic area corrupt ERR_WRONG_PHASE Directive was called before OCEOS init is finished ERR_ID_INVALID Task ID is invalid ERR_ID_WRONG Task ID is wrong ERR_SYS_BUSY Failed to grab the lock Example Usage
S32_t status; ... // Disable task t_1 status = oceos_task_disable(t_1);oceos_task_enable()
Header File
tasks.h
Description
This function enables a task. Only enabled tasks may be started.Prototype
/** * Enable a task - only enabled tasks are placed on readyQ or started. * * This function should only be called after OCEOS is initialised * and the dynamic task and job structures set up * * @param taskID Task ID must be in range 0 to 254 * @return OCEOS_SUCCESS * WARN_ALREADY_ENABLED Task already enabled * * 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 Task ID is invalid * ERR_ID_WRONG Task ID is wrong * ERR_SYS_BUSY Failed to grab the lock */ S32_t oceos_task_enable( const U32_t task_id // task ID, must be in range 0 to 254 );Parameters
Parameter Description taskID U32_t task ID must be in range 0 to 254 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 WARN_ALREADY_ENABLED Task already enabled 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 Task ID is invalid ERR_ID_WRONG Task ID is wrong ERR_SYS_BUSY Failed to grab the lock Example Usage
S32_t status; ... // Enable task t_2 status = oceos_task_enable(t_2);oceos_task_self()
Header File
tasks.h
Description
This function returns the task number of the currently running task on the calling CPU.Prototype
/** * Get currently running task on calling CPU * * @param t_id Task ID 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 init is finished * ERR_CPU_DYN_PTR_BAD CPU dynamic area pointer corrupt */ S32_t oceos_task_self( U32_t *t_id );Parameters
Parameter Description t_id S32_t * pointer to variable where task ID will be written. 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 ERR_SYS_FIXED_CORRUPT System Fixed area corrupt ERR_SYS_DYN_CORRUPT System Dynamic area corrupt ERR_WRONG_PHASE Directive was called before OCEOS init is finished ERR_CPU_DYN_PTR_BAD CPU dynamic area pointer corrupt Example Usage
S32_t status, task_running; ... // Return task ID that's running on this core status = oceos_task_self(&task_running);oceos_task_get_priority()
Header File
tasks.h
Description
This function returns the priority of the task ID passed to it.Prototype
/** * Get priority of the task * * @param taskID ID of task, must be in range 0 to 254 * @param t_priority Pointer to task priority 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 init is finished * ERR_ID_INVALID Task ID is invalid * ERR_ID_WRONG Task ID is wrong */ S32_t oceos_task_get_priority( const U32_t task_id, // task ID, must be in range 0 to 254 U32_t *t_priority // Pointer to task priority holder );Parameters
Parameter Description task_id S32_t task ID of task whose priority is required t_priority S32_t * pointer to variable where priority will be written 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 ERR_SYS_FIXED_CORRUPT System Fixed area corrupt ERR_SYS_DYN_CORRUPT System Dynamic area corrupt ERR_WRONG_PHASE Directive was called before OCEOS init is finished ERR_ID_INVALID Task ID is invalid ERR_ID_WRONG Task ID is wrong Example Usage
S32_t status; U32_t t_priority; ... // Return the priority of task ID t_4 status = oceos_task_get_priority(t_4, &t_priority);oceos_task_get_status()
Header File
tasks.h
Description
This function returns the status of the task ID passed to it.Prototype
/** * Get status of the task; * if OK t_status holds enum TASK_STATUS * * @param taskID ID of task, must be in range 0 to 254 * @param t_status enum TASK_STATUS 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 init is finished * ERR_ID_INVALID Task ID is invalid * ERR_ID_WRONG Task ID is wrong */ S32_t oceos_task_get_status( const U32_t task_id, U32_t *t_status );Parameters
Parameter Description task_id S32_t task ID of task whose priority is required t_status S32_t * pointer to variable where status will be written 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 ERR_SYS_FIXED_CORRUPT System Fixed area corrupt ERR_SYS_DYN_CORRUPT System Dynamic area corrupt ERR_WRONG_PHASE Directive was called before OCEOS init is finished ERR_ID_INVALID Task ID is invalid ERR_ID_WRONG Task ID is wrong Example Usage
S32_t status; U32_t t_status; ... // Return the status of task ID t_4 status = oceos_task_get_status(t_4, &t_status);oceos_task_get_info()
Header File
tasks.h
Description
This function returns the task information for the specified task.Prototype
/** * Get task information for task with ID. * * User must pass pointer to struct task_info in order to retrieve data. * * @param task_id Task ID * @param info Pointer to struct task_info * * @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 Task ID invalid * ERR_ID_WRONG Task ID wrong * ERR_TASK_INFO_PTR_BAD Task info pointer provided by user is NULL */ S32_t oceos_task_get_info ( const U32_t task_id, // Task ID struct task_info *info // Pointer to struct task_info );Parameters
Parameter Description task_id ID of task for which information is required task_info struct task_info * pointer to the structure where task information is to be written 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 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 Task ID invalid ERR_ID_WRONG Task ID wrong ERR_TASK_INFO_PTR_BAD Task info pointer provided by user is NULL Example Usage
S32_t status; struct task_info info; ... // Get information for task T3 status = oceos_task_get_info(t_3, &info);oceosmp_task_kill()
Header File
tasks.h
Description
This function kills the specified task running on the specified CPU.Prototype
/** * Function to kill currently running task on CPU; * Can be used: * From Mode_SVC => normal running mode for application * If nesting level is zero and Mode_SVC * From Mode_IRQ => from IRQ handler * If nesting level is not zero, set flag to call this function within IRQ handler * From Exception => Mode_ABT and Mode_UND * If nesting level is zero and NOT Mode_SVC, it is exception; * Disable IRQs on current CPU; * Set kill current task flag to TRUE; * Issue SGI on current CPU, will be interrupted on return from Exception and * this function will be called within IRQ handler * * @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_CPU_DYN_PTR_BAD CPU dynamic area pointer corrupt * ERR_ID_INVALID Task ID invalid * ERR_ID_WRONG Task ID wrong * ERR_CPU_ID_WRONG CPU ID wrong */ S32_t oceosmp_task_kill( U32_t task_id, U32_t cpu_id );Parameters
Parameter Description task_id U32_t task ID to be killed (must be in range 0 to 254) cpu_id U32_t CPU ID where task_id is to be killed 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 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_CPU_DYN_PTR_BAD CPU dynamic area pointer corrupt ERR_ID_INVALID Task ID invalid ERR_ID_WRONG Task ID wrong ERR_CPU_ID_WRONG CPU ID wrong Example Usage
S32_t status; ... // Kill task t_2 on CPU cpu_1 status = oceosmp_task_kill(t_2, cpu_1);Mutex directives
oceos_mutex_create()
Header File
mutex.h
Description
This function creates a mutex of specified ID with a specified priority ceiling.Prototype
/** * Creates a mutex with priority ceiling * * NOTE: This function should only be called after OCEOSmp is initialised with * oceos_init() and before initialisation ends with oceos_init_finish() * and scheduling starts with oceos_start() * * @param mutex_id mutex ID value 0 to 62 * @param priority mutex priority ceiling 1 to 254 (high to low task priority) * * @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 MUTEXs already created * ERR_ID_INVALID MUTEX ID outside allowed range 0 to 62 * ERR_ID_WRONG MUTEX ID >= number of MUTEXs * ERR_MX_ALREADY_ALLOCATED MUTEX ID already used * ERR_MX_PRIORITY_WRONG MUTEX priority ceiling outside allowed range 1 to 254 */ S32_t oceos_mutex_create( const U32_t mutex_id, // mutex ID, must be in range 0 to 62 const U8_t priority // mutex priority ceiling );Parameters
Parameter Description mutex_id u32_t mutex ID to be created (value 0 to 62). priority_ceiling U32_t mutex priority ceiling 1 to 254 (high to low task priority) 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 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 MUTEXs already created ERR_ID_INVALID MUTEX ID outside allowed range 0 to 62 ERR_ID_WRONG MUTEX ID >= number of MUTEXs ERR_MX_ALREADY_ALLOCATED MUTEX ID already used ERR_MX_PRIORITY_WRONG MUTEX priority ceiling outside allowed range 1 to 254 Example Usage
S32_t status; ... // Create mutex with ID print_mutex and priority ceiling of 5 status = oceos_mutex_create(print_mutex, 5);oceos_mutex_wait()
Header File
mutex.h
Description
This function makes the task wait until the specified mutex is available.Prototype
/* * Wait on mutex with ID. * If task succeeds in grabbing mutex, system level priority rises to * priority of this mutex, so tasks with lower or equal priority will * not be able to start till mutex is released. * * This should only be called after OCEOSmp scheduling has started. * * @param mutex_id const U32_t : value 0 to 62 * * @return OCEOS_SUCCESS * WARN_MX_INCORRECT_ORDER MUTEX acquired in incorrect order * * ERR_SYS_FIXED_CORRUPT System Fixed area corrupt * ERR_SYS_DYN_CORRUPT System Dynamic area corrupt * ERR_WRONG_PHASE Directive was called before OCEOSmp initialisation is finished * ERR_ID_INVALID MUTEX ID outside allowed range 0 to 62 * ERR_ID_WRONG MUTEX ID >= number of MUTEXs * ERR_MX_CEILING_BAD MUTEX ceiling not lower priority than job priority * ERR_MX_ALREADY_HELD MUTEX already held by this job * ERR_SYS_BUSY Failed to grab context switch guard */ S32_t oceos_mutex_wait( const U32_t mutex_id // mutex ID, must be in range 0 to 62 );Parameters
Parameter Description mutex_id u32_t mutex ID to be waited on (value 0 to 62). 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 WARN_MX_INCORRECT_ORDER MUTEX acquired in incorrect order ERR_SYS_FIXED_CORRUPT System Fixed area corrupt ERR_SYS_DYN_CORRUPT System Dynamic area corrupt ERR_WRONG_PHASE Directive was called before OCEOSmp initialisation is finished ERR_ID_INVALID MUTEX ID outside allowed range 0 to 62 ERR_ID_WRONG MUTEX ID >= number of MUTEXs ERR_MX_CEILING_BAD MUTEX ceiling not lower priority than job priority ERR_MX_ALREADY_HELD MUTEX already held by this job ERR_SYS_BUSY Failed to grab context switch guard Example Usage
S32_t status; ... // Wait on mutex m_2 status = oceos_mutex_wait(m_2);oceos_mutex_signal()
Header File
mutex.h
Description
This function signals the specified mutex.Prototype
/** * Signal a mutex with ID * * N.B. : * This function should not be called from an interrupt handler * This should only be called after OCEOSmp scheduling has started. * * @param mutex_id const U32_t : value 0 to 62 * * @return OCEOS_SUCCESS * WARN_MX_ALREADY_FREE MUTEX is free already * WARN_MX_NESTING_BAD MUTEX nesting incorrect * * ERR_SYS_FIXED_CORRUPT System Fixed area corrupt * ERR_SYS_DYN_CORRUPT System Dynamic area corrupt * ERR_WRONG_PHASE Directive was called before OCEOSmp initialisation is finished * ERR_ID_INVALID MUTEX ID outside allowed range 0 to 62 * ERR_ID_WRONG MUTEX ID >= number of MUTEXs * ERR_MX_WRONG_JOB MUTEX not held by this job * ERR_SYS_BUSY Failed to grab context switch guard */ S32_t oceos_mutex_signal( const U32_t mutex_id // mutex ID, must be in range 0 to 62 );Parameters
Parameter Description mutex_id u32_t mutex ID to be signalled (value 0 to 62). 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 WARN_MX_ALREADY_FREE MUTEX is free already WARN_MX_NESTING_BAD MUTEX nesting incorrect ERR_SYS_FIXED_CORRUPT System Fixed area corrupt ERR_SYS_DYN_CORRUPT System Dynamic area corrupt ERR_WRONG_PHASE Directive was called before OCEOSmp initialisation is finished ERR_ID_INVALID MUTEX ID outside allowed range 0 to 62 ERR_ID_WRONG MUTEX ID >= number of MUTEXs ERR_MX_WRONG_JOB MUTEX not held by this job ERR_SYS_BUSY Failed to grab context switch guard Example Usage
S32_t status; ... // Signal mutex m_2 status = oceos_mutex_signal(m_2);oceos_mutex_get_value()
Header File
mutex.h
Description
This function returns the value of the specified mutex.Prototype
/** * Get current value of mutex with ID * * @param mutex_id const U32_t : value 0 to 62 * @param m_value pointer to MUTEX value 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 OCEOSmp initialisation is finished * ERR_ID_INVALID MUTEX ID outside allowed range 0 to 62 * ERR_ID_WRONG MUTEX ID >= number of MUTEXs * ERR_MX_DATA_PTR_BAD Pointer to MUTEX value return holder is null */ S32_t oceos_mutex_get_value( const U32_t mutex_id, // mutex ID, must be in range 0 to 62 U32_t *m_value // Pointer to MUTEX value holder );Parameters
Parameter Description mutex_id u32_t mutex ID to be signalled (value 0 to 62) m_value u32_t * pointer where mutex value is to be written 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 ERR_SYS_FIXED_CORRUPT System Fixed area corrupt ERR_SYS_DYN_CORRUPT System Dynamic area corrupt ERR_WRONG_PHASE Directive was called before OCEOSmp initialisation is finished ERR_ID_INVALID MUTEX ID outside allowed range 0 to 62 ERR_ID_WRONG MUTEX ID >= number of MUTEXs ERR_MX_DATA_PTR_BAD Pointer to MUTEX value return holder is null Example Usage
S32_t status; U32_t value; ... // Get value of mutex m_2 status = oceos_mutex_get_value(m_2, &value);
Read/write mutex directives
Read/write mutex overview
Contents:
1. Read/Write Mutex features 2. Read/Write Mutex data structures 3. Read/Write Mutex constants 4. Read/Write Mutex manager DirectivesRead/Write Mutex Features
Read/Write Mutexes (rwmutexes) can be held for 'read' at the same time by multiple jobs on different CPUs, but once held for 'write' by any job cannot be obtained for 'read' or for 'write' by another job until released.
They can be used to allow data be read simultaneously by multiple jobs when the data is not being updated while ensuring that no updating can take place while any job is reading the data.
Pending write requests take precedence over pending read requests and are done on a first come, first served basis. Once any job on a CPU has a rwmutex for 'read' no other job on that CPU can acquire it so as to avoid potential problems and minimise delays in servicing write requests by other CPUs.
While any job holds a rwmutex for reading any job on another CPU can also acquire it for reading. Other jobs on the same CPU that may attempt to acquire the rwmutex are delayed in starting until return of the rwmutex. No job can acquire the rwmutex for writing until all read acquisitions have been returned.
No job will acquire a rwmutex for reading if any job is trying to acquire it for writing, giving write precedence over read. Multiple write requests waiting for existing read acquisitions to complete are serviced in the order in which they were made when the current read acquisitions complete.
If a task waits on a rwmutex that it already holds a system log entry is made (LOG_RWMUTEX_ALREADY_HELD) and an INTERNAL_ERROR status code returned.
If a task attempts to release a rwmutex it does not hold a system log entry is made (LOG_RWMUTEX_ALREADY_FREE) and an INTERNAL_ERROR status code returned.
If a job holds more than one rwmutex at the same time these must be acquired and released in a nested manner (e.g. wait 1, wait 2, wait 3, signal 3, signal 2, signal 1).
If a task exits while holding one or more rwmutexes these are returned and a system log entry made (LOG_RWMUTEX_NOT_RETURNED).
Read/Write Mutex data structures
In OCEOSmp each rwmutex has a priority ceiling, the priority of the highest priority task that acquires the rwmutex for read or for write. OCEOSmp uses this to ensure that once a job on a particular CPU has the rwmutex for reading or for writing no other job on that CPU can be started that might try to obtain that rwmutex.
The priority ceiling of a rwmutex is specified when the rwmutex is created and does not change subsequently. Priority ceilings are stored in the fixed data area as an array U8_t rwmutexCeilings[] indexed by mutex ID. This array is extended to be a whole number of 32-bit words.
A rwmutex has a unique rwmutex ID, an unsigned integer usually defined in the application header file as an enum RWMUTEX_NAME{} thus allowing a user-friendly name be associated with each rwmutex ID.
Using an enum is strongly recommended as it allows a user-friendly name be associated with each ID, and helps ensure IDs are contiguous from 0.
These rwmutex IDs are used as indices into both fixed and dynamic data arrays and must cover the range 0 to ((number of rwmutexes) -1). Using enum RWMUTEX_NAME{} automatically assigns names to IDs 0, 1, 2...
Read write mutex dynamic data such as the current write requests and current read count are stored in the dynamic data area in an array of struct rwmutex_dyn_block also indexed by the rwmutex ID.
A further dynamic area array of guard_t is used in providing mutual exclusion when updating the rwmutex dynamic data.
Read/Write Mutex constants
In OCEOSmp there can be a maximum of 63 rwmutexes, with IDs from 0 to 62 (the value 63 is used as an invalid ID).
The rwmutexes can be created in any order, but OCEOSmp will return an error and fail to start if the resulting IDs fail to be contiguous from 0 as IDs are used by OCEOS as indices into arrays.
Each rwmutex has a priority ceiling, the priority of the highest priority task that uses the rwmutex for reading or for writing. This is specified when the rwmutex is created, does not change subsequently, and must be in the range 1 (TASK_MAX_PRIORITY) to 254 (TASK_MIN_PRIORITY). The application developer must ensure that the correct rwmutex ceiling is used. OCEOSmp will detect an attempt to acquire a rwmutex by a task with higher priority than that rwmutex's priority ceiling, make a system log entry (LOG_RWMUTEX_BAD_CEILING) and return an INTERNAL_ERROR status code.
oceos_rwmutex_create()
Header File
rwmutex.h
Description
This function ees a read/write mutex.Prototype
/** * Creates a Read/Write Mutex (RWMUTEX) * * This function should only be called after OCEOSmp is initialised with * oceos_init() and before initialisation ends with oceos_init_finish() * and scheduling starts with oceos_start() * * @param rwm_id Read/Write RWMUTEX ID, must be in range 0 to 62 * @param priority Priority ceiling of highest priority task that uses the RWMUTEX * * @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 RWMUTEXs already created * ERR_ID_INVALID RWMUTEX ID outside allowed range 0 to 62 * ERR_ID_WRONG RWMUTEX ID >= number of RWMUTEXs * ERR_RWMX_ALREADY_ALLOCATED RWMUTEX ID already used * ERR_RWMX_PRIORITY_WRONG RWMUTEX priority ceiling outside allowed range 1 to 254 */ S32_t oceos_rwmutex_create( const U32_t rwm_id, // RWMUTEX ID, must be in range 0 to max rwm const U8_t priority // RWMUTEX priority ceiling );Parameters
Parameter Description rwm_id Read/Write RWMUTEX ID, must be in range 0 to 62 priority Priority ceiling of highest priority task that uses the RWMUTEX 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 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 RWMUTEXs already created ERR_ID_INVALID RWMUTEX ID outside allowed range 0 to 62 ERR_ID_WRONG RWMUTEX ID >= number of RWMUTEXs ERR_RWMX_ALREADY_ALLOCATED RWMUTEX ID already used ERR_RWMX_PRIORITY_WRONG RWMUTEX priority ceiling outside allowed range 1 to 254 Example Usage
S32_t status; ... // Create read/write mutex with ID rwm_2 and priority ceiling of 100 status = oceos_rwmutex_create(rwm_1, 100);oceos_rwmutex_read_wait()
Header File
rwmutex.h
Description
This function acquires a read/write mutex for read. If successful, jobs on other CPUs can also acquire it for read, but no job will be able to acquire it for write while any read is under way. If job already holds RWMUTEX for read or for write the appropriate status code is returned, a system log entry made, and the job continues. It will not succeed while any job is waiting to obtain RWMUTEX for write, and will loop waiting for all pending writes on this RWMUTEX to complete.Prototype
/** * Read wait on RWMUTEX. * * If successful jobs on other CPUs can also acquire it for read, but no job * will be able to acquire it for write while any read is under way. * If job already holds RWMUTEX for read or for write appropriate status code * is returned, a system log entry made, and the job continues. * Will not succeed while any job is waiting to obtain RWMUTEX for write, * will loop waiting for all pending writes on this RWMUTEX to complete. * * This should only be called after OCEOS scheduling has started. * * N.B. The returned status code must be checked and appropriate action * taken. * * @param rwm_id const U32_t : value 0 to 62 * * @return OCEOS_SUCCESS * WARN_RWMX_NOT_HIGHEST Already holds a RWMUTEX higher in the RWMUTEX order * (there then may be a risk of deadlock) * * 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 RWMUTEX ID outside allowed range 0 to 62 * ERR_ID_WRONG RWMUTEX ID >= number of RWMUTEXs * ERR_RWMX_CEILING_BAD RWMUTEX ceiling not lower priority than job priority * ERR_RWMX_ALREADY_HELD RWMUTEX already held by this job * ERR_RWMX_CPU_STACK_FULL CPU priority ceiling stack full */ S32_t oceos_rwmutex_read_wait( const U32_t rwm_id // RWMUTEX ID, must be in range 0 to 62 );Parameters
Parameter Description rwm_id U32_t rwmutex to be acquired for read (value 0 to 62) 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 WARN_RWMX_NOT_HIGHEST Already holds a RWMUTEX higher in the RWMUTEX order (deadlock risk) 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 RWMUTEX ID outside allowed range 0 to 62 ERR_ID_WRONG RWMUTEX ID >= number of RWMUTEXs ERR_RWMX_CEILING_BAD RWMUTEX ceiling not lower priority than job priority ERR_RWMX_ALREADY_HELD RWMUTEX already held by this job ERR_RWMX_CPU_STACK_FULL CPU priority ceiling stack full Example Usage
S32_t status; ... // Acquire read/write mutex rwm_1 for read status = oceos_rwmutex_read_wait(rwm_1);oceos_rwmutex_write_wait()
Header File
rwmutex.h
Description
This function acquires the specified read/write mutex for write. If successful, no other job can also obtain it for reading or for writing. Will not succeed while any other job has acquired RWMUTEX for write, or any jobs have obtained RWMUTEX for read. Will then loop until the RWMUTEX is released and for its turn in the sequence of jobs that have tried to acquire the RWMUTEX for writing. If already holds the RWMUTEX for writing or reading an appropriate status code is returned, a system log entry made, and the job continues. While there are any outstanding attempts to obtain the RWMUTEX for write no job will be able to acquire it for reading.Prototype
/** * Write wait on RWMUTEX. * * If successful no other job can also obtain it for reading or for writing. * Will not succeed while any other job has acquired RWMUTEX for write, * or any jobs have obtained RWMUTEX for read. Will then loop until the * RWMUTEX is released and for its turn in the sequence of jobs that have * tried to acquire the RWMUTEX for writing. * If already holds the RWMUTEX for writing or reading an appropriate status * code is returned, a system log entry made, and the job continues. * While there are any outstanding attempts to obtain the RWMUTEX for write * no job will be able to acquire it for reading. * * This should only be called after OCEOS scheduling has started. * * N.B. The returned status code must be checked and appropriate action * taken. * * @param rwm_id const U32_t : value 0 to 62 * * @return OCEOS_SUCCESS * WARN_RWMX_NOT_HIGHEST Already holds a RWMUTEX higher in the RWMUTEX order * (there then may be a risk of deadlock) * 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 RWMUTEX ID outside allowed range 0 to 62 * ERR_ID_WRONG RWMUTEX ID >= number of MUTEXs * ERR_RWMX_CEILING_BAD RWMUTEX ceiling not lower priority than job priority * ERR_RWMX_ALREADY_HELD RWMUTEX already held by this job * ERR_RWMX_CPU_STACK_FULL CPU priority ceiling stack full */ S32_t oceos_rwmutex_write_wait( const U32_t rwm_id // RWMUTEX ID, must be in range 0 to 62 );Parameters
Parameter Description rwm_id U32_t rwmutex to be acquired for write(value 0 to 62) 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 WARN_RWMX_NOT_HIGHEST Already holds a RWMUTEX higher in the RWMUTEX order (deadlock risk) 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 RWMUTEX ID outside allowed range 0 to 62 ERR_ID_WRONG RWMUTEX ID >= number of MUTEXs ERR_RWMX_CEILING_BAD RWMUTEX ceiling not lower priority than job priority ERR_RWMX_ALREADY_HELD RWMUTEX already held by this job ERR_RWMX_CPU_STACK_FULL CPU priority ceiling stack full Example Usage
S32_t status; ... // Acquire read/write mutex rwm_1 for write status = oceos_rwmutex_read_wait(rwm_1);oceos_rwmutex_signal()
Header File
rwmutex.h
Description
This function signals the specified read/write mutex. It frees the RWMUTEX for use by other jobs, irrespective of whether the RWMUTEX is held for reading or for writing. If the RWMUTEX is not held by the job then it returns an appropriate status code. It does not take into account how many times a job has obtained the RWMUTEX for read or for write.Prototype
/** * Signal a RWMUTEX * * Frees the RWMUTEX for use by other jobs, irrespective of whether * RWMUTEX is held for reading or for writing. * if the RWMUTEX is not held by the job returns an appropriate status code. * Does not take into account how many times a job has obtained the RWMUTEX * for read or for write. * * This should only be called after OCEOS scheduling has started. * * N.B. The returned status code must be checked and appropriate action taken. * * @param rwm_id const U32_t : value 0 to 62 * * @return OCEOS_SUCCESS * WARN_RWMX_ALREADY_FREE RWMUTEX is free already * * 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 RWMUTEX ID outside allowed range 0 to 62 * ERR_ID_WRONG RWMUTEX ID >= number of MUTEXs * ERR_RWMX_CEILING_BAD RWMUTEX ceiling not lower priority than job priority * ERR_RWMX_CPU_STACK_EMPTY CPU priority ceiling stack empty * ERR_RWMX_CEILING_INVALID CPU current priority ceiling on the priority stack is invalid */ S32_t oceos_rwmutex_signal( const U32_t rwm_id // RWMUTEX ID, must be in range 0 to 62 );Parameters
Parameter Description rwm_id U32_t rwmutex to be signaled(value 0 to 62) 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 WARN_RWMX_ALREADY_FREE RWMUTEX is free already 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 RWMUTEX ID outside allowed range 0 to 62 ERR_ID_WRONG RWMUTEX ID >= number of MUTEXs ERR_RWMX_CEILING_BAD RWMUTEX ceiling not lower priority than job priority ERR_RWMX_CPU_STACK_EMPTY CPU priority ceiling stack empty ERR_RWMX_CEILING_INVALID CPU current priority ceiling on the priority stack is invalid Example Usage
S32_t status; ... // Signal read/write mutex number rwm_4 status = oceos_rwmutex_signal(rwm_4);
oceos_rwmutex_check_status()
Header File
rwmutex.h
Description
This function checks the status of a read/write mutex. The possible states are free, in-use for read, and in-use for write.Prototype
/** * Check whether RWMUTEX is free * * @param rwm_id must be in range 0 to 62 * @param m_status pointer to RWMUTEX status holder; * if return code OCEOS_SUCCESS RWMUTEX status: * 0 => Free for use * 1 => In use for read * 2 => In use for write * * @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 RWMUTEX ID outside allowed range 0 to 62 * ERR_ID_WRONG RWMUTEX ID >= number of MUTEXs * ERR_RWMX_DATA_PTR_BAD Pointer to RWMUTEX status return holder is null */ S32_t oceos_rwmutex_check_status( const U32_t rwm_id, // RWMUTEX ID, must be in range 0 to 62 U32_t *m_status );Parameters
Parameter Description rwm_id read/write mutex number in range 0 to 62 m_status U32_t pointer to RWMUTEX status holder (0 = free, 1 = in-use for read, 2 = in-use for write 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 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 RWMUTEX ID outside allowed range 0 to 62 ERR_ID_WRONG RWMUTEX ID >= number of MUTEXs ERR_RWMX_DATA_PTR_BAD Pointer to RWMUTEX status return holder is null Example Usage
S32_t status, rwm_status; ... // Check the status of read/write mutex rwm_2 status = oceos_rwmutex_check_status(rwm_2, &rwm_status);oceos_rwmutex_reading_count()
Header File
rwmutex.h
Description
This function returns the current number of jobs holding a specified read/write mutex for read.Prototype
/** * * Get current number of jobs holding RWMUTEX for read * * @param rwm_id must be in range 0 to 62 * @param m_count pointer to RWMUTEX 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 RWMUTEX ID outside allowed range 0 to 62 * ERR_ID_WRONG RWMUTEX ID >= number of MUTEXs * ERR_RWMX_DATA_PTR_BAD Pointer to RWMUTEX count return holder is null */ S32_t oceos_rwmutex_reading_count( const U32_t rwm_id, // RWMUTEX ID, must be in range 0 to 62 U32_t *m_count );Parameters
Parameter Description rwm_id U32 value of read/write mutex (in range 0 to 62) m_count U32_t pointer to read/write mutex 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.
Error bit Description 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 RWMUTEX ID outside allowed range 0 to 62 ERR_ID_WRONG RWMUTEX ID >= number of MUTEXs ERR_RWMX_DATA_PTR_BAD Pointer to RWMUTEX count return holder is null Example Usage
S32_t status, rwm_count; ... // Get the number of jobs holding the read/write mutex rwm_2 for read status = oceos_rwmutex_reading_count(rwm_2, &rwm_count);
oceos_rwmutex_write_reqs_count()
Header File
header.h
Description
This function returns the current number of write requests for the specified read/write mutex .Prototype
/** * Get current RWMUTEX write requests count * * @param rwm_id must be in range 0 to 62 * @param m_count pointer to RWMUTEX 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 RWMUTEX ID outside allowed range 0 to 62 * ERR_ID_WRONG RWMUTEX ID >= number of MUTEXs * ERR_RWMX_DATA_PTR_BAD Pointer to RWMUTEX count return holder is null */ S32_t oceos_rwmutex_write_reqs_count( const U32_t rwm_id, // RWMUTEX ID, must be in range 0 to 62 U32_t *m_count );Parameters
rwm_id U32_t value of read/write mutex (must be in range 0 to 62) m_count U32_t pointer to read/write mutex 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.
Error bit Description 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 RWMUTEX ID outside allowed range 0 to 62 ERR_ID_WRONG RWMUTEX ID >= number of MUTEXs ERR_RWMX_DATA_PTR_BAD Pointer to RWMUTEX count return holder is null Example Usage
S32_t status, rwm_count; ... // Get the count of cuurent write requests for read/write mutex rwm_1 status = oceos_rwmutex_write_reqs_count(rwm_1, &rwm_count);oceos_rwmutex_writes_pending_count()
Header File
rwmutex.h
Description
This function returns the current number of pending writes for the specified read/write mutex.Prototype
/** * Get current RWMUTEX writes pending count * * @param rwm_id must be in range 0 to 62 * @param m_count pointer to RWMUTEX 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 RWMUTEX ID outside allowed range 0 to 62 * ERR_ID_WRONG RWMUTEX ID >= number of MUTEXs * ERR_RWMX_DATA_PTR_BAD Pointer to RWMUTEX pending count return holder is null */ S32_t oceos_rwmutex_writes_pending_count( const U32_t rwm_id, // RWMUTEX ID, must be in range 0 to 62 U32_t *m_count );Parameters
Parameter Description rwm_id U32_t value of read/write mutex (must be in range 0 to 62) m_count U32_t pointer to read/write mutex 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.
Error bit Description 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 RWMUTEX ID outside allowed range 0 to 62 ERR_ID_WRONG RWMUTEX ID >= number of MUTEXs ERR_RWMX_DATA_PTR_BAD Pointer to RWMUTEX count return holder is null Example Usage
S32_t status, rwm_count; ... // Get the count of cuurent write requests for read/write mutex rwm_1 status = oceos_rwmutex_writes_pending_count(rwm_1, &rwm_count);oceos_rwmutex_holding()
Header File
header.h
Description
This function returns the read/write mutexes currently held by this instance of this task (job).Prototype
/** * Get RWMUTEXs currently held by this instance of the task (job) * * @param m_data U64_t pointer, each bit indicating RWMUTEX held by current task * 0 => Not held by job * 1 => Held by job * @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_RWMX_DATA_PTR_BAD Pointer to RWMUTEX status return holder is null */ S32_t oceos_rwmutex_holding( U64_t *m_data );Parameters
Parameter Description m_data U64_t pointer, each bit indicating RWMUTEX held by current task, 0 => not held, 1 => held 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 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_RWMX_DATA_PTR_BAD Pointer to RWMUTEX status return holder is null Example Usage
S32_t status; U64_t rwm_held; ... // Which read/write mutexes does this job hold status = oceos_rwmutex_holding(&rwm_held);Semaphores directives
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.
Error bit Description 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.
Error bit Description 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.
Error bit Description 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.
Error bit Description 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.
Error bit Description 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.
Error bit Description 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.
Error bit Description 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.
Error bit Description 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);Data Queues
oceos_dataq_create()
Header File
dataq.h
Description
This function creates a data queue with the specified characteristics.Prototype
/** * Create data queue * If use_timeout = TRUE, timed actions must be initialised * * @param dataq_id data queue ID * @param dataq_size data queue size * @param pen_q_size pending jobs queue size * @param roll_over whether to roll over when full * @param use_timeout if TRUE, directive oceos_dataq_read_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 DATAQs already created * ERR_ID_INVALID DATAQ ID outside allowed range 0 to 62 * ERR_ID_WRONG DATAQ ID >= number of DATAQs * ERR_DQ_ALREADY_ALLOCATED DATAQ ID already used * ERR_DQ_SIZE_WRONG DATAQ size outside allowed range 1 to 255 * ERR_DQ_PENQ_SIZE_WRONG DATAQ pending queue size outside allowed range 1 to 253 * ERR_DQ_TA_MAX_NUM_REACHED Number of timed actions exceeds MAX allowed 255, * each task on DATAQ pending queue is timed action */ S32_t oceos_dataq_create( dataq_t dataq_id, // data queue ID U16_t dataq_size, // data queue size U16_t pen_q_size, // pending jobs queue size BOOLE_t roll_over, // whether to roll over when full BOOLE_t use_timeout // whether timeout is used oceos_dataq_read_restart_timeout );Parameters
Parameter Description dataq_id dataq_t data queue ID (number between 0 and 62) dataq_size data queue size (max number of pointers than can be added to the queue) pen_q_size pending jobs queue size roll_over whether to roll over when full (0 => disabled, 1 => enabled) use_timeout if TRUE, directive oceos_dataq_read_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.
Error bit Description 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 DATAQs already created ERR_ID_INVALID DATAQ ID outside allowed range 0 to 62 ERR_ID_WRONG DATAQ ID >= number of DATAQs ERR_DQ_ALREADY_ALLOCATED DATAQ ID already used ERR_DQ_SIZE_WRONG DATAQ size outside allowed range 1 to 255 ERR_DQ_PENQ_SIZE_WRONG DATAQ pending queue size outside allowed range 1 to 253 ERR_DQ_TA_MAX_NUM_REACHED Number of timed actions exceeds MAX allowed 255, each task on DATAQ pending queue is timed action Example Usage
S32_t status; ... // Create data queue d_3 with size 20, max pending jobs of 10, rollover enabled, timeouts disabled status = oceos_dataq_create(d_3, 20, 10, 1, 0));oceos_dataq_write()
Header File
dataq.h
Description
This function puts a non-null pointer on the specified data queue.Prototype
/** * Puts pointer to the data on data queue. * Pointer to the data must not be NULL * * @param dataq_t dataq_id Data queue ID * @param void* data Non-null pointer to data * * @return OCEOS_SUCCESS * WARN_DQ_NOW_FULL Warning, DATAQ is full now * 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 DATAQ ID outside allowed range 0 to 62 * ERR_ID_WRONG DATAQ ID >= number of DATAQs * ERR_DQ_DATA_BAD Data pointer is null * ERR_SYS_BUSY Failed to acquire guard * ERR_TOO_MANY DATAQ is full * ERR_DQ_JOB_ID_WRONG Job ID of the task on 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_dataq_write( dataq_t dataq_id, // data queue ID void *data // non-null pointer to data );Parameters
Parameter Description dataq_id dataq_t with value of Data queue ID ptr void* pointer to application data (non-null pointer) 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 WARN_DQ_NOW_FULL Warning, DATAQ is full now 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 DATAQ ID outside allowed range 0 to 62 ERR_ID_WRONG DATAQ ID >= number of DATAQs ERR_DQ_DATA_BAD Data pointer is null ERR_SYS_BUSY Failed to acquire guard ERR_TOO_MANY DATAQ is full ERR_DQ_JOB_ID_WRONG Job ID of the task on 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; char[100] message_in; ... // Put pointer to message_in on data queue s_2 status = oceos_dataq_write(s_2, (void *)message_in);oceos_dataq_read_continue()
Header File
dataq.h
Description
This function returns a pointer from the specified data queue.Prototype
/** * Read data queue * * @param dataq_t dataq_id Data queue ID * @param void* data Pointer to data * * @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 DATAQ ID outside allowed range 0 to 62 * ERR_ID_WRONG DATAQ ID >= number of DATAQs * ERR_SYS_BUSY Failed to acquire guard * ERR_DQ_EMPTY DATAQ empty(count zero) */ S32_t oceos_dataq_read_continue( dataq_t dataq_id, // data queue ID void* *data // return data );Parameters
Parameter Descriptionn dataq_id dataq_t with value of Data queue ID ptr void* pointer to store returned data queue pointer removed from the queue 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 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 DATAQ ID outside allowed range 0 to 62 ERR_ID_WRONG DATAQ ID >= number of DATAQs ERR_SYS_BUSY Failed to acquire guard ERR_DQ_EMPTY DATAQ empty(count zero) Example Usage
S32_t status; char *data_ptr; ... // Read pointer from data queue s_2 status = oceos_dataq_read_continue(s_2, (void *)data_ptr);oceos_dataq_read_restart()
Header File
dataq.h
Description
This function returns a pointer from the specified data queue. If the queue is empty, the job is added top the dataq pending queue. The job will be restarted when data is available.Prototype
/** * Read data queue next item. * If dataq is empty, task is put on pending Q for dataq and * restarted by oceos_dataq_write * * @param dataq_id Data queue ID * @param data Pointer to return data * * @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 DATAQ ID outside allowed range 0 to 62 * ERR_ID_WRONG DATAQ ID >= number of DATAQs * ERR_SYS_BUSY Failed to acquire guard * ERR_DQ_J_START_FROM_TIMOUT Job started from timeout already, DATAQ empty second time * ERR_FAILED Should never return this */ S32_t oceos_dataq_read_restart( dataq_t dataq_id, // data queue ID void* *data // pointer to return data );Parameters
Parameter Description dataq_id dataq_t with value of Data queue ID ptr void* pointer to store returned data queue pointer removed from the queue 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 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 DATAQ ID outside allowed range 0 to 62 ERR_ID_WRONG DATAQ ID >= number of DATAQs ERR_SYS_BUSY Failed to acquire guard ERR_DQ_J_START_FROM_TIMOUT Job started from timeout already, DATAQ empty second time ERR_FAILED Should never return this Example Usage
S32_t status; char *data_ptr; ... // Read pointer from data queue s_2 with restart when data is available status = oceos_dataq_read_restart(s_2, (void *)data_ptr);oceos_dataq_read_restart_timeout()
Header File
dataq.h
Description
This function returns a pointer from the specified data queue. If the queue is empty, the job is added top the dataq pending queue. The job will be restarted either when data is available or the timeout has expired.Prototype
/** * Read data queue next item. * If dataq is empty, task is put on pending Q for dataq and * restarted by oceos_dataq_write or by timeout if timeout != 0 * In order to use this feature timed actions must be configured and * dataq created with use timeout set to true * * @param dataq_id Data queue ID * @param data Pointer to return data * @param timeout Timeout, restart time if no entry, 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 DATAQ created without timeouts * ERR_ID_INVALID DATAQ ID outside allowed range 0 to 62 * ERR_ID_WRONG DATAQ ID >= number of DATAQs * ERR_SYS_BUSY Failed to acquire guard * ERR_DQ_EMPTY DATAQ empty(count zero) * ERR_DQ_J_START_FROM_TIMOUT Job started from timeout already, DATAQ empty second time * ERR_TOO_MANY DATAQ pending queue is full * ERR_FAILED Should never return this */ S32_t oceos_dataq_read_restart_timeout( dataq_t dataq_id, // data queue ID void* *data, // Pointer to return data U64_t timeout // timeout, restart time if no entry, 0 => ignore );Parameters
Parameter Description dataq_id dataq_t with value of Data queue ID ptr void* pointer to store returned data queue pointer removed from the queue timeout U64_t containing timeout value, restart time if no entry, 0 => ignore 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 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 DATAQ created without timeouts ERR_ID_INVALID DATAQ ID outside allowed range 0 to 62 ERR_ID_WRONG DATAQ ID >= number of DATAQs ERR_SYS_BUSY Failed to acquire guard ERR_DQ_EMPTY DATAQ empty(count zero) ERR_DQ_J_START_FROM_TIMOUT Job started from timeout already, DATAQ empty second time ERR_TOO_MANY DATAQ pending queue is full ERR_FAILED Should never return this Example Usage
S32_t status; char *data_ptr; ... // Read pointer from data queue s_2 with timeout after 10,000 time units if no data is available status = oceos_dataq_read_restart_timeout(s_2, (void *)data_ptr, 10000ull);
oceos_dataq_get_size()
Header File
dataq.h
Description
This function returns the number of items on the specified data queue.Prototype
/** * Returns number of items on the data queue with ID * * @param dataq_id DATAQ Id * @param d_size Pointer to 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 DATAQ ID outside allowed range 0 to 62 * ERR_ID_WRONG DATAQ ID >= number of DATAQs * ERR_DQ_DATA_BAD DATAQ size holder pointer is null */ S32_t oceos_dataq_get_size( dataq_t dataq_id, // data queue ID U32_t *d_size );Parameters
Parameter Description dataq_id dataq_t with the ID of the data queue (value between 0 and 62) d_size U32_t *d_size pointer to the variable to store the size 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 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 DATAQ ID outside allowed range 0 to 62 ERR_ID_WRONG DATAQ ID >= number of DATAQs ERR_DQ_DATA_BAD DATAQ size holder pointer is null Example Usage
S32_t status, d_size; ... // Get the number of entries on data queue d_0 status = oceos_dataq_get_size(d_0, &d_size);
oceos_dataq_penq_get_size()
Header File
dataq.h
Description
This function returns number of jobs on the specified data queue pending job's queue.Prototype
/** * Returns number of jobs on the dataq pending job's queue * * @param dataq_id DATAQ Id * @param d_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 DATAQ ID outside allowed range 0 to 62 * ERR_ID_WRONG DATAQ ID >= number of DATAQs * ERR_DQ_DATA_BAD DATAQ pending size holder pointer is null */ S32_t oceos_dataq_penq_get_size( dataq_t dataq_id, U32_t *d_size );Parameters
Parameter Description dataq_id dataq_t with the ID of the data queue (value between 0 and 62) d_jobs U32_t *d_jobs pointer to the variable to store the number of jobs on the pending queue 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 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 DATAQ ID outside allowed range 0 to 62 ERR_ID_WRONG DATAQ ID >= number of DATAQs ERR_DQ_DATA_BAD DATAQ pending size holder pointer is null Example Usage
S32_t status, d_jobs; ... // Get the number of jobs the the pending jubs queue for data queue d_1 status = oceos_dataq_penq_get_size(d_1, &d_jobs);oceos_dataq_clear()
Header File
dataq.h
Description
This function clears the specified data queue including pending jobs for that queue.Prototype
/** * Clears data queue and * frees tasks on pending queue * * @param dataq_t dataq_id Data queue 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 DATAQ ID outside allowed range 0 to 62 * ERR_ID_WRONG DATAQ ID >= number of DATAQs * ERR_SYS_BUSY Failed to acquire guard * ERR_DQ_JOB_ID_WRONG Job ID of the task on DATAQ 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_dataq_clear( dataq_t dataq_id // data queue ID );Parameters
Parameter Description dataq_id dataq_t with the ID of the data queue to be cleared (value between 0 and 62) 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 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 DATAQ ID outside allowed range 0 to 62 ERR_ID_WRONG DATAQ ID >= number of DATAQs ERR_SYS_BUSY Failed to acquire guard ERR_DQ_JOB_ID_WRONG Job ID of the task on DATAQ 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; ... // Clear data queue d_1 status = oceos_dataq_penq_get_size(d_1);Timed Actions
oceos_timed_output_add()
Header File
timed_action.h
Description
This function adds a timed action to the timed action queue. It writes a value to an address at a specified system time. An optional mask can be applied so that only those bits are changed. The action types are WRITE_ACTION, RMW_ACTION. WRITE_ACTION writes the value to the address. RMW_ACTION reads the values at the address and modifies the bits specified by the mask and value.Prototype
/** * Add output action to timed actions queue : * 1. Create timed output action * 2. Stop timer * 3. Add action to action_array * 4. Start timer or execute if time is right * * Returns timed action ID that can be used later to remove * if need by oceos_timed_output_remove * * @param enum ACTION_TYPE action_type Action type * @param U64_t act_time System time at which action should be done * @param U32_t before_time Forward tolerance for time * @param U32_t after_time Backward tolerance for time * @param adrs_t address Output address * @param U32_t value Output value * @param U32_t mask Output mask * @param U32_ *ta_index Pointer to store timed action index * * @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 inialisation is not done and tried to be used * ERR_TA_PTR_BAD Timed action pointer is null * ERR_TA_TYPE_WRONG Timed action type is wrong * ERR_TOO_LATE Timed action time is too late * ERR_SYS_BUSY Timed action guard failed to acquire * ERR_TA_Q_FULL Timed action queue is full * ERR_TA_START_FAILED Timed action execute failed; See log */ S32_t oceos_timed_output_add( const enum ACTION_TYPE action_type,// Action type U64_t act_time, // system time at which action should be done U32_t before_time, // forward tolerance for time U32_t after_time, // backward tolerance for time const adrs_t address, // output address const U32_t value, // output value const U32_t mask, // output mask U32_t *ta_index // Pointer to store timed action index );Parameters
enum ACTION_TYPE action_type Action type U64_t act_time System time at which action should be done U32_t before_time Forward tolerance for time U32_t after_time Backward tolerance for time adrs_t address Output address U32_t value Output value U32_t mask Output mask U32_ *ta_index Pointer to store timed action index 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 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 inialisation is not done and tried to be used ERR_TA_PTR_BAD Timed action pointer is null ERR_TA_TYPE_WRONG Timed action type is wrong ERR_TOO_LATE Timed action time is too late ERR_SYS_BUSY Timed action guard failed to acquire ERR_TA_Q_FULL Timed action queue is full ERR_TA_START_FAILED Timed action execute failed; See log Example Usage
#define OUTPUT_TIMED_VAL 0xDEADBEEF #define OUTPUT_TIMED_MASK 0x1000001 #define OUTPUT_TIME 0xfffff #define OUTPUT_TIME_FW 0x1000 #define OUTPUT_TIME_BW 0x1000 static U32_t test_data[16] = { 0 }; S32_t status; ... // Write OUTPUT_TIMED_VAL to test_data[0] at 0xfffff time units from now with a tolerance of 0x1000 before and after the specified time status = oceos_timed_output_add( WRITE_ACTION, OUTPUT_TIME, OUTPUT_TIME_FW, OUTPUT_TIME_BW, (adrs_t) &test_data[0], OUTPUT_TIMED_VAL, 0, &timed_action_index));oceos_timed_jobs_number()
Header File
timed_action.h
Description
This function returns the number of jobs on the timed actions queue.Prototype
/** * Get number of Jobs (request to start the task) waiting on timed action queue. * These jobs are added by oceos_task_timed_start() or * oceos_dataq_read_restart_timeout when data is not available (NULL) or * oceos_sem_wait_restart_timeout when counting semaphore is 0 * * @param total_jobs Pointer to store total jobs number waiting on timed action Q * @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 inialisation is not done and tried to be used * ERR_TA_PTR_BAD Timed action pointer is null */ S32_t oceos_timed_jobs_number(U32_t *total_jobs);Parameters
Parameter Description total_jobs s32_t pointer to store total jobs number waiting on timed action Q 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 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 inialisation is not done and tried to be used ERR_TA_PTR_BAD Timed action pointer is null Example Usage
S32_t status, no_of_jobs; ... // Get the number of jobs on the timed actions queue status = oceos_timed_jobs_number(&no_of_jobs);oceos_timed_output_number()
Header File
timed_action.h
Description
This function returns the number timed output actions waiting on the timed actions queue.Prototype
/** * Get number of timed output actions waiting on timed action queue. * These timed output actions are created by oceos_timed_output_add * * @param total_outputs Pointer to store total outputs number waiting on timed action Q * @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 inialisation is not done and tried to be used * ERR_TA_PTR_BAD Timed action pointer is null */ S32_t oceos_timed_output_number(U32_t *total_outputs);Parameters
Parameter Description total_outputs s32_t pointer to store total output actions waiting on timed action queue 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 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 inialisation is not done and tried to be used ERR_TA_PTR_BAD Timed action pointer is null Example Usage
S32_t status, no_of_outputs; ... // Get the number of output actions on the timed actions queue status = oceos_timed_output_number(&no_of_outputs);oceos_timed_jobs_remove()
Header File
timed_action.h
Description
This function removes the specified timed action from the queue.Prototype
/** * Remove job from timed action queue * When task started using oceos_task_timed_start(), * this directive requires pointer to store ID * of job that put on the timed action queue. * This job can be removed later using this directive and stored job ID. * * @param U32_t job_id Job 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_TA_NOT_INIT Timed action intialisation is not done and tried to be used * ERR_TA_PTR_BAD Timed action pointer corrupt * ERR_ID_WRONG Job ID is wrong * ERR_TA_NOT_FOUND Timed action ID not found for action with job_id or removed already * ERR_SYS_BUSY Failed to acquire timed action guard * WARN_TA_Q_EMPTY Timed action queue is empty * ERR_TA_START_FAILED Timed action execute failed; See log */ S32_t oceos_timed_jobs_remove( U32_t job_id // Job ID );Parameters
Parameter Description job_id U32_t Job ID to be removed from the timed actions queue 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 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 ERR_TA_PTR_BAD Timed action pointer corrupt ERR_ID_WRONG Job ID is wrong ERR_TA_NOT_FOUND Timed action ID not found for action with job_id or removed already ERR_SYS_BUSY Failed to acquire timed action guard WARN_TA_Q_EMPTY Timed action queue is empty ERR_TA_START_FAILED Timed action execute failed; See log Example Usage
S32_t status, job_id; ... // Remove job_id from the timed actions queue status = oceos_timed_jobs_remove(job_id);oceos_timed_jobs_reset()
Header File
timed_action.h
Description
This function removes all jobs from timed actions queue.Prototype
/** * Remove all jobs (requests to start a task) from timed actions queue * These jobs were added by oceos_task_timed_start() or * oceos_dataq_read_restart_timeout when data is not available (NULL) or * oceos_sem_wait_restart_timeout when counting semaphore is 0 * * @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 * ERR_TA_PTR_BAD Timed action pointer is null * ERR_SYS_BUSY Failed to acquire timed action guard * WARN_TA_Q_EMPTY Timed action queue is empty * ERR_TA_NOT_FOUND Timed action index not found * ERR_TA_START_FAILED Timed action execute failed; See log */ S32_t oceos_timed_jobs_reset(void);Parameters
There are no input parameters to this functionReturns
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 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 ERR_TA_PTR_BAD Timed action pointer is null ERR_SYS_BUSY Failed to acquire timed action guard WARN_TA_Q_EMPTY Timed action queue is empty ERR_TA_NOT_FOUND Timed action index not found ERR_TA_START_FAILED Timed action execute failed; See log Example Usage
S32_t status; ... // Remove all jobs from the timed actions queue status = oceos_timed_jobs_reset(job_id);
oceos_timed_output_remove()
Header File
timed_action.h
Description
This function removes the specified timed output action from timed actions queue.Prototype
/** * Remove timed output action from timed actions queue. * When action is created, action index should be stored * to remove if need * * @param action_index * @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 * ERR_TA_PTR_BAD Timed action pointer is null * ERR_ID_WRONG Timed action id is wrong * ERR_SYS_BUSY Failed to acquire timed action guard * ERR_TA_NOT_FOUND Timed action index not found * ERR_TA_START_FAILED Timed action execute failed */ S32_t oceos_timed_output_remove( const U8_t action_index // Index in action array, returned when action was created );Parameters
Parameter Description action_index S32_t specifying the timed output action index returned when the timed output was added. 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 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 ERR_TA_PTR_BAD Timed action pointer is null ERR_ID_WRONG Timed action id is wrong ERR_SYS_BUSY Failed to acquire timed action guard ERR_TA_NOT_FOUND Timed action index not found ERR_TA_START_FAILED Timed action execute failed Example Usage
S32_t status; U8_t action_index; ... // Remove timed output with specified action_index status = oceos_timed_output_remove(action_index);
oceos_timed_output_reset()
Header File
timed_action.h
Description
This function removes all timed output actions from timed actions queue.Prototype
/** * Remove all timed output actions from timed actions queue * These timed output actions were created by oceos_timed_output_add * * @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 * ERR_TA_PTR_BAD Timed action pointer is null * ERR_SYS_BUSY Failed to acquire timed action guard * WARN_TA_Q_EMPTY Timed action queue is empty * ERR_TA_NOT_FOUND Timed action index not found * ERR_TA_START_FAILED Timed action execute failed; See log */ S32_t oceos_timed_output_reset(void);Parameters
There are no input parameters to this 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 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 ERR_TA_PTR_BAD Timed action pointer is null ERR_SYS_BUSY Failed to acquire timed action guard WARN_TA_Q_EMPTY Timed action queue is empty ERR_TA_NOT_FOUND Timed action index not found ERR_TA_START_FAILED Timed action execute failed; See log Example Usage
S32_t status; ... // Remove all timed outputs from the timed actions queue status = oceos_timed_output_reset();Logging directives
Introduction
Log Area Features (for details of other areas see oceos_areas.h)
The system log area holds the system log and the records of the present and previous values of the system state variable.
It is set up initially as an array of 32-bit words that starts at a 32-bit aligned address provided by the application developer.
It is recommended that this address be in non-volatile RAM memory if this is available to allow information be preserved across power-up cycles.
OCEOS preserves log area information across resets as far as possible.
The system log itself is a circular buffer of struct log entry. Older entries are overwritten by new entries once all entries are in use.
The application developer can specify a function to be called when 3/4 of log entries are in use. This function is called again only after 3/4 of log entries have been read and the log has again become 3/4 full.
The read and write indices are stored in the log area and if equal indicate that the log is empty.
As with other OCEOS data areas, the log area starts with a header
- a 32-bit word holding a constant OCEOS_VERSION
- a 32-bit word holding the log area size in 32-bit words
- a 32-bit word, the system status variable
- a 32-bit word, the system status mask
- a 32-bit word, the accumulated system status
- a 32-bit word, the previous system status mask
- a 32-bit word, the log control, that gives whether the log full function was called
- the read index
- the write index
- an array of struct log_entry making up the system log itself
- ending with a 32-bit constant END_SENTINEL
The system fixed meta structure at sysMetaPtr provides
- system_log_ptr the start address of the log area
- logEntries the number of log entries
- logCreated flag indicating log was created successfully
- logFullFunction user defined function, called when the log becomes 3/4 full (or NULL if not used)
Log Entry Types and Structure
/***************************************************************************** * LOG ENTRY TYPES * * A log entry type is an 8-bit number. * Values from 0 to 127 can be defined by the application. * Values from 128 to 255 are used by OCEOS as below. * * * NOTE: Add new log types at the end for backward compatibility */ enum LOG_ENTRY_TYPE{ LOG_SYS_OK = 0x80U, LOG_OCEOS_ABORT, // when exiting from oceos_start LOG_LOG_NOT_VALID_ENTRY, // used to initialise log and when log empty LOG_INIT_TASK_START_FAIL, // initial task passed to oceos_start failed LOG_DEADLINE_MISSED, // task deadline missed LOG_JOB_NOT_ACTIVE, // cpu_terminate but job not active, absurd LOG_JOB_NOT_FREE, // job guarded but not free LOG_JOBS_INC_FAILED, // pending jobs increment failed LOG_JOB_NOT_GUARDED, // paranoia LOG_CS_LOG_SPIN_FAIL, // oceos_CPU_sleep, trying to update CS log LOG_MUTEX_ALREADY_HELD, // oceos_mutex_wait, code returned, not needed LOG_MUTEX_INCORRECT_ORDER, // oceos_mutex_wait LOG_MUTEX_EXIT_HOLDING, // task exits holding one or more mutexes LOG_MUTEX_EXIT_NONE, // __oceos_tasks_remove_mutexes called but no mutex held LOG_SEMAPHORE_PENDING_REMOVE_FAIL, // timed_action.c LOG_SEMAPHORE_PENDING_QUEUE_FULL, // __oceos_semaphore_add_pend LOG_SEMAPHORE_SPIN_FAILED, // trying to access semaphore LOG_DATAQ_PENDING_QUEUE_FULL, LOG_DATAQ_PENDING_REMOVE_FAIL, LOG_DATAQ_SPIN_FAILED, LOG_TIMED_ACTION_TIMER_NULL, LOG_TIMED_ACTION_INVALID, LOG_TIMED_ACTION_BAD_INDEX, LOG_TIMED_ACTION_MISSED, LOG_TIMED_ACTION_Q_EMPTY, LOG_TIMED_ACTION_REMOVE_FAIL, LOG_TIMED_ACTION_BAD_JOB_ID, LOG_TIMED_Q_SPIN_FAIL, LOG_SYSTEM_ERROR, LOG_ATOMICINC_FAILED, LOG_PENDING_PRI_UPDATE_FAILED, LOG_KILL_TASK_INVALID_ID, // Tried to kill task with invalid ID LOG_OCEOS_EXIT_REQUEST, // oceos_exit command was called LOG_RWMUTEX_NOT_RETURNED, LOG_RWMUTEX_NOT_HIGHEST }; /***************************************************************************** * Structures */ /** * Log entry structure */ struct log_entry{ U64_t time64; unsigned int entry_cpu :8; unsigned int entry_type :8; unsigned int entry_note :16; // not used at present U32_t entry_comment; }__attribute__ ((aligned (8)));oceos_log_add_entry()
Header File
system_log.h
Description
This function adds an entry to the log. The entry overwrites the oldest unread entry if the log is full. Custom log entries can be added to enum LOG_ENTRY from 0 to 128. The indices are incremented in a circular fashion. If the write index reaches the read_index the read index is moved on, as read and write indices equal would indicate an empty log.Prototype
/** * Add an entry to the log. * this overwrites the oldest unread entry if the log is full. * Custom log entries can be added to enum LOG_ENTRY from 0 to 128 * * N.B. The indices are incremented in a circular fashion. * If the write index reaches the read_index the read index is moved on, * as read and write indices equal would indicate an empty log. * * @param type enum LOG_ENTRY_TYPE * @param info extra information to be logged * * @return OCEOS_SUCCESS * ERR_SYS_FIXED_CORRUPT System Fixed area corrupt * ERR_SYS_LOG_CORRUPT System Log area corrupt * ERR_WRONG_PHASE Log directive called in wrong phase; can be used after oceos_init() called * ERR_ID_INVALID Log type invalid * ERR_SYS_BUSY Failed to acquire log guard * ERR_LOG_INDEX_WRONG Read/write log index is wrong */ S32_t oceos_log_add_entry( enum LOG_ENTRY_TYPE type, // 8 bits enum LOG_ENTRY_TYPE const U32_t info // information );Parameters
Parameter Description enum LOG_ENTRY_TYPE Log entry type (see previous section for a list) U32_t with the log information 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 ERR_SYS_FIXED_CORRUPT System Fixed area corrupt ERR_SYS_LOG_CORRUPT System Log area corrupt ERR_WRONG_PHASE Log directive called in wrong phase; can be used after oceos_init() called ERR_ID_INVALID Log type invalid ERR_SYS_BUSY Failed to acquire log guard ERR_LOG_INDEX_WRONG Read/write log index is wrong Example Usage
S32_t status, info; ... // Log LOG_APP_COMMS__ERROR (defined in enum LOG_ENTRY_TYPE) and info with more details status = oceos_log_add_entry(LOG_APP_COMMS__ERROR, info);oceos_log_get_indexed_entry()
Header File
system_log.h
Description
This function returns the entry at the specified position in the log. The entry is not removed and the log and log indices are not changed. One use of this function is to allow the log be examined after a reset.Prototype
/** * Returns the entry at the specified position in the log. * The entry is not removed and the log and log indices are not changed. * (intended to allow the log be examined for example after reset) * * @param index position in the log * @param outputPtr pointer to return log entry * * @return OCEOS_SUCCESS * ERR_SYS_FIXED_CORRUPT System Fixed area corrupt * ERR_SYS_LOG_CORRUPT System Log area corrupt * ERR_WRONG_PHASE Log directive called in wrong phase; can be used after oceos_init() called * ERR_LOG_INDEX_WRONG Read log index is wrong * ERR_LOG_DATA_PTR_BAD Data holder pointer is null */ S32_t oceos_log_get_indexed_entry( const unsigned int index, struct log_entry * const outputPtr );Parameters
Parameter Description index U32_t with position in the log outputPtr pointer to struct log_entry to hold the returned entry 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 ERR_SYS_FIXED_CORRUPT System Fixed area corrupt ERR_SYS_LOG_CORRUPT System Log area corrupt ERR_WRONG_PHASE Log directive called in wrong phase; can be used after oceos_init() called ERR_LOG_INDEX_WRONG Read log index is wrong ERR_LOG_DATA_PTR_BAD Data holder pointer is null Example Usage
S32_t status, index; struct log_entry store_entry; ... // Read log_entry at specified index into outputPtr status = oceos_log_get_indexed_entry(index, &store_entry);oceos_log_remove_entry()
Header File
system_log.h
Description
This function reads and removes the oldest unread log entry. If the log is not empty use the entry at the read index to update the value at the output pointer, returning OCEOS_SUCCESS. If outputPtr is NULL, entry is removed but no returned. If the log is empty, set the value at the output pointer to LOG_LOG_NOT_VALID_ENTRY and return ERR_LOG_EMPTY.Prototype
/** * Read and remove the oldest unread log entry * * If the log is not empty use the entry at the read index to update the value * at the output pointer, returning OCEOS_SUCCESS. * * If outputPtr is NULL, entry is removed but no returned * * If the log is empty, set the value at the output pointer to LOG_LOG_NOT_VALID_ENTRY * and return ERR_LOG_EMPTY * * @param outputPtr pointer to struct log_entry * * @return OCEOS_SUCCESS * ERR_SYS_FIXED_CORRUPT System Fixed area corrupt * ERR_SYS_LOG_CORRUPT System Log area corrupt * ERR_WRONG_PHASE Log directive called in wrong phase; can be used after oceos_init() called * ERR_SYS_BUSY Failed to acquire log guard * ERR_LOG_INDEX_WRONG Read/write log index is wrong * ERR_LOG_EMPTY Log is empty */ S32_t oceos_log_remove_entry( struct log_entry * const outputPtr );Parameters
Parameter Description outputPtr pointer to struct log_entry 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 ERR_SYS_FIXED_CORRUPT System Fixed area corrupt ERR_SYS_LOG_CORRUPT System Log area corrupt ERR_WRONG_PHASE Log directive called in wrong phase; can be used after oceos_init() called ERR_SYS_BUSY Failed to acquire log guard ERR_LOG_INDEX_WRONG Read/write log index is wrong ERR_LOG_EMPTY Log is empty Example Usage
S32_t status; struct log_entry *outputPtr; ... // Read log_entry into outputPtr and remove the oldest unread log entry status = oceos_log_remove_entry(outputPtr);oceos_log_reset()
Header File
system_log.h
Description
This function sets all log entries to LOG_LOG_NOT_VALID_ENTRY and the log to empty, with the read and write indices set to 0. The log is empty if the index of the next write is the same as the index of the next read. It does not affect the system status variable. It does not affect the context switch log.Prototype
/** * oceos_log_reset() * * Set all log entries to LOG_LOG_NOT_VALID_ENTRY and the log to empty, with the * read and write indices set to 0. and function called flag 0 * * The log is empty if the index of the next write * is the same as the index of the next read. * * Does not affect the system status variable * Does not affect the context switch log * * N.B The fixed data area may no longer be writable * * @return OCEOS_SUCCESS * ERR_SYS_FIXED_CORRUPT System Fixed area corrupt * ERR_SYS_LOG_CORRUPT System Log area corrupt; reset failed * ERR_WRONG_PHASE Log directive called in wrong phase; can be used after oceos_init() called * ERR_SYS_BUSY Failed to acquire log guard */ S32_t oceos_log_reset(void);Parameters
There are no input parameters to this 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 ERR_SYS_FIXED_CORRUPT System Fixed area corrupt ERR_SYS_LOG_CORRUPT System Log area corrupt; reset failed ERR_WRONG_PHASE Log directive called in wrong phase; can be used after oceos_init() called ERR_SYS_BUSY Failed to acquire log guard Example Usage
S32_t status; ... // Clear down the system log status = oceos_log_reset();oceos_log_get_size()
Header File
system_log.h
Description
This function returns the number of entries in the log according to the current values of the read and write indices. The value will be zero if the current values of the read and write indices are the same. There may still be useful information in the log, e.g. after system reset, this can be accessed using oceos_log_get_indexed_entry().Prototype
/** * Return the number of entries in the log * according to the current values of the read and write indices. * * The value will be zero if the current values of the read and write indices * are the same. * * There may still be useful information in the log, e.g. after system reset, * this can be accessed using oceos_log_get_indexed_entry() * * @param l_size pointer to log size holder * * @return OCEOS_SUCCESS * ERR_SYS_FIXED_CORRUPT System Fixed area corrupt * ERR_SYS_LOG_CORRUPT System Log area corrupt; * ERR_WRONG_PHASE Log directive called in wrong phase; can be used after oceos_init() called * ERR_LOG_DATA_PTR_BAD Pointer to log size holder is NULL * ERR_LOG_INDEX_WRONG Read/write log index is wrong */ S32_t oceos_log_get_size( U32_t *l_size );Parameters
Parameter Description l_size U32_t pointer where size will be written. 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 ERR_SYS_FIXED_CORRUPT System Fixed area corrupt ERR_SYS_LOG_CORRUPT System Log area corrupt; ERR_WRONG_PHASE Log directive called in wrong phase; can be used after oceos_init() called ERR_LOG_DATA_PTR_BAD Pointer to log size holder is NULL ERR_LOG_INDEX_WRONG Read/write log index is wrong Example Usage
S32_t status, size; ... // Clear down the system log status = oceos_log_get_size(&size);System State Variable and System State Mask
The System State variable provides a record of anomalies or problems detected by OCEOSmp's automatic consistency checks. An application handler for these can be set to be called automatically.
An anomaly or problem results in a flag bit being set in the 32-bit word used to store the system state variable. The flags are identified below.
All flags are reset to zero by oceos_init() when OCEOSmp is initialised, and may also be reset by the application using the directive provided.
To provide a record across OCEOSmp restarts a copy is updated automatically whenever the state variable is updated. This is not cleared by oceos_init() but may be cleared by the application using a directive.
Application software can define a problem handling function to be called automatically when specified system state flags are set. The flags are specified by setting the corresponding bits in the system state mask. The function and the state mask are defined in the system configuration.
Changing a state flag from clear to set results in the function being called (if defined). Subsequent settings of that flag have no effect until after it has been cleared using the directive provided.
N.B. In many cases when OCEOSmp sets a System State flag it also makes an entry in the system log that provides further information.
SYSTEM STATE VARIABLE FLAGS
These flags are updated by OCEOSmp using inclusive 'OR' when a consistency check detects a problem or anomaly. A copy of the system state variable is updated also and accumulates a record of flag settings that is preserved across restarts of OCEOSmp. OCEOSmp restarts reset the system state variable but not the copy.
Resetting the state variables is the responsibility of the application (except for the state variable reset done when OCEOSmp is restarted).
System Status Bits
#define STATUS_NORMAL 0u // No flag set YES #define STATUS_INVALID 0xffffffffu // System status is invalid YES BUT NO DETAIL!!! #define STATUS_MASK_NORMAL 0xffffffffu // Always call user def fn YES /* Task related problems */ #define STATUS_DISABLED_TASK_START 0x1U // An attempt to start a disabled task #define STATUS_TASK_JOB_LIMIT_OVER 0x2U // An attempt to execute a task when its jobs limit is already reached. #define STATUS_JOB_OVER_TIME 0x4U // Job time from creation to completion exceeds allowed maximum for task. YES #define STATUS_JOB_INTERVAL_SHORT 0x8U // Minimum time between job creations is less than the allowed minimum for task #define STATUS_READYQ_FULL 0x10U // Ready queue unable to accept job as result of being full #define STATUS_READYQ_NO_REMOVE 0x20U // Remove job from ready queue failed /* Mutex related problems */ #define STATUS_MUTEX_ALREADY_HELD 0x40U // Mutex wait() when mutex already held #define STATUS_MUTEX_NOT_HELD 0x80U // Mutex signal() when not already held #define STATUS_MUTEX_NOT_RETURNED 0x100U // Mutex not returned before job terminates #define STATUS_MUTEX_NOT_NESTED 0x200U // Use of multiple mutexes not nested /* Counting semaphore and data queue related problems */ #define STATUS_SEMAPHORE_JOBS_FULL 0x400U // Attempt to add job to semaphore pending list when list full #define STATUS_DATAQ_JOBS_FULL 0x800U // Attempt to add job to data queue pending list when list full #define STATUS_DATAQ_FULL 0x1000U // Data queue write when queue already full /* Timed actions related problems */ #define STATUS_TIMED_JOBS_FULL 0x2000U // Timed actions queue already full for timed task start #define STATUS_TIMED_OUTPUT_FULL 0x4000U // Timed actions queue already full for timed output #define STATUS_TIMED_ACTION_LATE 0x8000U // Timed action late YES /* Default trap handler should have been replaced * NOT USED AT THE MOMENT*/ #define STATUS_SYSTEM_ERROR 0x10000U // ERROR was handled by default trap handler YES /* Flag to indicate problem with Stack Pointer * NOT USED AT THE MOMENT*/ #define STATUS_SP_WARNING 0x20000U // SP not in expected range /* Log system error */ #define STATUS_BAD_LOG 0x40000U // System log problem #define STATUS_SPIN_FAILED 0x80000U // Get SPIN lock failed /* Not using next few bits */ /* Will have to exit */ #define STATUS_BAD_SENTINEL 0x40000000U // Area sentinel corrupt #define STATUS_BAD_META_PTR 0x80000000U // Null meta pointeroceos_system_state_get()
Header File
system_log.h
Description
This function returns of the system state variable.Prototype
/** * Returns the value of the system state variable * * @param state pointer to state holder * * @return OCEOS_SUCCESS * ERR_SYS_FIXED_CORRUPT System Fixed area corrupt * ERR_LOG_DATA_PTR_BAD Data holder pointer is null * ERR_SYS_LOG_CORRUPT LOG dynamic pointer is null */ S32_t oceos_system_state_get( U32_t *state // pointer to state holder );Parameters
Parameter Description state U32_t pointer to state 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.
Error bit Description ERR_SYS_FIXED_CORRUPT System Fixed area corrupt ERR_LOG_DATA_PTR_BAD Data holder pointer is null ERR_SYS_LOG_CORRUPT LOG dynamic pointer is null Example Usage
S32_t status, state; ... // Get the system state status = oceos_system_state_get(&state);oceos_system_state_set()
Header File
system_log.h
Description
This function sets system state variable.Prototype
/** * Sets system state variable * * @param new_state * * @return OCEOS_SUCCESS * ERR_SYS_FIXED_CORRUPT System Fixed area corrupt * ERR_SYS_LOG_CORRUPT LOG dynamic pointer is null */ S32_t oceos_system_state_set( U32_t new_state // new value of system state variable );Parameters
Parameter Description new_state U32_t containing new system state 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 ERR_SYS_FIXED_CORRUPT System Fixed area corrupt ERR_SYS_LOG_CORRUPT LOG dynamic pointer is null Example Usage
S32_t status, new_state; ... // Set new system state status = oceos_system_state_set(new_state);oceos_system_state_copy_get()
Header File
system_log.h
Description
This function returns the value of the system state copy variable.Prototype
/** * Returns the value of the copy of system state variable * * @param state pointer to state holder * * @return OCEOS_SUCCESS * ERR_SYS_FIXED_CORRUPT System Fixed area corrupt * ERR_LOG_DATA_PTR_BAD Data holder pointer is null * ERR_SYS_LOG_CORRUPT LOG dynamic pointer is null */ S32_t oceos_system_state_copy_get( U32_t *state // pointer to state copy holder );Parameters
Parameter Description state U32_t pointer to state copy 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.
Error bit Description ERR_SYS_FIXED_CORRUPT System Fixed area corrupt ERR_LOG_DATA_PTR_BAD Data holder pointer is null ERR_SYS_LOG_CORRUPT LOG dynamic pointer is null Example Usage
S32_t status, copy_state; ... // Get the system state copy status = oceos_system_state_copy_get(©_state);oceos_system_state_copy_set()
Header File
system_log.h
Description
This function loads a value to tha system state copy variable.Prototype
/** * Sets system state copy variable * * @param new_state * * @return OCEOS_SUCCESS * ERR_SYS_FIXED_CORRUPT System Fixed area corrupt * ERR_SYS_LOG_CORRUPT LOG dynamic pointer is null */ S32_t oceos_system_state_copy_set( U32_t new_state // new value of system state variable );Parameters
Parameter Description new_state U32_t containing new system state copy 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 ERR_SYS_FIXED_CORRUPT System Fixed area corrupt ERR_SYS_LOG_CORRUPT LOG dynamic pointer is null Example Usage
S32_t status, new_state; ... // Set new system state copy status = oceos_system_state_copy_set(new_state);Timing directives
Introduction
SPARC
In OCEOS system time is based on two chained 32-bit timers.
No interrupts are involved, the current system time is obtained by reading the two timer counter registers (in an atomic way) and then inverting the values since the timers count down.
The scaler associated with the timers is configured based on the system clock frequency to decrement the low order timer every microsecond. This decrements the high order timer when it rolls over, every 71.6 minutes approximately. The 64-bit time range is very long, over 584,000 years.
ARM Cortex-M
In OCEOS for ARM Cortex-M, system time is based on SysTick. The processor has a 24-bit system timer, SysTick, that counts down from the reload value to zero, reloads (wraps to) the value in the LOAD register on the next clock edge, then counts down on subsequent clocks.
Note: When the processor is halted for debugging the counter does not decrement.
OCEOS initializes the timer to be driven from MCK and counting down to zero asserts SysTick exception request. OCEOS has 64 bit counter which is increased by 0xFFFFFF value every time timer reloads.
RISC-V
In OCEOS for RISC-V systems time is based internally on clock cycles. The RISC-V processor typically has a 64 bit counter (typically mtime) that updates automatically on each clock cycle. Each hart typically has its own comparison register (typically mtimecmp) that can be used to interrupt that hart when a certain cycle count has been exceeded. If a particular RISC-V implementation provides a more restricted clock cycle count this will be used with appropriate modifications as clock cycles give the best timing precision available.
Note: The application configuration provides the constant needed to allow microseconds (as used in OCEOS directives) be converted to clock cycles. Time is reported by OCEOSmp as the number of microseconds since OCEOS was initialized.
A potential difficulty arises if the main system clock rate can change for power saving or other reasons, each system is probably different with regard to this. OCEOSmp can handle this, if needed.
The units of OCEOS system time are microseconds on SPARC and ARM and on RISC-V the period of the clock cycle.
The system time is reset to 0 by oceos_init()
oceos_time_sys_get64()
Header File
oceos_timer.h
Description
This function returns the current system time as a 64-bit number.Prototype
** * Get the current system time (64-bit) * * @return U64_t */ U64_t oceos_time_sys_get64(void);Parameters
There are no parameters to this function.
Returns
This function returns an S64_t with the current system time.Example Usage
S64_t now; ... // Get the time now = oceos_time_sys_get64();oceos_time_sys_get32()
Header File
oceos_timer.h
Description
This function returns the low 32 bits of the system time.Prototype
/** * Get the current system time (low 32 bits of 64 bit value) * * @return U32_t */ U32_t oceos_time_sys_get32(void);Parameters
There are no parameters to this function.Returns
This function returns an S32_t with the current system time.Example Usage
S32_t now; ... // Get the time now = oceos_time_sys_get32();