dpu.driver module

Features to drive DPUs

class dpu.driver.DpuContext(c_ctx: LP_struct_dpu_context_t)

Bases: object

A snapshot of a Dpu state.

threads

the thread-specific contexts

Type:

List[DpuThreadContext]

atomic_bits() → List[bool]

Returns:

a copy of the atomic memory

Return type:

List[bool]

bkp_fault() → Optional[Tuple[int, int]]

Returns:

if a breakpoint fault has been triggered,

a tuple with the responsible thread index and the fault id, None otherwise

Return type:

Optional[Tuple[int, int]]

dma_fault() → Optional[int]

Returns:

if a DMA fault has been triggered,

the responsible thread index, None otherwise

Return type:

Optional[Tuple[int, int]]

static from_buffer(buf: memoryview) → DpuContext

Deserialize a DpuContext from a byte representation.

Parameters:

buf (memoryview) – the byte representation of the DpuContext

Returns:

a DpuContext object

Return type:

DpuContext

Raises:

DpuError – if the deserialization fails

iram() → Optional[List[int]]

Returns:

a copy of the IRAM instructions if the IRAM was saved, None otherwise

Return type:

Optional[List[int]]

mem_fault() → Optional[int]

Returns:

if a memory fault has been triggered,

the responsible thread index, None otherwise

Return type:

Optional[Tuple[int, int]]

mram() → Optional[List[int]]

Returns:

a copy of the MRAM bytes if the MRAM was saved, None otherwise

Return type:

Optional[List[int]]

serialize() → bytearray

Serialize the current DpuContext to a byte representation.

Returns:

a serialized representation of the DpuContext

Return type:

bytearray

Raises:

DpuError – if the serialization fails

wram() → Optional[List[int]]

Returns:

a copy of the WRAM 32-bit words if the WRAM was saved, None otherwise

Return type:

Optional[List[int]]

exception dpu.driver.DpuError

Bases: Exception

Error raised by the API

class dpu.driver.DpuProgram(c_program: LP_struct_dpu_program_t)

Bases: object

Representation of DPU program

fetch_all_symbols() → Dict[str, DpuSymbol]

get_symbol(symbol: str) → Optional[DpuSymbol]

Fetch a symbol in the program

Parameters:

symbol (str) – the name of the symbol to look for in the program

Returns:

the symbol if found, None otherwise

Return type:

Optional[DpuSymbol]

class dpu.driver.DpuSet(nr_dpus: Optional[int] = None, nr_ranks: Optional[int] = None, profile: str = '', binary: Optional[Union[bytes, str]] = None, c_source: Optional[Union[IOBase, str, List[Union[IOBase, str]]]] = None, asm_source: Optional[Union[IOBase, str, List[Union[IOBase, str]]]] = None, log: Optional[Union[IOBase, List[IOBase]]] = None, async_mode: Optional[bool] = False, _do_internals=True)

Bases: object

A set of DPUs

Parameters:

• nr_dpus (Optional[int]) – the number of DPUs to allocate ALLOCATE_ALL will allocate all available DPUs

• nr_ranks (Optional[int]) – the number of DPU ranks to allocate ALLOCATE_ALL will allocate all available DPU ranks Cannot be set at the same time as nr_dpus. Setting none of them will behave as ALLOCATE_ALL.

• profile (str) – the profile of the DPUs

• binary (Optional[DpuBinaryProgram]) – a DPU binary program to load after the allocation

• c_source (Optional[DpuSourceProgram]) – a DPU C source code to compile and load after the allocation

• asm_source (Optional[DpuSourceProgram]) – a DPU assembly source code to compile and load after the allocation

• log (Optional[DpuConstructorLogObject]) – a object where the DPU log will be written. The object can either be a file object or a list of file object with one object per dpu

• async_mode (Optional[bool]) – the default behavior for copy and exec methods

Raises:

DpuError – if the allocation fails

call(fn: Callable[[DpuSet, int, Any], None], arg: Any, async_mode: Optional[bool] = None, is_blocking: bool = True, single_call: bool = False)

Call the user-provided function on the DPU set.

Parameters:

• fn (DpuCallbackFunction) – function called on the DPU set

• arg (Any) – argument passed to the function

• async_mode (Optional[bool]) – override the default behavior set in the constructor

• is_blocking (bool) – whether the DPU set must wait the end of the function before accessing the DPU set again (default is True)

• single_call (bool) – whether the function is called once for the whole DPU set, instead of once per DPU rank (default is False)

Raises:

DpuError – if the operation fails

checkpoint(iram: bool = True, mram: bool = True, wram: bool = True) → DpuContext

Extract the complete context of the DPU

Parameters:

• iram (bool) – also save the IRAM (default is True)

• mram (bool) – also save the MRAM (default is True)

• wram (bool) – also save the WRAM (default is True)

Raises:

DpuError – if the DPU context cannot be fetched, or the DPU set is invalid for this operation

copy(dst: Union[str, DpuSymbol, bytes, bytearray, memoryview, array, List[Optional[Union[bytes, bytearray, memoryview, array]]]], src: Union[str, DpuSymbol, bytes, bytearray, memoryview, array, List[Optional[Union[bytes, bytearray, memoryview, array]]]], size: Optional[int] = None, offset: int = 0, async_mode: Optional[bool] = None)

Copy data between the Host and the DPUs

Parameters:

• dst (DpuCopyBuffer) – the destination buffer for the copy. If the buffer is on the Host, this must be a bytearray, or a list of optional bytearrays. If the buffer is on the DPUs, this must be a str, representing a DPU symbol, or directly a DpuSymbol.

• src (DpuCopyBuffer) – the source buffer for the copy. If the buffer is on the Host, this must be a bytearray, or a list of optional bytearrays. If the buffer is on the DPUs, this must be a str, representing a DPU symbol, or directly a DpuSymbol.

• size (Optional[int]) – number of bytes to transfer. By default set to None, which will use the length of the Host buffer. If multiple Host buffers are provided, all buffers must have the same size.

• offset (int) – offset in bytes for the DPU symbol. By default set to 0.

• async_mode (Optional[bool]) – override the default behavior set in the constructor.

Raises:

DpuError – if the copy fails, because of invalid arguments, unknown symbols or out-of-bound accesses

dpus() → List[DpuSet]

Provides a List on the DPUs of the DPU set

exec(log: Optional[Union[IOBase, List[IOBase], Dict[DpuSet, IOBase]]] = None, async_mode: Optional[bool] = None)

Execute a program on the DPUs

Parameters:

• log (Optional[DpuExecLogObject]) – a object where the DPU log will be written. The object can either be a file object or a list of file object with one object per dpu or a dictionary of file object

• async_mode (Optional[bool]) – override the default behavior set in the constructor. When in asynchronous mode, the log argument is ignored.

Raises:

DpuError – if the program cannot be loaded, or the execution triggers a fault

free()

Release the DPUs of the set

load(binary: Optional[Union[bytes, str]] = None, c_source: Optional[Union[IOBase, str, List[Union[IOBase, str]]]] = None, asm_source: Optional[Union[IOBase, str, List[Union[IOBase, str]]]] = None) → DpuProgram

Load a program in the DPUs

Parameters:

• binary (Optional[DpuBinaryProgram]) – the DPU binary program to load

• c_source (Optional[DpuSourceProgram]) – the DPU C source code to compile and load

• asm_source (Optional[DpuSourceProgram]) – the DPU assembly source code to compile and load

Returns:

a representation of the loaded program

Return type:

DpuProgram

Raises:

DpuError – if the program cannot be loaded

log(stream: Optional[Union[IOBase, List[IOBase], Dict[DpuSet, IOBase]]] = None)

Print the DPU log on the Host standard output

Parameters:

stream – a writable object. If not specify, uses either the one specified in DpuSet’s constructor or sys.stdout otherwise

Raises:

DpuError – if the DPU log buffer cannot be fetched, or the DPU set is invalid for this operation

ranks() → List[DpuSet]

Provides a List on the ranks of the DPU set

restore(context: DpuContext, iram: bool = True, mram: bool = True, wram: bool = True)

Apply the context to the DPU

Parameters:

• context – the context to restore

• iram (bool) – also restore the IRAM (default is True)

• mram (bool) – also restore the MRAM (default is True)

• wram (bool) – also restore the WRAM (default is True)

Raises:

DpuError – if the DPU context cannot be restored, or the DPU set is invalid for this operation

sync()

Wait for all asynchronous operations to be complete

Raises:

DpuError – if the DPU set is invalid for this operation

class dpu.driver.DpuSymbol(name: str, c_symbol: Union[struct_dpu_symbol_t, Tuple[int, int]])

Bases: object

Symbol in a DPU program

name

the name of the symbol

Type:

str

size() → int

Fetch the symbol size

Returns:

the symbol size

Return type:

int

value() → int

Fetch the symbol value (ie. when done on a variable, its address)

Returns:

the symbol value

Return type:

int

class dpu.driver.DpuThreadContext(ctx: DpuContext, idx: int)

Bases: object

Thread-specific context from a DpuContext.

idx

the thread index

Type:

int

cf() → bool

Returns:

the thread Carry Flag

Return type:

bool

pc() → int

Returns:

the thread Program Counter

Return type:

int

regs() → List[int]

Returns:

a copy of the thread work register values

Return type:

List[int]

zf() → bool

Returns:

the thread Zero Flag

Return type:

bool

class dpu.driver.DpuVariable(contents: List[memoryview])

Bases: object

data() → Union[memoryview, List[memoryview]]

double() → Union[float, List[float], Sequence[float], List[Sequence[float]]]

float() → Union[float, List[float], Sequence[float], List[Sequence[float]]]

int16() → Union[int, List[int], Sequence[int], List[Sequence[int]]]

int32() → Union[int, List[int], Sequence[int], List[Sequence[int]]]

int64() → Union[int, List[int], Sequence[int], List[Sequence[int]]]

int8() → Union[int, List[int], Sequence[int], List[Sequence[int]]]

uint16() → Union[int, List[int], Sequence[int], List[Sequence[int]]]

uint32() → Union[int, List[int], Sequence[int], List[Sequence[int]]]

uint64() → Union[int, List[int], Sequence[int], List[Sequence[int]]]

uint8() → Union[int, List[int], Sequence[int], List[Sequence[int]]]