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


Generated on Wed Jul 29 18:01:05 2009 for MARS by  doxygen 1.5.7.1