wiki - User contributions [en-gb]

OCEOSmp/introduction

2024-12-05T12:42:29Z

Bkavanagh: /* Introduction */

= '''Introduction''' =

__NOTOC__

OCEOSmp is a multicore real-time pre-emptive fixed priority operating system that can be used in applications that require European Cooperation for Space Standardization Category B or ISO 26262 standards. It has a small memory footprint (<20 kBytes), requires only one system stack per CPU rather than a stack for each task, and provides support for precisely timed data outputs independent of task scheduling. OCEOS supports applications running on RISC-V, ARM, & SPARC based hardware.

OCEOSmp is designed to be suitable for high reliability embedded systems. It is not started initially on power up but is started by the main application code, to which it may return if a fatal error is detected. It is designed to be transparent with information stored at statically allocated locations and accessible both while OCEOSmp is running and after it exits.
In addition to deterministic scheduling the qualities most important in designing OCEOSmp were (i) robustness (ii) efficiency (iii) compactness.

[[File:Wikioceosmp.png|1000px]]

== Robustness ==
This is a primary objective in the design of OCEOSmp.
For a system design to be robust it must be possible to identify the range of problems with which it should deal and how it does so.
Such problems fall into three main categories, those excluded by the design, those that provide an advance warning that something is going wrong, and those that can occur without warning.

== Excluded by design ==

The design of OCEOSmp is based on the stack resource policy (https://www.math.unipd.it/~tullio/RTS/2009/Baker-1991.pdf). This has a number of advantages and excludes a number of potential problems.
*Unbounded priority inversion cannot occur in OCEOSmp.
*Deadlocks cannot occur if there is only one CPU.
*(With more than one CPU, deadlocks cannot occur if tasks always follow the same order in acquiring mutexes. OCEOSmp detects when this is not the case and automatically makes a system log entry, updates the state variable, and optionally calls a user defined problem handling function.)
*When a task is created an allowance of from 1 to 15 execution instances is specified. This can be set so that unexpected task start requests do not cause a problem. (It also allows the work of a task be split and done concurrently on multiple CPUs, or the same processing be done on multiple CPUs and results compared to check CPU behaviour.)
*With OCEOSmp no CPU in a multi-core system is a single point of failure once scheduling has begun, use of CPUs is then symmetric.

== Advance warning – problem anticipation ==
Some problems give advance warnings that things are going wrong, allowing preventive action be taken before the problem becomes critical. All software design involves assumptions and the ability to do run-time checks of how close these are to being violated allows preventative actions, or at least notification of what is happening, to be carried out before a critical situation develops.

OCEOSmp will be designed to facilitate noticing advance warnings. All memory is statically allocated with information on all aspects of operations at predetermined locations that can be checked at any time.

For software this information includes:
For each CPU:
*Maximum stack usage (OCEOSmp does not require a separate stack for each task)
*Currently executing and pending tasks
For each task:
*Minimum time between task start requests.
*Maximum time to completion.
*Maximum number of concurrent execution instances (jobs).
*Whether deadline (if specified) has been missed
For the system:
*System log
*Context switch log (if enabled)
*System state variable (reset on restart)
*System state variable backup (not reset on restart)
*System state variable action mask (selects automatic call of application defined problem handler)

Hardware problem warnings include:
For CPU problems:
*OCEOSmp allows simultaneous running of the same task on up to 15 different CPUs, with results stored on a per CPU basis and available for comparison.
*This can provide protection against CPU malfunction in carrying out critical tasks.
*It also allows background checks that can warn that a CPU has developed a problem.
*If a CPU is found to be faulty it can be taken out of use and the termination functions of its currently executing and pending tasks called from another CPU.
For memory problems:
*A memory scrubber task can be scheduled to start periodically to ensure single bit errors do not accumulate (assuming EDAC).
For peripheral hardware:
*The minimum time between task start requests can warn that a peripheral is malfunctioning.

== No warning ==
Software errors can arise suddenly due to unforeseen circumstances. The phrase ‘a failure mode we did not think of’ is not unknown among software developers. The resulting error typically occurs without warning.
Hardware errors can also occur without warning due to radiation or other factors.
Some protection against hardware CPU failures can be obtained by exploiting redundancy and running the same task on multiple CPUs, and OCEOSmp supports this.
Protection against memory errors is usually provided by EDAC. It is expected that an appropriate trap handler is put in place by the application to handle uncorrectable errors signalled by an EDAC system. The timed actions feature of OCEOSmp simplifies restarting a memory scrubber task at set time intervals, and allows the time interval be changed at run time depending on the error rate.
Memory protection may also be provided by memory protection units which restrict defined memory address ranges to use only for execution code or for reading but not writing. The fixed address ranges used by OCEOSmp simplify configuring these units.
OCEOSmp provides further protection against software and hardware errors by protecting data areas with fixed sentinels and automatically checking these, and checking other factors for consistency, whenever an OCEOSmp directive is used.
Similar checks can also be done by the application software, which can also check the fixed area checksum (this is not done automatically by OCEOSmp for reasons of efficiency). As the fixed data area does not change once scheduling begins it is possible to create it in advance and store it in ROM for use if it is necessary to restart scheduling.

== Fault isolation ==
When OCEOSmp detects a fault it can isolate it in a number of ways.
For software problems it can
*terminate the currently execution instance of a task
*disable a task so that it will not be put into execution again
*terminate all current execution instances of the task
If a CPU is found to be faulty
*OCEOSmp can take the CPU out of use by OCEOSmp
*OCEOSmp can put the CPU in sleep mode
*OCEOSmp can terminate all jobs pending or in execution on that CPU
The response usually involves
*Updating the system state flags
*Updating the system log
*If the action mask matches the system state flags calling the application defined problem handling function
In extreme cases where corruption of its internal structure is detected OCEOSmp will return to the main application with an appropriate system code. The system log, task information, and all other data are still available for analysis, and the main application code may restart OCEOSmp.

== Fault reporting ==
A system state variable contains flags that indicate what problems have been detected.
A backup of this variable that is not reset on start-up allows a record of past events be kept across start cycles.
An action mask variable allows an application defined function be called to handle certain problems.
The system log is automatically updated when OCEOSmp detects certain problems, and may be updated by the application if it detects problems. A range of system log codes are reserved for OCEOSmp, others are available for application use.
The system log size is set in the initial configuration. It is structured as a circular buffer and an optional function can be defined that is called when the system log becomes ¾ full.
A context switch log can be enabled and its size set in the initial configuration. Structured as a circular buffer, it can be read by an external debugger such as DMON, or its content output by a task.

== Fault recovery ==
As mentioned above under ‘Fault Isolation’, OCEOSmp can enable and disable tasks, terminate execution instances of tasks, put a CPU out of use by OCEOSmp, and put a CPU into sleep mode.
In most cases these actions will be taken by an application defined problem handling function. This is automatically called when a change in the system state corresponds to one of the action flags set by the application, and can then access the system log and system state variables and other information and use OCEOSmp directives to take the appropriate actions.
When an OCEOSmp task is created a termination function for the task is usually defined and this allows tasks that have already started be terminated in an orderly way if the CPU on which they are executing is found to be faulty.
An OCEOSmp directive causes an exit from OCEOSmp and return with an appropriate status code to the main application code that started OCEOSmp. This directive is used automatically by OCEOSmp if it detects a fatal error, and can be used by the application code. As well as the returned status code the main application code can readily access the system state variable, system logs, and all task and other information, and can use an OCEOSmp directive to restart scheduling.

== Implementation ==
The core aspects of OCEOSmp are written in C. This includes the code for initialising OCEOSmp data structures, for scheduling, and for mutexes, read-write mutexes, counting semaphores, data queues and timed actions.
CPU specific code is written in C and in assembly language for that CPU. This includes spin-lock mechanisms and interrupt control.
All OCEOSmp code is re-entrant and can be run in parallel on multiple CPUs. Spin locks and interrupt disabling are used to allow updating of shared data. Interrupts disabled times are kept to a minimum.
Use of the stack resource policy means that only a single system stack is needed for each CPU rather than a stack for each task. Context switch operations are basically function calls and done quickly.
A central priority queue of CPUs is used where CPU priority is based on having sufficient remaining stack space to allow pre-emption and on the pre-emption threshold of the currently executing task. If the highest priority pending task has higher priority than the threshold and the CPU has stack space then context switch processing is started on that CPU and its current task is pre-empted.
CPUs can be reserved for use only by tasks above a certain priority.
Behaviour is deterministic. The highest priority waiting task will always be run if sufficient stack space has been allocated.
OCEOSmp uses a log area, fixed data area, dynamic data area and stack area. The stack area is divided equally between the CPUs and initialised with a filler, allowing the maximum stack use by each CPU be readily determined. The other areas are typically set up as static arrays of 32-bit words with sentinels at each end and a size immediately after the first sentinel. The fixed data area contains pointers to the main components of all areas to simplify access and a checksum set when initialisation is complete.
The Misra-C standard is automatically applied to all C code and any exceptions justified.
The Eclipse IDE is used for development in conjunction with a Subversion code repository, and OCE’s DMON tool and other tools used in debugging.

== Efficiency ==
The use of the stack resource policy greatly simplifies context switching, allowing it be treated as essentially a function call to the start function of a task. Context switch times are expected to be significantly faster than for other RTOS.

== Compactness ==
In traditional RTOS each task must be allocated its own stack, and this must be done relatively generously. With many tasks, considerable RAM can be required.
With just one stack required per CPU the stack requirements in OCEOSmp are much less, perhaps making it possible to reduce the number of memory chips in a system.
OCEOSmp does not use virtual addressing, allowing further savings in memory as page tables are not required.
The code for OCEOSmp core components is small, about 20KiB.

[[Category:backup]]

OCEOSmp/directive reference

2024-06-24T16:16:12Z

Bkavanagh: /* oceos_timed_output_number() */

= Introduction =

To be added

= Directives =

== Initialisation directives ==

===oceos_init()===
<blockquote style="border-left-style: none;">
'''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 [[OCEOSmp/directive_reference#oceos_init_finish()|oceos_init_finish()]] has completed successfully. 
'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>
'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
/*
* 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
</syntaxhighlight>
</blockquote>

===oceos_init_finish()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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);
</syntaxhighlight>
'''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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
/*
* 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
</syntaxhighlight>
</blockquote>

===oceos_start()===
<blockquote style="border-left-style: none;">
'''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 [[OCEOSmp/directive_reference#oceos_init()|oceos_init()]] and [[OCEOSmp/directive_reference#oceos_init_finish()|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''' 
<syntaxhighlight lang="C">
/**
* 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
);

</syntaxhighlight>
'''Parameters''' 
{| class="wikitable"
|-
! 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. 
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
/* 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);
</syntaxhighlight>
</blockquote>

===oceos_exit()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''initialisation.h''''' 

'''Description''' 
Ends scheduling and exit from [[OCEOSmp/directive_reference#oceos_start()|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''' 
<syntaxhighlight lang="C">
/**
* 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);

</syntaxhighlight>
'''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. 
{| class="wikitable"
|-
! Error bit || Description
|-
| ERR_SYS_FIXED_CORRUPT || System Fixed area corrupt
|-
| ERR_WRONG_PHASE || Called before scheduling started
|}

'''Example Usage''' 
<syntaxhighlight lang="C">
// Exit OCEOS
oceos_exit();
</syntaxhighlight>
</blockquote>

===oceos_CPU_sleep()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''initialisation.h''''' 

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

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* Puts CPU in sleep mode.
* User must to be sure that interrupts are enabled.
*
* @return OCEOS_SUCCESS
*/
S32_t oceos_CPU_sleep(void);
</syntaxhighlight>

'''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''' 
<syntaxhighlight lang="C">
// Put CPU to sleep
oceos_CPU_sleep();
</syntaxhighlight>
</blockquote>

===oceosmp_cpu_disable()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''initialisation.h''''' 

'''Description''' 
This function ends execution of all tasks running on particular CPU and removes the CPU from scheduling.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, faulty_cpu;
...
// Disable faulty CPU core
status = oceosmp_cpu_disable(faulty_cpu));

</syntaxhighlight>
</blockquote>

===oceosmp_cpu_enable()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, good_cpu;
...
// Enable CPU core
status = oceosmp_cpu_enable(good_cpu));

</syntaxhighlight>
</blockquote>

===oceosmp_cpu_terminate()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, faulty_cpu;
...
// Terminate CPU core
status = oceosmp_cpu_terminate(faulty_cpu));

</syntaxhighlight>
</blockquote>

==Task directives==
{| class="wikitable"
|+ API Functions
|-
| Directive || Description || main || task || IRQ handler
|-
| [[OCEOSmp/directive reference#oceos_task_create()| oceos_task_create()]] || Create Task || * || ||
|-
| [[OCEOSmp/directive reference#oceos_task_start()| oceos_task_start()]] || Start Task || || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_timed_start()| oceos_task_timed_start()]] || Schedule a task to start execution at a given system time|| || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_disable()| oceos_task_disable()]] || Disable Task || || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_enable()| oceos_task_enable()]] || Enable Task || || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_self()| oceos_task_self()]] || Returns the task ID of the currently executing task || || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_get_priority()| oceos_task_get_priority()]] || Get priority of a task || || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_get_status()| oceos_task_get_status()]] || Get status of a task || || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_kill()| oceos_task_kill()]] || Directive to terminate current task|| || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_get_info()| oceos_task_get_info()]] || Get task information || || * || *
|-
| [[OCEOSmp/directive reference#oceosmp_task_kill()| oceosmp_task_kill()]] || Directive to terminate current task|| || * || *
|}

===Task data structures===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
The following data structures are used by some of the task directives.

'''Data structures''' 
<syntaxhighlight lang="C">
/**
* 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
};

</syntaxhighlight>

===oceos_task_create()===
<blockquote style="border-left-style: none;">

'''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 [[OCEOSmp/directive_reference#oceos_init()|oceos_init()]] and before [[OCEOSmp/directive_reference#oceos_init_finish()|oceos_init_finish()]]. 
It must be called for each task otherwise [[OCEOSmp/directive_reference#oceos_start()|oceos_start()]] will return an error.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>
'''Parameters''' 
{| class="wikitable"
|-
! 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.

{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">

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

</syntaxhighlight>
</blockquote>

===oceos_task_start()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
void *ptr;
...
// Start instance of task T_1 passing pointer ptr
status = oceos_task_start(t_1,ptr);

</syntaxhighlight>
</blockquote>

===oceos_task_timed_start()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function schedules a task to start execution at a given system time.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_task_disable()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''initialisation.h''''' 

'''Description''' 
This function disables a task and removes any current pending jobs from the readyQ.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.

{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Disable task t_1
status = oceos_task_disable(t_1);

</syntaxhighlight>
</blockquote>

===oceos_task_enable()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function enables a task. Only enabled tasks may be started.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);

</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Enable task t_2
status = oceos_task_enable(t_2);

</syntaxhighlight>
</blockquote>

===oceos_task_self()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function returns the task number of the currently running task on the calling CPU.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status, task_running;
...
// Return task ID that's running on this core
status = oceos_task_self(&task_running);

</syntaxhighlight>
</blockquote>

===oceos_task_get_priority()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function returns the priority of the task ID passed to it.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
U32_t t_priority;
...
// Return the priority of task ID t_4
status = oceos_task_get_priority(t_4, &t_priority);

</syntaxhighlight>
</blockquote>

===oceos_task_get_status()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function returns the status of the task ID passed to it.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
U32_t t_status;
...
// Return the status of task ID t_4
status = oceos_task_get_status(t_4, &t_status);

</syntaxhighlight>
</blockquote>

===oceos_task_get_info()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function returns the task information for the specified task.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
struct task_info info;
...
// Get information for task T3
status = oceos_task_get_info(t_3, &info);

</syntaxhighlight>
</blockquote>

===oceosmp_task_kill()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function kills the specified task running on the specified CPU.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Kill task t_2 on CPU cpu_1
status = oceosmp_task_kill(t_2, cpu_1);

</syntaxhighlight>
</blockquote>

==Mutex directives==

===oceos_mutex_create()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''mutex.h''''' 

'''Description''' 
This function creates a mutex of specified ID with a specified priority ceiling.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Create mutex with ID print_mutex and priority ceiling of 5
status = oceos_mutex_create(print_mutex, 5);

</syntaxhighlight>
</blockquote>

===oceos_mutex_wait()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''mutex.h''''' 

'''Description''' 
This function makes the task wait until the specified mutex is available.

'''Prototype''' 
<syntaxhighlight lang="C">
/*
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Wait on mutex m_2
status = oceos_mutex_wait(m_2);

</syntaxhighlight>
</blockquote>

===oceos_mutex_signal()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''mutex.h''''' 

'''Description''' 
This function signals the specified mutex.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Signal mutex m_2
status = oceos_mutex_signal(m_2);

</syntaxhighlight>
</blockquote>

===oceos_mutex_get_value()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''mutex.h''''' 

'''Description''' 
This function returns the value of the specified mutex.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
U32_t value;
...
// Get value of mutex m_2
status = oceos_mutex_get_value(m_2, &value);

</syntaxhighlight>
</blockquote>

==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()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''rwmutex.h''''' 

'''Description''' 
This function ees a read/write mutex.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Create read/write mutex with ID rwm_2 and priority ceiling of 100
status = oceos_rwmutex_create(rwm_1, 100);

</syntaxhighlight>
</blockquote>

===oceos_rwmutex_read_wait()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Acquire read/write mutex rwm_1 for read
status = oceos_rwmutex_read_wait(rwm_1);
</syntaxhighlight>
</blockquote>

===oceos_rwmutex_write_wait()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Acquire read/write mutex rwm_1 for write
status = oceos_rwmutex_read_wait(rwm_1);
</syntaxhighlight>
</blockquote>

===oceos_rwmutex_signal()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Signal read/write mutex number rwm_4
status = oceos_rwmutex_signal(rwm_4);
</syntaxhighlight>
</blockquote>

===oceos_rwmutex_check_status()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status, rwm_status;
...
// Check the status of read/write mutex rwm_2
status = oceos_rwmutex_check_status(rwm_2, &rwm_status);
</syntaxhighlight>
</blockquote>

===oceos_rwmutex_reading_count()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''rwmutex.h''''' 

'''Description''' 
This function returns the current number of jobs holding a specified read/write mutex for read.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
*
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_rwmutex_write_reqs_count()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''header.h''''' 

'''Description''' 
This function returns the current number of write requests for the specified read/write mutex .

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
| 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_rwmutex_writes_pending_count()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''rwmutex.h''''' 

'''Description''' 
This function returns the current number of pending writes for the specified read/write mutex.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>

===oceos_rwmutex_holding()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''header.h''''' 

'''Description''' 
This function returns the read/write mutexes currently held by this instance of this task (job).

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
U64_t rwm_held;
...
// Which read/write mutexes does this job hold
status = oceos_rwmutex_holding(&rwm_held);

</syntaxhighlight>
</blockquote>

== Semaphores directives ==

===oceos_sem_create()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''semaphore.h''''' 

'''Description''' 
This function creates a semaphore.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_sem_signal()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''semaphore.h''''' 

'''Description''' 
This function signals a semaphore, increments its count and transfers pending jobs to the ready queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Signal s_audi semaphore (increment its count)
status = oceos_sem_signal(s_audi);
</syntaxhighlight>
</blockquote>

===oceos_sem_wait_continue()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''semaphore.h''''' 

'''Description''' 
This function decrements the available permits of a sempahore otherwise returns an unsuccessful status code.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Decrement available permits on semaphore s_1
status = oceos_sem_wait_continue(s_1);

</syntaxhighlight>
</blockquote>

===oceos_sem_wait_restart()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Decrement available permits on semaphore s_1 otherwise job is put on pending queue
status = oceos_sem_wait_restart(s_1);

</syntaxhighlight>
</blockquote>

===oceos_sem_wait_restart_timeout()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! Parameter || Description
|-
| sem_id || U32_t value of semaphore to be decremented
|-
| timeout | 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>

===oceos_sem_get_value()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''semaphore.h''''' 

'''Description''' 
This function returns the number of available permits for the specified semaphore.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status, permit_count;
...
// Get the available permits for semaphore s_1
status = oceos_sem_get_value(s_1, &permit_count);

</syntaxhighlight>
</blockquote>

===oceos_sem_penq_get_size()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''semaphore.h''''' 

'''Description''' 
This function returns the number of jobs on the specified semaphore pending queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status, job_count;
...
// Get the available permits for semaphore s_1
status = oceos_sem_penq_get_size(s_1, &job_count);

</syntaxhighlight>
</blockquote>

===oceos_sem_reset()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Reset semaphore s_1
status = oceos_sem_reset(s_1);
</syntaxhighlight>
</blockquote>

== Data Queues ==

===oceos_dataq_create()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''dataq.h''''' 

'''Description''' 
This function creates a data queue with the specified characteristics.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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));
</syntaxhighlight>
</blockquote>

===oceos_dataq_write()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''dataq.h''''' 

'''Description''' 
This function puts a non-null pointer on the specified data queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>

===oceos_dataq_read_continue()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''dataq.h''''' 

'''Description''' 
This function returns a pointer from the specified data queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
char *data_ptr;
...
// Read pointer from data queue s_2
status = oceos_dataq_read_continue(s_2, (void *)data_ptr);
</syntaxhighlight>
</blockquote>

===oceos_dataq_read_restart()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>

===oceos_dataq_read_restart_timeout()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>

===oceos_dataq_get_size()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''dataq.h''''' 

'''Description''' 
This function returns the number of items on the specified data queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status, d_size;
...
// Get the number of entries on data queue d_0
status = oceos_dataq_get_size(d_0, &d_size);
</syntaxhighlight>
</blockquote>

===oceos_dataq_penq_get_size()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''dataq.h''''' 

'''Description''' 
This function returns number of jobs on the specified data queue pending job's queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>

===oceos_dataq_clear()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''dataq.h''''' 

'''Description''' 
This function clears the specified data queue including pending jobs for that queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Clear data queue d_1
status = oceos_dataq_penq_get_size(d_1);
</syntaxhighlight>
</blockquote>

== Timed Actions ==

===oceos_timed_output_add()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
| 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">

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

</syntaxhighlight>
</blockquote>

===oceos_timed_jobs_number()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''timed_action.h''''' 

'''Description''' 
This function returns the number of jobs on the timed actions queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, no_of_jobs;
...
// Get the number of jobs on the timed actions queue
status = oceos_timed_jobs_number(&no_of_jobs);

</syntaxhighlight>
</blockquote>

===oceos_timed_output_number()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''timed_action.h''''' 

'''Description''' 
This function returns the number timed output actions waiting on the timed actions queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_timed_jobs_remove()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''timed_action.h''''' 

'''Description''' 
This function removes the specified timed action from the queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, job_id;
...
// Remove job_id from the timed actions queue
status = oceos_timed_jobs_remove(job_id);

</syntaxhighlight>
</blockquote>

===oceos_timed_jobs_reset()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''timed_action.h''''' 

'''Description''' 
This function removes all jobs from timed actions queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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);
</syntaxhighlight>

'''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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Remove all jobs from the timed actions queue
status = oceos_timed_jobs_reset(job_id);
</syntaxhighlight>
</blockquote>

===oceos_timed_output_remove()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''timed_action.h''''' 

'''Description''' 
This function removes the specified timed output action from timed actions queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
| 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''' 
<syntaxhighlight lang="C">
S32_t status;
U8_t action_index;
...
// Remove timed output with specified action_index
status = oceos_timed_output_remove(action_index);

</syntaxhighlight>
</blockquote>

===oceos_timed_output_reset()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''timed_action.h''''' 

'''Description''' 
This function removes all timed output actions from timed actions queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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);
</syntaxhighlight>

'''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.
{| class="wikitable"
|-
| 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Remove all timed outputs from the timed actions queue
status = oceos_timed_output_reset();

</syntaxhighlight>
</blockquote>

== Logging directives ==

===Introduction===
<blockquote style="border-left-style: none;">

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''' 
<syntaxhighlight lang="C">
/*****************************************************************************
* 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)));

</syntaxhighlight>

===oceos_log_add_entry()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! Parameter || Description
|-
| enum LOG_ENTRY_TYPE || Log entry type (see previous section for a list)
|-
| info | 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_log_get_indexed_entry()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_log_remove_entry()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_log_reset()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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);
</syntaxhighlight>

'''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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...

// Clear down the system log
status = oceos_log_reset();

</syntaxhighlight>
</blockquote>

===oceos_log_get_size()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, size;
...

// Clear down the system log
status = oceos_log_get_size(&size);

</syntaxhighlight>
</blockquote>

===System State Variable and System State Mask===
<blockquote style="border-left-style: none;">

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''' 
<syntaxhighlight lang="C">

#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

</syntaxhighlight>

===oceos_system_state_get()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''system_log.h''''' 

'''Description''' 
This function returns of the system state variable.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, state;
...

// Get the system state
status = oceos_system_state_get(&state);

</syntaxhighlight>
</blockquote>

===oceos_system_state_set()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''system_log.h''''' 

'''Description''' 
This function sets system state variable.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! Error bit !! Description
|-
| ERR_SYS_FIXED_CORRUPT || System Fixed area corrupt
|-
| ERR_SYS_LOG_CORRUPT || LOG dynamic pointer is null
|}

'''Example Usage''' 
<syntaxhighlight lang="C">
S32_t status, new_state;
...

// Set new system state
status = oceos_system_state_set(new_state);

</syntaxhighlight>
</blockquote>

===oceos_system_state_copy_get()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''system_log.h''''' 

'''Description''' 
This function returns the value of the system state copy variable.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, copy_state;
...

// Get the system state copy
status = oceos_system_state_copy_get(&copy_state);

</syntaxhighlight>
</blockquote>

===oceos_system_state_copy_set()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''system_log.h''''' 

'''Description''' 
This function loads a value to tha system state copy variable.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! Error bit !! Description
|-
| ERR_SYS_FIXED_CORRUPT || System Fixed area corrupt
|-
| ERR_SYS_LOG_CORRUPT || LOG dynamic pointer is null
|}

'''Example Usage''' 
<syntaxhighlight lang="C">
S32_t status, new_state;
...

// Set new system state copy
status = oceos_system_state_copy_set(new_state);

</syntaxhighlight>
</blockquote>

== Timing directives ==

===Introduction===
<blockquote style="border-left-style: none;">

'''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()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''oceos_timer.h''''' 

'''Description''' 
This function returns the current system time as a 64-bit number.

'''Prototype''' 
<syntaxhighlight lang="C">
**
* Get the current system time (64-bit)
*
* @return U64_t
*/
U64_t oceos_time_sys_get64(void);
</syntaxhighlight>

'''Parameters''' 

There are no parameters to this function.

'''Returns''' 
This function returns an S64_t with the current system time.

'''Example Usage''' 
<syntaxhighlight lang="C">
S64_t now;
...
// Get the time
now = oceos_time_sys_get64();
</syntaxhighlight>
</blockquote>

===oceos_time_sys_get32()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''oceos_timer.h''''' 

'''Description''' 
This function returns the low 32 bits of the system time.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* Get the current system time (low 32 bits of 64 bit value)
*
* @return U32_t
*/
U32_t oceos_time_sys_get32(void);
</syntaxhighlight>

'''Parameters''' 
There are no parameters to this function.

'''Returns''' 
This function returns an S32_t with the current system time.

'''Example Usage''' 
<syntaxhighlight lang="C">
S32_t now;
...
// Get the time
now = oceos_time_sys_get32();
</syntaxhighlight>
</blockquote>

[[Category:backup]]

OCEOSmp/directive reference

2024-06-24T16:14:03Z

Bkavanagh: /* oceos_timed_output_number() */

= Introduction =

To be added

= Directives =

== Initialisation directives ==

===oceos_init()===
<blockquote style="border-left-style: none;">
'''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 [[OCEOSmp/directive_reference#oceos_init_finish()|oceos_init_finish()]] has completed successfully. 
'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>
'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
/*
* 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
</syntaxhighlight>
</blockquote>

===oceos_init_finish()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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);
</syntaxhighlight>
'''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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
/*
* 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
</syntaxhighlight>
</blockquote>

===oceos_start()===
<blockquote style="border-left-style: none;">
'''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 [[OCEOSmp/directive_reference#oceos_init()|oceos_init()]] and [[OCEOSmp/directive_reference#oceos_init_finish()|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''' 
<syntaxhighlight lang="C">
/**
* 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
);

</syntaxhighlight>
'''Parameters''' 
{| class="wikitable"
|-
! 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. 
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
/* 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);
</syntaxhighlight>
</blockquote>

===oceos_exit()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''initialisation.h''''' 

'''Description''' 
Ends scheduling and exit from [[OCEOSmp/directive_reference#oceos_start()|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''' 
<syntaxhighlight lang="C">
/**
* 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);

</syntaxhighlight>
'''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. 
{| class="wikitable"
|-
! Error bit || Description
|-
| ERR_SYS_FIXED_CORRUPT || System Fixed area corrupt
|-
| ERR_WRONG_PHASE || Called before scheduling started
|}

'''Example Usage''' 
<syntaxhighlight lang="C">
// Exit OCEOS
oceos_exit();
</syntaxhighlight>
</blockquote>

===oceos_CPU_sleep()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''initialisation.h''''' 

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

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* Puts CPU in sleep mode.
* User must to be sure that interrupts are enabled.
*
* @return OCEOS_SUCCESS
*/
S32_t oceos_CPU_sleep(void);
</syntaxhighlight>

'''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''' 
<syntaxhighlight lang="C">
// Put CPU to sleep
oceos_CPU_sleep();
</syntaxhighlight>
</blockquote>

===oceosmp_cpu_disable()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''initialisation.h''''' 

'''Description''' 
This function ends execution of all tasks running on particular CPU and removes the CPU from scheduling.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, faulty_cpu;
...
// Disable faulty CPU core
status = oceosmp_cpu_disable(faulty_cpu));

</syntaxhighlight>
</blockquote>

===oceosmp_cpu_enable()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, good_cpu;
...
// Enable CPU core
status = oceosmp_cpu_enable(good_cpu));

</syntaxhighlight>
</blockquote>

===oceosmp_cpu_terminate()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, faulty_cpu;
...
// Terminate CPU core
status = oceosmp_cpu_terminate(faulty_cpu));

</syntaxhighlight>
</blockquote>

==Task directives==
{| class="wikitable"
|+ API Functions
|-
| Directive || Description || main || task || IRQ handler
|-
| [[OCEOSmp/directive reference#oceos_task_create()| oceos_task_create()]] || Create Task || * || ||
|-
| [[OCEOSmp/directive reference#oceos_task_start()| oceos_task_start()]] || Start Task || || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_timed_start()| oceos_task_timed_start()]] || Schedule a task to start execution at a given system time|| || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_disable()| oceos_task_disable()]] || Disable Task || || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_enable()| oceos_task_enable()]] || Enable Task || || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_self()| oceos_task_self()]] || Returns the task ID of the currently executing task || || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_get_priority()| oceos_task_get_priority()]] || Get priority of a task || || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_get_status()| oceos_task_get_status()]] || Get status of a task || || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_kill()| oceos_task_kill()]] || Directive to terminate current task|| || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_get_info()| oceos_task_get_info()]] || Get task information || || * || *
|-
| [[OCEOSmp/directive reference#oceosmp_task_kill()| oceosmp_task_kill()]] || Directive to terminate current task|| || * || *
|}

===Task data structures===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
The following data structures are used by some of the task directives.

'''Data structures''' 
<syntaxhighlight lang="C">
/**
* 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
};

</syntaxhighlight>

===oceos_task_create()===
<blockquote style="border-left-style: none;">

'''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 [[OCEOSmp/directive_reference#oceos_init()|oceos_init()]] and before [[OCEOSmp/directive_reference#oceos_init_finish()|oceos_init_finish()]]. 
It must be called for each task otherwise [[OCEOSmp/directive_reference#oceos_start()|oceos_start()]] will return an error.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>
'''Parameters''' 
{| class="wikitable"
|-
! 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.

{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">

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

</syntaxhighlight>
</blockquote>

===oceos_task_start()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
void *ptr;
...
// Start instance of task T_1 passing pointer ptr
status = oceos_task_start(t_1,ptr);

</syntaxhighlight>
</blockquote>

===oceos_task_timed_start()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function schedules a task to start execution at a given system time.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_task_disable()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''initialisation.h''''' 

'''Description''' 
This function disables a task and removes any current pending jobs from the readyQ.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.

{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Disable task t_1
status = oceos_task_disable(t_1);

</syntaxhighlight>
</blockquote>

===oceos_task_enable()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function enables a task. Only enabled tasks may be started.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);

</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Enable task t_2
status = oceos_task_enable(t_2);

</syntaxhighlight>
</blockquote>

===oceos_task_self()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function returns the task number of the currently running task on the calling CPU.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status, task_running;
...
// Return task ID that's running on this core
status = oceos_task_self(&task_running);

</syntaxhighlight>
</blockquote>

===oceos_task_get_priority()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function returns the priority of the task ID passed to it.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
U32_t t_priority;
...
// Return the priority of task ID t_4
status = oceos_task_get_priority(t_4, &t_priority);

</syntaxhighlight>
</blockquote>

===oceos_task_get_status()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function returns the status of the task ID passed to it.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
U32_t t_status;
...
// Return the status of task ID t_4
status = oceos_task_get_status(t_4, &t_status);

</syntaxhighlight>
</blockquote>

===oceos_task_get_info()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function returns the task information for the specified task.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
struct task_info info;
...
// Get information for task T3
status = oceos_task_get_info(t_3, &info);

</syntaxhighlight>
</blockquote>

===oceosmp_task_kill()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function kills the specified task running on the specified CPU.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Kill task t_2 on CPU cpu_1
status = oceosmp_task_kill(t_2, cpu_1);

</syntaxhighlight>
</blockquote>

==Mutex directives==

===oceos_mutex_create()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''mutex.h''''' 

'''Description''' 
This function creates a mutex of specified ID with a specified priority ceiling.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Create mutex with ID print_mutex and priority ceiling of 5
status = oceos_mutex_create(print_mutex, 5);

</syntaxhighlight>
</blockquote>

===oceos_mutex_wait()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''mutex.h''''' 

'''Description''' 
This function makes the task wait until the specified mutex is available.

'''Prototype''' 
<syntaxhighlight lang="C">
/*
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Wait on mutex m_2
status = oceos_mutex_wait(m_2);

</syntaxhighlight>
</blockquote>

===oceos_mutex_signal()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''mutex.h''''' 

'''Description''' 
This function signals the specified mutex.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Signal mutex m_2
status = oceos_mutex_signal(m_2);

</syntaxhighlight>
</blockquote>

===oceos_mutex_get_value()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''mutex.h''''' 

'''Description''' 
This function returns the value of the specified mutex.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
U32_t value;
...
// Get value of mutex m_2
status = oceos_mutex_get_value(m_2, &value);

</syntaxhighlight>
</blockquote>

==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()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''rwmutex.h''''' 

'''Description''' 
This function ees a read/write mutex.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Create read/write mutex with ID rwm_2 and priority ceiling of 100
status = oceos_rwmutex_create(rwm_1, 100);

</syntaxhighlight>
</blockquote>

===oceos_rwmutex_read_wait()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Acquire read/write mutex rwm_1 for read
status = oceos_rwmutex_read_wait(rwm_1);
</syntaxhighlight>
</blockquote>

===oceos_rwmutex_write_wait()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Acquire read/write mutex rwm_1 for write
status = oceos_rwmutex_read_wait(rwm_1);
</syntaxhighlight>
</blockquote>

===oceos_rwmutex_signal()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Signal read/write mutex number rwm_4
status = oceos_rwmutex_signal(rwm_4);
</syntaxhighlight>
</blockquote>

===oceos_rwmutex_check_status()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status, rwm_status;
...
// Check the status of read/write mutex rwm_2
status = oceos_rwmutex_check_status(rwm_2, &rwm_status);
</syntaxhighlight>
</blockquote>

===oceos_rwmutex_reading_count()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''rwmutex.h''''' 

'''Description''' 
This function returns the current number of jobs holding a specified read/write mutex for read.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
*
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_rwmutex_write_reqs_count()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''header.h''''' 

'''Description''' 
This function returns the current number of write requests for the specified read/write mutex .

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
| 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_rwmutex_writes_pending_count()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''rwmutex.h''''' 

'''Description''' 
This function returns the current number of pending writes for the specified read/write mutex.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>

===oceos_rwmutex_holding()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''header.h''''' 

'''Description''' 
This function returns the read/write mutexes currently held by this instance of this task (job).

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
U64_t rwm_held;
...
// Which read/write mutexes does this job hold
status = oceos_rwmutex_holding(&rwm_held);

</syntaxhighlight>
</blockquote>

== Semaphores directives ==

===oceos_sem_create()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''semaphore.h''''' 

'''Description''' 
This function creates a semaphore.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_sem_signal()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''semaphore.h''''' 

'''Description''' 
This function signals a semaphore, increments its count and transfers pending jobs to the ready queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Signal s_audi semaphore (increment its count)
status = oceos_sem_signal(s_audi);
</syntaxhighlight>
</blockquote>

===oceos_sem_wait_continue()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''semaphore.h''''' 

'''Description''' 
This function decrements the available permits of a sempahore otherwise returns an unsuccessful status code.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Decrement available permits on semaphore s_1
status = oceos_sem_wait_continue(s_1);

</syntaxhighlight>
</blockquote>

===oceos_sem_wait_restart()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Decrement available permits on semaphore s_1 otherwise job is put on pending queue
status = oceos_sem_wait_restart(s_1);

</syntaxhighlight>
</blockquote>

===oceos_sem_wait_restart_timeout()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! Parameter || Description
|-
| sem_id || U32_t value of semaphore to be decremented
|-
| timeout | 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>

===oceos_sem_get_value()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''semaphore.h''''' 

'''Description''' 
This function returns the number of available permits for the specified semaphore.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status, permit_count;
...
// Get the available permits for semaphore s_1
status = oceos_sem_get_value(s_1, &permit_count);

</syntaxhighlight>
</blockquote>

===oceos_sem_penq_get_size()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''semaphore.h''''' 

'''Description''' 
This function returns the number of jobs on the specified semaphore pending queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status, job_count;
...
// Get the available permits for semaphore s_1
status = oceos_sem_penq_get_size(s_1, &job_count);

</syntaxhighlight>
</blockquote>

===oceos_sem_reset()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Reset semaphore s_1
status = oceos_sem_reset(s_1);
</syntaxhighlight>
</blockquote>

== Data Queues ==

===oceos_dataq_create()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''dataq.h''''' 

'''Description''' 
This function creates a data queue with the specified characteristics.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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));
</syntaxhighlight>
</blockquote>

===oceos_dataq_write()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''dataq.h''''' 

'''Description''' 
This function puts a non-null pointer on the specified data queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>

===oceos_dataq_read_continue()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''dataq.h''''' 

'''Description''' 
This function returns a pointer from the specified data queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
char *data_ptr;
...
// Read pointer from data queue s_2
status = oceos_dataq_read_continue(s_2, (void *)data_ptr);
</syntaxhighlight>
</blockquote>

===oceos_dataq_read_restart()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>

===oceos_dataq_read_restart_timeout()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>

===oceos_dataq_get_size()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''dataq.h''''' 

'''Description''' 
This function returns the number of items on the specified data queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status, d_size;
...
// Get the number of entries on data queue d_0
status = oceos_dataq_get_size(d_0, &d_size);
</syntaxhighlight>
</blockquote>

===oceos_dataq_penq_get_size()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''dataq.h''''' 

'''Description''' 
This function returns number of jobs on the specified data queue pending job's queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>

===oceos_dataq_clear()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''dataq.h''''' 

'''Description''' 
This function clears the specified data queue including pending jobs for that queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Clear data queue d_1
status = oceos_dataq_penq_get_size(d_1);
</syntaxhighlight>
</blockquote>

== Timed Actions ==

===oceos_timed_output_add()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
| 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">

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

</syntaxhighlight>
</blockquote>

===oceos_timed_jobs_number()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''timed_action.h''''' 

'''Description''' 
This function returns the number of jobs on the timed actions queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, no_of_jobs;
...
// Get the number of jobs on the timed actions queue
status = oceos_timed_jobs_number(&no_of_jobs);

</syntaxhighlight>
</blockquote>

===oceos_timed_output_number()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''timed_action.h''''' 

'''Description''' 
This function returns the number timed output actions waiting on the timed actions queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, no_of_outputs;
...
// Get the number of jobs on the timed actions queue
status = oceos_timed_output_number(&no_of_outputs);

</syntaxhighlight>
</blockquote>

===oceos_timed_jobs_remove()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''timed_action.h''''' 

'''Description''' 
This function removes the specified timed action from the queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, job_id;
...
// Remove job_id from the timed actions queue
status = oceos_timed_jobs_remove(job_id);

</syntaxhighlight>
</blockquote>

===oceos_timed_jobs_reset()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''timed_action.h''''' 

'''Description''' 
This function removes all jobs from timed actions queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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);
</syntaxhighlight>

'''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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Remove all jobs from the timed actions queue
status = oceos_timed_jobs_reset(job_id);
</syntaxhighlight>
</blockquote>

===oceos_timed_output_remove()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''timed_action.h''''' 

'''Description''' 
This function removes the specified timed output action from timed actions queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
| 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''' 
<syntaxhighlight lang="C">
S32_t status;
U8_t action_index;
...
// Remove timed output with specified action_index
status = oceos_timed_output_remove(action_index);

</syntaxhighlight>
</blockquote>

===oceos_timed_output_reset()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''timed_action.h''''' 

'''Description''' 
This function removes all timed output actions from timed actions queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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);
</syntaxhighlight>

'''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.
{| class="wikitable"
|-
| 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Remove all timed outputs from the timed actions queue
status = oceos_timed_output_reset();

</syntaxhighlight>
</blockquote>

== Logging directives ==

===Introduction===
<blockquote style="border-left-style: none;">

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''' 
<syntaxhighlight lang="C">
/*****************************************************************************
* 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)));

</syntaxhighlight>

===oceos_log_add_entry()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! Parameter || Description
|-
| enum LOG_ENTRY_TYPE || Log entry type (see previous section for a list)
|-
| info | 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_log_get_indexed_entry()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_log_remove_entry()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_log_reset()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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);
</syntaxhighlight>

'''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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...

// Clear down the system log
status = oceos_log_reset();

</syntaxhighlight>
</blockquote>

===oceos_log_get_size()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, size;
...

// Clear down the system log
status = oceos_log_get_size(&size);

</syntaxhighlight>
</blockquote>

===System State Variable and System State Mask===
<blockquote style="border-left-style: none;">

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''' 
<syntaxhighlight lang="C">

#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

</syntaxhighlight>

===oceos_system_state_get()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''system_log.h''''' 

'''Description''' 
This function returns of the system state variable.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, state;
...

// Get the system state
status = oceos_system_state_get(&state);

</syntaxhighlight>
</blockquote>

===oceos_system_state_set()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''system_log.h''''' 

'''Description''' 
This function sets system state variable.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! Error bit !! Description
|-
| ERR_SYS_FIXED_CORRUPT || System Fixed area corrupt
|-
| ERR_SYS_LOG_CORRUPT || LOG dynamic pointer is null
|}

'''Example Usage''' 
<syntaxhighlight lang="C">
S32_t status, new_state;
...

// Set new system state
status = oceos_system_state_set(new_state);

</syntaxhighlight>
</blockquote>

===oceos_system_state_copy_get()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''system_log.h''''' 

'''Description''' 
This function returns the value of the system state copy variable.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, copy_state;
...

// Get the system state copy
status = oceos_system_state_copy_get(&copy_state);

</syntaxhighlight>
</blockquote>

===oceos_system_state_copy_set()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''system_log.h''''' 

'''Description''' 
This function loads a value to tha system state copy variable.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! Error bit !! Description
|-
| ERR_SYS_FIXED_CORRUPT || System Fixed area corrupt
|-
| ERR_SYS_LOG_CORRUPT || LOG dynamic pointer is null
|}

'''Example Usage''' 
<syntaxhighlight lang="C">
S32_t status, new_state;
...

// Set new system state copy
status = oceos_system_state_copy_set(new_state);

</syntaxhighlight>
</blockquote>

== Timing directives ==

===Introduction===
<blockquote style="border-left-style: none;">

'''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()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''oceos_timer.h''''' 

'''Description''' 
This function returns the current system time as a 64-bit number.

'''Prototype''' 
<syntaxhighlight lang="C">
**
* Get the current system time (64-bit)
*
* @return U64_t
*/
U64_t oceos_time_sys_get64(void);
</syntaxhighlight>

'''Parameters''' 

There are no parameters to this function.

'''Returns''' 
This function returns an S64_t with the current system time.

'''Example Usage''' 
<syntaxhighlight lang="C">
S64_t now;
...
// Get the time
now = oceos_time_sys_get64();
</syntaxhighlight>
</blockquote>

===oceos_time_sys_get32()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''oceos_timer.h''''' 

'''Description''' 
This function returns the low 32 bits of the system time.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* Get the current system time (low 32 bits of 64 bit value)
*
* @return U32_t
*/
U32_t oceos_time_sys_get32(void);
</syntaxhighlight>

'''Parameters''' 
There are no parameters to this function.

'''Returns''' 
This function returns an S32_t with the current system time.

'''Example Usage''' 
<syntaxhighlight lang="C">
S32_t now;
...
// Get the time
now = oceos_time_sys_get32();
</syntaxhighlight>
</blockquote>

[[Category:backup]]

OCEOSmp/directive reference

2024-06-24T16:08:50Z

Bkavanagh: /* Timed Actions */

= Introduction =

To be added

= Directives =

== Initialisation directives ==

===oceos_init()===
<blockquote style="border-left-style: none;">
'''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 [[OCEOSmp/directive_reference#oceos_init_finish()|oceos_init_finish()]] has completed successfully. 
'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>
'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
/*
* 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
</syntaxhighlight>
</blockquote>

===oceos_init_finish()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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);
</syntaxhighlight>
'''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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
/*
* 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
</syntaxhighlight>
</blockquote>

===oceos_start()===
<blockquote style="border-left-style: none;">
'''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 [[OCEOSmp/directive_reference#oceos_init()|oceos_init()]] and [[OCEOSmp/directive_reference#oceos_init_finish()|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''' 
<syntaxhighlight lang="C">
/**
* 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
);

</syntaxhighlight>
'''Parameters''' 
{| class="wikitable"
|-
! 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. 
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
/* 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);
</syntaxhighlight>
</blockquote>

===oceos_exit()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''initialisation.h''''' 

'''Description''' 
Ends scheduling and exit from [[OCEOSmp/directive_reference#oceos_start()|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''' 
<syntaxhighlight lang="C">
/**
* 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);

</syntaxhighlight>
'''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. 
{| class="wikitable"
|-
! Error bit || Description
|-
| ERR_SYS_FIXED_CORRUPT || System Fixed area corrupt
|-
| ERR_WRONG_PHASE || Called before scheduling started
|}

'''Example Usage''' 
<syntaxhighlight lang="C">
// Exit OCEOS
oceos_exit();
</syntaxhighlight>
</blockquote>

===oceos_CPU_sleep()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''initialisation.h''''' 

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

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* Puts CPU in sleep mode.
* User must to be sure that interrupts are enabled.
*
* @return OCEOS_SUCCESS
*/
S32_t oceos_CPU_sleep(void);
</syntaxhighlight>

'''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''' 
<syntaxhighlight lang="C">
// Put CPU to sleep
oceos_CPU_sleep();
</syntaxhighlight>
</blockquote>

===oceosmp_cpu_disable()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''initialisation.h''''' 

'''Description''' 
This function ends execution of all tasks running on particular CPU and removes the CPU from scheduling.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, faulty_cpu;
...
// Disable faulty CPU core
status = oceosmp_cpu_disable(faulty_cpu));

</syntaxhighlight>
</blockquote>

===oceosmp_cpu_enable()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, good_cpu;
...
// Enable CPU core
status = oceosmp_cpu_enable(good_cpu));

</syntaxhighlight>
</blockquote>

===oceosmp_cpu_terminate()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, faulty_cpu;
...
// Terminate CPU core
status = oceosmp_cpu_terminate(faulty_cpu));

</syntaxhighlight>
</blockquote>

==Task directives==
{| class="wikitable"
|+ API Functions
|-
| Directive || Description || main || task || IRQ handler
|-
| [[OCEOSmp/directive reference#oceos_task_create()| oceos_task_create()]] || Create Task || * || ||
|-
| [[OCEOSmp/directive reference#oceos_task_start()| oceos_task_start()]] || Start Task || || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_timed_start()| oceos_task_timed_start()]] || Schedule a task to start execution at a given system time|| || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_disable()| oceos_task_disable()]] || Disable Task || || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_enable()| oceos_task_enable()]] || Enable Task || || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_self()| oceos_task_self()]] || Returns the task ID of the currently executing task || || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_get_priority()| oceos_task_get_priority()]] || Get priority of a task || || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_get_status()| oceos_task_get_status()]] || Get status of a task || || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_kill()| oceos_task_kill()]] || Directive to terminate current task|| || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_get_info()| oceos_task_get_info()]] || Get task information || || * || *
|-
| [[OCEOSmp/directive reference#oceosmp_task_kill()| oceosmp_task_kill()]] || Directive to terminate current task|| || * || *
|}

===Task data structures===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
The following data structures are used by some of the task directives.

'''Data structures''' 
<syntaxhighlight lang="C">
/**
* 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
};

</syntaxhighlight>

===oceos_task_create()===
<blockquote style="border-left-style: none;">

'''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 [[OCEOSmp/directive_reference#oceos_init()|oceos_init()]] and before [[OCEOSmp/directive_reference#oceos_init_finish()|oceos_init_finish()]]. 
It must be called for each task otherwise [[OCEOSmp/directive_reference#oceos_start()|oceos_start()]] will return an error.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>
'''Parameters''' 
{| class="wikitable"
|-
! 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.

{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">

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

</syntaxhighlight>
</blockquote>

===oceos_task_start()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
void *ptr;
...
// Start instance of task T_1 passing pointer ptr
status = oceos_task_start(t_1,ptr);

</syntaxhighlight>
</blockquote>

===oceos_task_timed_start()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function schedules a task to start execution at a given system time.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_task_disable()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''initialisation.h''''' 

'''Description''' 
This function disables a task and removes any current pending jobs from the readyQ.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.

{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Disable task t_1
status = oceos_task_disable(t_1);

</syntaxhighlight>
</blockquote>

===oceos_task_enable()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function enables a task. Only enabled tasks may be started.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);

</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Enable task t_2
status = oceos_task_enable(t_2);

</syntaxhighlight>
</blockquote>

===oceos_task_self()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function returns the task number of the currently running task on the calling CPU.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status, task_running;
...
// Return task ID that's running on this core
status = oceos_task_self(&task_running);

</syntaxhighlight>
</blockquote>

===oceos_task_get_priority()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function returns the priority of the task ID passed to it.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
U32_t t_priority;
...
// Return the priority of task ID t_4
status = oceos_task_get_priority(t_4, &t_priority);

</syntaxhighlight>
</blockquote>

===oceos_task_get_status()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function returns the status of the task ID passed to it.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
U32_t t_status;
...
// Return the status of task ID t_4
status = oceos_task_get_status(t_4, &t_status);

</syntaxhighlight>
</blockquote>

===oceos_task_get_info()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function returns the task information for the specified task.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
struct task_info info;
...
// Get information for task T3
status = oceos_task_get_info(t_3, &info);

</syntaxhighlight>
</blockquote>

===oceosmp_task_kill()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function kills the specified task running on the specified CPU.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Kill task t_2 on CPU cpu_1
status = oceosmp_task_kill(t_2, cpu_1);

</syntaxhighlight>
</blockquote>

==Mutex directives==

===oceos_mutex_create()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''mutex.h''''' 

'''Description''' 
This function creates a mutex of specified ID with a specified priority ceiling.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Create mutex with ID print_mutex and priority ceiling of 5
status = oceos_mutex_create(print_mutex, 5);

</syntaxhighlight>
</blockquote>

===oceos_mutex_wait()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''mutex.h''''' 

'''Description''' 
This function makes the task wait until the specified mutex is available.

'''Prototype''' 
<syntaxhighlight lang="C">
/*
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Wait on mutex m_2
status = oceos_mutex_wait(m_2);

</syntaxhighlight>
</blockquote>

===oceos_mutex_signal()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''mutex.h''''' 

'''Description''' 
This function signals the specified mutex.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Signal mutex m_2
status = oceos_mutex_signal(m_2);

</syntaxhighlight>
</blockquote>

===oceos_mutex_get_value()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''mutex.h''''' 

'''Description''' 
This function returns the value of the specified mutex.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
U32_t value;
...
// Get value of mutex m_2
status = oceos_mutex_get_value(m_2, &value);

</syntaxhighlight>
</blockquote>

==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()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''rwmutex.h''''' 

'''Description''' 
This function ees a read/write mutex.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Create read/write mutex with ID rwm_2 and priority ceiling of 100
status = oceos_rwmutex_create(rwm_1, 100);

</syntaxhighlight>
</blockquote>

===oceos_rwmutex_read_wait()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Acquire read/write mutex rwm_1 for read
status = oceos_rwmutex_read_wait(rwm_1);
</syntaxhighlight>
</blockquote>

===oceos_rwmutex_write_wait()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Acquire read/write mutex rwm_1 for write
status = oceos_rwmutex_read_wait(rwm_1);
</syntaxhighlight>
</blockquote>

===oceos_rwmutex_signal()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Signal read/write mutex number rwm_4
status = oceos_rwmutex_signal(rwm_4);
</syntaxhighlight>
</blockquote>

===oceos_rwmutex_check_status()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status, rwm_status;
...
// Check the status of read/write mutex rwm_2
status = oceos_rwmutex_check_status(rwm_2, &rwm_status);
</syntaxhighlight>
</blockquote>

===oceos_rwmutex_reading_count()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''rwmutex.h''''' 

'''Description''' 
This function returns the current number of jobs holding a specified read/write mutex for read.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
*
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_rwmutex_write_reqs_count()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''header.h''''' 

'''Description''' 
This function returns the current number of write requests for the specified read/write mutex .

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
| 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_rwmutex_writes_pending_count()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''rwmutex.h''''' 

'''Description''' 
This function returns the current number of pending writes for the specified read/write mutex.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>

===oceos_rwmutex_holding()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''header.h''''' 

'''Description''' 
This function returns the read/write mutexes currently held by this instance of this task (job).

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
U64_t rwm_held;
...
// Which read/write mutexes does this job hold
status = oceos_rwmutex_holding(&rwm_held);

</syntaxhighlight>
</blockquote>

== Semaphores directives ==

===oceos_sem_create()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''semaphore.h''''' 

'''Description''' 
This function creates a semaphore.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_sem_signal()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''semaphore.h''''' 

'''Description''' 
This function signals a semaphore, increments its count and transfers pending jobs to the ready queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Signal s_audi semaphore (increment its count)
status = oceos_sem_signal(s_audi);
</syntaxhighlight>
</blockquote>

===oceos_sem_wait_continue()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''semaphore.h''''' 

'''Description''' 
This function decrements the available permits of a sempahore otherwise returns an unsuccessful status code.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Decrement available permits on semaphore s_1
status = oceos_sem_wait_continue(s_1);

</syntaxhighlight>
</blockquote>

===oceos_sem_wait_restart()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Decrement available permits on semaphore s_1 otherwise job is put on pending queue
status = oceos_sem_wait_restart(s_1);

</syntaxhighlight>
</blockquote>

===oceos_sem_wait_restart_timeout()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! Parameter || Description
|-
| sem_id || U32_t value of semaphore to be decremented
|-
| timeout | 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>

===oceos_sem_get_value()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''semaphore.h''''' 

'''Description''' 
This function returns the number of available permits for the specified semaphore.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status, permit_count;
...
// Get the available permits for semaphore s_1
status = oceos_sem_get_value(s_1, &permit_count);

</syntaxhighlight>
</blockquote>

===oceos_sem_penq_get_size()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''semaphore.h''''' 

'''Description''' 
This function returns the number of jobs on the specified semaphore pending queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status, job_count;
...
// Get the available permits for semaphore s_1
status = oceos_sem_penq_get_size(s_1, &job_count);

</syntaxhighlight>
</blockquote>

===oceos_sem_reset()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Reset semaphore s_1
status = oceos_sem_reset(s_1);
</syntaxhighlight>
</blockquote>

== Data Queues ==

===oceos_dataq_create()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''dataq.h''''' 

'''Description''' 
This function creates a data queue with the specified characteristics.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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));
</syntaxhighlight>
</blockquote>

===oceos_dataq_write()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''dataq.h''''' 

'''Description''' 
This function puts a non-null pointer on the specified data queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>

===oceos_dataq_read_continue()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''dataq.h''''' 

'''Description''' 
This function returns a pointer from the specified data queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
char *data_ptr;
...
// Read pointer from data queue s_2
status = oceos_dataq_read_continue(s_2, (void *)data_ptr);
</syntaxhighlight>
</blockquote>

===oceos_dataq_read_restart()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>

===oceos_dataq_read_restart_timeout()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>

===oceos_dataq_get_size()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''dataq.h''''' 

'''Description''' 
This function returns the number of items on the specified data queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status, d_size;
...
// Get the number of entries on data queue d_0
status = oceos_dataq_get_size(d_0, &d_size);
</syntaxhighlight>
</blockquote>

===oceos_dataq_penq_get_size()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''dataq.h''''' 

'''Description''' 
This function returns number of jobs on the specified data queue pending job's queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>

===oceos_dataq_clear()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''dataq.h''''' 

'''Description''' 
This function clears the specified data queue including pending jobs for that queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Clear data queue d_1
status = oceos_dataq_penq_get_size(d_1);
</syntaxhighlight>
</blockquote>

== Timed Actions ==

===oceos_timed_output_add()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
| 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">

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

</syntaxhighlight>
</blockquote>

===oceos_timed_jobs_number()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''timed_action.h''''' 

'''Description''' 
This function returns the number of jobs on the timed actions queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, no_of_jobs;
...
// Get the number of jobs on the timed actions queue
status = oceos_timed_jobs_number(&no_of_jobs);

</syntaxhighlight>
</blockquote>

===oceos_timed_output_number()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''timed_action.h''''' 

'''Description''' 
This function returns the number of jobs on the timed actions queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, no_of_jobs;
...
// Get the number of jobs on the timed actions queue
status = oceos_timed_jobs_number(&no_of_jobs);

</syntaxhighlight>
</blockquote>

===oceos_timed_jobs_remove()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''timed_action.h''''' 

'''Description''' 
This function removes the specified timed action from the queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, job_id;
...
// Remove job_id from the timed actions queue
status = oceos_timed_jobs_remove(job_id);

</syntaxhighlight>
</blockquote>

===oceos_timed_jobs_reset()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''timed_action.h''''' 

'''Description''' 
This function removes all jobs from timed actions queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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);
</syntaxhighlight>

'''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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Remove all jobs from the timed actions queue
status = oceos_timed_jobs_reset(job_id);
</syntaxhighlight>
</blockquote>

===oceos_timed_output_remove()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''timed_action.h''''' 

'''Description''' 
This function removes the specified timed output action from timed actions queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
| 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''' 
<syntaxhighlight lang="C">
S32_t status;
U8_t action_index;
...
// Remove timed output with specified action_index
status = oceos_timed_output_remove(action_index);

</syntaxhighlight>
</blockquote>

===oceos_timed_output_reset()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''timed_action.h''''' 

'''Description''' 
This function removes all timed output actions from timed actions queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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);
</syntaxhighlight>

'''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.
{| class="wikitable"
|-
| 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Remove all timed outputs from the timed actions queue
status = oceos_timed_output_reset();

</syntaxhighlight>
</blockquote>

== Logging directives ==

===Introduction===
<blockquote style="border-left-style: none;">

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''' 
<syntaxhighlight lang="C">
/*****************************************************************************
* 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)));

</syntaxhighlight>

===oceos_log_add_entry()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! Parameter || Description
|-
| enum LOG_ENTRY_TYPE || Log entry type (see previous section for a list)
|-
| info | 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_log_get_indexed_entry()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_log_remove_entry()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_log_reset()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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);
</syntaxhighlight>

'''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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...

// Clear down the system log
status = oceos_log_reset();

</syntaxhighlight>
</blockquote>

===oceos_log_get_size()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, size;
...

// Clear down the system log
status = oceos_log_get_size(&size);

</syntaxhighlight>
</blockquote>

===System State Variable and System State Mask===
<blockquote style="border-left-style: none;">

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''' 
<syntaxhighlight lang="C">

#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

</syntaxhighlight>

===oceos_system_state_get()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''system_log.h''''' 

'''Description''' 
This function returns of the system state variable.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, state;
...

// Get the system state
status = oceos_system_state_get(&state);

</syntaxhighlight>
</blockquote>

===oceos_system_state_set()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''system_log.h''''' 

'''Description''' 
This function sets system state variable.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! Error bit !! Description
|-
| ERR_SYS_FIXED_CORRUPT || System Fixed area corrupt
|-
| ERR_SYS_LOG_CORRUPT || LOG dynamic pointer is null
|}

'''Example Usage''' 
<syntaxhighlight lang="C">
S32_t status, new_state;
...

// Set new system state
status = oceos_system_state_set(new_state);

</syntaxhighlight>
</blockquote>

===oceos_system_state_copy_get()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''system_log.h''''' 

'''Description''' 
This function returns the value of the system state copy variable.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, copy_state;
...

// Get the system state copy
status = oceos_system_state_copy_get(&copy_state);

</syntaxhighlight>
</blockquote>

===oceos_system_state_copy_set()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''system_log.h''''' 

'''Description''' 
This function loads a value to tha system state copy variable.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! Error bit !! Description
|-
| ERR_SYS_FIXED_CORRUPT || System Fixed area corrupt
|-
| ERR_SYS_LOG_CORRUPT || LOG dynamic pointer is null
|}

'''Example Usage''' 
<syntaxhighlight lang="C">
S32_t status, new_state;
...

// Set new system state copy
status = oceos_system_state_copy_set(new_state);

</syntaxhighlight>
</blockquote>

== Timing directives ==

===Introduction===
<blockquote style="border-left-style: none;">

'''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()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''oceos_timer.h''''' 

'''Description''' 
This function returns the current system time as a 64-bit number.

'''Prototype''' 
<syntaxhighlight lang="C">
**
* Get the current system time (64-bit)
*
* @return U64_t
*/
U64_t oceos_time_sys_get64(void);
</syntaxhighlight>

'''Parameters''' 

There are no parameters to this function.

'''Returns''' 
This function returns an S64_t with the current system time.

'''Example Usage''' 
<syntaxhighlight lang="C">
S64_t now;
...
// Get the time
now = oceos_time_sys_get64();
</syntaxhighlight>
</blockquote>

===oceos_time_sys_get32()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''oceos_timer.h''''' 

'''Description''' 
This function returns the low 32 bits of the system time.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* Get the current system time (low 32 bits of 64 bit value)
*
* @return U32_t
*/
U32_t oceos_time_sys_get32(void);
</syntaxhighlight>

'''Parameters''' 
There are no parameters to this function.

'''Returns''' 
This function returns an S32_t with the current system time.

'''Example Usage''' 
<syntaxhighlight lang="C">
S32_t now;
...
// Get the time
now = oceos_time_sys_get32();
</syntaxhighlight>
</blockquote>

[[Category:backup]]

OCEOSmp/directive reference

2024-06-24T13:21:00Z

Bkavanagh: /* Timed Actions */

= Introduction =

To be added

= Directives =

== Initialisation directives ==

===oceos_init()===
<blockquote style="border-left-style: none;">
'''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 [[OCEOSmp/directive_reference#oceos_init_finish()|oceos_init_finish()]] has completed successfully. 
'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>
'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
/*
* 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
</syntaxhighlight>
</blockquote>

===oceos_init_finish()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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);
</syntaxhighlight>
'''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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
/*
* 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
</syntaxhighlight>
</blockquote>

===oceos_start()===
<blockquote style="border-left-style: none;">
'''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 [[OCEOSmp/directive_reference#oceos_init()|oceos_init()]] and [[OCEOSmp/directive_reference#oceos_init_finish()|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''' 
<syntaxhighlight lang="C">
/**
* 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
);

</syntaxhighlight>
'''Parameters''' 
{| class="wikitable"
|-
! 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. 
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
/* 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);
</syntaxhighlight>
</blockquote>

===oceos_exit()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''initialisation.h''''' 

'''Description''' 
Ends scheduling and exit from [[OCEOSmp/directive_reference#oceos_start()|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''' 
<syntaxhighlight lang="C">
/**
* 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);

</syntaxhighlight>
'''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. 
{| class="wikitable"
|-
! Error bit || Description
|-
| ERR_SYS_FIXED_CORRUPT || System Fixed area corrupt
|-
| ERR_WRONG_PHASE || Called before scheduling started
|}

'''Example Usage''' 
<syntaxhighlight lang="C">
// Exit OCEOS
oceos_exit();
</syntaxhighlight>
</blockquote>

===oceos_CPU_sleep()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''initialisation.h''''' 

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

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* Puts CPU in sleep mode.
* User must to be sure that interrupts are enabled.
*
* @return OCEOS_SUCCESS
*/
S32_t oceos_CPU_sleep(void);
</syntaxhighlight>

'''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''' 
<syntaxhighlight lang="C">
// Put CPU to sleep
oceos_CPU_sleep();
</syntaxhighlight>
</blockquote>

===oceosmp_cpu_disable()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''initialisation.h''''' 

'''Description''' 
This function ends execution of all tasks running on particular CPU and removes the CPU from scheduling.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, faulty_cpu;
...
// Disable faulty CPU core
status = oceosmp_cpu_disable(faulty_cpu));

</syntaxhighlight>
</blockquote>

===oceosmp_cpu_enable()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, good_cpu;
...
// Enable CPU core
status = oceosmp_cpu_enable(good_cpu));

</syntaxhighlight>
</blockquote>

===oceosmp_cpu_terminate()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, faulty_cpu;
...
// Terminate CPU core
status = oceosmp_cpu_terminate(faulty_cpu));

</syntaxhighlight>
</blockquote>

==Task directives==
{| class="wikitable"
|+ API Functions
|-
| Directive || Description || main || task || IRQ handler
|-
| [[OCEOSmp/directive reference#oceos_task_create()| oceos_task_create()]] || Create Task || * || ||
|-
| [[OCEOSmp/directive reference#oceos_task_start()| oceos_task_start()]] || Start Task || || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_timed_start()| oceos_task_timed_start()]] || Schedule a task to start execution at a given system time|| || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_disable()| oceos_task_disable()]] || Disable Task || || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_enable()| oceos_task_enable()]] || Enable Task || || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_self()| oceos_task_self()]] || Returns the task ID of the currently executing task || || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_get_priority()| oceos_task_get_priority()]] || Get priority of a task || || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_get_status()| oceos_task_get_status()]] || Get status of a task || || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_kill()| oceos_task_kill()]] || Directive to terminate current task|| || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_get_info()| oceos_task_get_info()]] || Get task information || || * || *
|-
| [[OCEOSmp/directive reference#oceosmp_task_kill()| oceosmp_task_kill()]] || Directive to terminate current task|| || * || *
|}

===Task data structures===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
The following data structures are used by some of the task directives.

'''Data structures''' 
<syntaxhighlight lang="C">
/**
* 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
};

</syntaxhighlight>

===oceos_task_create()===
<blockquote style="border-left-style: none;">

'''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 [[OCEOSmp/directive_reference#oceos_init()|oceos_init()]] and before [[OCEOSmp/directive_reference#oceos_init_finish()|oceos_init_finish()]]. 
It must be called for each task otherwise [[OCEOSmp/directive_reference#oceos_start()|oceos_start()]] will return an error.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>
'''Parameters''' 
{| class="wikitable"
|-
! 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.

{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">

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

</syntaxhighlight>
</blockquote>

===oceos_task_start()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
void *ptr;
...
// Start instance of task T_1 passing pointer ptr
status = oceos_task_start(t_1,ptr);

</syntaxhighlight>
</blockquote>

===oceos_task_timed_start()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function schedules a task to start execution at a given system time.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_task_disable()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''initialisation.h''''' 

'''Description''' 
This function disables a task and removes any current pending jobs from the readyQ.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.

{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Disable task t_1
status = oceos_task_disable(t_1);

</syntaxhighlight>
</blockquote>

===oceos_task_enable()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function enables a task. Only enabled tasks may be started.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);

</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Enable task t_2
status = oceos_task_enable(t_2);

</syntaxhighlight>
</blockquote>

===oceos_task_self()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function returns the task number of the currently running task on the calling CPU.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status, task_running;
...
// Return task ID that's running on this core
status = oceos_task_self(&task_running);

</syntaxhighlight>
</blockquote>

===oceos_task_get_priority()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function returns the priority of the task ID passed to it.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
U32_t t_priority;
...
// Return the priority of task ID t_4
status = oceos_task_get_priority(t_4, &t_priority);

</syntaxhighlight>
</blockquote>

===oceos_task_get_status()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function returns the status of the task ID passed to it.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
U32_t t_status;
...
// Return the status of task ID t_4
status = oceos_task_get_status(t_4, &t_status);

</syntaxhighlight>
</blockquote>

===oceos_task_get_info()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function returns the task information for the specified task.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
struct task_info info;
...
// Get information for task T3
status = oceos_task_get_info(t_3, &info);

</syntaxhighlight>
</blockquote>

===oceosmp_task_kill()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function kills the specified task running on the specified CPU.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Kill task t_2 on CPU cpu_1
status = oceosmp_task_kill(t_2, cpu_1);

</syntaxhighlight>
</blockquote>

==Mutex directives==

===oceos_mutex_create()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''mutex.h''''' 

'''Description''' 
This function creates a mutex of specified ID with a specified priority ceiling.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Create mutex with ID print_mutex and priority ceiling of 5
status = oceos_mutex_create(print_mutex, 5);

</syntaxhighlight>
</blockquote>

===oceos_mutex_wait()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''mutex.h''''' 

'''Description''' 
This function makes the task wait until the specified mutex is available.

'''Prototype''' 
<syntaxhighlight lang="C">
/*
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Wait on mutex m_2
status = oceos_mutex_wait(m_2);

</syntaxhighlight>
</blockquote>

===oceos_mutex_signal()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''mutex.h''''' 

'''Description''' 
This function signals the specified mutex.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Signal mutex m_2
status = oceos_mutex_signal(m_2);

</syntaxhighlight>
</blockquote>

===oceos_mutex_get_value()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''mutex.h''''' 

'''Description''' 
This function returns the value of the specified mutex.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
U32_t value;
...
// Get value of mutex m_2
status = oceos_mutex_get_value(m_2, &value);

</syntaxhighlight>
</blockquote>

==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()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''rwmutex.h''''' 

'''Description''' 
This function ees a read/write mutex.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Create read/write mutex with ID rwm_2 and priority ceiling of 100
status = oceos_rwmutex_create(rwm_1, 100);

</syntaxhighlight>
</blockquote>

===oceos_rwmutex_read_wait()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Acquire read/write mutex rwm_1 for read
status = oceos_rwmutex_read_wait(rwm_1);
</syntaxhighlight>
</blockquote>

===oceos_rwmutex_write_wait()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Acquire read/write mutex rwm_1 for write
status = oceos_rwmutex_read_wait(rwm_1);
</syntaxhighlight>
</blockquote>

===oceos_rwmutex_signal()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Signal read/write mutex number rwm_4
status = oceos_rwmutex_signal(rwm_4);
</syntaxhighlight>
</blockquote>

===oceos_rwmutex_check_status()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status, rwm_status;
...
// Check the status of read/write mutex rwm_2
status = oceos_rwmutex_check_status(rwm_2, &rwm_status);
</syntaxhighlight>
</blockquote>

===oceos_rwmutex_reading_count()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''rwmutex.h''''' 

'''Description''' 
This function returns the current number of jobs holding a specified read/write mutex for read.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
*
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_rwmutex_write_reqs_count()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''header.h''''' 

'''Description''' 
This function returns the current number of write requests for the specified read/write mutex .

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
| 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_rwmutex_writes_pending_count()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''rwmutex.h''''' 

'''Description''' 
This function returns the current number of pending writes for the specified read/write mutex.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>

===oceos_rwmutex_holding()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''header.h''''' 

'''Description''' 
This function returns the read/write mutexes currently held by this instance of this task (job).

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
U64_t rwm_held;
...
// Which read/write mutexes does this job hold
status = oceos_rwmutex_holding(&rwm_held);

</syntaxhighlight>
</blockquote>

== Semaphores directives ==

===oceos_sem_create()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''semaphore.h''''' 

'''Description''' 
This function creates a semaphore.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_sem_signal()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''semaphore.h''''' 

'''Description''' 
This function signals a semaphore, increments its count and transfers pending jobs to the ready queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Signal s_audi semaphore (increment its count)
status = oceos_sem_signal(s_audi);
</syntaxhighlight>
</blockquote>

===oceos_sem_wait_continue()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''semaphore.h''''' 

'''Description''' 
This function decrements the available permits of a sempahore otherwise returns an unsuccessful status code.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Decrement available permits on semaphore s_1
status = oceos_sem_wait_continue(s_1);

</syntaxhighlight>
</blockquote>

===oceos_sem_wait_restart()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Decrement available permits on semaphore s_1 otherwise job is put on pending queue
status = oceos_sem_wait_restart(s_1);

</syntaxhighlight>
</blockquote>

===oceos_sem_wait_restart_timeout()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! Parameter || Description
|-
| sem_id || U32_t value of semaphore to be decremented
|-
| timeout | 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>

===oceos_sem_get_value()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''semaphore.h''''' 

'''Description''' 
This function returns the number of available permits for the specified semaphore.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status, permit_count;
...
// Get the available permits for semaphore s_1
status = oceos_sem_get_value(s_1, &permit_count);

</syntaxhighlight>
</blockquote>

===oceos_sem_penq_get_size()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''semaphore.h''''' 

'''Description''' 
This function returns the number of jobs on the specified semaphore pending queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status, job_count;
...
// Get the available permits for semaphore s_1
status = oceos_sem_penq_get_size(s_1, &job_count);

</syntaxhighlight>
</blockquote>

===oceos_sem_reset()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Reset semaphore s_1
status = oceos_sem_reset(s_1);
</syntaxhighlight>
</blockquote>

== Data Queues ==

===oceos_dataq_create()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''dataq.h''''' 

'''Description''' 
This function creates a data queue with the specified characteristics.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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));
</syntaxhighlight>
</blockquote>

===oceos_dataq_write()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''dataq.h''''' 

'''Description''' 
This function puts a non-null pointer on the specified data queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>

===oceos_dataq_read_continue()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''dataq.h''''' 

'''Description''' 
This function returns a pointer from the specified data queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
char *data_ptr;
...
// Read pointer from data queue s_2
status = oceos_dataq_read_continue(s_2, (void *)data_ptr);
</syntaxhighlight>
</blockquote>

===oceos_dataq_read_restart()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>

===oceos_dataq_read_restart_timeout()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>

===oceos_dataq_get_size()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''dataq.h''''' 

'''Description''' 
This function returns the number of items on the specified data queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status, d_size;
...
// Get the number of entries on data queue d_0
status = oceos_dataq_get_size(d_0, &d_size);
</syntaxhighlight>
</blockquote>

===oceos_dataq_penq_get_size()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''dataq.h''''' 

'''Description''' 
This function returns number of jobs on the specified data queue pending job's queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>

===oceos_dataq_clear()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''dataq.h''''' 

'''Description''' 
This function clears the specified data queue including pending jobs for that queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Clear data queue d_1
status = oceos_dataq_penq_get_size(d_1);
</syntaxhighlight>
</blockquote>

== Timed Actions ==

===oceos_timed_output_add()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
| 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">

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

</syntaxhighlight>
</blockquote>

===oceos_timed_jobs_number()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''timed_action.h''''' 

'''Description''' 
This function returns the number of jobs on the timed actions queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, no_of_jobs;
...
// Get the number of jobs on the timed actions queue
status = oceos_timed_jobs_number(&no_of_jobs);

</syntaxhighlight>
</blockquote>

===oceos_timed_jobs_remove()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''timed_action.h''''' 

'''Description''' 
This function removes the specified timed action from the queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, job_id;
...
// Remove job_id from the timed actions queue
status = oceos_timed_jobs_remove(job_id);

</syntaxhighlight>
</blockquote>

===oceos_timed_jobs_reset()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''timed_action.h''''' 

'''Description''' 
This function removes all jobs from timed actions queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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);
</syntaxhighlight>

'''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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Remove all jobs from the timed actions queue
status = oceos_timed_jobs_reset(job_id);
</syntaxhighlight>
</blockquote>

===oceos_timed_output_remove()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''timed_action.h''''' 

'''Description''' 
This function removes the specified timed output action from timed actions queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
| 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''' 
<syntaxhighlight lang="C">
S32_t status;
U8_t action_index;
...
// Remove timed output with specified action_index
status = oceos_timed_output_remove(action_index);

</syntaxhighlight>
</blockquote>

===oceos_timed_output_reset()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''timed_action.h''''' 

'''Description''' 
This function removes all timed output actions from timed actions queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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);
</syntaxhighlight>

'''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.
{| class="wikitable"
|-
| 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Remove all timed outputs from the timed actions queue
status = oceos_timed_output_reset();

</syntaxhighlight>
</blockquote>

== Logging directives ==

===Introduction===
<blockquote style="border-left-style: none;">

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''' 
<syntaxhighlight lang="C">
/*****************************************************************************
* 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)));

</syntaxhighlight>

===oceos_log_add_entry()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! Parameter || Description
|-
| enum LOG_ENTRY_TYPE || Log entry type (see previous section for a list)
|-
| info | 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_log_get_indexed_entry()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_log_remove_entry()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_log_reset()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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);
</syntaxhighlight>

'''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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...

// Clear down the system log
status = oceos_log_reset();

</syntaxhighlight>
</blockquote>

===oceos_log_get_size()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, size;
...

// Clear down the system log
status = oceos_log_get_size(&size);

</syntaxhighlight>
</blockquote>

===System State Variable and System State Mask===
<blockquote style="border-left-style: none;">

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''' 
<syntaxhighlight lang="C">

#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

</syntaxhighlight>

===oceos_system_state_get()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''system_log.h''''' 

'''Description''' 
This function returns of the system state variable.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, state;
...

// Get the system state
status = oceos_system_state_get(&state);

</syntaxhighlight>
</blockquote>

===oceos_system_state_set()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''system_log.h''''' 

'''Description''' 
This function sets system state variable.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! Error bit !! Description
|-
| ERR_SYS_FIXED_CORRUPT || System Fixed area corrupt
|-
| ERR_SYS_LOG_CORRUPT || LOG dynamic pointer is null
|}

'''Example Usage''' 
<syntaxhighlight lang="C">
S32_t status, new_state;
...

// Set new system state
status = oceos_system_state_set(new_state);

</syntaxhighlight>
</blockquote>

===oceos_system_state_copy_get()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''system_log.h''''' 

'''Description''' 
This function returns the value of the system state copy variable.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, copy_state;
...

// Get the system state copy
status = oceos_system_state_copy_get(&copy_state);

</syntaxhighlight>
</blockquote>

===oceos_system_state_copy_set()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''system_log.h''''' 

'''Description''' 
This function loads a value to tha system state copy variable.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! Error bit !! Description
|-
| ERR_SYS_FIXED_CORRUPT || System Fixed area corrupt
|-
| ERR_SYS_LOG_CORRUPT || LOG dynamic pointer is null
|}

'''Example Usage''' 
<syntaxhighlight lang="C">
S32_t status, new_state;
...

// Set new system state copy
status = oceos_system_state_copy_set(new_state);

</syntaxhighlight>
</blockquote>

== Timing directives ==

===Introduction===
<blockquote style="border-left-style: none;">

'''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()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''oceos_timer.h''''' 

'''Description''' 
This function returns the current system time as a 64-bit number.

'''Prototype''' 
<syntaxhighlight lang="C">
**
* Get the current system time (64-bit)
*
* @return U64_t
*/
U64_t oceos_time_sys_get64(void);
</syntaxhighlight>

'''Parameters''' 

There are no parameters to this function.

'''Returns''' 
This function returns an S64_t with the current system time.

'''Example Usage''' 
<syntaxhighlight lang="C">
S64_t now;
...
// Get the time
now = oceos_time_sys_get64();
</syntaxhighlight>
</blockquote>

===oceos_time_sys_get32()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''oceos_timer.h''''' 

'''Description''' 
This function returns the low 32 bits of the system time.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* Get the current system time (low 32 bits of 64 bit value)
*
* @return U32_t
*/
U32_t oceos_time_sys_get32(void);
</syntaxhighlight>

'''Parameters''' 
There are no parameters to this function.

'''Returns''' 
This function returns an S32_t with the current system time.

'''Example Usage''' 
<syntaxhighlight lang="C">
S32_t now;
...
// Get the time
now = oceos_time_sys_get32();
</syntaxhighlight>
</blockquote>

[[Category:backup]]

OCEOSmp/directive reference

2024-06-24T13:13:17Z

Bkavanagh: /* oceos_timed_jobs_number() */

= Introduction =

To be added

= Directives =

== Initialisation directives ==

===oceos_init()===
<blockquote style="border-left-style: none;">
'''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 [[OCEOSmp/directive_reference#oceos_init_finish()|oceos_init_finish()]] has completed successfully. 
'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>
'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
/*
* 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
</syntaxhighlight>
</blockquote>

===oceos_init_finish()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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);
</syntaxhighlight>
'''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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
/*
* 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
</syntaxhighlight>
</blockquote>

===oceos_start()===
<blockquote style="border-left-style: none;">
'''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 [[OCEOSmp/directive_reference#oceos_init()|oceos_init()]] and [[OCEOSmp/directive_reference#oceos_init_finish()|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''' 
<syntaxhighlight lang="C">
/**
* 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
);

</syntaxhighlight>
'''Parameters''' 
{| class="wikitable"
|-
! 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. 
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
/* 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);
</syntaxhighlight>
</blockquote>

===oceos_exit()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''initialisation.h''''' 

'''Description''' 
Ends scheduling and exit from [[OCEOSmp/directive_reference#oceos_start()|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''' 
<syntaxhighlight lang="C">
/**
* 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);

</syntaxhighlight>
'''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. 
{| class="wikitable"
|-
! Error bit || Description
|-
| ERR_SYS_FIXED_CORRUPT || System Fixed area corrupt
|-
| ERR_WRONG_PHASE || Called before scheduling started
|}

'''Example Usage''' 
<syntaxhighlight lang="C">
// Exit OCEOS
oceos_exit();
</syntaxhighlight>
</blockquote>

===oceos_CPU_sleep()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''initialisation.h''''' 

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

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* Puts CPU in sleep mode.
* User must to be sure that interrupts are enabled.
*
* @return OCEOS_SUCCESS
*/
S32_t oceos_CPU_sleep(void);
</syntaxhighlight>

'''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''' 
<syntaxhighlight lang="C">
// Put CPU to sleep
oceos_CPU_sleep();
</syntaxhighlight>
</blockquote>

===oceosmp_cpu_disable()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''initialisation.h''''' 

'''Description''' 
This function ends execution of all tasks running on particular CPU and removes the CPU from scheduling.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, faulty_cpu;
...
// Disable faulty CPU core
status = oceosmp_cpu_disable(faulty_cpu));

</syntaxhighlight>
</blockquote>

===oceosmp_cpu_enable()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, good_cpu;
...
// Enable CPU core
status = oceosmp_cpu_enable(good_cpu));

</syntaxhighlight>
</blockquote>

===oceosmp_cpu_terminate()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, faulty_cpu;
...
// Terminate CPU core
status = oceosmp_cpu_terminate(faulty_cpu));

</syntaxhighlight>
</blockquote>

==Task directives==
{| class="wikitable"
|+ API Functions
|-
| Directive || Description || main || task || IRQ handler
|-
| [[OCEOSmp/directive reference#oceos_task_create()| oceos_task_create()]] || Create Task || * || ||
|-
| [[OCEOSmp/directive reference#oceos_task_start()| oceos_task_start()]] || Start Task || || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_timed_start()| oceos_task_timed_start()]] || Schedule a task to start execution at a given system time|| || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_disable()| oceos_task_disable()]] || Disable Task || || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_enable()| oceos_task_enable()]] || Enable Task || || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_self()| oceos_task_self()]] || Returns the task ID of the currently executing task || || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_get_priority()| oceos_task_get_priority()]] || Get priority of a task || || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_get_status()| oceos_task_get_status()]] || Get status of a task || || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_kill()| oceos_task_kill()]] || Directive to terminate current task|| || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_get_info()| oceos_task_get_info()]] || Get task information || || * || *
|-
| [[OCEOSmp/directive reference#oceosmp_task_kill()| oceosmp_task_kill()]] || Directive to terminate current task|| || * || *
|}

===Task data structures===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
The following data structures are used by some of the task directives.

'''Data structures''' 
<syntaxhighlight lang="C">
/**
* 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
};

</syntaxhighlight>

===oceos_task_create()===
<blockquote style="border-left-style: none;">

'''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 [[OCEOSmp/directive_reference#oceos_init()|oceos_init()]] and before [[OCEOSmp/directive_reference#oceos_init_finish()|oceos_init_finish()]]. 
It must be called for each task otherwise [[OCEOSmp/directive_reference#oceos_start()|oceos_start()]] will return an error.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>
'''Parameters''' 
{| class="wikitable"
|-
! 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.

{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">

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

</syntaxhighlight>
</blockquote>

===oceos_task_start()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
void *ptr;
...
// Start instance of task T_1 passing pointer ptr
status = oceos_task_start(t_1,ptr);

</syntaxhighlight>
</blockquote>

===oceos_task_timed_start()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function schedules a task to start execution at a given system time.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_task_disable()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''initialisation.h''''' 

'''Description''' 
This function disables a task and removes any current pending jobs from the readyQ.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.

{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Disable task t_1
status = oceos_task_disable(t_1);

</syntaxhighlight>
</blockquote>

===oceos_task_enable()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function enables a task. Only enabled tasks may be started.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);

</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Enable task t_2
status = oceos_task_enable(t_2);

</syntaxhighlight>
</blockquote>

===oceos_task_self()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function returns the task number of the currently running task on the calling CPU.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status, task_running;
...
// Return task ID that's running on this core
status = oceos_task_self(&task_running);

</syntaxhighlight>
</blockquote>

===oceos_task_get_priority()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function returns the priority of the task ID passed to it.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
U32_t t_priority;
...
// Return the priority of task ID t_4
status = oceos_task_get_priority(t_4, &t_priority);

</syntaxhighlight>
</blockquote>

===oceos_task_get_status()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function returns the status of the task ID passed to it.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
U32_t t_status;
...
// Return the status of task ID t_4
status = oceos_task_get_status(t_4, &t_status);

</syntaxhighlight>
</blockquote>

===oceos_task_get_info()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function returns the task information for the specified task.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
struct task_info info;
...
// Get information for task T3
status = oceos_task_get_info(t_3, &info);

</syntaxhighlight>
</blockquote>

===oceosmp_task_kill()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function kills the specified task running on the specified CPU.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Kill task t_2 on CPU cpu_1
status = oceosmp_task_kill(t_2, cpu_1);

</syntaxhighlight>
</blockquote>

==Mutex directives==

===oceos_mutex_create()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''mutex.h''''' 

'''Description''' 
This function creates a mutex of specified ID with a specified priority ceiling.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Create mutex with ID print_mutex and priority ceiling of 5
status = oceos_mutex_create(print_mutex, 5);

</syntaxhighlight>
</blockquote>

===oceos_mutex_wait()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''mutex.h''''' 

'''Description''' 
This function makes the task wait until the specified mutex is available.

'''Prototype''' 
<syntaxhighlight lang="C">
/*
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Wait on mutex m_2
status = oceos_mutex_wait(m_2);

</syntaxhighlight>
</blockquote>

===oceos_mutex_signal()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''mutex.h''''' 

'''Description''' 
This function signals the specified mutex.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Signal mutex m_2
status = oceos_mutex_signal(m_2);

</syntaxhighlight>
</blockquote>

===oceos_mutex_get_value()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''mutex.h''''' 

'''Description''' 
This function returns the value of the specified mutex.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
U32_t value;
...
// Get value of mutex m_2
status = oceos_mutex_get_value(m_2, &value);

</syntaxhighlight>
</blockquote>

==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()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''rwmutex.h''''' 

'''Description''' 
This function ees a read/write mutex.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Create read/write mutex with ID rwm_2 and priority ceiling of 100
status = oceos_rwmutex_create(rwm_1, 100);

</syntaxhighlight>
</blockquote>

===oceos_rwmutex_read_wait()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Acquire read/write mutex rwm_1 for read
status = oceos_rwmutex_read_wait(rwm_1);
</syntaxhighlight>
</blockquote>

===oceos_rwmutex_write_wait()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Acquire read/write mutex rwm_1 for write
status = oceos_rwmutex_read_wait(rwm_1);
</syntaxhighlight>
</blockquote>

===oceos_rwmutex_signal()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Signal read/write mutex number rwm_4
status = oceos_rwmutex_signal(rwm_4);
</syntaxhighlight>
</blockquote>

===oceos_rwmutex_check_status()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status, rwm_status;
...
// Check the status of read/write mutex rwm_2
status = oceos_rwmutex_check_status(rwm_2, &rwm_status);
</syntaxhighlight>
</blockquote>

===oceos_rwmutex_reading_count()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''rwmutex.h''''' 

'''Description''' 
This function returns the current number of jobs holding a specified read/write mutex for read.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
*
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_rwmutex_write_reqs_count()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''header.h''''' 

'''Description''' 
This function returns the current number of write requests for the specified read/write mutex .

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
| 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_rwmutex_writes_pending_count()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''rwmutex.h''''' 

'''Description''' 
This function returns the current number of pending writes for the specified read/write mutex.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>

===oceos_rwmutex_holding()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''header.h''''' 

'''Description''' 
This function returns the read/write mutexes currently held by this instance of this task (job).

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
U64_t rwm_held;
...
// Which read/write mutexes does this job hold
status = oceos_rwmutex_holding(&rwm_held);

</syntaxhighlight>
</blockquote>

== Semaphores directives ==

===oceos_sem_create()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''semaphore.h''''' 

'''Description''' 
This function creates a semaphore.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_sem_signal()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''semaphore.h''''' 

'''Description''' 
This function signals a semaphore, increments its count and transfers pending jobs to the ready queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Signal s_audi semaphore (increment its count)
status = oceos_sem_signal(s_audi);
</syntaxhighlight>
</blockquote>

===oceos_sem_wait_continue()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''semaphore.h''''' 

'''Description''' 
This function decrements the available permits of a sempahore otherwise returns an unsuccessful status code.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Decrement available permits on semaphore s_1
status = oceos_sem_wait_continue(s_1);

</syntaxhighlight>
</blockquote>

===oceos_sem_wait_restart()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Decrement available permits on semaphore s_1 otherwise job is put on pending queue
status = oceos_sem_wait_restart(s_1);

</syntaxhighlight>
</blockquote>

===oceos_sem_wait_restart_timeout()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! Parameter || Description
|-
| sem_id || U32_t value of semaphore to be decremented
|-
| timeout | 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>

===oceos_sem_get_value()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''semaphore.h''''' 

'''Description''' 
This function returns the number of available permits for the specified semaphore.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status, permit_count;
...
// Get the available permits for semaphore s_1
status = oceos_sem_get_value(s_1, &permit_count);

</syntaxhighlight>
</blockquote>

===oceos_sem_penq_get_size()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''semaphore.h''''' 

'''Description''' 
This function returns the number of jobs on the specified semaphore pending queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status, job_count;
...
// Get the available permits for semaphore s_1
status = oceos_sem_penq_get_size(s_1, &job_count);

</syntaxhighlight>
</blockquote>

===oceos_sem_reset()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Reset semaphore s_1
status = oceos_sem_reset(s_1);
</syntaxhighlight>
</blockquote>

== Data Queues ==

===oceos_dataq_create()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''dataq.h''''' 

'''Description''' 
This function creates a data queue with the specified characteristics.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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));
</syntaxhighlight>
</blockquote>

===oceos_dataq_write()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''dataq.h''''' 

'''Description''' 
This function puts a non-null pointer on the specified data queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>

===oceos_dataq_read_continue()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''dataq.h''''' 

'''Description''' 
This function returns a pointer from the specified data queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
char *data_ptr;
...
// Read pointer from data queue s_2
status = oceos_dataq_read_continue(s_2, (void *)data_ptr);
</syntaxhighlight>
</blockquote>

===oceos_dataq_read_restart()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>

===oceos_dataq_read_restart_timeout()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>

===oceos_dataq_get_size()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''dataq.h''''' 

'''Description''' 
This function returns the number of items on the specified data queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status, d_size;
...
// Get the number of entries on data queue d_0
status = oceos_dataq_get_size(d_0, &d_size);
</syntaxhighlight>
</blockquote>

===oceos_dataq_penq_get_size()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''dataq.h''''' 

'''Description''' 
This function returns number of jobs on the specified data queue pending job's queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>

===oceos_dataq_clear()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''dataq.h''''' 

'''Description''' 
This function clears the specified data queue including pending jobs for that queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Clear data queue d_1
status = oceos_dataq_penq_get_size(d_1);
</syntaxhighlight>
</blockquote>

== Timed Actions ==

===oceos_timed_output_add()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
| 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">

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

</syntaxhighlight>
</blockquote>

===oceos_timed_jobs_number()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''timed_action.h''''' 

'''Description''' 
This function returns the number of jobs on the timed actions queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, no_of_jobs;
...
// Get the number of jobs on the timed actions queue
status = oceos_timed_jobs_number(&no_of_jobs);

</syntaxhighlight>
</blockquote>

===oceos_timed_jobs_remove()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''timed_action.h''''' 

'''Description''' 
This function removes the specified timed action from the queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, job_id;
...
// Remove job_id from the timed actions queue
status = oceos_timed_jobs_remove(job_id);

</syntaxhighlight>
</blockquote>

===oceos_timed_jobs_reset()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''timed_action.h''''' 

'''Description''' 
This function removes all jobs from timed actions queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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);
</syntaxhighlight>

'''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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Remove all jobs from the timed actions queue
status = oceos_timed_jobs_reset(job_id);
</syntaxhighlight>
</blockquote>

===oceos_timed_output_remove()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''timed_action.h''''' 

'''Description''' 
This function removes the specified timed output action from timed actions queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
| 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''' 
<syntaxhighlight lang="C">
S32_t status;
U8_t action_index;
...
// Remove timed output with specified action_index
status = oceos_timed_output_remove(action_index);

</syntaxhighlight>
</blockquote>

===oceos_timed_output_reset()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''timed_action.h''''' 

'''Description''' 
This function removes all timed output actions from timed actions queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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);
</syntaxhighlight>

'''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.
{| class="wikitable"
|-
| 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Remove all timed outputs from the timed actions queue
status = oceos_timed_output_reset();

</syntaxhighlight>
</blockquote>

== Logging directives ==

===Introduction===
<blockquote style="border-left-style: none;">

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''' 
<syntaxhighlight lang="C">
/*****************************************************************************
* 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)));

</syntaxhighlight>

===oceos_log_add_entry()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! Parameter || Description
|-
| enum LOG_ENTRY_TYPE || Log entry type (see previous section for a list)
|-
| info | 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_log_get_indexed_entry()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_log_remove_entry()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_log_reset()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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);
</syntaxhighlight>

'''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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...

// Clear down the system log
status = oceos_log_reset();

</syntaxhighlight>
</blockquote>

===oceos_log_get_size()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, size;
...

// Clear down the system log
status = oceos_log_get_size(&size);

</syntaxhighlight>
</blockquote>

===System State Variable and System State Mask===
<blockquote style="border-left-style: none;">

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''' 
<syntaxhighlight lang="C">

#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

</syntaxhighlight>

===oceos_system_state_get()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''system_log.h''''' 

'''Description''' 
This function returns of the system state variable.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, state;
...

// Get the system state
status = oceos_system_state_get(&state);

</syntaxhighlight>
</blockquote>

===oceos_system_state_set()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''system_log.h''''' 

'''Description''' 
This function sets system state variable.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! Error bit !! Description
|-
| ERR_SYS_FIXED_CORRUPT || System Fixed area corrupt
|-
| ERR_SYS_LOG_CORRUPT || LOG dynamic pointer is null
|}

'''Example Usage''' 
<syntaxhighlight lang="C">
S32_t status, new_state;
...

// Set new system state
status = oceos_system_state_set(new_state);

</syntaxhighlight>
</blockquote>

===oceos_system_state_copy_get()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''system_log.h''''' 

'''Description''' 
This function returns the value of the system state copy variable.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, copy_state;
...

// Get the system state copy
status = oceos_system_state_copy_get(&copy_state);

</syntaxhighlight>
</blockquote>

===oceos_system_state_copy_set()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''system_log.h''''' 

'''Description''' 
This function loads a value to tha system state copy variable.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! Error bit !! Description
|-
| ERR_SYS_FIXED_CORRUPT || System Fixed area corrupt
|-
| ERR_SYS_LOG_CORRUPT || LOG dynamic pointer is null
|}

'''Example Usage''' 
<syntaxhighlight lang="C">
S32_t status, new_state;
...

// Set new system state copy
status = oceos_system_state_copy_set(new_state);

</syntaxhighlight>
</blockquote>

== Timing directives ==

===Introduction===
<blockquote style="border-left-style: none;">

'''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()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''oceos_timer.h''''' 

'''Description''' 
This function returns the current system time as a 64-bit number.

'''Prototype''' 
<syntaxhighlight lang="C">
**
* Get the current system time (64-bit)
*
* @return U64_t
*/
U64_t oceos_time_sys_get64(void);
</syntaxhighlight>

'''Parameters''' 

There are no parameters to this function.

'''Returns''' 
This function returns an S64_t with the current system time.

'''Example Usage''' 
<syntaxhighlight lang="C">
S64_t now;
...
// Get the time
now = oceos_time_sys_get64();
</syntaxhighlight>
</blockquote>

===oceos_time_sys_get32()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''oceos_timer.h''''' 

'''Description''' 
This function returns the low 32 bits of the system time.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* Get the current system time (low 32 bits of 64 bit value)
*
* @return U32_t
*/
U32_t oceos_time_sys_get32(void);
</syntaxhighlight>

'''Parameters''' 
There are no parameters to this function.

'''Returns''' 
This function returns an S32_t with the current system time.

'''Example Usage''' 
<syntaxhighlight lang="C">
S32_t now;
...
// Get the time
now = oceos_time_sys_get32();
</syntaxhighlight>
</blockquote>

[[Category:backup]]

MediaWiki:Sidebar

2024-06-17T11:52:43Z

Bkavanagh:

OCEOSmp/polarfire

2024-06-17T11:51:02Z

Bkavanagh: /* OCEOSmp BSP for PolarFire */

= OCEOSmp BSP for PolarFire® SoC FPGA =

OCEOSmp is a real-time operating system compliant with European Space Agency standards (ECSS Category B). It occupies a small memory footprint and provides a unique set of functions to help police the application tasks. It supports RISC-V, ARM, and SPARC processor architectures and has been designed to provide deterministic task scheduling.
The installation package contains documentation, header files, static link libraries, and code examples.

== Using OCEOSmp with Soft Console ==

The steps to use OCEOSmp with Soft Console are as follows:
#Add OCEOSmp header files folder to application project
#Add OCEOSmp directory search path option to the linker -LPathToOCEOSmpDirectory
#Add OCEOSmp library name to the linker options -loceosmp
#Copy oceosmp_config.h to project include folder
#Update oceosmp_config.h according to project requirements (number of tasks, mutexes, semaphores, data Qs, timed actions)
#Set size of log area, fixed area and dynamic areas
#Copy oceosmp_config.c to project source directory and modify configuration struct as required
#Copy oceosmp_config_riscv64.h to project include folder
#Modify oceosmp_config_riscv64.h to select CPUs to be used with OCEOSmp
#Starting CPU must call main() at the end of initialisation
#Other CPUs must call oceos_start(NULL, 0, NULL) function
#Mss_entry.S must be updated to include a call to oceosmp_trap_from_machine_mode from trap_handler
#User trap handlers are called from oceosmp_trap_from_machine_mode
#Update linker script symbols for per CPU stack size
#Write the application code referring to examples provided, where necessary.
#The bare metal device drivers provided with Soft Console can generally be used with OCEOSmp. The weak references in the OCEOSmp interrupt vectors module will resolve to the device drivers to be used.
#Build the application as normal.

The OCEOSmp documentation includes a user manual, wiki, and header files.

== Licensing & services ==

Licensing plans for OCEOSmp are as follows:

#Development Kit (software, documentation, and unlimited runtime licences[note 1])
#Annual support fee (upgrades, unlimited runtime licences, access to support resources)
#Customer board OCEOSmp functional certification service
#A Safety Assurance Pack is available to provide an easy route to achieving safety certification
#Source code is available under special licence conditions

Note 1: Unlimited runtime licences require annual support fee after first year

== Contact information ==

For sales contact sales@ocetechnology.com or call +353 1 716 3530.

For support contact support@ocetechnology.com

OCEOSmp/polarfire

2024-06-17T11:50:04Z

Bkavanagh: /* OCEOSmp BSP for Polarfire */

= OCEOSmp BSP for PolarFire =

OCEOSmp is a real-time operating system compliant with European Space Agency standards (ECSS Category B). It occupies a small memory footprint and provides a unique set of functions to help police the application tasks. It supports RISC-V, ARM, and SPARC processor architectures and has been designed to provide deterministic task scheduling.
The installation package contains documentation, header files, static link libraries, and code examples.

== Using OCEOSmp with Soft Console ==

The steps to use OCEOSmp with Soft Console are as follows:
#Add OCEOSmp header files folder to application project
#Add OCEOSmp directory search path option to the linker -LPathToOCEOSmpDirectory
#Add OCEOSmp library name to the linker options -loceosmp
#Copy oceosmp_config.h to project include folder
#Update oceosmp_config.h according to project requirements (number of tasks, mutexes, semaphores, data Qs, timed actions)
#Set size of log area, fixed area and dynamic areas
#Copy oceosmp_config.c to project source directory and modify configuration struct as required
#Copy oceosmp_config_riscv64.h to project include folder
#Modify oceosmp_config_riscv64.h to select CPUs to be used with OCEOSmp
#Starting CPU must call main() at the end of initialisation
#Other CPUs must call oceos_start(NULL, 0, NULL) function
#Mss_entry.S must be updated to include a call to oceosmp_trap_from_machine_mode from trap_handler
#User trap handlers are called from oceosmp_trap_from_machine_mode
#Update linker script symbols for per CPU stack size
#Write the application code referring to examples provided, where necessary.
#The bare metal device drivers provided with Soft Console can generally be used with OCEOSmp. The weak references in the OCEOSmp interrupt vectors module will resolve to the device drivers to be used.
#Build the application as normal.

The OCEOSmp documentation includes a user manual, wiki, and header files.

== Licensing & services ==

Licensing plans for OCEOSmp are as follows:

#Development Kit (software, documentation, and unlimited runtime licences[note 1])
#Annual support fee (upgrades, unlimited runtime licences, access to support resources)
#Customer board OCEOSmp functional certification service
#A Safety Assurance Pack is available to provide an easy route to achieving safety certification
#Source code is available under special licence conditions

Note 1: Unlimited runtime licences require annual support fee after first year

== Contact information ==

For sales contact sales@ocetechnology.com or call +353 1 716 3530.

For support contact support@ocetechnology.com

OCEOSmp/polarfire

2024-06-14T10:54:40Z

Bkavanagh: /* Contact information */

= OCEOSmp BSP for Polarfire =

OCEOSmp is a real-time operating system compliant with European Space Agency standards (ECSS Category B). It occupies a small memory footprint and provides a unique set of functions to help police the application tasks. It supports RISC-V, ARM, and SPARC processor architectures and has been designed to provide deterministic task scheduling.
The installation package contains documentation, header files, static link libraries, and code examples.

== Using OCEOSmp with Soft Console ==

The steps to use OCEOSmp with Soft Console are as follows:
#Add OCEOSmp header files folder to application project
#Add OCEOSmp directory search path option to the linker -LPathToOCEOSmpDirectory
#Add OCEOSmp library name to the linker options -loceosmp
#Copy oceosmp_config.h to project include folder
#Update oceosmp_config.h according to project requirements (number of tasks, mutexes, semaphores, data Qs, timed actions)
#Set size of log area, fixed area and dynamic areas
#Copy oceosmp_config.c to project source directory and modify configuration struct as required
#Copy oceosmp_config_riscv64.h to project include folder
#Modify oceosmp_config_riscv64.h to select CPUs to be used with OCEOSmp
#Starting CPU must call main() at the end of initialisation
#Other CPUs must call oceos_start(NULL, 0, NULL) function
#Mss_entry.S must be updated to include a call to oceosmp_trap_from_machine_mode from trap_handler
#User trap handlers are called from oceosmp_trap_from_machine_mode
#Update linker script symbols for per CPU stack size
#Write the application code referring to examples provided, where necessary.
#The bare metal device drivers provided with Soft Console can generally be used with OCEOSmp. The weak references in the OCEOSmp interrupt vectors module will resolve to the device drivers to be used.
#Build the application as normal.

The OCEOSmp documentation includes a user manual, wiki, and header files.

== Licensing & services ==

Licensing plans for OCEOSmp are as follows:

#Development Kit (software, documentation, and unlimited runtime licences[note 1])
#Annual support fee (upgrades, unlimited runtime licences, access to support resources)
#Customer board OCEOSmp functional certification service
#A Safety Assurance Pack is available to provide an easy route to achieving safety certification
#Source code is available under special licence conditions

Note 1: Unlimited runtime licences require annual support fee after first year

== Contact information ==

For sales contact sales@ocetechnology.com or call +353 1 716 3530.

For support contact support@ocetechnology.com

OCEOSmp/polarfire

2024-06-14T10:53:48Z

Bkavanagh:

OCEOSmp/polarfire

2024-06-14T10:52:26Z

Bkavanagh:

= OCEOSmp BSP for Polarfire =

OCEOSmp is a real-time operating system compliant with European Space Agency standards (ECSS Category B). It occupies a small memory footprint and provides a unique set of functions to help police the application tasks. It supports RISC-V, ARM, and SPARC processor architectures and has been designed to provide deterministic task scheduling.
The installation package contains documentation, header files, static link libraries, and code examples.

== Using OCEOSmp with Soft Console ==

The steps to use OCEOSmp with Soft Console are as follows:
#Add OCEOSmp header files folder to application project
#Add OCEOSmp directory search path option to the linker -LPathToOCEOSmpDirectory
#Add OCEOSmp library name to the linker options -loceosmp
#Copy oceosmp_config.h to project include folder
#Update oceosmp_config.h according to project requirements (number of tasks, mutexes, semaphores, data Qs, timed actions)
#Set size of log area, fixed area and dynamic areas
#Copy oceosmp_config.c to project source directory and modify configuration struct as required
#Copy oceosmp_config_riscv64.h to project include folder
#Modify oceosmp_config_riscv64.h to select CPUs to be used with OCEOSmp
#Starting CPU must call main() at the end of initialisation
#Other CPUs must call oceos_start(NULL, 0, NULL) function
#Mss_entry.S must be updated to include a call to oceosmp_trap_from_machine_mode from trap_handler
#User trap handlers are called from oceosmp_trap_from_machine_mode
#Update linker script symbols for per CPU stack size
#Write the application code referring to examples provided, where necessary.
#The bare metal device drivers provided with Soft Console can generally be used with OCEOSmp. The weak references in the OCEOSmp interrupt vectors module will resolve to the device drivers to be used.
#Build the application as normal.

The OCEOSmp documentation includes a user manual, wiki, and header files.

== Licensing & services ==

Licensing plans for OCEOSmp are as follows:

#Development Kit (software, documentation, and unlimited runtime licences1)
#Annual support fee (upgrades, unlimited runtime licences, access to support resources)
#Customer board OCEOSmp functional certification service
#A Safety Assurance Pack is available to provide an easy route to achieving safety certification
#Source code is available under special licence conditions
#Unlimited runtime licences require annual support fee after first year

== Contact information ==

For sales contact sales@ocetechnology.com or call +353 1 716 3530.
For support contact support@ocetechnology.com

OCEOSmp/polarfire

2024-06-14T09:41:43Z

Bkavanagh: Created page with "OCEOSmp BSP for Polarfire OCEOSmp is a real-time operating system compliant with European Space Agency standards (ECSS Category B). It occupies a small memory footprint and p..."

OCEOSmp BSP for Polarfire

OCEOSmp is a real-time operating system compliant with European Space Agency standards (ECSS Category B). It occupies a small memory footprint and provides a unique set of functions to help police the application tasks. It supports RISC-V, ARM, and SPARC processor architectures and has been designed to provide deterministic task scheduling.
The installation package contains documentation, header files, static link libraries, and code examples.

Using OCEOSmp with Soft Console

The steps to use OCEOSmp with Soft Console are as follows:
#Add OCEOSmp header files folder to application project
#Add OCEOSmp directory search path option to the linker -LPathToOCEOSmpDirectory
#Add OCEOSmp library name to the linker options -loceosmp
#Copy oceosmp_config.h to project include folder
#Update oceosmp_config.h according to project requirements (number of tasks, mutexes, semaphores, data Qs, timed actions)
#Set size of log area, fixed area and dynamic areas
#Copy oceosmp_config.c to project source directory and modify configuration struct as required
#Copy oceosmp_config_riscv64.h to project include folder
#Modify oceosmp_config_riscv64.h to select CPUs to be used with OCEOSmp
#Starting CPU must call main() at the end of initialisation
#Other CPUs must call oceos_start(NULL, 0, NULL) function
#Mss_entry.S must be updated to include a call to oceosmp_trap_from_machine_mode from trap_handler
#User trap handlers are called from oceosmp_trap_from_machine_mode
#Update linker script symbols for per CPU stack size
#Write the application code referring to examples provided, where necessary.
#The bare metal device drivers provided with Soft Console can generally be used with OCEOSmp. The weak references in the OCEOSmp interrupt vectors module will resolve to the device drivers to be used.
#Build the application as normal.

The OCEOSmp documentation includes a user manual, wiki, and header files.

Licensing & services

Licensing plans for OCEOSmp are as follows:

#Development Kit (software, documentation, and unlimited runtime licences1)
#Annual support fee (upgrades, unlimited runtime licences, access to support resources)
#Customer board OCEOSmp functional certification service
#A Safety Assurance Pack is available to provide an easy route to achieving safety certification
#Source code is available under special licence conditions
#Unlimited runtime licences require annual support fee after first year

Contact information

For sales contact sales@ocetechnology.com or call +353 1 716 3530.
For support contact support@ocetechnology.com

MediaWiki:Sidebar

2024-06-14T09:37:57Z

Bkavanagh:

OCEOSmp/directive reference

2024-05-03T17:04:26Z

Bkavanagh: /* Task data structures */

= Introduction =

To be added

= Directives =

== Initialisation directives ==

===oceos_init()===
<blockquote style="border-left-style: none;">
'''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 [[OCEOSmp/directive_reference#oceos_init_finish()|oceos_init_finish()]] has completed successfully. 
'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>
'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
/*
* 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
</syntaxhighlight>
</blockquote>

===oceos_init_finish()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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);
</syntaxhighlight>
'''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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
/*
* 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
</syntaxhighlight>
</blockquote>

===oceos_start()===
<blockquote style="border-left-style: none;">
'''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 [[OCEOSmp/directive_reference#oceos_init()|oceos_init()]] and [[OCEOSmp/directive_reference#oceos_init_finish()|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''' 
<syntaxhighlight lang="C">
/**
* 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
);

</syntaxhighlight>
'''Parameters''' 
{| class="wikitable"
|-
! 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. 
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
/* 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);
</syntaxhighlight>
</blockquote>

===oceos_exit()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''initialisation.h''''' 

'''Description''' 
Ends scheduling and exit from [[OCEOSmp/directive_reference#oceos_start()|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''' 
<syntaxhighlight lang="C">
/**
* 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);

</syntaxhighlight>
'''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. 
{| class="wikitable"
|-
! Error bit || Description
|-
| ERR_SYS_FIXED_CORRUPT || System Fixed area corrupt
|-
| ERR_WRONG_PHASE || Called before scheduling started
|}

'''Example Usage''' 
<syntaxhighlight lang="C">
// Exit OCEOS
oceos_exit();
</syntaxhighlight>
</blockquote>

===oceos_CPU_sleep()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''initialisation.h''''' 

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

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* Puts CPU in sleep mode.
* User must to be sure that interrupts are enabled.
*
* @return OCEOS_SUCCESS
*/
S32_t oceos_CPU_sleep(void);
</syntaxhighlight>

'''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''' 
<syntaxhighlight lang="C">
// Put CPU to sleep
oceos_CPU_sleep();
</syntaxhighlight>
</blockquote>

===oceosmp_cpu_disable()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''initialisation.h''''' 

'''Description''' 
This function ends execution of all tasks running on particular CPU and removes the CPU from scheduling.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, faulty_cpu;
...
// Disable faulty CPU core
status = oceosmp_cpu_disable(faulty_cpu));

</syntaxhighlight>
</blockquote>

===oceosmp_cpu_enable()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, good_cpu;
...
// Enable CPU core
status = oceosmp_cpu_enable(good_cpu));

</syntaxhighlight>
</blockquote>

===oceosmp_cpu_terminate()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, faulty_cpu;
...
// Terminate CPU core
status = oceosmp_cpu_terminate(faulty_cpu));

</syntaxhighlight>
</blockquote>

==Task directives==
{| class="wikitable"
|+ API Functions
|-
| Directive || Description || main || task || IRQ handler
|-
| [[OCEOSmp/directive reference#oceos_task_create()| oceos_task_create()]] || Create Task || * || ||
|-
| [[OCEOSmp/directive reference#oceos_task_start()| oceos_task_start()]] || Start Task || || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_timed_start()| oceos_task_timed_start()]] || Schedule a task to start execution at a given system time|| || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_disable()| oceos_task_disable()]] || Disable Task || || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_enable()| oceos_task_enable()]] || Enable Task || || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_self()| oceos_task_self()]] || Returns the task ID of the currently executing task || || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_get_priority()| oceos_task_get_priority()]] || Get priority of a task || || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_get_status()| oceos_task_get_status()]] || Get status of a task || || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_kill()| oceos_task_kill()]] || Directive to terminate current task|| || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_get_info()| oceos_task_get_info()]] || Get task information || || * || *
|-
| [[OCEOSmp/directive reference#oceosmp_task_kill()| oceosmp_task_kill()]] || Directive to terminate current task|| || * || *
|}

===Task data structures===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
The following data structures are used by some of the task directives.

'''Data structures''' 
<syntaxhighlight lang="C">
/**
* 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
};

</syntaxhighlight>

===oceos_task_create()===
<blockquote style="border-left-style: none;">

'''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 [[OCEOSmp/directive_reference#oceos_init()|oceos_init()]] and before [[OCEOSmp/directive_reference#oceos_init_finish()|oceos_init_finish()]]. 
It must be called for each task otherwise [[OCEOSmp/directive_reference#oceos_start()|oceos_start()]] will return an error.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>
'''Parameters''' 
{| class="wikitable"
|-
! 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.

{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">

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

</syntaxhighlight>
</blockquote>

===oceos_task_start()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
void *ptr;
...
// Start instance of task T_1 passing pointer ptr
status = oceos_task_start(t_1,ptr);

</syntaxhighlight>
</blockquote>

===oceos_task_timed_start()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function schedules a task to start execution at a given system time.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_task_disable()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''initialisation.h''''' 

'''Description''' 
This function disables a task and removes any current pending jobs from the readyQ.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.

{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Disable task t_1
status = oceos_task_disable(t_1);

</syntaxhighlight>
</blockquote>

===oceos_task_enable()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function enables a task. Only enabled tasks may be started.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);

</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Enable task t_2
status = oceos_task_enable(t_2);

</syntaxhighlight>
</blockquote>

===oceos_task_self()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function returns the task number of the currently running task on the calling CPU.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status, task_running;
...
// Return task ID that's running on this core
status = oceos_task_self(&task_running);

</syntaxhighlight>
</blockquote>

===oceos_task_get_priority()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function returns the priority of the task ID passed to it.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
U32_t t_priority;
...
// Return the priority of task ID t_4
status = oceos_task_get_priority(t_4, &t_priority);

</syntaxhighlight>
</blockquote>

===oceos_task_get_status()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function returns the status of the task ID passed to it.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
U32_t t_status;
...
// Return the status of task ID t_4
status = oceos_task_get_status(t_4, &t_status);

</syntaxhighlight>
</blockquote>

===oceos_task_get_info()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function returns the task information for the specified task.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
struct task_info info;
...
// Get information for task T3
status = oceos_task_get_info(t_3, &info);

</syntaxhighlight>
</blockquote>

===oceosmp_task_kill()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function kills the specified task running on the specified CPU.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Kill task t_2 on CPU cpu_1
status = oceosmp_task_kill(t_2, cpu_1);

</syntaxhighlight>
</blockquote>

==Mutex directives==

===oceos_mutex_create()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''mutex.h''''' 

'''Description''' 
This function creates a mutex of specified ID with a specified priority ceiling.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Create mutex with ID print_mutex and priority ceiling of 5
status = oceos_mutex_create(print_mutex, 5);

</syntaxhighlight>
</blockquote>

===oceos_mutex_wait()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''mutex.h''''' 

'''Description''' 
This function makes the task wait until the specified mutex is available.

'''Prototype''' 
<syntaxhighlight lang="C">
/*
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Wait on mutex m_2
status = oceos_mutex_wait(m_2);

</syntaxhighlight>
</blockquote>

===oceos_mutex_signal()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''mutex.h''''' 

'''Description''' 
This function signals the specified mutex.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Signal mutex m_2
status = oceos_mutex_signal(m_2);

</syntaxhighlight>
</blockquote>

===oceos_mutex_get_value()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''mutex.h''''' 

'''Description''' 
This function returns the value of the specified mutex.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
U32_t value;
...
// Get value of mutex m_2
status = oceos_mutex_get_value(m_2, &value);

</syntaxhighlight>
</blockquote>

==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()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''rwmutex.h''''' 

'''Description''' 
This function ees a read/write mutex.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Create read/write mutex with ID rwm_2 and priority ceiling of 100
status = oceos_rwmutex_create(rwm_1, 100);

</syntaxhighlight>
</blockquote>

===oceos_rwmutex_read_wait()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Acquire read/write mutex rwm_1 for read
status = oceos_rwmutex_read_wait(rwm_1);
</syntaxhighlight>
</blockquote>

===oceos_rwmutex_write_wait()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Acquire read/write mutex rwm_1 for write
status = oceos_rwmutex_read_wait(rwm_1);
</syntaxhighlight>
</blockquote>

===oceos_rwmutex_signal()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Signal read/write mutex number rwm_4
status = oceos_rwmutex_signal(rwm_4);
</syntaxhighlight>
</blockquote>

===oceos_rwmutex_check_status()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status, rwm_status;
...
// Check the status of read/write mutex rwm_2
status = oceos_rwmutex_check_status(rwm_2, &rwm_status);
</syntaxhighlight>
</blockquote>

===oceos_rwmutex_reading_count()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''rwmutex.h''''' 

'''Description''' 
This function returns the current number of jobs holding a specified read/write mutex for read.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
*
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_rwmutex_write_reqs_count()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''header.h''''' 

'''Description''' 
This function returns the current number of write requests for the specified read/write mutex .

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
| 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_rwmutex_writes_pending_count()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''rwmutex.h''''' 

'''Description''' 
This function returns the current number of pending writes for the specified read/write mutex.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>

===oceos_rwmutex_holding()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''header.h''''' 

'''Description''' 
This function returns the read/write mutexes currently held by this instance of this task (job).

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
U64_t rwm_held;
...
// Which read/write mutexes does this job hold
status = oceos_rwmutex_holding(&rwm_held);

</syntaxhighlight>
</blockquote>

== Semaphores directives ==

===oceos_sem_create()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''semaphore.h''''' 

'''Description''' 
This function creates a semaphore.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_sem_signal()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''semaphore.h''''' 

'''Description''' 
This function signals a semaphore, increments its count and transfers pending jobs to the ready queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Signal s_audi semaphore (increment its count)
status = oceos_sem_signal(s_audi);
</syntaxhighlight>
</blockquote>

===oceos_sem_wait_continue()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''semaphore.h''''' 

'''Description''' 
This function decrements the available permits of a sempahore otherwise returns an unsuccessful status code.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Decrement available permits on semaphore s_1
status = oceos_sem_wait_continue(s_1);

</syntaxhighlight>
</blockquote>

===oceos_sem_wait_restart()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Decrement available permits on semaphore s_1 otherwise job is put on pending queue
status = oceos_sem_wait_restart(s_1);

</syntaxhighlight>
</blockquote>

===oceos_sem_wait_restart_timeout()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! Parameter || Description
|-
| sem_id || U32_t value of semaphore to be decremented
|-
| timeout | 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>

===oceos_sem_get_value()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''semaphore.h''''' 

'''Description''' 
This function returns the number of available permits for the specified semaphore.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status, permit_count;
...
// Get the available permits for semaphore s_1
status = oceos_sem_get_value(s_1, &permit_count);

</syntaxhighlight>
</blockquote>

===oceos_sem_penq_get_size()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''semaphore.h''''' 

'''Description''' 
This function returns the number of jobs on the specified semaphore pending queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status, job_count;
...
// Get the available permits for semaphore s_1
status = oceos_sem_penq_get_size(s_1, &job_count);

</syntaxhighlight>
</blockquote>

===oceos_sem_reset()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Reset semaphore s_1
status = oceos_sem_reset(s_1);
</syntaxhighlight>
</blockquote>

== Data Queues ==

===oceos_dataq_create()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''dataq.h''''' 

'''Description''' 
This function creates a data queue with the specified characteristics.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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));
</syntaxhighlight>
</blockquote>

===oceos_dataq_write()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''dataq.h''''' 

'''Description''' 
This function puts a non-null pointer on the specified data queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>

===oceos_dataq_read_continue()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''dataq.h''''' 

'''Description''' 
This function returns a pointer from the specified data queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
char *data_ptr;
...
// Read pointer from data queue s_2
status = oceos_dataq_read_continue(s_2, (void *)data_ptr);
</syntaxhighlight>
</blockquote>

===oceos_dataq_read_restart()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>

===oceos_dataq_read_restart_timeout()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>

===oceos_dataq_get_size()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''dataq.h''''' 

'''Description''' 
This function returns the number of items on the specified data queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status, d_size;
...
// Get the number of entries on data queue d_0
status = oceos_dataq_get_size(d_0, &d_size);
</syntaxhighlight>
</blockquote>

===oceos_dataq_penq_get_size()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''dataq.h''''' 

'''Description''' 
This function returns number of jobs on the specified data queue pending job's queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>

===oceos_dataq_clear()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''dataq.h''''' 

'''Description''' 
This function clears the specified data queue including pending jobs for that queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Clear data queue d_1
status = oceos_dataq_penq_get_size(d_1);
</syntaxhighlight>
</blockquote>

== Timed Actions ==

===oceos_timed_output_add()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
| 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">

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

</syntaxhighlight>
</blockquote>

===oceos_timed_jobs_number()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''timed_action.h''''' 

'''Description''' 
This function returns the number of jobs on the timed actions queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, no_of_jobs;
...
// Get the number of jobs on the timed actions queue
status = oceos_timed_jobs_number(&no_of_jobs);

</syntaxhighlight>
</blockquote>

===oceos_timed_jobs_remove()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''timed_action.h''''' 

'''Description''' 
This function removes the specified timed action from the queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, job_id;
...
// Remove job_id from the timed actions queue
status = oceos_timed_jobs_remove(job_id);

</syntaxhighlight>
</blockquote>

===oceos_timed_jobs_reset()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''timed_action.h''''' 

'''Description''' 
This function removes all jobs from timed actions queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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);
</syntaxhighlight>

'''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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Remove all jobs from the timed actions queue
status = oceos_timed_jobs_reset(job_id);
</syntaxhighlight>
</blockquote>

===oceos_timed_output_remove()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''timed_action.h''''' 

'''Description''' 
This function removes the specified timed output action from timed actions queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
| 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''' 
<syntaxhighlight lang="C">
S32_t status;
U8_t action_index;
...
// Remove timed output with specified action_index
status = oceos_timed_output_remove(action_index);

</syntaxhighlight>
</blockquote>

===oceos_timed_output_reset()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''timed_action.h''''' 

'''Description''' 
This function removes all timed output actions from timed actions queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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);
</syntaxhighlight>

'''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.
{| class="wikitable"
|-
| 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Remove all timed outputs from the timed actions queue
status = oceos_timed_output_reset();

</syntaxhighlight>
</blockquote>

== Logging directives ==

===Introduction===
<blockquote style="border-left-style: none;">

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''' 
<syntaxhighlight lang="C">
/*****************************************************************************
* 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)));

</syntaxhighlight>

===oceos_log_add_entry()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! Parameter || Description
|-
| enum LOG_ENTRY_TYPE || Log entry type (see previous section for a list)
|-
| info | 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_log_get_indexed_entry()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_log_remove_entry()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_log_reset()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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);
</syntaxhighlight>

'''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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...

// Clear down the system log
status = oceos_log_reset();

</syntaxhighlight>
</blockquote>

===oceos_log_get_size()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, size;
...

// Clear down the system log
status = oceos_log_get_size(&size);

</syntaxhighlight>
</blockquote>

===System State Variable and System State Mask===
<blockquote style="border-left-style: none;">

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''' 
<syntaxhighlight lang="C">

#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

</syntaxhighlight>

===oceos_system_state_get()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''system_log.h''''' 

'''Description''' 
This function returns of the system state variable.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, state;
...

// Get the system state
status = oceos_system_state_get(&state);

</syntaxhighlight>
</blockquote>

===oceos_system_state_set()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''system_log.h''''' 

'''Description''' 
This function sets system state variable.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! Error bit !! Description
|-
| ERR_SYS_FIXED_CORRUPT || System Fixed area corrupt
|-
| ERR_SYS_LOG_CORRUPT || LOG dynamic pointer is null
|}

'''Example Usage''' 
<syntaxhighlight lang="C">
S32_t status, new_state;
...

// Set new system state
status = oceos_system_state_set(new_state);

</syntaxhighlight>
</blockquote>

===oceos_system_state_copy_get()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''system_log.h''''' 

'''Description''' 
This function returns the value of the system state copy variable.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, copy_state;
...

// Get the system state copy
status = oceos_system_state_copy_get(&copy_state);

</syntaxhighlight>
</blockquote>

===oceos_system_state_copy_set()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''system_log.h''''' 

'''Description''' 
This function loads a value to tha system state copy variable.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! Error bit !! Description
|-
| ERR_SYS_FIXED_CORRUPT || System Fixed area corrupt
|-
| ERR_SYS_LOG_CORRUPT || LOG dynamic pointer is null
|}

'''Example Usage''' 
<syntaxhighlight lang="C">
S32_t status, new_state;
...

// Set new system state copy
status = oceos_system_state_copy_set(new_state);

</syntaxhighlight>
</blockquote>

== Timing directives ==

===Introduction===
<blockquote style="border-left-style: none;">

'''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()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''oceos_timer.h''''' 

'''Description''' 
This function returns the current system time as a 64-bit number.

'''Prototype''' 
<syntaxhighlight lang="C">
**
* Get the current system time (64-bit)
*
* @return U64_t
*/
U64_t oceos_time_sys_get64(void);
</syntaxhighlight>

'''Parameters''' 

There are no parameters to this function.

'''Returns''' 
This function returns an S64_t with the current system time.

'''Example Usage''' 
<syntaxhighlight lang="C">
S64_t now;
...
// Get the time
now = oceos_time_sys_get64();
</syntaxhighlight>
</blockquote>

===oceos_time_sys_get32()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''oceos_timer.h''''' 

'''Description''' 
This function returns the low 32 bits of the system time.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* Get the current system time (low 32 bits of 64 bit value)
*
* @return U32_t
*/
U32_t oceos_time_sys_get32(void);
</syntaxhighlight>

'''Parameters''' 
There are no parameters to this function.

'''Returns''' 
This function returns an S32_t with the current system time.

'''Example Usage''' 
<syntaxhighlight lang="C">
S32_t now;
...
// Get the time
now = oceos_time_sys_get32();
</syntaxhighlight>
</blockquote>

[[Category:backup]]

OCEOSmp/directive reference

2024-05-03T17:03:02Z

Bkavanagh:

= Introduction =

To be added

= Directives =

== Initialisation directives ==

===oceos_init()===
<blockquote style="border-left-style: none;">
'''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 [[OCEOSmp/directive_reference#oceos_init_finish()|oceos_init_finish()]] has completed successfully. 
'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>
'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
/*
* 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
</syntaxhighlight>
</blockquote>

===oceos_init_finish()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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);
</syntaxhighlight>
'''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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
/*
* 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
</syntaxhighlight>
</blockquote>

===oceos_start()===
<blockquote style="border-left-style: none;">
'''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 [[OCEOSmp/directive_reference#oceos_init()|oceos_init()]] and [[OCEOSmp/directive_reference#oceos_init_finish()|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''' 
<syntaxhighlight lang="C">
/**
* 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
);

</syntaxhighlight>
'''Parameters''' 
{| class="wikitable"
|-
! 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. 
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
/* 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);
</syntaxhighlight>
</blockquote>

===oceos_exit()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''initialisation.h''''' 

'''Description''' 
Ends scheduling and exit from [[OCEOSmp/directive_reference#oceos_start()|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''' 
<syntaxhighlight lang="C">
/**
* 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);

</syntaxhighlight>
'''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. 
{| class="wikitable"
|-
! Error bit || Description
|-
| ERR_SYS_FIXED_CORRUPT || System Fixed area corrupt
|-
| ERR_WRONG_PHASE || Called before scheduling started
|}

'''Example Usage''' 
<syntaxhighlight lang="C">
// Exit OCEOS
oceos_exit();
</syntaxhighlight>
</blockquote>

===oceos_CPU_sleep()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''initialisation.h''''' 

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

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* Puts CPU in sleep mode.
* User must to be sure that interrupts are enabled.
*
* @return OCEOS_SUCCESS
*/
S32_t oceos_CPU_sleep(void);
</syntaxhighlight>

'''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''' 
<syntaxhighlight lang="C">
// Put CPU to sleep
oceos_CPU_sleep();
</syntaxhighlight>
</blockquote>

===oceosmp_cpu_disable()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''initialisation.h''''' 

'''Description''' 
This function ends execution of all tasks running on particular CPU and removes the CPU from scheduling.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, faulty_cpu;
...
// Disable faulty CPU core
status = oceosmp_cpu_disable(faulty_cpu));

</syntaxhighlight>
</blockquote>

===oceosmp_cpu_enable()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, good_cpu;
...
// Enable CPU core
status = oceosmp_cpu_enable(good_cpu));

</syntaxhighlight>
</blockquote>

===oceosmp_cpu_terminate()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, faulty_cpu;
...
// Terminate CPU core
status = oceosmp_cpu_terminate(faulty_cpu));

</syntaxhighlight>
</blockquote>

==Task directives==
{| class="wikitable"
|+ API Functions
|-
| Directive || Description || main || task || IRQ handler
|-
| [[OCEOSmp/directive reference#oceos_task_create()| oceos_task_create()]] || Create Task || * || ||
|-
| [[OCEOSmp/directive reference#oceos_task_start()| oceos_task_start()]] || Start Task || || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_timed_start()| oceos_task_timed_start()]] || Schedule a task to start execution at a given system time|| || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_disable()| oceos_task_disable()]] || Disable Task || || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_enable()| oceos_task_enable()]] || Enable Task || || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_self()| oceos_task_self()]] || Returns the task ID of the currently executing task || || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_get_priority()| oceos_task_get_priority()]] || Get priority of a task || || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_get_status()| oceos_task_get_status()]] || Get status of a task || || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_kill()| oceos_task_kill()]] || Directive to terminate current task|| || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_get_info()| oceos_task_get_info()]] || Get task information || || * || *
|-
| [[OCEOSmp/directive reference#oceosmp_task_kill()| 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''' 
<syntaxhighlight lang="C">
/**
* 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
};

</syntaxhighlight>

===oceos_task_create()===
<blockquote style="border-left-style: none;">

'''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 [[OCEOSmp/directive_reference#oceos_init()|oceos_init()]] and before [[OCEOSmp/directive_reference#oceos_init_finish()|oceos_init_finish()]]. 
It must be called for each task otherwise [[OCEOSmp/directive_reference#oceos_start()|oceos_start()]] will return an error.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>
'''Parameters''' 
{| class="wikitable"
|-
! 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.

{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">

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

</syntaxhighlight>
</blockquote>

===oceos_task_start()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
void *ptr;
...
// Start instance of task T_1 passing pointer ptr
status = oceos_task_start(t_1,ptr);

</syntaxhighlight>
</blockquote>

===oceos_task_timed_start()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function schedules a task to start execution at a given system time.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_task_disable()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''initialisation.h''''' 

'''Description''' 
This function disables a task and removes any current pending jobs from the readyQ.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.

{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Disable task t_1
status = oceos_task_disable(t_1);

</syntaxhighlight>
</blockquote>

===oceos_task_enable()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function enables a task. Only enabled tasks may be started.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);

</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Enable task t_2
status = oceos_task_enable(t_2);

</syntaxhighlight>
</blockquote>

===oceos_task_self()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function returns the task number of the currently running task on the calling CPU.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status, task_running;
...
// Return task ID that's running on this core
status = oceos_task_self(&task_running);

</syntaxhighlight>
</blockquote>

===oceos_task_get_priority()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function returns the priority of the task ID passed to it.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
U32_t t_priority;
...
// Return the priority of task ID t_4
status = oceos_task_get_priority(t_4, &t_priority);

</syntaxhighlight>
</blockquote>

===oceos_task_get_status()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function returns the status of the task ID passed to it.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
U32_t t_status;
...
// Return the status of task ID t_4
status = oceos_task_get_status(t_4, &t_status);

</syntaxhighlight>
</blockquote>

===oceos_task_get_info()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function returns the task information for the specified task.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
struct task_info info;
...
// Get information for task T3
status = oceos_task_get_info(t_3, &info);

</syntaxhighlight>
</blockquote>

===oceosmp_task_kill()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function kills the specified task running on the specified CPU.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Kill task t_2 on CPU cpu_1
status = oceosmp_task_kill(t_2, cpu_1);

</syntaxhighlight>
</blockquote>

==Mutex directives==

===oceos_mutex_create()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''mutex.h''''' 

'''Description''' 
This function creates a mutex of specified ID with a specified priority ceiling.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Create mutex with ID print_mutex and priority ceiling of 5
status = oceos_mutex_create(print_mutex, 5);

</syntaxhighlight>
</blockquote>

===oceos_mutex_wait()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''mutex.h''''' 

'''Description''' 
This function makes the task wait until the specified mutex is available.

'''Prototype''' 
<syntaxhighlight lang="C">
/*
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Wait on mutex m_2
status = oceos_mutex_wait(m_2);

</syntaxhighlight>
</blockquote>

===oceos_mutex_signal()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''mutex.h''''' 

'''Description''' 
This function signals the specified mutex.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Signal mutex m_2
status = oceos_mutex_signal(m_2);

</syntaxhighlight>
</blockquote>

===oceos_mutex_get_value()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''mutex.h''''' 

'''Description''' 
This function returns the value of the specified mutex.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
U32_t value;
...
// Get value of mutex m_2
status = oceos_mutex_get_value(m_2, &value);

</syntaxhighlight>
</blockquote>

==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()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''rwmutex.h''''' 

'''Description''' 
This function ees a read/write mutex.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Create read/write mutex with ID rwm_2 and priority ceiling of 100
status = oceos_rwmutex_create(rwm_1, 100);

</syntaxhighlight>
</blockquote>

===oceos_rwmutex_read_wait()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Acquire read/write mutex rwm_1 for read
status = oceos_rwmutex_read_wait(rwm_1);
</syntaxhighlight>
</blockquote>

===oceos_rwmutex_write_wait()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Acquire read/write mutex rwm_1 for write
status = oceos_rwmutex_read_wait(rwm_1);
</syntaxhighlight>
</blockquote>

===oceos_rwmutex_signal()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Signal read/write mutex number rwm_4
status = oceos_rwmutex_signal(rwm_4);
</syntaxhighlight>
</blockquote>

===oceos_rwmutex_check_status()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status, rwm_status;
...
// Check the status of read/write mutex rwm_2
status = oceos_rwmutex_check_status(rwm_2, &rwm_status);
</syntaxhighlight>
</blockquote>

===oceos_rwmutex_reading_count()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''rwmutex.h''''' 

'''Description''' 
This function returns the current number of jobs holding a specified read/write mutex for read.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
*
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_rwmutex_write_reqs_count()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''header.h''''' 

'''Description''' 
This function returns the current number of write requests for the specified read/write mutex .

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
| 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_rwmutex_writes_pending_count()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''rwmutex.h''''' 

'''Description''' 
This function returns the current number of pending writes for the specified read/write mutex.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>

===oceos_rwmutex_holding()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''header.h''''' 

'''Description''' 
This function returns the read/write mutexes currently held by this instance of this task (job).

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
U64_t rwm_held;
...
// Which read/write mutexes does this job hold
status = oceos_rwmutex_holding(&rwm_held);

</syntaxhighlight>
</blockquote>

== Semaphores directives ==

===oceos_sem_create()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''semaphore.h''''' 

'''Description''' 
This function creates a semaphore.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_sem_signal()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''semaphore.h''''' 

'''Description''' 
This function signals a semaphore, increments its count and transfers pending jobs to the ready queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Signal s_audi semaphore (increment its count)
status = oceos_sem_signal(s_audi);
</syntaxhighlight>
</blockquote>

===oceos_sem_wait_continue()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''semaphore.h''''' 

'''Description''' 
This function decrements the available permits of a sempahore otherwise returns an unsuccessful status code.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Decrement available permits on semaphore s_1
status = oceos_sem_wait_continue(s_1);

</syntaxhighlight>
</blockquote>

===oceos_sem_wait_restart()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Decrement available permits on semaphore s_1 otherwise job is put on pending queue
status = oceos_sem_wait_restart(s_1);

</syntaxhighlight>
</blockquote>

===oceos_sem_wait_restart_timeout()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! Parameter || Description
|-
| sem_id || U32_t value of semaphore to be decremented
|-
| timeout | 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>

===oceos_sem_get_value()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''semaphore.h''''' 

'''Description''' 
This function returns the number of available permits for the specified semaphore.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status, permit_count;
...
// Get the available permits for semaphore s_1
status = oceos_sem_get_value(s_1, &permit_count);

</syntaxhighlight>
</blockquote>

===oceos_sem_penq_get_size()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''semaphore.h''''' 

'''Description''' 
This function returns the number of jobs on the specified semaphore pending queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status, job_count;
...
// Get the available permits for semaphore s_1
status = oceos_sem_penq_get_size(s_1, &job_count);

</syntaxhighlight>
</blockquote>

===oceos_sem_reset()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Reset semaphore s_1
status = oceos_sem_reset(s_1);
</syntaxhighlight>
</blockquote>

== Data Queues ==

===oceos_dataq_create()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''dataq.h''''' 

'''Description''' 
This function creates a data queue with the specified characteristics.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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));
</syntaxhighlight>
</blockquote>

===oceos_dataq_write()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''dataq.h''''' 

'''Description''' 
This function puts a non-null pointer on the specified data queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>

===oceos_dataq_read_continue()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''dataq.h''''' 

'''Description''' 
This function returns a pointer from the specified data queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
char *data_ptr;
...
// Read pointer from data queue s_2
status = oceos_dataq_read_continue(s_2, (void *)data_ptr);
</syntaxhighlight>
</blockquote>

===oceos_dataq_read_restart()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>

===oceos_dataq_read_restart_timeout()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>

===oceos_dataq_get_size()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''dataq.h''''' 

'''Description''' 
This function returns the number of items on the specified data queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status, d_size;
...
// Get the number of entries on data queue d_0
status = oceos_dataq_get_size(d_0, &d_size);
</syntaxhighlight>
</blockquote>

===oceos_dataq_penq_get_size()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''dataq.h''''' 

'''Description''' 
This function returns number of jobs on the specified data queue pending job's queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>

===oceos_dataq_clear()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''dataq.h''''' 

'''Description''' 
This function clears the specified data queue including pending jobs for that queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Clear data queue d_1
status = oceos_dataq_penq_get_size(d_1);
</syntaxhighlight>
</blockquote>

== Timed Actions ==

===oceos_timed_output_add()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
| 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">

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

</syntaxhighlight>
</blockquote>

===oceos_timed_jobs_number()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''timed_action.h''''' 

'''Description''' 
This function returns the number of jobs on the timed actions queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, no_of_jobs;
...
// Get the number of jobs on the timed actions queue
status = oceos_timed_jobs_number(&no_of_jobs);

</syntaxhighlight>
</blockquote>

===oceos_timed_jobs_remove()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''timed_action.h''''' 

'''Description''' 
This function removes the specified timed action from the queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, job_id;
...
// Remove job_id from the timed actions queue
status = oceos_timed_jobs_remove(job_id);

</syntaxhighlight>
</blockquote>

===oceos_timed_jobs_reset()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''timed_action.h''''' 

'''Description''' 
This function removes all jobs from timed actions queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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);
</syntaxhighlight>

'''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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Remove all jobs from the timed actions queue
status = oceos_timed_jobs_reset(job_id);
</syntaxhighlight>
</blockquote>

===oceos_timed_output_remove()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''timed_action.h''''' 

'''Description''' 
This function removes the specified timed output action from timed actions queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
| 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''' 
<syntaxhighlight lang="C">
S32_t status;
U8_t action_index;
...
// Remove timed output with specified action_index
status = oceos_timed_output_remove(action_index);

</syntaxhighlight>
</blockquote>

===oceos_timed_output_reset()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''timed_action.h''''' 

'''Description''' 
This function removes all timed output actions from timed actions queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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);
</syntaxhighlight>

'''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.
{| class="wikitable"
|-
| 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Remove all timed outputs from the timed actions queue
status = oceos_timed_output_reset();

</syntaxhighlight>
</blockquote>

== Logging directives ==

===Introduction===
<blockquote style="border-left-style: none;">

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''' 
<syntaxhighlight lang="C">
/*****************************************************************************
* 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)));

</syntaxhighlight>

===oceos_log_add_entry()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! Parameter || Description
|-
| enum LOG_ENTRY_TYPE || Log entry type (see previous section for a list)
|-
| info | 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_log_get_indexed_entry()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_log_remove_entry()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_log_reset()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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);
</syntaxhighlight>

'''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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...

// Clear down the system log
status = oceos_log_reset();

</syntaxhighlight>
</blockquote>

===oceos_log_get_size()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, size;
...

// Clear down the system log
status = oceos_log_get_size(&size);

</syntaxhighlight>
</blockquote>

===System State Variable and System State Mask===
<blockquote style="border-left-style: none;">

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''' 
<syntaxhighlight lang="C">

#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

</syntaxhighlight>

===oceos_system_state_get()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''system_log.h''''' 

'''Description''' 
This function returns of the system state variable.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, state;
...

// Get the system state
status = oceos_system_state_get(&state);

</syntaxhighlight>
</blockquote>

===oceos_system_state_set()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''system_log.h''''' 

'''Description''' 
This function sets system state variable.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! Error bit !! Description
|-
| ERR_SYS_FIXED_CORRUPT || System Fixed area corrupt
|-
| ERR_SYS_LOG_CORRUPT || LOG dynamic pointer is null
|}

'''Example Usage''' 
<syntaxhighlight lang="C">
S32_t status, new_state;
...

// Set new system state
status = oceos_system_state_set(new_state);

</syntaxhighlight>
</blockquote>

===oceos_system_state_copy_get()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''system_log.h''''' 

'''Description''' 
This function returns the value of the system state copy variable.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, copy_state;
...

// Get the system state copy
status = oceos_system_state_copy_get(&copy_state);

</syntaxhighlight>
</blockquote>

===oceos_system_state_copy_set()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''system_log.h''''' 

'''Description''' 
This function loads a value to tha system state copy variable.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! Error bit !! Description
|-
| ERR_SYS_FIXED_CORRUPT || System Fixed area corrupt
|-
| ERR_SYS_LOG_CORRUPT || LOG dynamic pointer is null
|}

'''Example Usage''' 
<syntaxhighlight lang="C">
S32_t status, new_state;
...

// Set new system state copy
status = oceos_system_state_copy_set(new_state);

</syntaxhighlight>
</blockquote>

== Timing directives ==

===Introduction===
<blockquote style="border-left-style: none;">

'''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()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''oceos_timer.h''''' 

'''Description''' 
This function returns the current system time as a 64-bit number.

'''Prototype''' 
<syntaxhighlight lang="C">
**
* Get the current system time (64-bit)
*
* @return U64_t
*/
U64_t oceos_time_sys_get64(void);
</syntaxhighlight>

'''Parameters''' 

There are no parameters to this function.

'''Returns''' 
This function returns an S64_t with the current system time.

'''Example Usage''' 
<syntaxhighlight lang="C">
S64_t now;
...
// Get the time
now = oceos_time_sys_get64();
</syntaxhighlight>
</blockquote>

===oceos_time_sys_get32()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''oceos_timer.h''''' 

'''Description''' 
This function returns the low 32 bits of the system time.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* Get the current system time (low 32 bits of 64 bit value)
*
* @return U32_t
*/
U32_t oceos_time_sys_get32(void);
</syntaxhighlight>

'''Parameters''' 
There are no parameters to this function.

'''Returns''' 
This function returns an S32_t with the current system time.

'''Example Usage''' 
<syntaxhighlight lang="C">
S32_t now;
...
// Get the time
now = oceos_time_sys_get32();
</syntaxhighlight>
</blockquote>

[[Category:backup]]

OCEOSmp/directive reference

2024-05-03T16:59:36Z

Bkavanagh:

= Introduction =

To be added

= Directives =

== Initialisation directives ==

===oceos_init()===
<blockquote style="border-left-style: none;">
'''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 [[OCEOSmp/directive_reference#oceos_init_finish()|oceos_init_finish()]] has completed successfully. 
'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>
'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
/*
* 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
</syntaxhighlight>
</blockquote>

===oceos_init_finish()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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);
</syntaxhighlight>
'''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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
/*
* 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
</syntaxhighlight>
</blockquote>

===oceos_start()===
<blockquote style="border-left-style: none;">
'''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 [[OCEOSmp/directive_reference#oceos_init()|oceos_init()]] and [[OCEOSmp/directive_reference#oceos_init_finish()|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''' 
<syntaxhighlight lang="C">
/**
* 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
);

</syntaxhighlight>
'''Parameters''' 
{| class="wikitable"
|-
! 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. 
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
/* 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);
</syntaxhighlight>
</blockquote>

===oceos_exit()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''initialisation.h''''' 

'''Description''' 
Ends scheduling and exit from [[OCEOSmp/directive_reference#oceos_start()|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''' 
<syntaxhighlight lang="C">
/**
* 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);

</syntaxhighlight>
'''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. 
{| class="wikitable"
|-
! Error bit || Description
|-
| ERR_SYS_FIXED_CORRUPT || System Fixed area corrupt
|-
| ERR_WRONG_PHASE || Called before scheduling started
|}

'''Example Usage''' 
<syntaxhighlight lang="C">
// Exit OCEOS
oceos_exit();
</syntaxhighlight>
</blockquote>

===oceos_CPU_sleep()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''initialisation.h''''' 

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

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* Puts CPU in sleep mode.
* User must to be sure that interrupts are enabled.
*
* @return OCEOS_SUCCESS
*/
S32_t oceos_CPU_sleep(void);
</syntaxhighlight>

'''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''' 
<syntaxhighlight lang="C">
// Put CPU to sleep
oceos_CPU_sleep();
</syntaxhighlight>
</blockquote>

===oceosmp_cpu_disable()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''initialisation.h''''' 

'''Description''' 
This function ends execution of all tasks running on particular CPU and removes the CPU from scheduling.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, faulty_cpu;
...
// Disable faulty CPU core
status = oceosmp_cpu_disable(faulty_cpu));

</syntaxhighlight>
</blockquote>

===oceosmp_cpu_enable()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, good_cpu;
...
// Enable CPU core
status = oceosmp_cpu_enable(good_cpu));

</syntaxhighlight>
</blockquote>

===oceosmp_cpu_terminate()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, faulty_cpu;
...
// Terminate CPU core
status = oceosmp_cpu_terminate(faulty_cpu));

</syntaxhighlight>
</blockquote>

==Task directives==
{| class="wikitable"
|+ API Functions
|-
| Directive || Description || main || task || IRQ handler
|-
| [[OCEOSmp/directive reference#oceos_task_create()| oceos_task_create()]] || Create Task || * || ||
|-
| [[OCEOSmp/directive reference#oceos_task_start()| oceos_task_start()]] || Start Task || || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_timed_start()| oceos_task_timed_start()]] || Schedule a task to start execution at a given system time|| || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_disable()| oceos_task_disable()]] || Disable Task || || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_enable()| oceos_task_enable()]] || Enable Task || || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_self()| oceos_task_self()]] || Returns the task ID of the currently executing task || || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_get_priority()| oceos_task_get_priority()]] || Get priority of a task || || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_get_status()| oceos_task_get_status()]] || Get status of a task || || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_kill()| oceos_task_kill()]] || Directive to terminate current task|| || * || *
|-
| [[OCEOSmp/directive reference#oceos_task_get_info()| oceos_task_get_info()]] || Get task information || || * || *
|-
| [[OCEOSmp/directive reference#oceosmp_task_kill()| oceosmp_task_kill()]] || Directive to terminate current task|| || * || *
|}

===Task data structures===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
The following data structures are used by some of the task directives.

'''Data structures''' 
<syntaxhighlight lang="C">
/**
* 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
};

</syntaxhighlight>

===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 [[OCEOSmp/directive_reference#oceos_init()|oceos_init()]] and before [[OCEOSmp/directive_reference#oceos_init_finish()|oceos_init_finish()]]. 
It must be called for each task otherwise [[OCEOSmp/directive_reference#oceos_start()|oceos_start()]] will return an error.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>
'''Parameters''' 
{| class="wikitable"
|-
! 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.

{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">

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

</syntaxhighlight>
</blockquote>

===oceos_task_start()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
void *ptr;
...
// Start instance of task T_1 passing pointer ptr
status = oceos_task_start(t_1,ptr);

</syntaxhighlight>
</blockquote>

===oceos_task_timed_start()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function schedules a task to start execution at a given system time.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_task_disable()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''initialisation.h''''' 

'''Description''' 
This function disables a task and removes any current pending jobs from the readyQ.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.

{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Disable task t_1
status = oceos_task_disable(t_1);

</syntaxhighlight>
</blockquote>

===oceos_task_enable()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function enables a task. Only enabled tasks may be started.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);

</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Enable task t_2
status = oceos_task_enable(t_2);

</syntaxhighlight>
</blockquote>

===oceos_task_self()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function returns the task number of the currently running task on the calling CPU.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status, task_running;
...
// Return task ID that's running on this core
status = oceos_task_self(&task_running);

</syntaxhighlight>
</blockquote>

===oceos_task_get_priority()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function returns the priority of the task ID passed to it.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
U32_t t_priority;
...
// Return the priority of task ID t_4
status = oceos_task_get_priority(t_4, &t_priority);

</syntaxhighlight>
</blockquote>

===oceos_task_get_status()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function returns the status of the task ID passed to it.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
U32_t t_status;
...
// Return the status of task ID t_4
status = oceos_task_get_status(t_4, &t_status);

</syntaxhighlight>
</blockquote>

===oceos_task_get_info()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function returns the task information for the specified task.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
struct task_info info;
...
// Get information for task T3
status = oceos_task_get_info(t_3, &info);

</syntaxhighlight>
</blockquote>

===oceosmp_task_kill()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''tasks.h''''' 

'''Description''' 
This function kills the specified task running on the specified CPU.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Kill task t_2 on CPU cpu_1
status = oceosmp_task_kill(t_2, cpu_1);

</syntaxhighlight>
</blockquote>

==Mutex directives==

===oceos_mutex_create()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''mutex.h''''' 

'''Description''' 
This function creates a mutex of specified ID with a specified priority ceiling.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Create mutex with ID print_mutex and priority ceiling of 5
status = oceos_mutex_create(print_mutex, 5);

</syntaxhighlight>
</blockquote>

===oceos_mutex_wait()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''mutex.h''''' 

'''Description''' 
This function makes the task wait until the specified mutex is available.

'''Prototype''' 
<syntaxhighlight lang="C">
/*
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Wait on mutex m_2
status = oceos_mutex_wait(m_2);

</syntaxhighlight>
</blockquote>

===oceos_mutex_signal()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''mutex.h''''' 

'''Description''' 
This function signals the specified mutex.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Signal mutex m_2
status = oceos_mutex_signal(m_2);

</syntaxhighlight>
</blockquote>

===oceos_mutex_get_value()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''mutex.h''''' 

'''Description''' 
This function returns the value of the specified mutex.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
U32_t value;
...
// Get value of mutex m_2
status = oceos_mutex_get_value(m_2, &value);

</syntaxhighlight>
</blockquote>

==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()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''rwmutex.h''''' 

'''Description''' 
This function ees a read/write mutex.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Create read/write mutex with ID rwm_2 and priority ceiling of 100
status = oceos_rwmutex_create(rwm_1, 100);

</syntaxhighlight>
</blockquote>

===oceos_rwmutex_read_wait()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Acquire read/write mutex rwm_1 for read
status = oceos_rwmutex_read_wait(rwm_1);
</syntaxhighlight>
</blockquote>

===oceos_rwmutex_write_wait()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Acquire read/write mutex rwm_1 for write
status = oceos_rwmutex_read_wait(rwm_1);
</syntaxhighlight>
</blockquote>

===oceos_rwmutex_signal()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Signal read/write mutex number rwm_4
status = oceos_rwmutex_signal(rwm_4);
</syntaxhighlight>
</blockquote>

===oceos_rwmutex_check_status()===
<blockquote style="border-left-style: none;">
'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status, rwm_status;
...
// Check the status of read/write mutex rwm_2
status = oceos_rwmutex_check_status(rwm_2, &rwm_status);
</syntaxhighlight>
</blockquote>

===oceos_rwmutex_reading_count()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''rwmutex.h''''' 

'''Description''' 
This function returns the current number of jobs holding a specified read/write mutex for read.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
*
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_rwmutex_write_reqs_count()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''header.h''''' 

'''Description''' 
This function returns the current number of write requests for the specified read/write mutex .

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
| 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_rwmutex_writes_pending_count()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''rwmutex.h''''' 

'''Description''' 
This function returns the current number of pending writes for the specified read/write mutex.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>

===oceos_rwmutex_holding()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''header.h''''' 

'''Description''' 
This function returns the read/write mutexes currently held by this instance of this task (job).

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
U64_t rwm_held;
...
// Which read/write mutexes does this job hold
status = oceos_rwmutex_holding(&rwm_held);

</syntaxhighlight>
</blockquote>

== Semaphores directives ==

===oceos_sem_create()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''semaphore.h''''' 

'''Description''' 
This function creates a semaphore.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_sem_signal()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''semaphore.h''''' 

'''Description''' 
This function signals a semaphore, increments its count and transfers pending jobs to the ready queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Signal s_audi semaphore (increment its count)
status = oceos_sem_signal(s_audi);
</syntaxhighlight>
</blockquote>

===oceos_sem_wait_continue()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''semaphore.h''''' 

'''Description''' 
This function decrements the available permits of a sempahore otherwise returns an unsuccessful status code.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Decrement available permits on semaphore s_1
status = oceos_sem_wait_continue(s_1);

</syntaxhighlight>
</blockquote>

===oceos_sem_wait_restart()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Decrement available permits on semaphore s_1 otherwise job is put on pending queue
status = oceos_sem_wait_restart(s_1);

</syntaxhighlight>
</blockquote>

===oceos_sem_wait_restart_timeout()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! Parameter || Description
|-
| sem_id || U32_t value of semaphore to be decremented
|-
| timeout | 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>

===oceos_sem_get_value()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''semaphore.h''''' 

'''Description''' 
This function returns the number of available permits for the specified semaphore.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status, permit_count;
...
// Get the available permits for semaphore s_1
status = oceos_sem_get_value(s_1, &permit_count);

</syntaxhighlight>
</blockquote>

===oceos_sem_penq_get_size()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''semaphore.h''''' 

'''Description''' 
This function returns the number of jobs on the specified semaphore pending queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status, job_count;
...
// Get the available permits for semaphore s_1
status = oceos_sem_penq_get_size(s_1, &job_count);

</syntaxhighlight>
</blockquote>

===oceos_sem_reset()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Reset semaphore s_1
status = oceos_sem_reset(s_1);
</syntaxhighlight>
</blockquote>

== Data Queues ==

===oceos_dataq_create()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''dataq.h''''' 

'''Description''' 
This function creates a data queue with the specified characteristics.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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));
</syntaxhighlight>
</blockquote>

===oceos_dataq_write()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''dataq.h''''' 

'''Description''' 
This function puts a non-null pointer on the specified data queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>

===oceos_dataq_read_continue()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''dataq.h''''' 

'''Description''' 
This function returns a pointer from the specified data queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
char *data_ptr;
...
// Read pointer from data queue s_2
status = oceos_dataq_read_continue(s_2, (void *)data_ptr);
</syntaxhighlight>
</blockquote>

===oceos_dataq_read_restart()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>

===oceos_dataq_read_restart_timeout()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>

===oceos_dataq_get_size()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''dataq.h''''' 

'''Description''' 
This function returns the number of items on the specified data queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status, d_size;
...
// Get the number of entries on data queue d_0
status = oceos_dataq_get_size(d_0, &d_size);
</syntaxhighlight>
</blockquote>

===oceos_dataq_penq_get_size()===
<blockquote style="border-left-style: none;">
'''Header File''' 
'''''dataq.h''''' 

'''Description''' 
This function returns number of jobs on the specified data queue pending job's queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>

===oceos_dataq_clear()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''dataq.h''''' 

'''Description''' 
This function clears the specified data queue including pending jobs for that queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Clear data queue d_1
status = oceos_dataq_penq_get_size(d_1);
</syntaxhighlight>
</blockquote>

== Timed Actions ==

===oceos_timed_output_add()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
| 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">

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

</syntaxhighlight>
</blockquote>

===oceos_timed_jobs_number()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''timed_action.h''''' 

'''Description''' 
This function returns the number of jobs on the timed actions queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, no_of_jobs;
...
// Get the number of jobs on the timed actions queue
status = oceos_timed_jobs_number(&no_of_jobs);

</syntaxhighlight>
</blockquote>

===oceos_timed_jobs_remove()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''timed_action.h''''' 

'''Description''' 
This function removes the specified timed action from the queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, job_id;
...
// Remove job_id from the timed actions queue
status = oceos_timed_jobs_remove(job_id);

</syntaxhighlight>
</blockquote>

===oceos_timed_jobs_reset()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''timed_action.h''''' 

'''Description''' 
This function removes all jobs from timed actions queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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);
</syntaxhighlight>

'''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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Remove all jobs from the timed actions queue
status = oceos_timed_jobs_reset(job_id);
</syntaxhighlight>
</blockquote>

===oceos_timed_output_remove()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''timed_action.h''''' 

'''Description''' 
This function removes the specified timed output action from timed actions queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
| 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''' 
<syntaxhighlight lang="C">
S32_t status;
U8_t action_index;
...
// Remove timed output with specified action_index
status = oceos_timed_output_remove(action_index);

</syntaxhighlight>
</blockquote>

===oceos_timed_output_reset()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''timed_action.h''''' 

'''Description''' 
This function removes all timed output actions from timed actions queue.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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);
</syntaxhighlight>

'''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.
{| class="wikitable"
|-
| 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''' 
<syntaxhighlight lang="C">
S32_t status;
...
// Remove all timed outputs from the timed actions queue
status = oceos_timed_output_reset();

</syntaxhighlight>
</blockquote>

== Logging directives ==

===Introduction===
<blockquote style="border-left-style: none;">

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''' 
<syntaxhighlight lang="C">
/*****************************************************************************
* 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)));

</syntaxhighlight>

===oceos_log_add_entry()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! Parameter || Description
|-
| enum LOG_ENTRY_TYPE || Log entry type (see previous section for a list)
|-
| info | 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_log_get_indexed_entry()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_log_remove_entry()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
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);

</syntaxhighlight>
</blockquote>

===oceos_log_reset()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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);
</syntaxhighlight>

'''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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status;
...

// Clear down the system log
status = oceos_log_reset();

</syntaxhighlight>
</blockquote>

===oceos_log_get_size()===
<blockquote style="border-left-style: none;">

'''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''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, size;
...

// Clear down the system log
status = oceos_log_get_size(&size);

</syntaxhighlight>
</blockquote>

===System State Variable and System State Mask===
<blockquote style="border-left-style: none;">

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''' 
<syntaxhighlight lang="C">

#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

</syntaxhighlight>

===oceos_system_state_get()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''system_log.h''''' 

'''Description''' 
This function returns of the system state variable.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, state;
...

// Get the system state
status = oceos_system_state_get(&state);

</syntaxhighlight>
</blockquote>

===oceos_system_state_set()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''system_log.h''''' 

'''Description''' 
This function sets system state variable.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! Error bit !! Description
|-
| ERR_SYS_FIXED_CORRUPT || System Fixed area corrupt
|-
| ERR_SYS_LOG_CORRUPT || LOG dynamic pointer is null
|}

'''Example Usage''' 
<syntaxhighlight lang="C">
S32_t status, new_state;
...

// Set new system state
status = oceos_system_state_set(new_state);

</syntaxhighlight>
</blockquote>

===oceos_system_state_copy_get()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''system_log.h''''' 

'''Description''' 
This function returns the value of the system state copy variable.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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''' 
<syntaxhighlight lang="C">
S32_t status, copy_state;
...

// Get the system state copy
status = oceos_system_state_copy_get(&copy_state);

</syntaxhighlight>
</blockquote>

===oceos_system_state_copy_set()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''system_log.h''''' 

'''Description''' 
This function loads a value to tha system state copy variable.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>

'''Parameters''' 
{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! Error bit !! Description
|-
| ERR_SYS_FIXED_CORRUPT || System Fixed area corrupt
|-
| ERR_SYS_LOG_CORRUPT || LOG dynamic pointer is null
|}

'''Example Usage''' 
<syntaxhighlight lang="C">
S32_t status, new_state;
...

// Set new system state copy
status = oceos_system_state_copy_set(new_state);

</syntaxhighlight>
</blockquote>

== Timing directives ==

===Introduction===
<blockquote style="border-left-style: none;">

'''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()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''oceos_timer.h''''' 

'''Description''' 
This function returns the current system time as a 64-bit number.

'''Prototype''' 
<syntaxhighlight lang="C">
**
* Get the current system time (64-bit)
*
* @return U64_t
*/
U64_t oceos_time_sys_get64(void);
</syntaxhighlight>

'''Parameters''' 

There are no parameters to this function.

'''Returns''' 
This function returns an S64_t with the current system time.

'''Example Usage''' 
<syntaxhighlight lang="C">
S64_t now;
...
// Get the time
now = oceos_time_sys_get64();
</syntaxhighlight>
</blockquote>

===oceos_time_sys_get32()===
<blockquote style="border-left-style: none;">

'''Header File''' 
'''''oceos_timer.h''''' 

'''Description''' 
This function returns the low 32 bits of the system time.

'''Prototype''' 
<syntaxhighlight lang="C">
/**
* Get the current system time (low 32 bits of 64 bit value)
*
* @return U32_t
*/
U32_t oceos_time_sys_get32(void);
</syntaxhighlight>

'''Parameters''' 
There are no parameters to this function.

'''Returns''' 
This function returns an S32_t with the current system time.

'''Example Usage''' 
<syntaxhighlight lang="C">
S32_t now;
...
// Get the time
now = oceos_time_sys_get32();
</syntaxhighlight>
</blockquote>

[[Category:backup]]