Memory Management

Functions
PolarisStatus	polaris_malloc (PolarisContext *ctxt, size_t size, void **ptr)
	Allocate a block of memory on FPGA. More...
PolarisStatus	polaris_malloc_host (PolarisContext *ctxt, size_t size, void **ptr)
	Allocate a block of memory on host(CPU) memory. More...
PolarisStatus	polaris_free (PolarisContext *ctxt, void *ptr)
	Free a block of memory on FPGA. More...
PolarisStatus	polaris_free_host (PolarisContext *ctxt, void *ptr)
	Free a block of memory on host(CPU) memory. More...
PolarisStatus	polaris_memcpy (PolarisContext *ctxt, PolarisMemcpyKind kind, void *dest, const void *src, size_t size)
	Copy block of memory between CPU and FPGA. More...
PolarisStatus	polaris_memset (PolarisContext *ctxt, void *ptr, size_t size)
	Fill a range of FPGA memory with zero. More...
PolarisStatus	polaris_memcpy_2d (PolarisContext *ctxt, PolarisMemcpyKind kind, int m, int n, void *dest, int stride_dest, const void *src, int stride_src)
	Perform batched memcpy in a 2-D pattern. Often used to copy sub-matrices. More...

Detailed Description

Functions related to memory allocation, free and copy, including memcpy between CPU and FPGA and kinds of on-FPGA memcpy.

Function Documentation

polaris_malloc()

PolarisStatus polaris_malloc	(	PolarisContext *	ctxt,
		size_t	size,
		void **	ptr
	)

Allocate a block of memory on FPGA.

The allocated memory block is associated with the Context object, it will be auto released if the context is destroyed. But there is no boundary in the access of memory allocated in different contexts, that is to say, one context could read/write the content of the memory allocated in another context.

Parameters

[in]	ctxt	pointer to PolarisContext object
[in]	size	size of memory in bytes to allocate
[out]	ptr	malloced FPGA memory, NULL on error

Returns

Execution status, POLARIS_OK on success.

polaris_malloc_host()

PolarisStatus polaris_malloc_host	(	PolarisContext *	ctxt,
		size_t	size,
		void **	ptr
	)

Allocate a block of memory on host(CPU) memory.

CPU memory allocated by polaris_malloc_host() is faster than that of glibc malloc() when performing polaris_memcpy(), it is highly recommended to use this function to allocate memory for those blocks that need to be frequently copied to or from FPGA memory.

Note

Memory allocated by this function will be pinned in the physical memory, so avoid using this function for CPU-use-only memory.

Parameters

[in]	ctxt	pointer to PolarisContext object
[in]	size	number of bytes to allocate
[out]	ptr	malloced CPU memory address

Returns

Execution status, POLARIS_OK on success.

polaris_free()

PolarisStatus polaris_free	(	PolarisContext *	ctxt,
		void *	ptr
	)

Free a block of memory on FPGA.

You can only free those memories that were allocated in the same context.

Parameters

[in]	ctxt	pointer to PolarisContext object
[in]	ptr	start address of the FPGA memory to be freed

Returns

Execution status, POLARIS_OK on success.

polaris_free_host()

PolarisStatus polaris_free_host	(	PolarisContext *	ctxt,
		void *	ptr
	)

Free a block of memory on host(CPU) memory.

Parameters

[in]	ctxt	pointer to PolarisContext object
[in]	ptr	start address of the CPU memory to be freed

Returns

Execution status, POLARIS_OK on success.

polaris_memcpy()

PolarisStatus polaris_memcpy	(	PolarisContext *	ctxt,
		PolarisMemcpyKind	kind,
		void *	dest,
		const void *	src,
		size_t	size
	)

Copy block of memory between CPU and FPGA.

Copy size bytes from the memory area pointed to by src to the memory area pointed to by dest, where kind specifies the direction of the copy, and must by one of POLARIS_DEVICE_TO_HOST, POLARIS_HOST_TO_DEVICE, POLARIS_DEVICE_TO_DEVICE

Parameters

[in]	ctxt	pointer to PolarisContext object
[in]	kind	direction of the transfer
[out]	dest	destination FPGA/CPU memory address
[in]	src	source CPU/FPGA memory address
[in]	size	number of bytes to be copied

Returns

Execution status, POLARIS_OK on success.

See also

PolarisMemcpyKind

polaris_memset()

PolarisStatus polaris_memset	(	PolarisContext *	ctxt,
		void *	ptr,
		size_t	size
	)

Fill a range of FPGA memory with zero.

This function fills the first size bytes of the FPGA memory area pointed to by ptr with 0.

Parameters

[in]	ctxt	pointer to PolarisContext object
[in]	ptr	address of the FPGA memory to be set
[in]	size	size of the memory (in bytes)

Returns

Execution status, POLARIS_OK on success.

polaris_memcpy_2d()

PolarisStatus polaris_memcpy_2d	(	PolarisContext *	ctxt,
		PolarisMemcpyKind	kind,
		int	m,
		int	n,
		void *	dest,
		int	stride_dest,
		const void *	src,
		int	stride_src
	)

Perform batched memcpy in a 2-D pattern. Often used to copy sub-matrices.

Copy m rows of data, the size (in bytes) of each row is indicated by n, and the source and destination address of i-th copy (i = 0, 1, ..., m - 1) is &src[i * stride_src] and &dest[i * stride_dest] separately.

Parameters

[in]	ctxt	pointer to PolarisContext
[in]	kind	direction of the transfer
[in]	m	rows of matrix data (number of memory blocks to be copied)
[in]	n	cols (in bytes) of matrix data (size of each memory copy)
[out]	dest	destination memory address
[in]	stride_dest	destination step
[in]	src	source memory address
[in]	stride_src	source step

Note

Not supported by FPGA hardware yet.

Returns

Execution status, POLARIS_OK on success.