Context Management API

Files
file	context.h
	[host] MARS Context API
Functions
int	mars_context_create (struct mars_context **mars, uint32_t num_mpus, uint8_t shared)
	[host] Creates a single MARS context.
int	mars_context_destroy (struct mars_context *mars)
	[host] Destroys a single MARS context.
uint32_t	mars_context_get_num_mpus (struct mars_context *mars)
	[host] Returns number of MPUs allocated for 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_context_create	(	struct mars_context **	mars,
		uint32_t	num_mpus,
		uint8_t	shared
	)

[host] Creates a single MARS context.

This function creates a single MARS context. A MARS context must be created 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 destroyed through mars_context_destroy.

Key Parameters:

num_mpus

• Specify total number of MPUs to be used by the MARS context
• If 0 is specified, MARS will use the maximum number of MPUs available in the system.

shared

• Specify 1 to share the context with other libraries linked into the application that also utilize MARS.
• Specify 0 to create an independent MARS context that is not shared with other libraries linked into the application that also utilize MARS.
• Sharing a single MARS context within an application with other libraries will maximize the MARS benefits of MPU utilization.

Note:

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

Parameters:

[out]	mars	- address of pointer to MARS context
[in]	num_mpus	- number of mpus requested by MARS context
[in]	shared	- specifies if context is shared or not

Returns:

MARS_SUCCESS - successfully created MARS context
MARS_ERROR_NULL - null pointer specified
MARS_ERROR_LIMIT - no more available MPUs or system threads
MARS_ERROR_PARAMS - more MPUs requested than there are available
MARS_ERROR_MEMORY - not enough memory
MARS_ERROR_INTERNAL - some internal error occurred

int mars_context_destroy

(

struct mars_context *

mars

)

[host] Destroys a single MARS context.

This function destroys a single MARS context that was previously created by mars_context_create. In order to successfully destroy a MARS context, all workloads added to the workload queue must be completed and destroyed so that the workload queue is empty.

Parameters:

[in]

mars

- pointer to MARS context

Returns:

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

uint32_t mars_context_get_num_mpus

(

struct mars_context *

mars

)

[host] Returns number of MPUs allocated for MARS context.

This function returns the number of MPUs allocated for the MARS context.

Parameters:

[in]

mars

- pointer to MARS context

Returns:

non-zero - number of MPUs
0 - invalid MARS context