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_CONTEXT_SIZE   128
	Size of workload context structure.
#define	MARS_WORKLOAD_CONTEXT_ALIGN   128
	Alignment of workload context structure.
Functions
int	mars_workload_queue_add_begin (struct mars_context *mars, uint16_t *id, uint64_t *workload_ea)
	[host] Begins adding workload to workload queue.
int	mars_workload_queue_add_end (struct mars_context *mars, uint16_t id)
	[host] Ends adding of specified workload.
int	mars_workload_queue_add_cancel (struct mars_context *mars, uint16_t id)
	[host] Cancels 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)
	[host] Ends removing of specified workload.
int	mars_workload_queue_remove_cancel (struct mars_context *mars, uint16_t id)
	[host] Cancels 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)
	[host] Ends scheduling of specified workload.
int	mars_workload_queue_schedule_cancel (struct mars_context *mars, uint16_t id)
	[host] Cancels scheduling 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_add_begin	(	struct mars_context *	mars,
		uint16_t *	id,
		uint64_t *	workload_ea
	)

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

This call will lock the workload queue 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

Returns:

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

int mars_workload_queue_add_end	(	struct mars_context *	mars,
		uint16_t	id
	)

[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

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_add_cancel	(	struct mars_context *	mars,
		uint16_t	id
	)

[host] Cancels adding of specified workload.

This function will cancel an add operation previously initiated with mars_workload_queue_add_begin. If scheduling is canceled, mars_workload_queue_add_end should not be called.

Parameters:

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

Returns:

MARS_SUCCESS - workload adding canceled
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.

This call will lock the workload queue 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
	)

[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

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_remove_cancel	(	struct mars_context *	mars,
		uint16_t	id
	)

[host] Cancels removing of specified workload.

This function will cancel a remove operation previously initiated with mars_workload_queue_remove_begin. If removing is canceled, mars_workload_queue_remove_end should not be called.

Parameters:

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

Returns:

MARS_SUCCESS - workload removing canceled
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.

This call will lock the workload queue 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
	)

[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

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_schedule_cancel	(	struct mars_context *	mars,
		uint16_t	id
	)

[host] Cancels scheduling of specified workload.

This function will cancel a schedule operation previously initiated with mars_workload_queue_schedule_begin. If scheduling is canceled, mars_workload_queue_schedule_end should not be called.

Parameters:

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

Returns:

MARS_SUCCESS - workload scheduling canceled
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_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