OCEOSmp/directive reference

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