OCEOS/oceos kernel/initialisation

OCEOS Initialization

Introduction

This section describes the OCEOS directives used to in most applications.
The application code (starting at main()) will typically carry out various system self test and initialization routines and set up interrupt/trap handlers, and then use OCEOS

The calls to get OCEOS running are:

1. oceos_init - Uses oceos_init to Initialize fixed data and start system time and log
2. oceos_task_create - Create task setting priority, maximum number of jobs, start function, etc.
3. oceos_init_finish - Complete and check fixed data area
4. oceos_start - Start the scheduler - will start optional initial task or put CPU in sleep mode waiting for interrupt.

The functions that implement the operations of each task are defined in the application. The start function for each task and optional task tidy up kill function are specified when a task is created.

If mutexes, semaphores, data queues and/or timed actions are required they also are created at step 2.

Note

It is mandatory to create the number of tasks, mutexes, semaphores, and data queues declared in oceos_config.h otherwise oceos_init_finish() will return an error.

In OCEOS all task, mutex and other names are unsigned integers and it is strongly recommended that enumerated types are used for this purpose, so as to provide user friendly names.

It is suggested that these names be defined in the application header that is also used for application function declarations. To avoid possible confusion between names, it is suggested also that all task names start with 't_', all mutex names with 'm_', etc.

API Functions

API Functions

Directive	Description	main	task	IRQ handler
oceos_init()	Initialize fixed data	*
oceos_init_finish()	Complete and check fixed data area	*
oceos_start()	Start the scheduler	*
oceos_exit()	Stop the scheduler		*	*
oceos_CPU_sleep()	Put CPU to sleep		*

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

enum DIRECTIVE_STATUS   oceos_init(
    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_init_finish()

Header File
initialisation.h

Description
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.

Prototype

enum DIRECTIVE_STATUS   oceos_init_finish();

Parameters

Parameter	Description

Returns
This function returns enum DIRECTIVE_STATUS.

enum DIRECTIVE_STATUS	Description
INCORRECT_STATE	If system Meta pointer is NULL or Init pointer is NULL or Start up phase check fail or Fixed data checksum failed (check log)
INVALID_NAME	If Start Sentinel for fixed area is corrupt or Start Sentinel for dynamic area is corrupt
INVALID_NUMBER	If Configuration and actual parameters do not match (In configuration file was defined 5 tasks, but created less)
SUCCESSFUL	If All OK

Example Usage

    /*
     * Finish initialising OCEOS and setting up the fixed data
     */
    enum DIRECTIVE_STATUS status;
    status = oceos_init_finish();
    if(SUCCESSFUL != status){
        // LOG
        return -1;
    }

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

enum DIRECTIVE_STATUS   oceos_start(
    const U32_t * const fixed_array_ptr, // pointer to fixed data array
    const unsigned int start_task,       // taskID. If invalid CPU enters sleep mode
    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 enum DIRECTIVE_STATUS.

enum DIRECTIVE_STATUS	Description
INTERNAL_ERROR	If fixed_array_ptr is NULL or fixed_array_ptr start sentinel is corrupt or Size of fixed area is not correct or fixed_array_ptr checksum failed
INCORRECT_STATE	If Dynamic area setup failed

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[];
...
enum DIRECTIVE_STATUS 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

enum DIRECTIVE_STATUS   oceos_exit();

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

oceos_CPU_sleep()

Header File
initialisation.h

Description
Puts CPU in sleep mode.
User must to be sure that interrupts are enabled.

Prototype

enum DIRECTIVE_STATUS   oceos_CPU_sleep();

Parameters

Parameter	Description

Returns
This function returns enum DIRECTIVE_STATUS.

enum DIRECTIVE_STATUS	Description
SUCCESSFUL	When CPU returns from sleep

Example Usage

// Put CPU to sleep
oceos_CPU_sleep();