This document describes how DaPPA turns a pipeline into a UPMEM program. It is meant for readers who want to modify or extend the framework. See the programming guide for how to use it.
| File | Contents |
|---|---|
include/dappa.h |
User-facing header: primitive and argument macros, compile-time switches. |
include/pipeline.h, src/pipeline.cpp, src/pipeline.tpp |
Pipeline: stage registration, data layout, code generation, execution, recipe and bbop emission. |
include/pipeline_full.h, src/pipeline_full.cpp |
PipelineFull: splits non-fusible stage sequences into several Pipelines. |
include/kernel.h, src/kernel.cpp |
Kernel: one stage, its arguments, and its per-tasklet cache layout. |
include/arg*.h, src/arg*.cpp |
Arg/ArgTyped: host buffers, flags, padding, reduction buffers. |
include/device.h, src/device.cpp |
Thin wrapper over the UPMEM host library (allocation, transfers, launch). |
src/device_template.c.inja |
Inja template of the DPU program. |
include/shared.h |
Structs shared between the host and the DPU program. |
include/logging.h |
Log macros for both the host and the DPU program. |
- Stage registration. Each primitive macro expands into the arguments of
Pipeline::stage(): the stage function as source text (#func), the same function as astd::function(used for the host-side share of the data), a tuple of typed arguments, and the window overlap and group size.stage()turns these into aKerneland records every argument by its host pointer, so that later stages can refer to the outputs of earlier ones. - Data layout (
calcElementCounts,calcOffsets). DaPPA splits the input into DPUs, tasklets, and rounds. A round is the amount of data that fits into the MRAM of all DPUs at once; larger inputs are processed in several rounds. Each tasklet streams its share through a small WRAM cache in blocks that keep every argument 8-byte aligned in MRAM. Windowed stages add an overlap region at tasklet boundaries. - Code generation (
buildJson). The stages and the layout are rendered intosrc/device_template.c.inja. The template,logging.h, andshared.hare embedded intolibdappaat build time withincbin, so the library has no run-time dependency on the source tree. - Compilation and execution. At
execute()time the generated C code is written to a temporary directory and compiled withdpu-upmem-dpurte-clang. The host then loads the binary, and, for every round, copies the inputs, launches the DPUs, and copies the fetched outputs back. A configurable share of the elements (DAPPA_TARGET_CPU_LOAD) is processed on the host in parallel, using thestd::functionversions of the stages. - Post-processing. Filtered outputs are compacted on the host, partial reductions of all tasklets and DPUs are merged with the combine function, and the per-block results of scans are offset into a global scan.
All decisions are driven by the argument flags (ArgFlags), not by the C++
types:
- Vectors (
INPUT,OUTPUT,INOUT) are sharded across DPUs and tasklets. Scalars (PARAMETER) are broadcast and stored once in WRAM. Lookup tables (LOOKUP_INPUT) are broadcast once into the MRAM of every DPU and read on demand. - Fusion. All stages of a
Pipelinerun in one DPU program, one element block at a time, so that intermediate vectors never leave WRAM. A stage that reads a filtered or reduced vector cannot be fused;PipelineFullstarts a newPipelineat that point. - Filtering. Filter stages mark elements as invalid instead of compacting them on the DPU. Compaction happens on the host while the next round runs, which avoids the synchronization between tasklets that on-DPU compaction requires.
- Reductions. Each reduction accumulator is replicated R times in WRAM. With R equal to the number of tasklets, every tasklet updates a private copy without locking. Large accumulators (e.g., histograms with many bins) use fewer copies, each protected by a mutex, so that enough WRAM remains for the input cache. If the accumulator does not fit in WRAM at all, the pipeline runs on the host.
- Interleaved indexing. Pipelines consisting only of map and reduce stages assign blocks to tasklets in a strided order, so that the tasklets' MRAM accesses are spread over time instead of contending in lockstep.
- Scans are computed in two passes per DPU (a local scan per tasklet, followed by applying the prefix of the preceding tasklets). The host then offsets each (round, DPU) block by the fold of all preceding blocks.
dpu_alloc is the most expensive host operation. The DPU set is therefore
allocated by the first Pipeline and reused by all later ones that use the
same number of DPUs (e.g., the layers of an MLP), which only load their own
program. The set is released at process exit.
include/device.h contains the parameters of the target DPU: 11 tasklets
(enough to fill the 11-stage revolver pipeline), 64 KB of WRAM, 64 MB of
MRAM, 512-byte tasklet stacks, and the MRAM and WRAM alignment. backend
selects the UPMEM backend ("simulator" for the SDK's functional simulator,
"" for real hardware).
execute() has two additional modes that stop before compiling the DPU
program:
DAPPA_EMIT_RECIPE=<dir>(emitRecipe) writes the generated code together with the exact MRAM and WRAM contents of every DPU for every round. Seeintegrations/upimulator.DAPPA_EMIT_BBOP=<dir>(emitBbop) lowers the stages to bulk bitwise operations for processing-using-DRAM. It runs before the UPMEM data layout is computed, since the backend does its own tiling. Seeintegrations/simdram.