The UPMEM DPU toolchain
=======================

Notes before starting
---------------------

This document expects the reader to know the DPU architecture.

The toolchain purpose
---------------------

The UPMEM DPU toolchain is designed to answer the following requirements:
 * Creating the programs embedded on DPUs
 * Creating the host application that will drive the DPU programs
 * Debugging both the host application and the DPU programs

To this intent, it provides the following tools:
 * A C compiler to build DPU programs: dpu-upmem-dpurte-clang_

 * A `Runtime Library`__ for the DPU programs

 * A `Host Library`__ to create DPU-enabled host applications

 * A debugger for both host application & DPU programs: dpu-lldb_

.. _dpu-upmem-dpurte-clang:

dpu-upmem-dpurte-clang
----------------------

``dpu-upmem-dpurte-clang`` is the compiler for the DPU target. It is based on ``clang 12.0.0`` with the added support for the DPU target (which is the default target of ``dpu-upmem-dpurte-clang``).

See the official `Clang 10 documentation <https://releases.llvm.org/12.0.0/tools/clang/docs/index.html>`_ for any help with the tool.

As the DPU compiler is based on the LLVM compilation toolchain, UPMEM SDK also provides some utility tools from the LLVM compilation toolchain like ``llvm-objdump``, ``llvm-objcopy``, ``llvm-readelf`` and some others.

The DPU binaries generated by ``dpu-upmem-dpurte-clang`` are standard ``ELF`` files, for the DPU architecture.

Limitations
~~~~~~~~~~~

 * Dynamic libraries are not supported as the DPU does not support IO file operation.

 * Dynamic allocation on the stack is not supported.

.. __:

The DPU Runtime Library
-----------------------

The DPU Runtime Library is a set of functions for a DPU program that provides:

 * **MRAM** access
 * Synchronization primitives
 * Memory allocation
 * Performance counter
 * A subset of functions from the standard C library

See sections :doc:`Programming<03_ProgrammingWithUpmemDpu>` and :doc:`DPU Runtime Library<202_RTL>` for more information.

.. __:

The Host Library
----------------

The Host Library is a set of functions that allows a host application to:

 * Functions to read and write into the DPU memories
 * Functions to boot the DPU or to get its status

See sections :doc:`Programming<03_ProgrammingWithUpmemDpu>` and :doc:`Host Library<203_HostAPI>` for more information.
A :doc:`C++ API<205_CppHostAPI>`, a :doc:`Python API<PythonAPI/modules>` and a :doc:`Java API<206_JavaAPI>` are also available.

.. _dpu-lldb:

dpu-lldb
--------

UPMEM DPU programs can be debugged through ``dpu-lldb`` (based on ``lldb 12.0.0``).

`LLDB <https://lldb.llvm.org/>`_ `is a next-generation, high-performance debugger. It is built as a set of reusable components which highly leverage existing libraries in the larger LLVM Project, such as the Clang expression parser and LLVM disassembler.`

For GDB users, here is a document to easily find the corresponding LLDB command from a GDB one: `GDB to LLDB command map <https://lldb.llvm.org/use/map.html>`_

For more information about ``dpu-lldb`` see section :doc:`Debugging<08_DebuggingWithUpmemDpu>`.