Workload Module Management API


Files

file  workload_types.h
 [host/MPU] MARS Workload Types
file  module.h
 [MPU] MARS Workload Module API

Data Structures

struct  mars_workload_module
 MARS workload module structure. More...

Defines

#define MARS_WORKLOAD_MODULE_BASE_ADDR   0x4000
 Base address of workload module.
#define MARS_WORKLOAD_MODULE_SIZE   20
 Size of workload module structure.

Functions

void mars_module_main (void)
 [MPU] Entry point for workload module.
uint32_t mars_module_get_ticks (void)
 [MPU] Gets tick counter value.
uint64_t mars_module_get_mars_context_ea (void)
 [MPU] Gets ea of MARS context.
uint32_t mars_module_get_kernel_id (void)
 [MPU] Gets id of kernel that the module is being executed on.
uint16_t mars_module_get_workload_id (void)
 [MPU] Gets id of current workload context.
struct mars_workload_context * mars_module_get_workload (void)
 [MPU] Gets pointer to current workload context.
struct mars_workload_context * mars_module_get_workload_by_id (uint16_t id)
 [MPU] Gets pointer to workload context specified by id.
int mars_module_workload_is_initialized (uint16_t id)
 [MPU] Returns whether or not specified workload is initialized.
int mars_module_workload_is_ready (uint16_t id)
 [MPU] Returns whether or not specified workload is ready.
int mars_module_workload_is_waiting (uint16_t id)
 [MPU] Returns whether or not specified workload is waiting.
int mars_module_workload_is_running (uint16_t id)
 [MPU] Returns whether or not specified workload is running.
int mars_module_workload_is_finished (uint16_t id)
 [MPU] Returns whether or not specified workload is finished.
int mars_module_workload_is_signal_set (uint16_t id)
 [MPU] Returns whether or not specified workload has signal set.
int mars_module_workload_wait_set (uint16_t id)
 [MPU] Sets calling workload to wait for completion of specified workload.
int mars_module_workload_wait_reset (void)
 [MPU] Sets calling workload to not wait for completion of any workloads.
int mars_module_workload_signal_set (uint16_t id)
 [MPU] Sets signal for specified workload.
int mars_module_workload_signal_reset (void)
 [MPU] Resets signal for specified workload.
int mars_module_workload_schedule_begin (uint16_t id, uint8_t priority, struct mars_workload_context **workload)
 [MPU] Begins scheduling of specified workload.
int mars_module_workload_schedule_end (uint16_t id)
 [MPU] Ends scheduling of specified workload.
int mars_module_workload_schedule_cancel (uint16_t id)
 [MPU] Cancels scheduling of specified workload.
void mars_module_workload_wait (void)
 [MPU] Returns execution to kernel with workload in wait state.
void mars_module_workload_yield (void)
 [MPU] Returns execution to kernel with workload in ready state.
void mars_module_workload_finish (void)
 [MPU] Returns execution to kernel with workload in finished state.

Variables

struct mars_workload_module packed
 MARS workload module structure.

Detailed Description

The workload module API is the interface between the MARS core kernel and the MARS workload module for the specified workload model. The workload specific module will need to use the workload module API in order to provide proper workload management functionalities.

The workload module API provides the basic functions to get various workload information, schedule other workloads, handle workload signals, and also functions to transition the workload state and return execution back to the MARS kernel.

Function Documentation

void mars_module_main ( void   ) 

[MPU] Entry point for workload module.

This function is the main entry point for the workload module. All workload modules will need to have a definition of this function. This function is called from the MARS kernel when a workload context that specifies this workload module is scheduled for execution.

Note:
Returning from this function is equivalent to calling mars_module_workload_finish.

uint32_t mars_module_get_ticks ( void   ) 

[MPU] Gets tick counter value.

Note:
Counter's frequency depends on runtime environment.
Returns:
uint32_t - 32-bit tick counter value

uint64_t mars_module_get_mars_context_ea ( void   ) 

[MPU] Gets ea of MARS context.

Returns:
uint64_t - ea of MARS context

uint32_t mars_module_get_kernel_id ( void   ) 

[MPU] Gets id of kernel that the module is being executed on.

Returns:
uint32_t - id of MARS kernel

uint16_t mars_module_get_workload_id ( void   ) 

[MPU] Gets id of current workload context.

Returns:
uint16_t - id of workload

struct mars_workload_context* mars_module_get_workload ( void   )  [read]

[MPU] Gets pointer to current workload context.

Returns:
struct mars_workload_context * - pointer to current workload context

struct mars_workload_context* mars_module_get_workload_by_id ( uint16_t  id  )  [read]

[MPU] Gets pointer to workload context specified by id.

Parameters:
[in] id - id of workload
Returns:
struct mars_workload_context * - pointer to specified workload context

int mars_module_workload_is_initialized ( uint16_t  id  ) 

[MPU] Returns whether or not specified workload is initialized.

Parameters:
[in] id - id of workload
Returns:
int - non-zero if condition satisfied

int mars_module_workload_is_ready ( uint16_t  id  ) 

[MPU] Returns whether or not specified workload is ready.

Parameters:
[in] id - id of workload
Returns:
int - non-zero if condition satisfied

int mars_module_workload_is_waiting ( uint16_t  id  ) 

[MPU] Returns whether or not specified workload is waiting.

Parameters:
[in] id - id of workload
Returns:
int - non-zero if condition satisfied

int mars_module_workload_is_running ( uint16_t  id  ) 

[MPU] Returns whether or not specified workload is running.

Parameters:
[in] id - id of workload
Returns:
int - non-zero if condition satisfied

int mars_module_workload_is_finished ( uint16_t  id  ) 

[MPU] Returns whether or not specified workload is finished.

Parameters:
[in] id - id of workload
Returns:
int - non-zero if condition satisfied

int mars_module_workload_is_signal_set ( uint16_t  id  ) 

[MPU] Returns whether or not specified workload has signal set.

Parameters:
[in] id - id of workload
Returns:
int - non-zero if condition satisfied

int mars_module_workload_wait_set ( uint16_t  id  ) 

[MPU] Sets calling workload to wait for completion of specified workload.

Note:
This function only sets the id of workload to wait for completion. The caller should also mars_module_workload_wait immediately after this call so the calling workload yields execution and enters the waiting state.
Parameters:
[in] id - id of workload
Returns:
MARS_SUCCESS - id of workload to wait for set
MARS_ERROR_PARAMS - invalid workload id specified

int mars_module_workload_wait_reset ( void   ) 

[MPU] Sets calling workload to not wait for completion of any workloads.

Returns:
MARS_SUCCESS - id of workload to wait for reset
MARS_ERROR_PARAMS - invalid workload id specified

int mars_module_workload_signal_set ( uint16_t  id  ) 

[MPU] Sets signal for specified workload.

Parameters:
[in] id - id of workload
Returns:
MARS_SUCCESS - signal set
MARS_ERROR_PARAMS - invalid workload id specified

int mars_module_workload_signal_reset ( void   ) 

[MPU] Resets signal for specified workload.

Returns:
MARS_SUCCESS - signal reset
MARS_ERROR_PARAMS - invalid workload id specified

int mars_module_workload_schedule_begin ( uint16_t  id,
uint8_t  priority,
struct mars_workload_context **  workload 
)

[MPU] 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_module_workload_schedule_end to guarantee the completion of the scheduling.

This call will lock the workload queue until the matching call to mars_module_workload_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] id - id of workload
[in] priority - scheduling priority of workload
[out] workload - address of pointer to workload context
Returns:
MARS_SUCCESS - workload scheduling started
MARS_ERROR_PARAMS - invalid workload id specified
MARS_ERROR_STATE - specified workload not added or finished

int mars_module_workload_schedule_end ( uint16_t  id  ) 

[MPU] Ends scheduling of specified workload.

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

Returns:
MARS_SUCCESS - workload scheduling complete
MARS_ERROR_PARAMS - invalid workload id specified
MARS_ERROR_STATE - workload scheduling not started

int mars_module_workload_schedule_cancel ( uint16_t  id  ) 

[MPU] Cancels scheduling of specified workload.

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

Returns:
MARS_SUCCESS - workload scheduling canceled
MARS_ERROR_PARAMS - invalid workload id specified
MARS_ERROR_STATE - workload scheduling not started

void mars_module_workload_wait ( void   ) 

[MPU] Returns execution to kernel with workload in wait state.

This function will yield execution of the calling workload module and return execution back to the kernel. The workload currently being processed will be put into a waiting state.

Note:
This function will exit the workload module and is not re-entrant.

void mars_module_workload_yield ( void   ) 

[MPU] Returns execution to kernel with workload in ready state.

This function will yield execution of the calling workload module and return execution back to the kernel. The workload currently being processed will be put into a ready state.

Note:
This function will exit the workload module and is not re-entrant.

void mars_module_workload_finish ( void   ) 

[MPU] Returns execution to kernel with workload in finished state.

This function will yield execution of the calling workload module and return execution back to the kernel. The workload currently being processed will be put into a finished state.

Note:
This function will exit the workload module and is not re-entrant.

Variable Documentation

struct mars_workload_module packed

MARS workload module structure.

This structure stores information about the workload module executable that needs to be loaded and executed in order to handle processing of a workload context.

The workload model implementation is responsible for populating this structure inside the workload context before adding the workload context to the workload queue.

Generated on Fri Dec 19 21:36:44 2008 for MARS by  doxygen 1.5.6