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 (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.
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)
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	(	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.
• 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_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 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	(	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 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

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