Task Management API


Data Structures
struct	mars_task_id
	MARS task id structure. More...
struct	mars_task_args
	MARS task argument structure. More...
Files
file	task_types.h
	[host/MPU] MARS Task Types
file	task.h
	[host] MARS Task API
file	task.h
	[MPU] MARS Task API
Defines
#define	MARS_TASK_BASE_ADDR 0x4000
	Base address of task.
#define	MARS_TASK_CONTEXT_SAVE_SIZE_MAX 0x3c000
	Max size of context save area.
#define	MARS_TASK_NAME_LEN_MAX 21
	Max length of task name.
Functions
int	mars_task_create (struct mars_context mars, struct mars_task_id id, const char name, const void elf_image, uint32_t context_save_size)
	[host] Creates a MARS task.
int	mars_task_destroy (struct mars_task_id *id)
	[host] Destroys a MARS task.
int	mars_task_schedule (const struct mars_task_id id, const struct mars_task_args args, uint8_t priority)
	[host/MPU] Schedules a MARS task for execution.
int	mars_task_unschedule (const struct mars_task_id *id, int32_t exit_code)
	[host/MPU] Unschedules a MARS task from being executed.
int	mars_task_wait (const struct mars_task_id id, int32_t exit_code)
	[host/MPU] Waits for task completion. (Task Switch Call)
int	mars_task_try_wait (const struct mars_task_id id, int32_t exit_code)
	[host/MPU] Waits for a task completion.
uint32_t	mars_task_get_ticks (void)
	[host/MPU] Gets tick counter value.
int	mars_task_main (const struct mars_task_args *args)
	[MPU] Entry point for task.
void	mars_task_exit (int32_t exit_code)
	[MPU] Exits and terminates task.
int	mars_task_yield (void)
	[MPU] Yields caller task so other workloads can run. (Task Switch Call)
int	mars_task_call_host (uint64_t callback_ea, const struct mars_callback_args in, struct mars_callback_args out)
	[MPU] Calls the specified host callback. (Task Switch Call)
uint16_t	mars_task_get_kernel_id (void)
	[MPU] Gets id of kernel that the task is being executed on.
struct mars_task_id *	mars_task_get_id (void)
	[MPU] Gets id of caller task.
const char *	mars_task_get_name (void)
	[MPU] Gets name of caller task.

Detailed Description

The MARS task is one type of MARS workload model. The MARS task is a single execution of an MPU program that is scheduled to be run by the MARS kernel.

Tasks can be used to run a small MPU program many times. However the primary usage of the task model is for large grained programs that take long amounts of time to process. Since tasks may occupy the MPU for a long time and prevent other workloads to be executed on that MPU, it has the ability to yield the MPU to other workloads.

The MARS task synchronization API also provides various methods that when used to wait for certain events, allows it to enter a wait state. When tasks have yielded or are waiting, the task state is saved into host storage and the MPU is freed up to process other available workloads.

Function Documentation

int mars_task_create	(	struct mars_context *	mars,
		struct mars_task_id *	id,
		const char *	name,
		const void *	elf_image,
		uint32_t	context_save_size
	)

[host] Creates a MARS task.

This function creates a single task and adds it the MARS context's workload queue. Upon success, a valid task id will be returned. You must call mars_task_schedule in order for it to be scheduled for execution by the kernel. The task is in the finished state upon creation and may be destroyed by mars_task_destroy without ever being scheduled for execution.

Key Parameters:

name

The name is optional, but if specified to other than NULL its length must not exceed MARS_TASK_NAME_LEN_MAX.
An empty string will be treated the same as passing NULL, and will return NULL if mars_task_get_name is called on the task.
The name does need to be kept allocated after this function returns.

elf_image

The address of MPU program elf image in host storage that will be run by this task.
The elf image must remain allocated until the task is destroyed.

context_save_size

If 0 is specified, then no context save area will be allocated for the task and therefore the task must be a run-complete task.
A run-complete task will run and occupy an MPU until it has completed running and exits.
A run-complete task cannot context switch, and therefore cannot call functions that will enter that task into a wait state.
If MARS_TASK_CONTEXT_SAVE_SIZE_MAX is specified, the maximum size context save area required will be allocated and all of the MPU storage area used by the task will be saved and restored.
Advanced users can specify a size between 0 and MARS_TASK_CONTEXT_SAVE_SIZE_MAX in order to minimize memory usage for the context save area.
The size specified must be large enough to hold all of the task program's text, data, heap, stack and non-volatile registers 80-127.

Parameters:

`[in]`	mars	- pointer to MARS context
`[out]`	id	- address of pointer to task id instance
`[in]`	name	- name of task
`[in]`	elf_image	- address of MPU program elf image
`[in]`	context_save_size	- [ 0 ~ MARS_TASK_CONTEXT_SAVE_SIZE_MAX ]

Returns:: MARS_SUCCESS - successfully created MARS task
MARS_ERROR_NULL - null pointer specified
MARS_ERROR_PARAMS - bad params specified
MARS_ERROR_MEMORY - not enough memory
MARS_ERROR_LIMIT - task queue is currently full

int mars_task_destroy ( struct mars_task_id * id )

[host] Destroys a MARS task.

This function destroys a task created by mars_task_create. The task will only be destroyed if the task is in the finished state. Once this function returns successfully and the task is destroyed, the task id is no longer valid. To guarantee the task has finished before calling this function, you should wait for task completion by calling mars_task_wait or mars_task_try_wait.

Parameters:

[in] id - pointer to task id instance

Returns:: MARS_SUCCESS - successfully destroyed MARS task
MARS_ERROR_NULL - null pointer specified
MARS_ERROR_PARAMS - bad task id specified
MARS_ERROR_STATE - task is in an invalid state

int mars_task_schedule	(	const struct mars_task_id *	id,
		const struct mars_task_args *	args,
		uint8_t	priority
	)

[host/MPU] Schedules a MARS task for execution.

This function schedules the task specified for execution. The actual time of execution is determined by the scheduler. Once the task is scheduled for execution by this function, it may not be scheduled for execution until previous execution has finished. You can wait for task completion by calling mars_task_wait or mars_task_try_wait.

You can call this function with a valid task id returned by mars_task_create as many times as you want after each scheduled execution has completed. The task id is valid until the task is destroyed by mars_task_destroy.

Key Parameters:

args

The task args (mars_task_args) are optional, and only need to be passed in if the task executable expects it.
If NULL is specified the task args passed into the task executable's main function will not be initialized.
The args does need to be kept allocated after this function returns.

priority

This is the priority of the task between 0 to 255, 0 being the lowest priority and 255 being the highest priority.
Tasks with higher priority will be prioritized during scheduling if both tasks are ready to run at the time of scheduling.

Parameters:

`[in]`	id	- pointer to task id to schedule
`[in]`	args	- pointer to task args to pass into task main
`[in]`	priority	- priority of scheduling for the task

Returns:: MARS_SUCCESS - successfully scheduled MARS task for execution
MARS_ERROR_NULL - null pointer specified
MARS_ERROR_PARAMS - bad task id specified
MARS_ERROR_STATE - task is in an invalid state

int mars_task_unschedule	(	const struct mars_task_id *	id,
		int32_t	exit_code
	)

[host/MPU] Unschedules a MARS task from being executed.

This function unschedules a previously scheduled task.

When a task is unscheduled, it will behave as if the task has completed execution. The user is responsible for specifying a unique exit code when unscheduling tasks to handle the condition accordingly.

If a scheduled task is unscheduled before execution, the workload will not be executed until a subsequent scheduling request is made.

If the task is currently in a waiting state, calling unschedule will finish the workload and will not be resumed from the waiting state.

If the task is currently in a running state, calling unschedule will immediately put the task into a finished state. However, execution of the task will only be suspended when the task yields, waits, or exits.

Note:: Trying to unschedule a task that has not yet been scheduled, or has already finished a previously scheduled execution will return an error.

Key Parameters:

exit_code

The value passed into here can be obtained when calling mars_task_wait or mars_task_try_wait.

Parameters:

`[in]`	id	- pointer to task id to abort
`[out]`	exit_code	- value to be returned to the task wait call

Returns:: MARS_SUCCESS - successfully scheduled MARS task for execution
MARS_ERROR_NULL - null pointer specified
MARS_ERROR_PARAMS - bad task id specified
MARS_ERROR_STATE - task is in an invalid state

int mars_task_wait	(	const struct mars_task_id *	id,
		int32_t *	exit_code
	)

[host/MPU] Waits for task completion. (Task Switch Call)

Note:: The [MPU] call may result in a task switch and put this task into the waiting state. Understand all the limitations before calling a Task Switch Call (See 7.5 Task Switching).

This function will block until the scheduled task specified is finished.

Any number of host threads or tasks can wait for a specific task to complete execution as long as it holds the task's id. However, the task being waited on should not be re-scheduled until all wait calls for the task have returned. Otherwise it is not guaranteed that all wait calls will return after the completion of the initial schedule call.

Key Parameters:

exit_code

Pass in a pointer to store the task exit code.
If NULL is specified, no exit code can be obtained when the task completes and returns.

Note:: This function is a scheduling call and may cause a task switch and put the caller task into a waiting state.

Parameters:

`[in]`	id	- pointer to task id to wait for
`[out]`	exit_code	- pointer to variable to store task exit code

Returns:: MARS_SUCCESS - task execution finished
MARS_ERROR_NULL - null pointer specified
MARS_ERROR_PARAMS - bad task id specified
MARS_ERROR_STATE - task is in an invalid state
MARS_ERROR_FORMAT - no context save area specified

int mars_task_try_wait	(	const struct mars_task_id *	id,
		int32_t *	exit_code
	)

[host/MPU] Waits for a task completion.

This function will check whether the scheduled task specified is finished or not and return immediately without blocking.

Key Parameters:

exit_code

Pass in a pointer to store the task exit code.
If NULL is specified, no exit code can be obtained when the task completes and returns.

Parameters:

`[in]`	id	- pointer to task id to wait for
`[out]`	exit_code	- pointer to variable to store task exit code

Returns:: MARS_SUCCESS - task execution finished
MARS_ERROR_NULL - null pointer specified
MARS_ERROR_PARAMS - bad task id specified
MARS_ERROR_STATE - task is in an invalid state
MARS_ERROR_BUSY - task has not yet finished execution

uint32_t mars_task_get_ticks ( void )

[host/MPU] Gets tick counter value.

Note:: Counter's frequency depends on runtime environment.

Returns:: uint32_t - 32-bit tick counter value

int mars_task_main ( const struct mars_task_args * args )

[MPU] Entry point for task.

This function is the main entry point for the task program. All task programs will need to have a definition of this function. The arguments passed into this function are specified during task scheduling through the call to mars_task_schedule.

Note:: If NULL was specified for args when calling mars_task_schedule, the contents of args are undefined.

Parameters:

[in] args - pointer to task args structure in MPU storage

Returns:: user specified

void mars_task_exit ( int32_t exit_code )

[MPU] Exits and terminates task.

This function causes the task to exit and terminate execution. Calling this function will cause the task to enter the finished state, and will no longer be scheduled to run. This function does not need to be called when returning from mars_task_main since it is called automatically.

Note:: This function is a scheduling call and will put the caller task into a finished state.

Key Parameters:

exit_code

The value passed into here can be obtained when calling mars_task_wait or mars_task_try_wait.

Parameters:

[out] exit_code - value to be returned to the task wait call

int mars_task_yield ( void )

[MPU] Yields caller task so other workloads can run. (Task Switch Call)

Note:: The [MPU] call may result in a task switch and put this task into the waiting state. Understand all the limitations before calling a Task Switch Call (See 7.5 Task Switching).

This function causes the task to yield and allow other workloads to be scheduled to run if available. The task's context state is saved and the kernel will reschedule the next available workload. If there are no other workloads to be scheduled, the task that called to yield will be rescheduled for resumed execution.

Note:: This function is a scheduling call and may cause a task switch and put the caller task into a ready state.

Returns:: MARS_SUCCESS - successfully yielded task
MARS_ERROR_FORMAT - no context save area specified

int mars_task_call_host	(	uint64_t	callback_ea,
		const struct mars_callback_args *	in,
		struct mars_callback_args *	out
	)

[MPU] Calls the specified host callback. (Task Switch Call)

Note:: The [MPU] call may result in a task switch and put this task into the waiting state. Understand all the limitations before calling a Task Switch Call (See 7.5 Task Switching).

This function will block until the requested host callback function returns.

Key Parameters:

callback_ea

Pass in the EA of the host callback function you want called. This function should be of type mars_callback.
If an invalid EA is specified, the resulting behavior is undetermined.

in

Pass in a pointer to an initialized callback argument structure instance.
If NULL is specified, a pointer to an uninitialized callback argument structure will be passed into the host callback function.

out

Pass in a pointer to a callback argument structure instance, which can be initialized by the host callback function.
If NULL is specified, the output argument structure initialized by the host callback function will not be returned to the caller.

Parameters:

`[in]`	callback_ea	- ea of host callback of type mars_callback
`[in]`	in	- pointer to args, passed into to host callback
`[out]`	out	- pointer to args, initialized by host callback

Returns:: MARS_SUCCESS - host callback successful
MARS_ERROR_LIMIT - host callback queue is full
MARS_ERROR_FORMAT - no context save area specified

uint16_t mars_task_get_kernel_id ( void )

[MPU] Gets id of kernel that the task is being executed on.

Note:: The kernel id refers to an index of the MPU it is being executed on and will range from 0 to (# of MPUs initiialized for MARS context) - 1.

Returns:: uint16_t - id of MARS kernel

struct mars_task_id* mars_task_get_id ( void ) [read]

[MPU] Gets id of caller task.

Returns:: const struct mars_task_id * - pointer to task id in MPU storage

const char* mars_task_get_name ( void )

[MPU] Gets name of caller task.

Returns:: const char * - pointer to task name in MPU storage

Task Management API

Data Structures

Files

Defines

Functions

Detailed Description

Function Documentation