Context Management API

Files
file	mars.h
	[host] MARS API
file	mars.h
	[MPU] MARS API
Data Structures
struct	mars_params
	MARS params structure. More...
struct	mars_context
	MARS context structure. More...
Functions
int	mars_initialize (struct mars_context *ctx, struct mars_params *params)
	[host] Initializes a single MARS context.
int	mars_finalize (struct mars_context *ctx)
	[host] Finalizes a single MARS context.

---

Detailed Description

The MARS context is what holds all necessary information and data for each MARS instance initialized for the system.

Before any of the MARS functionalities can be utilized, an instance of a MARS context must be initialized. When the system is completely done with MARS functionality, the context must be finalized.

When a context is initialized within a system by the host processor, each MPU (depending on how many MPUs are initialized for the context) is loaded with the MARS kernel that stays resident in MPU storage and continues to run until the host processor finalizes the context.

The context also creates the workload queue in host storage. Each kernel, through the use of atomic synchronization primitives, will reserve and schedule workloads from this queue.

When the context is finalized, all kernels running on the MPUs are terminated and all resources are freed.

In a system, multiple MARS contexts may be initialized and the kernels and workloads of each context will be independent of each other. However, one of the main purposes of MARS is to avoid the high cost of process context switches within MPUs initiated by the host processor. If multiple MARS contexts are initialized, there will be an enormous decrease in performance as each MARS context is context switched in and out. In the ideal scenario, there should be a single MARS context initialized for the whole system.

---

Function Documentation

int mars_initialize	(	struct mars_context *	ctx,
		struct mars_params *	params
	)

[host] Initializes a single MARS context.

This function initializes a single MARS context. A MARS context must be initialized before any of the MARS functionality can be used. This will create the MPU contexts that are each loaded with and run the MARS kernel. The MARS kernel on each MPU will continue to run until the MARS context is finalized through mars_finalize.

Note:

If there are multiple MARS contexts initialized in the system, then each MARS context will suffer the large over head of MPU context switches.

Parameters:

[out]	ctx	- address of context instance to initialize
[in]	params	- pointer to MARS parameters structure

Returns:

MARS_SUCCESS - successfully initialized MARS context
MARS_ERROR_NULL - null pointer specified
MARS_ERROR_PARAMS - bad MARS params specified
MARS_ERROR_MEMORY - not enough memory
MARS_ERROR_INTERNAL - some internal error occurred

int mars_finalize

(

struct mars_context *

ctx

)

[host] Finalizes a single MARS context.

This function finalizes a single MARS context that was previously initialized by mars_initialize. In order to successfully finalize a MARS context, all workloads added to the workload queue must be completed and finalized so that the workload queue is empty.

Parameters:

[in]

ctx

- address of context instance to finalize

Returns:

MARS_SUCCESS - successfully finalized MARS context
MARS_ERROR_NULL - null pointer specified
MARS_ERROR_STATE - workload queue is not empty

---