Task Management API

Files
file	task_types.h
	MARS Task Types.
file	task.h
	[host] MARS Task API
file	task.h
	[MPU] MARS Task API
Data Structures
struct	mars_task_id
	MARS task id structure. More...
struct	mars_task_args
	MARS task argument structure. More...
struct	mars_task_context_save_unit
	MARS task context save unit structure. More...
Defines
#define	MARS_TASK_BASE_ADDR   0x10000
	Base address of task elf.
#define	MARS_TASK_CONTEXT_SAVE_SIZE_MAX   0x30000
	Max size of context save area.
#define	MARS_TASK_CONTEXT_SAVE_UNIT_MAX   16
	Max number of context save units.
#define	MARS_TASK_CONTEXT_SAVE_ALL   mars_task_context_save_all
	Parameter for full context switch.
#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, const struct mars_task_context_save_unit *save_units)
	[host] Creates a MARS task.
int	mars_task_destroy (struct mars_task_id *id)
	[host] Destroys a MARS task.
int	mars_task_schedule (struct mars_task_id *id, struct mars_task_args *args, uint8_t priority)
	[host/MPU] Schedules a MARS task for execution.
int	mars_task_wait (struct mars_task_id *id, int32_t *exit_code)
	[host/MPU] Waits for task completion. (Task Switch Call)
int	mars_task_try_wait (struct mars_task_id *id, int32_t *exit_code)
	[host/MPU] Waits for a task completion.
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)
uint32_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. 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,
		const struct mars_task_context_save_unit *	save_units
	)

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

elf_image

• The address of MPU program elf image in host storage that will be to be run by this task.

save_units

• A list of structures defining the areas of MPU storage to save and restore during a task context switch.
• If NULL 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_ALL is specified, the maximum size context save area will be allocated and all of the MPU storage not occuppied by the MARS kernel will be saved and restored. This will guarantee all necessary areas of the task context will be saved and restored during a context switch. However, this also may not be the most efficient, since areas of MPU storage not needed by the task may be saved and restored.
• For maximum efficiency, the user should initialize a static list of struct mars_task_context_save_unit that define each memory areas to save and restore during a task context switch.
• A maximum of MARS_TASK_CONTEXT_SAVE_UNIT_MAX separate context save units can be specified.
• If you want to specify a context save unit list of size less than MARS_TASK_CONTEXT_SAVE_UNIT_MAX, you must specify a terminating unit with an address and size of 0.
• Each context save unit defines an address offset from the task program's base address (MARS_TASK_BASE_ADDR) and the size of the unit.
• The address must be aligned to a 16-byte address and the size must be a multiple of 16 bytes. Otherwise MARS_ERROR_PARAMS will be returned.

Note:

The efficiency and validity of the specified context save unit list is left up to the responsibility of the user.

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]	save_units	- pointer to list of context save units

Returns:

MARS_SUCCESS - successfully created 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_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	(	struct mars_task_id *	id,
		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.

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
[out]	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,
		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 6.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
[in]	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	(	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
[in]	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

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:

[in]

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 6.5 Task Switching).

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.

Note:

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

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 the task is 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