OCEOSmp/directive reference
This section is under construction
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 enum DIRECTIVE_STATUS.
Target ARM:
enum DIRECTIVE_STATUS Description INVALID_ADDRESS If Failed on memory initialisation (write to memory) UNSATISFIED If Failed on Log area initialisation NOT_CONFIGURED If System frequency is not set or
oceos_SysTick_Handler is not in trap table or
Timer start called without initialisation (check log)SUCCESSFUL If All OK Target SPARC:
enum DIRECTIVE_STATUS Description INVALID_ADDRESS If Failed on memory initialisation (write to memory) UNSATISFIED If Failed on Log area initialisation NOT_CONFIGURED If System timer handler is NULL or
System frequency is not set
INVALID_ID If System sub timer ID is not valid FAILED_TO_SET_REGISTER If Failed on register write (check log) SUCCESSFUL If All OK Example Usage
/* * Create the application configuration structure */ struct application_configuration app_config = {0}; /* * Fill in the application parameters */ app_config.log_address = (adrs_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 = OCEOS_STACK_START_ADDRESS; // 0 => no check app_config.stack_lower_bound_address = OCEOS_STACK_LOW_BOUND_ADDRESS; // 0 => no check app_config.system_error_function = &oceos_on_error; // NULL => ignore app_config.log_full_function = &oceos_on_full_log; // NULL => ignore #ifdef __sparc__ /** * FOR SPARC TARGET ONLY. * Not Used for ARM. Always Nested */ app_config.interrupt_nesting_enabled = TRUE; // TRUE => single vector #endif // 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_readyQ_entries = NUMBER_OF_READYQ_ENTRIES; // 0 => calculate size app_config.number_of_mutexes = NUMBER_OF_MUTEXES; app_config.number_of_counting_semaphores = NUMBER_OF_SEMAPHORES; app_config.number_of_data_queues = NUMBER_OF_DATAQS; #ifdef __sparc__ /** * FOR SPARC TARGET ONLY. * ARM SysTick is used for System Time */ app_config.sys_time_timer_index = SYS_TIME_TIMER_INDEX; // 0 => invalid index #endif app_config.timed_actions_queue_size = NUMBER_OF_ACTION_ENTRIES; app_config.CS_log_entries_base2 = CS_LOG_DEF_ENTRIES_BASE2; app_config.use_oceos_system_time = TRUE; // initialise OCEOS enum DIRECTIVE_STATUS status; status = oceos_init(app_config); if (SUCCESSFUL == status) { return 1; } else { printf("\n oceos_init failure\n"); return -1; } // else
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 S32_t with one of the status codes defined above.
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 S32_t with one of the status codes defined above.
Example Usage
// Exit OCEOS oceos_exit();