Workload Module Management API

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_NAME_LEN_MAX   23
	Maximum length of workload module name.
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, int cancel)
	[MPU] Ends scheduling of specified workload.
int	mars_module_workload_unschedule_begin (uint16_t id, struct mars_workload_context **workload)
	[MPU] Begins unscheduling of specified workload.
int	mars_module_workload_unschedule_end (uint16_t id)
	[MPU] Ends unscheduling 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_host_callback_set (uint64_t callback_ea, const struct mars_callback_args *in)
	[MPU] Request host to call registered callback.
int	mars_module_host_callback_reset (struct mars_callback_args *out)
	[MPU] Resets a host callback request and requests result.
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.

---

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.

The workload scheduling process is not complete 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,
		int	cancel
	)

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

Parameters:

[in]	id	- id of workload
[in]	cancel	- cancels the 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_unschedule_begin	(	uint16_t	id,
		struct mars_workload_context **	workload
	)

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

The workload unscheduling process is not complete until the matching call to mars_module_workload_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]	id	- id of workload
[out]	workload	- address of pointer to workload context

Returns:

MARS_SUCCESS - workload unscheduling started
MARS_ERROR_PARAMS - invalid workload id specified
MARS_ERROR_STATE - workload is not scheduled or has finished

int mars_module_workload_unschedule_end

(

uint16_t

id

)

[MPU] Ends unscheduling of specified workload.

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

Returns:

MARS_SUCCESS - workload unscheduling complete
MARS_ERROR_PARAMS - invalid workload id specified
MARS_ERROR_STATE - workload unscheduling 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_host_callback_set	(	uint64_t	callback_ea,
		const struct mars_callback_args *	in
	)

[MPU] Request host to call registered callback.

Parameters:

[in]	callback_ea	- ea of function of type mars_callback
[in]	in	- pointer to input args in MPU storage

Returns:

MARS_SUCCESS - callback requested to host

int mars_module_host_callback_reset

(

struct mars_callback_args *

out

)

[MPU] Resets a host callback request and requests result.

Parameters:

[out]

out

- pointer to output args to store result

Returns:

MARS_SUCCESS - callback request reset

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