C API to manage DPUs. More...

#include <limits.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <dpu_checkpoint.h>
#include <dpu_error.h>
#include <dpu_types.h>
#include <dpu_macro_utils.h>
#include <dpu_fifo.h>
#include <dpu_bank_interface_pmc.h>

Include dependency graph for dpu.h:

Data Structures
struct	sg_block_info
	Structure that stores the information about each scatter transfer memory block. More...

struct	get_block_t
	User API structure that stores the scatter transfer get_block function pointer and its arguments, provided by user application. More...

Macros
#define	DPU_CHECK(statement, on_error)
	Error management for DPU api functions. More...

#define	DPU_ASSERT(statement)
	Error management for DPU api functions, calling exit if an error happens. More...

#define	DPU_ALLOCATE_ALL
	Allow user to allocate all dpus available with function `dpu_alloc`

#define	DPU_RANK_FOREACH(set, ...)
	Iterator over all DPU ranks of a DPU set. More...

#define	_DPU_RANK_FOREACH_X(set, rank)
	Intenal macro for DPU_RANK_FOREACH without rank index.

#define	_DPU_RANK_FOREACH_I(set, rank, i)
	Intenal macro for DPU_RANK_FOREACH with rank index.

#define	DPU_FOREACH(set, ...)
	Iterator over all DPUs of a DPU set. More...

#define	_DPU_FOREACH_X(set, dpu)
	Intenal macro for DPU_RANK_FOREACH without rank index.

#define	_DPU_FOREACH_I(set, dpu, i)
	Intenal macro for DPU_RANK_FOREACH with rank index.

#define	DPU_INCBIN(name, file)
	Embed a binary inside the ELF program. More...

Typedefs
typedef enum _dpu_launch_policy_t	dpu_launch_policy_t
	The different synchronization methods for launching DPUs. polling method to check whether the execution is complete or not.

typedef enum _dpu_xfer_t	dpu_xfer_t
	Direction for a DPU memory transfer.

typedef enum _dpu_xfer_flags_t	dpu_xfer_flags_t
	Options for a DPU memory transfer.

typedef enum _dpu_sg_xfer_flags_t	dpu_sg_xfer_flags_t
	Options for a DPU scatter gather memory transfer.

typedef enum _dpu_callback_flags_t	dpu_callback_flags_t
	Options for a DPU callback.

typedef bool(*	get_block_func_t) (struct sg_block_info out, uint32_t dpu_index, uint32_t block_index, void args)
	User API prototype of the get_block function for scatter transfers. More...

typedef struct get_block_t	get_block_t
	User API structure that stores the scatter transfer get_block function pointer and its arguments, provided by user application.

Enumerations
enum	_dpu_launch_policy_t { DPU_ASYNCHRONOUS, DPU_SYNCHRONOUS }
	The different synchronization methods for launching DPUs. polling method to check whether the execution is complete or not. More...

enum	_dpu_xfer_t { DPU_XFER_TO_DPU, DPU_XFER_FROM_DPU }
	Direction for a DPU memory transfer. More...

enum	_dpu_xfer_flags_t { DPU_XFER_DEFAULT = 0, DPU_XFER_NO_RESET = 1 << 0, DPU_XFER_ASYNC = 1 << 1, DPU_XFER_PARALLEL = 1 << 2 }
	Options for a DPU memory transfer. More...

enum	_dpu_sg_xfer_flags_t { DPU_SG_XFER_DEFAULT = 0, DPU_SG_XFER_ASYNC = 1 << 1, DPU_SG_XFER_DISABLE_LENGTH_CHECK = 1 << 2 }
	Options for a DPU scatter gather memory transfer. More...

enum	_dpu_callback_flags_t { DPU_CALLBACK_DEFAULT = 0, DPU_CALLBACK_ASYNC = 1 << 0, DPU_CALLBACK_NONBLOCKING = 1 << 1, DPU_CALLBACK_SINGLE_CALL = 1 << 2, DPU_CALLBACK_PARALLEL = 1 << 3 }
	Options for a DPU callback. More...

Functions
dpu_error_t	dpu_alloc (uint32_t nr_dpus, const char profile, struct dpu_set_t dpu_set)
	Allocate a number of ranks that will have the specified number of DPUs. More...

dpu_error_t	dpu_alloc_ranks (uint32_t nr_ranks, const char profile, struct dpu_set_t dpu_set)
	Allocate the specified number of DPU ranks. More...

dpu_error_t	dpu_free (struct dpu_set_t dpu_set)
	Free all the DPUs of a DPU set. More...

dpu_error_t	dpu_get_nr_ranks (struct dpu_set_t dpu_set, uint32_t *nr_ranks)
	Fetch the number of DPU ranks in a given DPU set. More...

dpu_error_t	dpu_get_nr_dpus (struct dpu_set_t dpu_set, uint32_t *nr_dpus)
	Fetch the number of DPUs in a given DPU set. More...

dpu_error_t	dpu_load_from_memory (struct dpu_set_t dpu_set, uint8_t buffer, size_t buffer_size, struct dpu_program_t *program)
	Load a program from the memory in all the DPUs of a DPU set. More...

dpu_error_t	dpu_load_from_incbin (struct dpu_set_t dpu_set, struct dpu_incbin_t incbin, struct dpu_program_t *program)
	Load a program from a "struct dpu_incbin" in all the DPUs of a DPU set. More...

dpu_error_t	dpu_load (struct dpu_set_t dpu_set, const char binary_path, struct dpu_program_t *program)
	Load a program in all the DPUs of a DPU set. More...

dpu_error_t	dpu_get_symbol (struct dpu_program_t program, const char symbol_name, struct dpu_symbol_t *symbol)
	Get the requested symbol information. More...

dpu_error_t	dpu_launch (struct dpu_set_t dpu_set, dpu_launch_policy_t policy)
	Request the boot of all the DPUs in a DPU set. More...

dpu_error_t	dpu_status (struct dpu_set_t dpu_set, bool done, bool fault)
	Fetch the current state of the DPU set. More...

dpu_error_t	dpu_sync (struct dpu_set_t dpu_set)
	Wait for the end of the execution on the DPU set. More...

dpu_error_t	dpu_copy_to (struct dpu_set_t dpu_set, const char symbol_name, uint32_t symbol_offset, const void src, size_t length)
	Copy data from the Host memory buffer to one the DPU memories. More...

dpu_error_t	dpu_copy_from (struct dpu_set_t dpu_set, const char symbol_name, uint32_t symbol_offset, void dst, size_t length)
	Copy data from one of the DPU memories to the Host memory buffer. More...

dpu_error_t	dpu_copy_to_symbol (struct dpu_set_t dpu_set, struct dpu_symbol_t symbol, uint32_t symbol_offset, const void *src, size_t length)
	Copy data from the Host memory buffer to one the DPU memories. More...

dpu_error_t	dpu_copy_from_symbol (struct dpu_set_t dpu_set, struct dpu_symbol_t symbol, uint32_t symbol_offset, void *dst, size_t length)
	Copy data from one of the DPU memories to the Host memory buffer. More...

dpu_error_t	dpu_prepare_xfer (struct dpu_set_t dpu_set, void *buffer)
	Set the Host buffer of all DPUs of the DPU set for the next memory transfer. More...

dpu_error_t	dpu_push_sg_xfer (struct dpu_set_t dpu_set, dpu_xfer_t xfer, const char symbol_name, uint32_t symbol_offset, size_t length, get_block_t get_block_info, dpu_sg_xfer_flags_t flags)
	Execute the scatter/gather memory transfer on the DPU set. More...

dpu_error_t	dpu_push_sg_xfer_symbol (struct dpu_set_t dpu_set, dpu_xfer_t xfer, struct dpu_symbol_t symbol, uint32_t symbol_offset, size_t length, get_block_t *get_block_info, dpu_sg_xfer_flags_t flags)
	Execute the scatter/gather memory transfer on the DPU set. More...

dpu_error_t	dpu_push_xfer (struct dpu_set_t dpu_set, dpu_xfer_t xfer, const char *symbol_name, uint32_t symbol_offset, size_t length, dpu_xfer_flags_t flags)
	Execute the memory transfer on the DPU set. More...

dpu_error_t	dpu_push_xfer_symbol (struct dpu_set_t dpu_set, dpu_xfer_t xfer, struct dpu_symbol_t symbol, uint32_t symbol_offset, size_t length, dpu_xfer_flags_t flags)
	Execute the memory transfer on the DPU set. More...

dpu_error_t	dpu_broadcast_to (struct dpu_set_t dpu_set, const char symbol_name, uint32_t symbol_offset, const void src, size_t length, dpu_xfer_flags_t flags)
	Execute the broadcast memory transfer on the DPU set. More...

dpu_error_t	dpu_broadcast_to_symbol (struct dpu_set_t dpu_set, struct dpu_symbol_t symbol, uint32_t symbol_offset, const void *src, size_t length, dpu_xfer_flags_t flags)
	Execute the broadcast memory transfer on the DPU set. More...

dpu_error_t	dpu_fifo_prepare_xfer (struct dpu_set_t dpu_set, struct dpu_fifo_link_t fifo_link, void buffer)
	Set the specified buffer to be transfered for the next DPU FIFO transfer. More...

dpu_error_t	dpu_fifo_push_xfer (struct dpu_set_t dpu_set, struct dpu_fifo_link_t *fifo_link, dpu_xfer_flags_t flags)
	Execute the memory transfer on the DPU FIFOs. More...

dpu_error_t	dpu_callback (struct dpu_set_t dpu_set, dpu_error_t(callback)(struct dpu_set_t, uint32_t, void ), void *args, dpu_callback_flags_t flags)
	Execute a user-defined function with the given DPU set as argument. More...

dpu_error_t	dpu_log_read (struct dpu_set_t set, FILE *stream)
	reads and displays the contents of the log of a DPU More...

Detailed Description

C API to manage DPUs.

This API allows to get, pilot and share information with multiple DPUs.

Macro Definition Documentation

◆ DPU_ASSERT

#define DPU_ASSERT ( statement )

Error management for DPU api functions, calling exit if an error happens.

Parameters

statement the call to the DPU api to execute and check

◆ DPU_CHECK

#define DPU_CHECK	(	statement,
		on_error
	)

Error management for DPU api functions.

Parameters

statement	the call to the DPU api to execute and check
on_error	the statement to execute in case of an error in the DPU api call

◆ DPU_FOREACH

#define DPU_FOREACH	(	set,
		...
	)

Iterator over all DPUs of a DPU set.

Parameters

set	the targeted DPU set
...	a pointer to a `struct dpu_set_t`, which will store the dpu context for the current iteration, and an optional pointer to an integer that will store the dpu index for the current iteration

◆ DPU_INCBIN

#define DPU_INCBIN	(	name,
		file
	)

Embed a binary inside the ELF program.

Parameters

name	the name of the "struct dpu_incbin" that will be created by the MACRO.
file	the binary to embbed.

◆ DPU_RANK_FOREACH

#define DPU_RANK_FOREACH	(	set,
		...
	)

Iterator over all DPU ranks of a DPU set.

Parameters

set	the targeted DPU set
...	a pointer to a `struct dpu_set_t`, which will store the DPU rank context for the current iteration and an optional pointer to an integer that will store the rank index for the current iteration

Typedef Documentation

◆ get_block_func_t

typedef bool(* get_block_func_t) (struct sg_block_info *out, uint32_t dpu_index, uint32_t block_index, void *args)

User API prototype of the get_block function for scatter transfers.

Parameters

out	(output) block information
dpu_index	index of the dpu
block_index	index of the block for the current DPU
args	user arguments

Returns: Whether this block exists or not

Enumeration Type Documentation

◆ _dpu_callback_flags_t

enum _dpu_callback_flags_t

Options for a DPU callback.

Enumerator
DPU_CALLBACK_DEFAULT	Callback is synchronous and called for each rank of the DPU set.
DPU_CALLBACK_ASYNC	Callback is asynchronous and blocking.
DPU_CALLBACK_NONBLOCKING	Callback does not block the API calls to the ranks of the DPU set. Callback must be asynchronous for this to have an effect.
DPU_CALLBACK_SINGLE_CALL	Callback is called once only with the whole DPU set as argument. Callback must be asynchronous and non-blocking for this to have an effect.
DPU_CALLBACK_PARALLEL	The callback is scheduled in parallel of the DPU execution, it does not need to wait for the DPU to finish.

◆ _dpu_launch_policy_t

enum _dpu_launch_policy_t

The different synchronization methods for launching DPUs. polling method to check whether the execution is complete or not.

Enumerator
DPU_ASYNCHRONOUS	Do not wait for the DPUs to complete their execution. The application is given back the control once the DPUs are booted and shall use a synchronization
DPU_SYNCHRONOUS	Suspend the application execution until the booted DPUs complete their work.

◆ _dpu_sg_xfer_flags_t

enum _dpu_sg_xfer_flags_t

Options for a DPU scatter gather memory transfer.

Enumerator
DPU_SG_XFER_DEFAULT	Memory transfer is executed and transfer buffer pointers are cleared.
DPU_SG_XFER_ASYNC	Memory transfer is done asynchronously. The application is given back the control once the transfer is enqueue in the asynchronous job list of the rank(s).
DPU_SG_XFER_DISABLE_LENGTH_CHECK	Authorize scatter/gather memory transfers with a total number of bytes less than the value specified with the argument "length" (dpu_push_sg_xfer(.., length,..)). If this happen during a DPU_XFER_TO_DPU transfer, the remaining MRAM bytes will be filled with zeros.

◆ _dpu_xfer_flags_t

enum _dpu_xfer_flags_t

Options for a DPU memory transfer.

Enumerator
DPU_XFER_DEFAULT	Memory transfer is executed and transfer buffer pointers are cleared.
DPU_XFER_NO_RESET	Memory transfer is executed and transfer buffer pointers are not cleared
DPU_XFER_ASYNC	Memory transfer is done asynchronously. The application is given back the control once the transfer is enqueue in the asynchronous job list of the rank(s).
DPU_XFER_PARALLEL	The memory transfer is scheduled in parallel of the DPU execution, it does not need to wait for the DPU to finish. This is supported for WRAM transfer only. Warning there is no synchronization between the host and the DPU for this transfer. The user needs to take care of it.

◆ _dpu_xfer_t

enum _dpu_xfer_t

Direction for a DPU memory transfer.

Enumerator
DPU_XFER_TO_DPU	Transfer from Host to DPU.
DPU_XFER_FROM_DPU	Transfer from DPU to Host.

Function Documentation

◆ dpu_alloc()

dpu_error_t dpu_alloc	(	uint32_t	nr_dpus,
		const char *	profile,
		struct dpu_set_t *	dpu_set
	)

Allocate a number of ranks that will have the specified number of DPUs.

Fails if the given number of DPUs cannot be allocated (unless DPU_ALLOCATE_ALL is used).

Parameters

nr_dpus	number of DPUs to allocate. Use `DPU_ALLOCATE_ALL` to allocate all available DPUs.
profile	list of (key=value) separated by comma to specify what kind of dpu to allocate. Use `NULL` for the default profile.
dpu_set	storage for the DPU set

Returns: Whether the operation was successful.

◆ dpu_alloc_ranks()

dpu_error_t dpu_alloc_ranks	(	uint32_t	nr_ranks,
		const char *	profile,
		struct dpu_set_t *	dpu_set
	)

Allocate the specified number of DPU ranks.

Fails if the given number of DPU ranks cannot be allocated (unless DPU_ALLOCATE_ALL is used).

Parameters

nr_ranks	number of DPU ranks to allocate. Use `DPU_ALLOCATE_ALL` to allocate all available DPU ranks.
profile	list of (key=value) separated by comma to specify what kind of dpu to allocate. Use `NULL` for the default profile.
dpu_set	storage for the DPU set

Returns: Whether the operation was successful.

◆ dpu_broadcast_to()

dpu_error_t dpu_broadcast_to	(	struct dpu_set_t	dpu_set,
		const char *	symbol_name,
		uint32_t	symbol_offset,
		const void *	src,
		size_t	length,
		dpu_xfer_flags_t	flags
	)

Execute the broadcast memory transfer on the DPU set.

Parameters

dpu_set	the identifier of the DPU set
symbol_name	the name of the DPU symbol where the transfer starts
symbol_offset	the byte offset from the base DPU symbol address where the transfer starts
src	the host buffer containing the data to copy
length	the number of bytes to copy
flags	options of the transfer

Returns: Whether the operation was successful.

◆ dpu_broadcast_to_symbol()

dpu_error_t dpu_broadcast_to_symbol	(	struct dpu_set_t	dpu_set,
		struct dpu_symbol_t	symbol,
		uint32_t	symbol_offset,
		const void *	src,
		size_t	length,
		dpu_xfer_flags_t	flags
	)

Execute the broadcast memory transfer on the DPU set.

Parameters

dpu_set	the identifier of the DPU set
symbol	the DPU symbol where the transfer starts
symbol_offset	the byte offset from the base DPU symbol address where the transfer starts
src	the host buffer containing the data to copy
length	the number of bytes to copy
flags	options of the transfer

Returns: Whether the operation was successful.

◆ dpu_callback()

dpu_error_t dpu_callback	(	struct dpu_set_t	dpu_set,
		dpu_error_t()(struct dpu_set_t, uint32_t, void )	callback,
		void *	args,
		dpu_callback_flags_t	flags
	)

Execute a user-defined function with the given DPU set as argument.

Parameters

dpu_set	the identifier of the DPU set
callback	the function to call
args	the argument to pass to the callback function
flags	options of the callback

Returns: Whether the operation was successful.

◆ dpu_copy_from()

dpu_error_t dpu_copy_from	(	struct dpu_set_t	dpu_set,
		const char *	symbol_name,
		uint32_t	symbol_offset,
		void *	dst,
		size_t	length
	)

Copy data from one of the DPU memories to the Host memory buffer.

Parameters

dpu_set	the identifier of the DPU set
symbol_name	the name of the DPU symbol from where to copy the data
symbol_offset	the byte offset from the base DPU symbol address from where to copy the data
dst	the host buffer where the data is copied
length	the number of bytes to copy

Returns: Whether the operation was successful.

◆ dpu_copy_from_symbol()

dpu_error_t dpu_copy_from_symbol	(	struct dpu_set_t	dpu_set,
		struct dpu_symbol_t	symbol,
		uint32_t	symbol_offset,
		void *	dst,
		size_t	length
	)

Copy data from one of the DPU memories to the Host memory buffer.

Parameters

dpu_set	the identifier of the DPU set
symbol	the DPU symbol from where the data is copied
symbol_offset	the byte offset from the base DPU symbol address from where to copy the data
dst	the host buffer where the data is copied
length	the number of bytes to copy

Returns: Whether the operation was successful.

◆ dpu_copy_to()

dpu_error_t dpu_copy_to	(	struct dpu_set_t	dpu_set,
		const char *	symbol_name,
		uint32_t	symbol_offset,
		const void *	src,
		size_t	length
	)

Copy data from the Host memory buffer to one the DPU memories.

Parameters

dpu_set	the identifier of the DPU set
symbol_name	the name of the DPU symbol where to copy the data
symbol_offset	the byte offset from the base DPU symbol address where to copy the data
src	the host buffer containing the data to copy
length	the number of bytes to copy

Returns: Whether the operation was successful.

◆ dpu_copy_to_symbol()

dpu_error_t dpu_copy_to_symbol	(	struct dpu_set_t	dpu_set,
		struct dpu_symbol_t	symbol,
		uint32_t	symbol_offset,
		const void *	src,
		size_t	length
	)

Copy data from the Host memory buffer to one the DPU memories.

Parameters

dpu_set	the identifier of the DPU set
symbol	the DPU symbol where the data is copied
symbol_offset	the byte offset from the base DPU symbol address where to copy the data
src	the host buffer containing the data to copy
length	the number of bytes to copy

Returns: Whether the operation was successful.

◆ dpu_fifo_prepare_xfer()

dpu_error_t dpu_fifo_prepare_xfer	(	struct dpu_set_t	dpu_set,
		struct dpu_fifo_link_t *	fifo_link,
		void *	buffer
	)

Set the specified buffer to be transfered for the next DPU FIFO transfer.

Parameters

dpu_set	the identifier of the DPU set
fifo_link	the link to the DPU FIFOs
buffer	pointer to the host buffer

Returns: Whether the operation was successful.

◆ dpu_fifo_push_xfer()

dpu_error_t dpu_fifo_push_xfer	(	struct dpu_set_t	dpu_set,
		struct dpu_fifo_link_t *	fifo_link,
		dpu_xfer_flags_t	flags
	)

Execute the memory transfer on the DPU FIFOs.

Use the host buffers previously defined by dpu_fifo_prepare_xfer. When reading memory from the DPUs, if a host buffer is used for multiple DPUs, no error will be reported, and the buffer contents are undefined.

If the transfer is to the DPU FIFOs (input FIFO link), one element is transfered at a time If the transfer is from the DPU FIFOs (output FIFO link), all elements are transfered at a time (the output FIFO is emptied)

Parameters

dpu_set	the identifier of the DPU set
fifo_link	the link to the DPU FIFOs
flags	options of the transfer

Returns: Whether the operation was successful.

◆ dpu_free()

dpu_error_t dpu_free ( struct dpu_set_t dpu_set )

Free all the DPUs of a DPU set.

Note that this function will fail if called with a DPU set not provided by dpu_alloc.

Parameters

dpu_set the identifier of the freed DPU set

Returns: Whether the operation was successful.

◆ dpu_get_nr_dpus()

dpu_error_t dpu_get_nr_dpus	(	struct dpu_set_t	dpu_set,
		uint32_t *	nr_dpus
	)

Fetch the number of DPUs in a given DPU set.

Parameters

dpu_set	the DPU set identifier
nr_dpus	the number of DPUs in the DPU set

Returns: Whether the operation was successful.

◆ dpu_get_nr_ranks()

dpu_error_t dpu_get_nr_ranks	(	struct dpu_set_t	dpu_set,
		uint32_t *	nr_ranks
	)

Fetch the number of DPU ranks in a given DPU set.

Parameters

dpu_set	the DPU set identifier
nr_ranks	the number of DPU ranks in the DPU set

Returns: Whether the operation was successful.

◆ dpu_get_symbol()

dpu_error_t dpu_get_symbol	(	struct dpu_program_t *	program,
		const char *	symbol_name,
		struct dpu_symbol_t *	symbol
	)

Get the requested symbol information.

Parameters

program	the DPU program information
symbol_name	the name of the symbol to look for
symbol	where to store the symbol information if found

Returns: Whether the symbol was found.

◆ dpu_launch()

dpu_error_t dpu_launch	(	struct dpu_set_t	dpu_set,
		dpu_launch_policy_t	policy
	)

Request the boot of all the DPUs in a DPU set.

Parameters

dpu_set	the identifier of the DPU set we want to boot
policy	how to synchronize with the booted DPUs

Returns: Whether the operation was successful.

◆ dpu_load()

dpu_error_t dpu_load	(	struct dpu_set_t	dpu_set,
		const char *	binary_path,
		struct dpu_program_t **	program
	)

Load a program in all the DPUs of a DPU set.

Parameters

dpu_set	the targeted DPU set
binary_path	the path of the binary file we want to load in the DPUs
program	the DPU program information. Can be `NULL`.

Returns: Whether the operation was successful.

◆ dpu_load_from_incbin()

dpu_error_t dpu_load_from_incbin	(	struct dpu_set_t	dpu_set,
		struct dpu_incbin_t *	incbin,
		struct dpu_program_t **	program
	)

Load a program from a "struct dpu_incbin" in all the DPUs of a DPU set.

Parameters

dpu_set	the targeted DPU set.
incbin	the struct created with DPU_INCBIN
program	the DPU program information. Can be `NULL`.

Returns: Whether the operation was successful.

◆ dpu_load_from_memory()

dpu_error_t dpu_load_from_memory	(	struct dpu_set_t	dpu_set,
		uint8_t *	buffer,
		size_t	buffer_size,
		struct dpu_program_t **	program
	)

Load a program from the memory in all the DPUs of a DPU set.

Parameters

dpu_set	the targeted DPU set.
buffer	the buffer where the program is stored.
buffer_size	the size of the buffer
program	the DPU program information. Can be `NULL`.

Returns: Whether the operation was successful.

◆ dpu_log_read()

dpu_error_t dpu_log_read	(	struct dpu_set_t	set,
		FILE *	stream
	)

reads and displays the contents of the log of a DPU

Parameters

set	the dpu_set_t from which to extract the log (should be a single DPU)
stream	output stream where messages should be sent

Returns: whether the log was successfully read

◆ dpu_prepare_xfer()

dpu_error_t dpu_prepare_xfer	(	struct dpu_set_t	dpu_set,
		void *	buffer
	)

Set the Host buffer of all DPUs of the DPU set for the next memory transfer.

NULL can be used to clear the buffer pointer. An error will be reported if any buffer was already set; the buffer pointer will be overridden.

Parameters

dpu_set	the identifier of the DPU set
buffer	pointer to the host buffer

Returns: Whether the operation was successful.

◆ dpu_push_sg_xfer()

dpu_error_t dpu_push_sg_xfer	(	struct dpu_set_t	dpu_set,
		dpu_xfer_t	xfer,
		const char *	symbol_name,
		uint32_t	symbol_offset,
		size_t	length,
		get_block_t *	get_block_info,
		dpu_sg_xfer_flags_t	flags
	)

Execute the scatter/gather memory transfer on the DPU set.

First, prepare the host buffer blocks to be gathered from the HOST memory to the DPU MRAM or to be scattered from the DPU MRAM to the HOST memory, depending on the transfer direction. Then, performs the transfer. Blocks are prepared using the callback function (get_block_info.f), defined within the user application.

Parameters

dpu_set	the identifier of the DPU set
xfer	direction of the transfer
symbol_name	the name of the DPU symbol where the transfer starts
symbol_offset	the byte offset from the base DPU symbol address where the transfer starts
length	the number of bytes to copy
get_block_info	a structure containing user function and user arguments, used to prepare the transfer
flags	options of the transfer

Returns: Whether the operation was successful.

◆ dpu_push_sg_xfer_symbol()

dpu_error_t dpu_push_sg_xfer_symbol	(	struct dpu_set_t	dpu_set,
		dpu_xfer_t	xfer,
		struct dpu_symbol_t	symbol,
		uint32_t	symbol_offset,
		size_t	length,
		get_block_t *	get_block_info,
		dpu_sg_xfer_flags_t	flags
	)

Execute the scatter/gather memory transfer on the DPU set.

First, prepare the host buffer blocks to be gathered from the HOST memory to the DPU MRAM or to be scattered from the DPU MRAM to the HOST memory, depending on the transfer direction. Then, performs the transfer. Blocks are prepared using the callback function (get_block_info.f), defined within the user application.

Parameters

dpu_set	the identifier of the DPU set
xfer	direction of the transfer
symbol	the DPU symbol where the transfer starts
symbol_offset	the byte offset from the base DPU symbol address where the transfer starts
length	the number of bytes to copy
get_block_info	a structure containing user function and user arguments, used to prepare the transfer
flags	options of the transfer

Returns: Whether the operation was successful.

◆ dpu_push_xfer()

dpu_error_t dpu_push_xfer	(	struct dpu_set_t	dpu_set,
		dpu_xfer_t	xfer,
		const char *	symbol_name,
		uint32_t	symbol_offset,
		size_t	length,
		dpu_xfer_flags_t	flags
	)

Execute the memory transfer on the DPU set.

Use the host buffers previously defined by dpu_prepare_xfer. When reading memory from the DPUs, if a host buffer is used for multiple DPUs, no error will be reported, and the buffer contents are undefined.

Parameters

dpu_set	the identifier of the DPU set
xfer	direction of the transfer
symbol_name	the name of the DPU symbol where the transfer starts
symbol_offset	the byte offset from the base DPU symbol address where the transfer starts
length	the number of bytes to copy
flags	options of the transfer

Returns: Whether the operation was successful.

◆ dpu_push_xfer_symbol()

dpu_error_t dpu_push_xfer_symbol	(	struct dpu_set_t	dpu_set,
		dpu_xfer_t	xfer,
		struct dpu_symbol_t	symbol,
		uint32_t	symbol_offset,
		size_t	length,
		dpu_xfer_flags_t	flags
	)

Execute the memory transfer on the DPU set.

Use the host buffers previously defined by dpu_prepare_xfer. When reading memory from the DPUs, if a host buffer is used for multiple DPUs, no error will be reported, and the buffer contents are undefined.

Parameters

dpu_set	the identifier of the DPU set
xfer	direction of the transfer
symbol	the DPU symbol where the transfer starts
symbol_offset	the byte offset from the base DPU symbol address where the transfer starts
length	the number of bytes to copy
flags	options of the transfer

Returns: Whether the operation was successful.

◆ dpu_status()

dpu_error_t dpu_status	(	struct dpu_set_t	dpu_set,
		bool *	done,
		bool *	fault
	)

Fetch the current state of the DPU set.

Parameters

dpu_set	the identifier of the DPU set
done	whether all DPUs of the DPU set have finished
fault	whether any DPU of the DPU set is in fault

Returns: Whether the operation was successful.

◆ dpu_sync()

dpu_error_t dpu_sync ( struct dpu_set_t dpu_set )

Wait for the end of the execution on the DPU set.

Parameters

dpu_set the identifier of the DPU set

Returns: Whether the operation was successful.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ DPU_ASSERT

◆ DPU_CHECK

◆ DPU_FOREACH

◆ DPU_INCBIN

◆ DPU_RANK_FOREACH

Typedef Documentation

◆ get_block_func_t

Enumeration Type Documentation

◆ _dpu_callback_flags_t

◆ _dpu_launch_policy_t

◆ _dpu_sg_xfer_flags_t

◆ _dpu_xfer_flags_t

◆ _dpu_xfer_t

Function Documentation

◆ dpu_alloc()

◆ dpu_alloc_ranks()

◆ dpu_broadcast_to()

◆ dpu_broadcast_to_symbol()

◆ dpu_callback()

◆ dpu_copy_from()

◆ dpu_copy_from_symbol()

◆ dpu_copy_to()

◆ dpu_copy_to_symbol()

◆ dpu_fifo_prepare_xfer()

◆ dpu_fifo_push_xfer()

◆ dpu_free()

◆ dpu_get_nr_dpus()

◆ dpu_get_nr_ranks()

◆ dpu_get_symbol()

◆ dpu_launch()

◆ dpu_load()

◆ dpu_load_from_incbin()

◆ dpu_load_from_memory()

◆ dpu_log_read()

◆ dpu_prepare_xfer()

◆ dpu_push_sg_xfer()

◆ dpu_push_sg_xfer_symbol()

◆ dpu_push_xfer()

◆ dpu_push_xfer_symbol()

◆ dpu_status()

◆ dpu_sync()