OCEOS/oceos kernel/task
OCEOS Task
Introduction
In OCEOS all tasks are defined before scheduling begins and each task assigned a fixed priority, a pre-emption threshold, a current jobs limit, a maximum start to completion time, and an expected minimum inter start request time.
A task’s pre-emption threshold limits the tasks that can pre-empt it to those with higher priority than this threshold. Tasks with short run times can use this to avoid context switch overheads.
Each task has two main states, enabled or disabled. OCEOS provides system calls to change task state. The state is usually enabled when the task is created, but can be initially disabled.
A disabled task will not be executed, and any attempt to start it will be logged and the system state variable updated.
A request to start an enabled task creates an execution instance of the task, a ‘job’. A count is kept for each task of the number of times it has been started, i.e. total number of jobs created.
Multiple jobs of the same task can be in existence simultaneously. A limit for the maximum number of these current jobs is set when a task is created, the ‘current jobs limit’.
Each task has a current jobs count. This increments each time a task is started and decrements on job completion unless completion creates a further job from this task.
A further execution instance of a task is not created if the current jobs count has reached the current jobs limit. Such job creation failures are logged and the system state updated.
For each task a record is kept of the shortest time between attempts to create a new job, and a record of the maximum time between these attempts.
For each task a record is kept also of the maximum time a job was waiting before starting, the minimum execution time, the maximum execution time, the maximum time from job creation to completion, and the maximum number of job pre-emptions. The system state variable is updated if necessary.
Task chaining is supported. A job can create a new job and pass this to the scheduler or place it on the timed actions queue.
Tasks provide a start address for a termination routine for use if task execution must be abandoned.
Note
All Tasks must be created before oceos_init_finish() is called.
API Functions
| Directive | Description | main | task | IRQ handler |
|---|---|---|---|---|
| oceos_task_create() | Create Task | * | ||
| oceos_task_start() | Start Task | * | * | |
| oceos_task_timed_start() | Schedule a task to start execution at a given system time | * | * | |
| oceos_task_disable() | Disable Task | * | * | |
| oceos_task_enable() | Enable Task | * | * | |
| oceos_task_self() | Returns the task ID of the currently executing task | * | * | |
| oceos_task_get_priority() | Get priority of a task | * | * | |
| oceos_task_get_status() | Get status of a task | * | * | |
| oceos_task_kill() | Directive to terminate current task | * | * | |
| oceos_task_get_info() | Get task information | * | * |
oceos_task_create()
Header File
tasks.h
Description
Create a task. Can only be use before OCEOS starts. Stores the task information in the OCEOS fixed data area. This directive populates the data structures for a task. It should be called after oceos_init() and before oceos_init_finish().
It must be called for each task otherwise oceos_start() will return an error.Prototype
enum DIRECTIVE_STATUS oceos_task_create( unsigned int taskID, // unique, 0 to TASKS_MAX_ID U32_t priority, // TASK_MAX_PRIORITY to TASK_MIN_PRIORITY U32_t threshold, // TASK_MAX_PRIORITY to priority U32_t jobs_max, // 1 to JOBS_MAX BOOLE_t FP_used, // whether uses floating point hardware BOOLE_t initially_enabled, // whether task enabled initially void (void *) start_function,// task start address void (void *) end_function, // start of task end function U32_t time_deadline, // maximum time to complete (ignore if 0) U32_t time_mininterstart // minimum time between start requests );Parameters
Parameter Description taskID Unique task ID from 0 to TASKS_MAX_ID priority TASK_MAX_PRIORITY to TASK_MIN_PRIORITY threshold TASK_MAX_PRIORITY to priority jobs_max Number of 1 to JOBS_MAX FP_used whether uses floating point hardware initially_enabled whether task enabled initially start_function task start address end_function start of task end function time_deadline maximum time to complete (ignore if 0) time_mininterstart minimum time between start requests Returns
This function returns enum DIRECTIVE_STATUS.
enum DIRECTIVE_STATUS Description INCORRECT_STATE Init Meta Pointer is NULL or Pointer to Task fixed data is NULL
TOO_MANY Exceeds number of MAX Tasks or Exceeds number of MAX Jobs
INTERNAL_ERROR System Meta pointer is NULL or System Meta pointer start sentinel is corrupt
INVALID_ID Failed on task ID check INVALID_NAME Task ID is already in use INVALID_PRIORITY Failed on task priority check INVALID_NUMBER Failed on task threshold check INVALID_SIZE Failed on task max job check SUCCESSFUL All is OK Example Usage
enum TASK_NAME{ t_tom, // will have task ID 0 t_dick, // will have task ID 1 }; extern int task_tom_start(void* data); ... enum DIRECTIVE_STATUS status; // Task 0: priority 10, max jobs 1, enabled (consumer task) status = oceos_task_create(t_tom, // unique, 0 to TASKS_MAX_ID 10, // TASK_MAX_PRIORITY to TASK_MIN_PRIORITY 10, // TASK_MAX_PRIORITY to priority 1, // 1 to JOBS_MAX 0, // whether uses floating point hardware TASK_ENABLED, // whether task enabled initially task_tom_start, // task start address NULL, // start of task end function 0, // maximum time to complete (ignore if 0) 0 // minimum time between start requests );
oceos_task_start()
Header File
tasks.h
Description
Starting a task involves three main stages:
- Setting up a job
- Finding a free job entry
- Setting up this entry
- Placing the job on ready queue
- Doing a context switch
This function should only be called after OCEOS is initialized and the dynamic task and job structures are set up.
When used from an interrupt handler, the context switch is only done after all nested interrupts have unwound.
Note
FOR SPARC ONLY : Tasks can be started in IRQ routines but CANNOT be started in TRAP handlers.
Prototype
enum DIRECTIVE_STATUS oceos_task_start( const unsigned int taskID, // task ID, must be in range 0 to 254 void * const ptr // pointer to data );Parameters
Parameter Description taskID Task ID must be in range 0 to 254 ptr Pointer to task data Returns
This function returns enum DIRECTIVE_STATUS.
enum DIRECTIVE_STATUS Description NOT_CONFIGURED System Meta pointer is NULL or Fixed data start sentinel is corrupt INCORRECT_STATE One of the System Meta pointers is NULL INVALID_ID Failed on task ID check INCORRECT_STATE Tried to start disabled task TOO_MANY Max number of jobs(requests to start) for task is exceeded FAILED_TO_PUT_JOB_ON_REDYQ Failed to put job for task on ready Q SUCCESSFUL All is OK Example Usage
enum TASK_NAME{ t_tom, // will have task ID 0 t_dick, // will have task ID 1 }; ... enum DIRECTIVE_STATUS status; status = oceos_task_start(t_tom, NULL); if (SUCCESS != status) { // Deal with the problem return status; }
oceos_task_timed_start()
Header File
tasks.h
Description
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.
return_job_id can be stored and used later to cancel if need.
Times are in microseconds.
This function should only be used after oceos_start() is called.Note
This directive can only be called if timed actions (software timers) are initialized. Please see HERE.
Prototype
enum DIRECTIVE_STATUS oceos_task_timed_start( const unsigned int taskID,// Task ID void * const ptr, // data to be used by task U64_t start_time, // system time at which task should start U32_t before, // offset before time in which start o.k. U32_t after, // offset after time in which start o.k. U32_t *return_job_id // in case need to cancel later );Parameters
Parameter Description taskID Task ID must be in range 0 to 254 ptr Pointer to data start_time System time at which job should start before Forward tolerance for time after Backward tolerance for time return_job_id Return job_id to the user, to remove this job from timed action if needed Returns
This function returns enum DIRECTIVE_STATUS.
enum DIRECTIVE_STATUS Description NOT_CONFIGURED System Meta pointer is NULL or Fixed data start sentinel is corrupt
INCORRECT_STATE One of the System Meta pointers is NULL or System time is not initialized or Tried to start disabled task
INVALID_ID Failed on task ID check UNSATISFIED System time is greater when start time plus after time TOO_MANY Max number of jobs(requests to start) for task is exceeded INTERNAL_ERROR Failed to put job for task on ready Q SUCCESSFUL All is OK Example Usage
enum TASK_NAME{ t_tom, // will have task ID 0 t_dick, // will have task ID 1 }; ... enum DIRECTIVE_STATUS status; U32_t return_job_id = 0; U64_t time = oceos_time_sys_get64(); status = oceos_task_timed_start(t_tom, // Task ID must be in range 0 to 254 NULL, // Pointer to data time + 1000000, // System time at which job should start 1000, // Forward tolerance for time 1000, // Backward tolerance for time &return_job_id // Return job_id to the user, to remove this job from timed action if needed ); if (SUCCESS != status) { // Handle ERROR return status; }
oceos_task_disable()
Header File
tasks.h
Description
Disable a task and remove any current pending jobs on ready queue. A disabled task's jobs will not be put into execution nor put on ready queue.Note
If execution of a task has already commenced, disabling the task will not prevent it from completing.
Prototype
enum DIRECTIVE_STATUS oceos_task_disable( const unsigned int taskID // task ID, must be in range 0 to 254 );Parameters
Parameter Description taskID Task ID must be in range 0 to 254 Returns
This function returns enum DIRECTIVE_STATUS.
enum DIRECTIVE_STATUS Description NOT_CONFIGURED System Meta pointer is NULL or Fixed data start sentinel is corrupt
INTERNAL_ERROR One of the System Meta pointers is NULL or Dynamic Meta pointer is NULL
INVALID_ID Failed on task ID check ALREADY_SUSPENDED Task is already disabled SUCCESSFUL All is OK Example Usage
enum TASK_NAME{ t_tom, // will have task ID 0 t_dick, // will have task ID 1 }; ... enum DIRECTIVE_STATUS status; status = oceos_task_disable(t_tom); if (SUCCESS != status) { // Deal with the problem return status; }
oceos_task_enable()
Header File
tasks.h
Description
Prototype
Parameters
Parameter Description Returns
This function returns enum DIRECTIVE_STATUS.
enum DIRECTIVE_STATUS Description INCORRECT_STATE If system Meta pointer is NULL or Init pointer is NULL or Start up phase check fail or Fixed data checksum failed (check log)
INVALID_NAME If Start Sentinel for fixed area is corrupt or Start Sentinel for dynamic area is corrupt
INVALID_NUMBER If Configuration and actual parameters do not match (In configuration file was defined 5 tasks, but created less)
SUCCESSFUL If All OK Example Usage
oceos_task_self()
Header File
tasks.h
Description
Prototype
Parameters
Parameter Description Returns
This function returns enum DIRECTIVE_STATUS.
enum DIRECTIVE_STATUS Description INCORRECT_STATE If system Meta pointer is NULL or Init pointer is NULL or Start up phase check fail or Fixed data checksum failed (check log)
INVALID_NAME If Start Sentinel for fixed area is corrupt or Start Sentinel for dynamic area is corrupt
INVALID_NUMBER If Configuration and actual parameters do not match (In configuration file was defined 5 tasks, but created less)
SUCCESSFUL If All OK Example Usage
oceos_task_get_priority()
Header File
tasks.h
Description
Prototype
Parameters
Parameter Description Returns
This function returns enum DIRECTIVE_STATUS.
enum DIRECTIVE_STATUS Description INCORRECT_STATE If system Meta pointer is NULL or Init pointer is NULL or Start up phase check fail or Fixed data checksum failed (check log)
INVALID_NAME If Start Sentinel for fixed area is corrupt or Start Sentinel for dynamic area is corrupt
INVALID_NUMBER If Configuration and actual parameters do not match (In configuration file was defined 5 tasks, but created less)
SUCCESSFUL If All OK Example Usage
oceos_task_get_status()
Header File
tasks.h
Description
Prototype
Parameters
Parameter Description Returns
This function returns enum DIRECTIVE_STATUS.
enum DIRECTIVE_STATUS Description INCORRECT_STATE If system Meta pointer is NULL or Init pointer is NULL or Start up phase check fail or Fixed data checksum failed (check log)
INVALID_NAME If Start Sentinel for fixed area is corrupt or Start Sentinel for dynamic area is corrupt
INVALID_NUMBER If Configuration and actual parameters do not match (In configuration file was defined 5 tasks, but created less)
SUCCESSFUL If All OK Example Usage
oceos_task_kill()
Header File
tasks.h
Description
Prototype
Parameters
Parameter Description Returns
This function returns enum DIRECTIVE_STATUS.
enum DIRECTIVE_STATUS Description INCORRECT_STATE If system Meta pointer is NULL or Init pointer is NULL or Start up phase check fail or Fixed data checksum failed (check log)
INVALID_NAME If Start Sentinel for fixed area is corrupt or Start Sentinel for dynamic area is corrupt
INVALID_NUMBER If Configuration and actual parameters do not match (In configuration file was defined 5 tasks, but created less)
SUCCESSFUL If All OK Example Usage
oceos_task_get_info()
Header File
tasks.h
Description
Prototype
Parameters
Parameter Description Returns
This function returns enum DIRECTIVE_STATUS.
enum DIRECTIVE_STATUS Description INCORRECT_STATE If system Meta pointer is NULL or Init pointer is NULL or Start up phase check fail or Fixed data checksum failed (check log)
INVALID_NAME If Start Sentinel for fixed area is corrupt or Start Sentinel for dynamic area is corrupt
INVALID_NUMBER If Configuration and actual parameters do not match (In configuration file was defined 5 tasks, but created less)
SUCCESSFUL If All OK Example Usage