Core Management API

Files
file	error.h
	[host/MPU] MARS Error Values
file	core.h
	[host] MARS Core API
file	dma.h
	[MPU] MARS DMA API
Defines
#define	mars_alloca_align(boundary, size)
	[host] Allocates memory on the stack
Functions
void *	mars_malloc (size_t size)
	[host] Allocates memory in host storage.
void *	mars_realloc (void *ptr, size_t size)
	[host] Re-allocates memory in host storage.
void	mars_free (void *ptr)
	[host] Frees memory allocated in host storage.
uint64_t	mars_ea_memalign (size_t boundary, size_t size)
	[host] Allocates memory in shared storage accessible from MPU.
void	mars_ea_free (uint64_t ea)
	[host] Frees memory allocated in shared storage.
void	mars_ea_get (uint64_t ea, void *ptr, size_t size)
	[host] Copy memory block from shared memory to host memory.
uint16_t	mars_ea_get_uint16 (uint64_t ea)
	[host] Get 16-bit integer value from shared memory
uint32_t	mars_ea_get_uint32 (uint64_t ea)
	[host] Get 32-bit integer value from shared memory atomically
uint64_t	mars_ea_get_uint64 (uint64_t ea)
	[host] Get 64-bit integer value from shared memory
void	mars_ea_put (uint64_t ea, const void *ptr, size_t size)
	[host] Copy memory block from host memory to shared memory.
void	mars_ea_put_uint16 (uint64_t ea, uint16_t value)
	[host] Put 16-bit integer value to shared memory atomically
void	mars_ea_put_uint32 (uint64_t ea, uint32_t value)
	[host] Put 32-bit integer value to shared memory atomically
void	mars_ea_put_uint64 (uint64_t ea, uint64_t value)
	[host] Put 64-bit integer value to shared memory atomically
uint64_t	mars_ea_map (void *ptr, size_t size)
	[host] Enable read access to data in specified memory block from MPU
void	mars_ea_unmap (uint64_t ea, size_t size)
	[host] Disable data access enabled by mars_ea_map
void	mars_ea_sync (void)
	[host] Memory barrier
static void *	mars_ea_to_ptr (uint64_t ea)
	[host] Converts a 64-bit address to pointer.
static uint64_t	mars_ptr_to_ea (const void *ptr)
	[host] Converts a pointer to 64-bit address.
uint32_t	mars_get_ticks (void)
	[host/MPU] Returns tick counter value.
static void	mars_dma_wait (uint32_t tag)
	[MPU] Waits for a dma transfer to complete.
static void	mars_dma_sync (uint32_t tag)
	[MPU] Syncs all dma requests with specified tag.
static void	mars_dma_get (void *ls, uint64_t ea, uint32_t size, uint32_t tag)
	[MPU] Starts dma transfer from host storage to MPU storage.
static void	mars_dma_get_and_wait (void *ls, uint64_t ea, uint32_t size, uint32_t tag)
	[MPU] Starts dma get operation and waits for completion.
static void	mars_dma_put (const void *ls, uint64_t ea, uint32_t size, uint32_t tag)
	[MPU] Starts dma transfer from MPU storage to host storage.
static void	mars_dma_put_and_wait (const void *ls, uint64_t ea, uint32_t size, uint32_t tag)
	[MPU] Starts dma put operation and waits for completion.

---

Define Documentation

#define mars_alloca_align	(	boundary,
		size		)

Value:

( (void *)( ( (uintptr_t)alloca((size) + (boundary) - 1) +      \
                      (boundary) - 1) &                         \
                    ~(uintptr_t)((boundary) - 1) ) )

[host] Allocates memory on the stack

Parameters:

[in]	boundary	- memory address will be a multiple of boundary
[in]	size	- size of memory block to allocate

Returns:

void * - pointer to allocated memory block

---

Function Documentation

void* mars_malloc

(

size_t

size

)

[host] Allocates memory in host storage.

Parameters:

[in]

size

- size of memory block to allocate

Returns:

void * - pointer to allocated memory block

void* mars_realloc	(	void *	ptr,
		size_t	size
	)

[host] Re-allocates memory in host storage.

Parameters:

[in]	ptr	- ptr to memory block to re-allocate
[in]	size	- size of memory block to resize to

Returns:

void * - pointer to re-allocated memory block

void mars_free

(

void *

ptr

)

[host] Frees memory allocated in host storage.

Parameters:

[in]

ptr

- ptr to memory block to free

uint64_t mars_ea_memalign	(	size_t	boundary,
		size_t	size
	)

[host] Allocates memory in shared storage accessible from MPU.

Parameters:

[in]	boundary	- memory address will be a multiple of boundary
[in]	size	- size of memory block to allocate

Returns:

uint64_t - 64-bit address of allocated memory block

void mars_ea_free

(

uint64_t

ea

)

[host] Frees memory allocated in shared storage.

Parameters:

[in]

ea

- 64-bit address of allocated memory block to free

void mars_ea_get	(	uint64_t	ea,
		void *	ptr,
		size_t	size
	)

[host] Copy memory block from shared memory to host memory.

Parameters:

[in]	ea	- 64-bit address of source
[in]	ptr	- pointer to destination
[in]	size	- size of memory block to copy

uint16_t mars_ea_get_uint16

(

uint64_t

ea

)

[host] Get 16-bit integer value from shared memory

Parameters:

[in]

ea

- 64-bit address of source

Returns:

uint16_t - 16-bit result, no guarantee that it is loaded atomically

uint32_t mars_ea_get_uint32

(

uint64_t

ea

)

[host] Get 32-bit integer value from shared memory atomically

Parameters:

[in]

ea

- 64-bit address of source

Returns:

uint32_t - 32-bit result

uint64_t mars_ea_get_uint64

(

uint64_t

ea

)

[host] Get 64-bit integer value from shared memory

Parameters:

[in]

ea

- 64-bit address of source

Returns:

uint64_t - 64-bit result, no guarantee that it is loaded atomically

void mars_ea_put	(	uint64_t	ea,
		const void *	ptr,
		size_t	size
	)

[host] Copy memory block from host memory to shared memory.

Parameters:

[in]	ea	- 64-bit address of destination
[in]	ptr	- pointer to source
[in]	size	- size of memory block to copy

void mars_ea_put_uint16	(	uint64_t	ea,
		uint16_t	value
	)

[host] Put 16-bit integer value to shared memory atomically

Parameters:

[in]	ea	- 64-bit address of destination
[in]	value	- 16-bit value to be stored in shared memory, no guarantee that it is stored atomically

void mars_ea_put_uint32	(	uint64_t	ea,
		uint32_t	value
	)

[host] Put 32-bit integer value to shared memory atomically

Parameters:

[in]	ea	- 64-bit address of destination
[in]	value	- 32-bit value to be stored in shared memory

void mars_ea_put_uint64	(	uint64_t	ea,
		uint64_t	value
	)

[host] Put 64-bit integer value to shared memory atomically

Parameters:

[in]	ea	- 64-bit address of destination
[in]	value	- 64-bit value to be stored in shared memory, no guarantee that it is stored atomically

uint64_t mars_ea_map	(	void *	ptr,
		size_t	size
	)

[host] Enable read access to data in specified memory block from MPU

Parameters:

[in]	ptr	- pointer to source
[in]	size	- size of memory block

Returns:

uint64_t - 64-bit address of memory block

void mars_ea_unmap	(	uint64_t	ea,
		size_t	size
	)

[host] Disable data access enabled by mars_ea_map

Parameters:

[in]	ea	- 64-bit address of memory block
[in]	size	- size of memory block

static void* mars_ea_to_ptr

(

uint64_t

ea

)

[inline, static]

[host] Converts a 64-bit address to pointer.

Parameters:

[in]

ea

- 64-bit address

Returns:

void * - pointer value

static uint64_t mars_ptr_to_ea

(

const void *

ptr

)

[inline, static]

[host] Converts a pointer to 64-bit address.

Parameters:

[in]

ptr

- pointer value

Returns:

uint64_t - 64-bit address

uint32_t mars_get_ticks

(

void

)

[host/MPU] Returns tick counter value.

Note:

Counter's frequency depends on runtime environment.

Returns:

uint32_t - 32-bit tick counter value

static void mars_dma_wait

(

uint32_t

tag

)

[inline, static]

[MPU] Waits for a dma transfer to complete.

This function will wait until all dma transfer operations currently initialized with the specified tag completes.

Parameters:

[in]

tag

- tag identifier of dma transfer [between 0 and 31]

Returns:

none

static void mars_dma_sync

(

uint32_t

tag

)

[inline, static]

[MPU] Syncs all dma requests with specified tag.

This function will wait until all dma requests with the specified tag are processed before continuing past the synchronization point.

Parameters:

[in]

tag

- tag identifier of dma transfer [between 0 and 31]

Returns:

none

static void mars_dma_get	(	void *	ls,
		uint64_t	ea,
		uint32_t	size,
		uint32_t	tag
	)			[inline, static]

[MPU] Starts dma transfer from host storage to MPU storage.

This function will start a dma transfer to copy the specified number of bytes from host storage to MPU storage.

Parameters:

[in]	ls	- destination MPU storage address [16 byte aligned]
[in]	ea	- source host storage address [16 byte aligned]
[in]	size	- size of bytes to transfer
[in]	tag	- tag identifier of dma transfer [between 0 and 31]

Returns:

none

static void mars_dma_get_and_wait	(	void *	ls,
		uint64_t	ea,
		uint32_t	size,
		uint32_t	tag
	)			[inline, static]

[MPU] Starts dma get operation and waits for completion.

Parameters:

[in]	ls	- destination MPU storage address [16 byte aligned]
[in]	ea	- source host storage address [16 byte aligned]
[in]	size	- size of bytes to transfer
[in]	tag	- tag identifier of dma transfer [between 0 and 31]

Returns:

none

static void mars_dma_put	(	const void *	ls,
		uint64_t	ea,
		uint32_t	size,
		uint32_t	tag
	)			[inline, static]

[MPU] Starts dma transfer from MPU storage to host storage.

This function will start a dma transfer to copy the specified number of bytes from MPU storage to host storage.

Parameters:

[in]	ls	- source MPU storage address [16 byte aligned]
[in]	ea	- destination host storage address [16 byte aligned]
[in]	size	- size of bytes to transfer
[in]	tag	- tag identifier of dma transfer [between 0 and 31]

Returns:

none

static void mars_dma_put_and_wait	(	const void *	ls,
		uint64_t	ea,
		uint32_t	size,
		uint32_t	tag
	)			[inline, static]

[MPU] Starts dma put operation and waits for completion.

Parameters:

[in]	ls	- source MPU storage address [16 byte aligned]
[in]	ea	- destination host storage address [16 byte aligned]
[in]	size	- size of bytes to transfer
[in]	tag	- tag identifier of dma transfer [between 0 and 31]

Returns:

none