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

/**
 * 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 started

Prototype

/**
 *  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

API Functions

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 Directives

Read/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 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 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 pointer

oceos_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(&copy_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();