Workload Queue Management API

Files
file	workload_types.h
	[host/MPU] MARS Workload Types
file	workload_queue.h
	[host] MARS Workload Queue API
Defines
#define	MARS_WORKLOAD_RESERVED_SIZE   128
	Size of workload module structure.
#define	MARS_WORKLOAD_CONTEXT_SIZE   256
	Size of workload context structure.
#define	MARS_WORKLOAD_CONTEXT_ALIGN   128
	Alignment of workload context structure.
Functions
int	mars_workload_queue_query (struct mars_context *mars, uint16_t id, int query)
	[host] Returns whether or not specified query is satisfied.
int	mars_workload_queue_add_begin (struct mars_context *mars, uint16_t *id, uint64_t *workload_ea, const void *module_elf, const char *module_name)
	[host] Begins adding workload to workload queue.
int	mars_workload_queue_add_end (struct mars_context *mars, uint16_t id, int cancel)
	[host] Ends adding of specified workload.
int	mars_workload_queue_remove_begin (struct mars_context *mars, uint16_t id, uint64_t *workload_ea)
	[host] Begins removing workload from workload queue.
int	mars_workload_queue_remove_end (struct mars_context *mars, uint16_t id, int cancel)
	[host] Ends removing of specified workload.
int	mars_workload_queue_schedule_begin (struct mars_context *mars, uint16_t id, uint8_t priority, uint64_t *workload_ea)
	[host] Begins scheduling of specified workload.
int	mars_workload_queue_schedule_end (struct mars_context *mars, uint16_t id, int cancel)
	[host] Ends scheduling of specified workload.
int	mars_workload_queue_unschedule_begin (struct mars_context *mars, uint16_t id, uint64_t *workload_ea)
	[host] Begins unscheduling of specified workload.
int	mars_workload_queue_unschedule_end (struct mars_context *mars, uint16_t id)
	[host] Ends unscheduling of specified workload.
int	mars_workload_queue_wait (struct mars_context *mars, uint16_t id, uint64_t *workload_ea)
	[host] Waits for specified workload to finish.
int	mars_workload_queue_try_wait (struct mars_context *mars, uint16_t id, uint64_t *workload_ea)
	[host] Waits for specified workload to finish.
int	mars_workload_queue_signal_send (struct mars_context *mars, uint16_t id)
	[host] Sends signal to specified workload.

---

Detailed Description

The workload queue API is the interface between the MARS context and the MARS workload model host library. The host library of the workload model implementation will need to use the workload queue API in order to provide proper workload management functionalities.

The workload queue API provides the basic funtions to create, schedule, remove a workload context within the workload queue. It also provides APIs to do signal handling of workloads and to wait for specific workloads to complete.

---

Function Documentation

int mars_workload_queue_query	(	struct mars_context *	mars,
		uint16_t	id,
		int	query
	)

[host] Returns whether or not specified query is satisfied.

Note:

Query type MARS_WORKLOAD_QUERY_IS_MODULE_CACHED and MARS_WORKLOAD_QUERY_IS_CONTEXT_CACHED are only valid queries for the MPU-side call to mars_module_workload_query. Calling mars_workload_queue_query with these queries will always return 0.

Parameters:

[in]	mars	- address of pointer to MARS context
[in]	id	- id of workload
[in]	query	- query type

Returns:

int - non-zero if query satisfied

int mars_workload_queue_add_begin	(	struct mars_context *	mars,
		uint16_t *	id,
		uint64_t *	workload_ea,
		const void *	module_elf,
		const char *	module_name
	)

[host] Begins adding workload to workload queue.

This function will begin the process to add a workload to the workload queue. This only initiates the add operation. This function must be completed with a matching call to mars_workload_queue_add_end to guarantee the completion of the add operation.

If workload_ea is not NULL, the ea of the workload will be returned.

The workload adding process is not completed until the matching call to mars_workload_queue_add_end is made. The user should make any necessary updates to the returned workload context in between this begin call and the end call.

Parameters:

[in]	mars	- address of pointer to MARS context
[out]	id	- pointer to return workload id
[out]	workload_ea	- address of pointer to workload context ea
[in]	module_elf	- pointer to workload module elf image
[in]	module_name	- name of module

Returns:

MARS_SUCCESS - workload adding started
MARS_ERROR_NULL - null pointer specified
MARS_ERROR_PARAMS - invalid mars context or module specified
MARS_ERROR_LIMIT - workload queue is full

int mars_workload_queue_add_end	(	struct mars_context *	mars,
		uint16_t	id,
		int	cancel
	)

[host] Ends adding of specified workload.

This function will complete a add operation previously initiated with mars_workload_queue_add_begin. This function must be called in pair for each call to mars_workload_queue_add_begin to guarantee the completion of the initiated add operation.

Parameters:

[in]	mars	- address of pointer to MARS context
[in]	id	- id of workload to end add
[in]	cancel	- cancels the add operation

Returns:

MARS_SUCCESS - workload adding complete
MARS_ERROR_NULL - null pointer specified
MARS_ERROR_PARAMS - invalid mars context or workload id specified
MARS_ERROR_STATE - workload adding not started

int mars_workload_queue_remove_begin	(	struct mars_context *	mars,
		uint16_t	id,
		uint64_t *	workload_ea
	)

[host] Begins removing workload from workload queue.

This function will begin the process to remove a workload from the workload queue. This only initiates the remove operation. This function must be completed with a matching call to mars_workload_queue_remove_end to guarantee the completion of the remove operation.

If workload_ea is not NULL, the ea of the workload will be returned.

The workload removing process is not completed until the matching call to mars_workload_queue_remove_end is made. The user should make any necessary updates to the returned workload context in between this begin call and the end call.

Parameters:

[in]	mars	- address of pointer to MARS context
[in]	id	- id of workload to begin remove
[out]	workload_ea	- address of pointer to workload context ea

Returns:

MARS_SUCCESS - workload removing started
MARS_ERROR_NULL - null pointer specified
MARS_ERROR_PARAMS - invalid mars context specified
MARS_ERROR_STATE - specified workload not added or finished

int mars_workload_queue_remove_end	(	struct mars_context *	mars,
		uint16_t	id,
		int	cancel
	)

[host] Ends removing of specified workload.

This function will complete a remove operation previously initiated with mars_workload_queue_remove_begin. This function must be called in pair for each call to mars_workload_queue_remove_begin to guarantee the completion of the initiated remove operation.

Parameters:

[in]	mars	- address of pointer to MARS context
[in]	id	- id of workload
[in]	cancel	- cancels the remove operation

Returns:

MARS_SUCCESS - workload removing complete
MARS_ERROR_PARAMS - invalid mars context or workload id specified
MARS_ERROR_STATE - workload removing not started

int mars_workload_queue_schedule_begin	(	struct mars_context *	mars,
		uint16_t	id,
		uint8_t	priority,
		uint64_t *	workload_ea
	)

[host] Begins scheduling of specified workload.

This function will begin scheduling the workload specified. This only initiates the scheduling of the workload. This function must be completed with a matching call to mars_workload_queue_schedule_end to guarantee the completion of the scheduling.

If workload_ea is not NULL, the ea of the workload will be returned.

The workload scheduling process is not completed until the matching call to mars_workload_queue_schedule_end is made. The user should make any necessary updates to the returned workload context in between this begin call and the end call.

Parameters:

[in]	mars	- address of pointer to MARS context
[in]	id	- id of workload
[in]	priority	- scheduling priority of workload
[out]	workload_ea	- address of pointer to workload context ea

Returns:

MARS_SUCCESS - workload scheduling started
MARS_ERROR_NULL - null pointer specified
MARS_ERROR_PARAMS - invalid mars context or workload id specified
MARS_ERROR_STATE - specified workload not added or finished

int mars_workload_queue_schedule_end	(	struct mars_context *	mars,
		uint16_t	id,
		int	cancel
	)

[host] Ends scheduling of specified workload.

This function will complete a schedule operation previously initiated with mars_workload_queue_schedule_begin. This function must be called in pair for each call to mars_workload_queue_schedule_begin to guarantee the completion of the initiated schedule operation.

Parameters:

[in]	mars	- address of pointer to MARS context
[in]	id	- id of workload
[in]	cancel	- cancels the schedule operation

Returns:

MARS_SUCCESS - workload scheduling complete
MARS_ERROR_NULL - null pointer specified
MARS_ERROR_PARAMS - invalid mars context or workload id specified
MARS_ERROR_STATE - workload scheduling not started

int mars_workload_queue_unschedule_begin	(	struct mars_context *	mars,
		uint16_t	id,
		uint64_t *	workload_ea
	)

[host] Begins unscheduling of specified workload.

This function will begin unscheduling the workload specified. This only initiates the unscheduling of the workload. This function must be completed with a matching call to mars_workload_queue_unschedule_end to guarantee the completion of the unscheduling.

If workload_ea is not NULL, the ea of the workload will be returned.

The workload unscheduling process is not completed until the matching call to mars_workload_queue_unschedule_end is made. The user should make any necessary updates to the returned workload context in between this begin call and the end call.

When a workload is unscheduled, it will be put into a finished state and any entities waiting on the workload to finish will be resumed.

If a scheduled workload is unscheduled before execution, the workload will not be executed until a subsequent scheduling request is made.

If the workload is currently in a waiting state, calling unschedule will finish the workload and will not be resumed from the waiting state.

If the workload is currently in a running state, calling unschedule will immediately put the workload into a finished state. However, execution of the workload will only be suspended when the workload yields, waits, or finishes.

Note:

Trying to unschedule a workload that has not yet been scheduled, or has already finished a previously scheduled execution will return an error.

Parameters:

[in]	mars	- address of pointer to MARS context
[in]	id	- id of workload
[out]	workload_ea	- address of pointer to workload context ea

Returns:

MARS_SUCCESS - workload aborted
MARS_ERROR_NULL - null pointer specified
MARS_ERROR_PARAMS - invalid mars context or workload id specified
MARS_ERROR_STATE - workload is not scheduled or has finished

int mars_workload_queue_unschedule_end	(	struct mars_context *	mars,
		uint16_t	id
	)

[host] Ends unscheduling of specified workload.

This function will complete an unschedule operation previously initiated with mars_workload_queue_unschedule_begin. This function must be called in pair for each call to mars_workload_queue_unschedule_begin to guarantee the completion of the initiated unschedule operation.

Parameters:

[in]	mars	- address of pointer to MARS context
[in]	id	- id of workload

Returns:

MARS_SUCCESS - workload unscheduling complete
MARS_ERROR_NULL - null pointer specified
MARS_ERROR_PARAMS - invalid mars context or workload id specified
MARS_ERROR_STATE - workload unscheduling not started

int mars_workload_queue_wait	(	struct mars_context *	mars,
		uint16_t	id,
		uint64_t *	workload_ea
	)

[host] Waits for specified workload to finish.

This function will block and wait until the specified workload finishes.

If workload_ea is not NULL, the ea of the workload will be returned.

Parameters:

[in]	mars	- address of pointer to MARS context
[in]	id	- id of workload
[out]	workload_ea	- address of pointer to workload context ea

Returns:

MARS_SUCCESS - workload is finished
MARS_ERROR_NULL - null pointer specified
MARS_ERROR_PARAMS - invalid mars context or workload id specified
MARS_ERROR_STATE - invalid workload specified

int mars_workload_queue_try_wait	(	struct mars_context *	mars,
		uint16_t	id,
		uint64_t *	workload_ea
	)

[host] Waits for specified workload to finish.

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

If workload_ea is not NULL, the ea of the workload will be returned.

Parameters:

[in]	mars	- address of pointer to MARS context
[in]	id	- id of workload
[out]	workload_ea	- address of pointer to workload context ea

Returns:

MARS_SUCCESS - workload is finished
MARS_ERROR_NULL - null pointer specified
MARS_ERROR_PARAMS - invalid mars context or workload id specified
MARS_ERROR_STATE - invalid workload specified
MARS_ERROR_BUSY - workload has not yet finished

int mars_workload_queue_signal_send	(	struct mars_context *	mars,
		uint16_t	id
	)

[host] Sends signal to specified workload.

This function will send a signal to the specified workload.

Parameters:

[in]	mars	- address of pointer to MARS context
[in]	id	- id of workload

Returns:

MARS_SUCCESS - signalled workload
MARS_ERROR_NULL - null pointer specified
MARS_ERROR_PARAMS - invalid mars context or workload id specified
MARS_ERROR_STATE - invalid workload specified