OCEOSmp/directive reference

Initialisation directives

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

Parameter	Description

Returns
This function returns enum DIRECTIVE_STATUS.

enum DIRECTIVE_STATUS	Description
INCORRECT_STATE	If System Meta pointer is NULL or Initialisation is not finished or Scheduling was not started
INTERNAL_ERROR	If Dynamic Meta pointer is NULL
SUCCESSFUL	If All OK

Example Usage

// Exit OCEOS
oceos_exit();