Workload Module Management API

Data Structures
struct	mars_workload_module
	MARS workload module structure. More...
Files
file	workload_types.h
	[host/MPU] MARS Workload Types
file	module.h
	[MPU] MARS Workload Module API
Defines
#define	MARS_WORKLOAD_MODULE_BASE_ADDR   0x3000
	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.
uint16_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_query (uint16_t id, int query)
	[MPU] Returns whether or not specified query is satisfied.
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.
int	mars_module_host_signal_send (uint64_t watch_point_ea)
	[MPU] Notify host a particular 32-bit area is modified.
int	mars_module_mutex_lock_get (uint64_t mutex_ea, struct mars_mutex *mutex)
	[MPU] Locks a mutex.
int	mars_module_mutex_unlock_put (uint64_t mutex_ea, struct mars_mutex *mutex)
	[MPU] Unlocks a mutex.
int	mars_module_dma_get (void *ls, uint64_t ea, uint32_t size, uint32_t tag)
	[MPU] DMA transfer from host storage to MPU storage.
int	mars_module_dma_put (const void *ls, uint64_t ea, uint32_t size, uint32_t tag)
	[MPU] DMA transfer from MPU storage to host storage.
int	mars_module_dma_wait (uint32_t tag)
	[MPU] Waits for completion of requested DMA transfer.
Variables
struct mars_workload_module	packed
	MARS workload module structure.

---

Detailed Description

The workload module API is the interface between the MARS 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

uint16_t mars_module_get_kernel_id

(

void

)

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

Returns:

uint16_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_query	(	uint16_t	id,
		int	query
	)

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

Parameters:

[in]	id	- id of workload
[in]	query	- query type

Returns:

int - non-zero if query 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.

int mars_module_host_signal_send

(

uint64_t

watch_point_ea

)

[MPU] Notify host a particular 32-bit area is modified.

Parameters:

[in]

watch_point_ea

- ea of modified area

Returns:

MARS_SUCCESS - signal sent to host

int mars_module_mutex_lock_get	(	uint64_t	mutex_ea,
		struct mars_mutex *	mutex
	)

[MPU] Locks a mutex.

This function locks a mutex and blocks other requests to lock it. It also loads the mutex instance from the effective address specified into the local mutex instance.

Parameters:

[in]	mutex_ea	- ea of mutex instance to lock
[in]	mutex	- pointer to local mutex instance

Returns:

MARS_SUCCESS - successfully locked mutex
MARS_ERROR_NULL - ea is 0 or mutex is NULL
MARS_ERROR_ALIGN - ea or mutex not aligned properly

int mars_module_mutex_unlock_put	(	uint64_t	mutex_ea,
		struct mars_mutex *	mutex
	)

[MPU] Unlocks a mutex.

This function unlocks a previously locked mutex to allow other lock requests. It also stores the local mutex instance into the effective address specified.

Parameters:

[in]	mutex_ea	- ea of mutex instance to unlock
[in]	mutex	- pointer to local mutex instance

Returns:

MARS_SUCCESS - successfully unlocked mutex
MARS_ERROR_NULL - ea is 0 or mutex is NULL
MARS_ERROR_ALIGN - ea or mutex not aligned properly
MARS_ERROR_STATE - instance not in locked state

int mars_module_dma_get	(	void *	ls,
		uint64_t	ea,
		uint32_t	size,
		uint32_t	tag
	)

[MPU] DMA transfer from host storage to MPU storage.

This function begins a DMA transfer request from host storage to MPU storage. Transfer completion is not guaranteed until calling mars_module_dma_wait with the corresponding tag used to request the transfer.

Parameters:

[in]	ls	- address of MPU storage to transfer to
[in]	ea	- ea of host storage to transfer from
[in]	size	- size of dma transfer
[in]	tag	- tag of dma transfer

Returns:

MARS_SUCCESS - successfully tranferred data
MARS_ERROR_PARAMS - invalid tag specified
MARS_ERROR_ALIGN - ls or ea not aligned properly

int mars_module_dma_put	(	const void *	ls,
		uint64_t	ea,
		uint32_t	size,
		uint32_t	tag
	)

[MPU] DMA transfer from MPU storage to host storage.

This function begins a DMA transfer request from MPU storage to host storage. Transfer completion is not guaranteed until calling mars_module_dma_wait with the corresponding tag used to request the transfer.

Parameters:

[in]	ls	- address of MPU storage to transfer to
[in]	ea	- ea of host storage to transfer from
[in]	size	- size of dma transfer
[in]	tag	- tag of dma transfer

Returns:

MARS_SUCCESS - successfully tranferred data
MARS_ERROR_PARAMS - invalid tag specified
MARS_ERROR_ALIGN - ls or ea not aligned properly

int mars_module_dma_wait

(

uint32_t

tag

)

[MPU] Waits for completion of requested DMA transfer.

This function waits until completion of all previously started DMA transfer requests with the same tag.

Parameters:

[in]

tag

- tag of dma transfer

Returns:

MARS_SUCCESS - successfully waited for transfer completion
MARS_ERROR_PARAMS - invalid tag specified

---

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.