Python Library

The UPMEM DPU toolchain contains a Python Host library to manage DPUs. It is based on the C Host library and provides a subset of its features, which should cover the main use cases. Knowing the C API should not be necessary to understand the Python API.

Contents

• dpu package
  • Subpackages
    • dpu.vpd package
      • Submodules
      • Module contents
  • Submodules
    • dpu.compiler module
      • Compiler
      • O0
      • O1
      • O2
      • O3
      • Os
      • Oz
      • getDpuArchVersion()
    • dpu.disasm module
      • Instruction
      • disassemble()
      • disassemble_raw()
    • dpu.driver module
      • DpuContext
      • DpuError
      • DpuProgram
      • DpuSet
      • DpuSymbol
      • DpuThreadContext
      • DpuVariable
  • Module contents

Overview

The following code is an example of a Python application with a simple DPU program with no real use case. The goal here is to present some of the main features of the Python API.

#!/bin/env python3

from dpu import DpuSet
from io import StringIO
from sys import stdout

DPU_PROGRAM = '''
    #include <mram.h>
    #include <stdint.h>
    #include <stdio.h>

    __mram uint64_t my_var; // Initialized by the host application

    int main() {
        uint64_t data = my_var;
        printf("My_Var before = 0x%016lx\\n", data);

        my_var = data + 1;

        return 0;
    }
'''

with DpuSet(nr_dpus=1, c_source=StringIO(DPU_PROGRAM)) as dpu:
    dpu.my_var = bytearray([0, 1, 2, 3, 4, 5, 6, 7])
    dpu.exec(log=stdout)
    value = dpu.my_var.uint64()
    print('My_Var after = 0x%016x' % value)

Creating a DpuSet will allocate a number of DPUs (which can be changed with the nr_dpus and defaults to the ALLOCATE_ALL value). It can be used as a context manager: the allocated DPUs will be freed at the end of the with block. Multiple parameters can be applied to the DpuSet constructor. Here c_source is used to compile and load the DPU program based on the Python string. binary could have been used instead to directly provide an existing file path for the DPU binary program. See the dpu.driver module for a complete documentation of the DpuSet methods.

All public DPU variables (using the __host or __mram attributes) are accessible in the DpuSet as attributes. Setting/Fetching one of these attributes will copy the provided data to/from the DPUs. For more options, the copy() method can be used.

The exec() method will boot the DPUs and wait until the program completion. Here the log parameter is also specified, to print the DPU logs on the host standard output.

When fetching a DPU attribute, the raw byte data can be retrieved with the data() method, but other methods, like uint64(), can be used to get directly an inter.

The program can be run with:

python3 python_example.py

And will give the output:

=== DPU#0x0 ===
My_Var before = 0x0706050403020100
My_Var after = 0x0706050403020101

Debugging

Some rudimentary debugging features are available when using the Python API. It is possible to use dpu-lldb to observe and attach to running DPUs. Notably, as described in Debugging a Host application, the dpu_attach_on_boot command will be useful to debug a DPU program.

Currently, the same features are not available while using Pdb.