MARS: Task Management API

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_initialize	(	struct mars_context *	mars,
		struct mars_task_id *	id,
		struct mars_task_params *	params
	)

[host] Initializes a MARS task.

This function initializes a single task and adds it the MARS context's workload queue. Upon success, the specified id structure params will hold the initilized task's id information. 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 finalized by mars_task_finalize without ever being scheduled for execution.

When initializing a MARS task, you must specify its parameters through the mars_task_params structure:

name: The name is optional, but if specified to other than NULL its length must not exceed MARS_TASK_NAME_LEN_MAX.
elf_image: The address of MPU program elf image in host storage that will be to be run by this task.
context_save_size: The size of context save area allocated and used during the time a task enters into the wait state. 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 enter the wait state, and therefore cannot call functions that will enter that task into a wait state. Currently either 0 or MARS_TASK_CONTEXT_SAVE_SIZE_MAX must be specified.

Parameters:

`[in]`	mars	- pointer to initialized MARS context
`[out]`	id	- pointer to task id to be initialized
`[in]`	params	- pointer to task params of this task

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

int mars_task_finalize ( struct mars_task_id * id )

[host] Finalizes a MARS task.

This function finalizes a task initialized by mars_task_initialize. The task will only be finalized if the task is in the finished state. Once this function returns successfully and the task is finalized, the task id should no longer be used. If you want to make sure the task has finished before calling this function, you can wait for task completion by calling mars_task_wait or mars_task_try_wait.

Parameters:

[in] id - pointer to task id to finalize

Returns:: MARS_SUCCESS - successfully finalized 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	(	struct mars_task_id *	id,
		struct mars_task_args *	args,
		uint8_t	priority
	)

[host] 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.

args: The task args (mars_task_args) are optional, and only need to be passed in if the task executable expects it. If you specify NULL the task args passed into the task executable's main function will not be initialized.
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:

`[out]`	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_wait ( struct mars_task_id * id )

[host] Waits for task completion. (Blocking)

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

Parameters:

[in] id - pointer to task id to wait for

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

int mars_task_try_wait ( struct mars_task_id * id )

[host] Waits for a task completion. (Non-Blocking)

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

Parameters:

[in] id - pointer to task id to wait for

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

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 initialization through the call to mars_task_initialize.

Parameters:

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

Returns:: user specified

void mars_task_exit ( void )

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

int mars_task_yield ( void )

[MPU] Yields caller task so other workloads can run.

This function causes the task to yield and allow other tasks to be scheduled to run if available. If other tasks are available to be scheduled to run then this task enters the waiting state until the next time it is scheduled to run. If there are no other tasks available to be scheduled at the time of this function call, then this function has no effect and will return immediately.

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

uint32_t mars_task_get_kernel_id ( void )

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

Returns:: id of MARS kernel [0 to number of MPUS used by MARS context]

struct mars_task_id* mars_task_get_id ( void ) [read]

[MPU] Gets id of caller task.

Returns:: pointer to task id in MPU storage

const char* mars_task_get_name ( void )

[MPU] Gets name of caller task.

Returns:: pointer to task name in MPU storage

Variable Documentation

struct mars_task_args MARS_TASK_ARGS_ALIGN

MARS task argument structure.

This structure is initialized by the user and within the mars_task_params structure which is passed into mars_task_initialize for MARS task initialization.

This argument structure is directly passed into the MARS task's mars_task_main function at task execution.

struct mars_task_id MARS_TASK_ID_ALIGN

MARS task id structure.

This structure is initialized during MARS task initialization and returned when calling mars_task_initialize.

An instance of this structure must be kept until the task is finalized by calling mars_task_finalize.


Files
file	mars_task_types.h
	MARS Task Types.
file	mars_task.h
	[host] MARS Task API
file	mars_task.h
	[MPU] MARS Task API
Data Structures
struct	mars_task_args
	MARS task argument structure. More...
struct	mars_task_id
	MARS task id structure. More...
struct	mars_task_params
	MARS task params structure. More...
Defines
#define	MARS_TASK_ARGS_SIZE 32
	Arguments structure size.
#define	MARS_TASK_ARGS_ALIGN 16
	Arguments structure alignment.
#define	MARS_TASK_ID_SIZE 32
	ID structure alignment.
#define	MARS_TASK_ID_ALIGN 16
	ID structure alignment.
#define	MARS_TASK_CONTEXT_SIZE 112
	Context structure size.
#define	MARS_TASK_CONTEXT_ALIGN 16
	Context structure alignment.
#define	MARS_TASK_CONTEXT_SAVE_ALIGN 128
	Context save area alignment.
#define	MARS_TASK_CONTEXT_SAVE_SIZE_MAX 0x30000
	Max context save area size (LS size - task LS addr).
#define	MARS_TASK_NAME_LEN_MAX 22
	Max length of task name.
Functions
int	mars_task_initialize (struct mars_context mars, struct mars_task_id id, struct mars_task_params *params)
	[host] Initializes a MARS task.
int	mars_task_finalize (struct mars_task_id *id)
	[host] Finalizes a MARS task.
int	mars_task_schedule (struct mars_task_id id, struct mars_task_args args, uint8_t priority)
	[host] Schedules a MARS task for execution.
int	mars_task_wait (struct mars_task_id *id)
	[host] Waits for task completion. (Blocking)
int	mars_task_try_wait (struct mars_task_id *id)
	[host] Waits for a task completion. (Non-Blocking)
int	mars_task_main (const struct mars_task_args *args)
	[MPU] Entry point for task.
void	mars_task_exit (void)
	[MPU] Exits and terminates task.
int	mars_task_yield (void)
	[MPU] Yields caller task so other workloads can run.
uint32_t	mars_task_get_kernel_id (void)
	[MPU] Gets id of kernel that task is currently being executed on.
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.
Variables
mars_task_args	MARS_TASK_ARGS_ALIGN
	MARS task argument structure.
mars_task_id	MARS_TASK_ID_ALIGN
	MARS task id structure.

Task Management API

Files

Data Structures

Defines

Functions

Variables

Detailed Description

Function Documentation

Variable Documentation