# pulp-platform/dory architecture

> Architecture diagram of the GitHub repository pulp-platform/dory, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pulp-platform/dory
- Repository: https://github.com/pulp-platform/dory

## Overview

##### Project type and purpose
- DORY is a command-line, full-pipeline code-generation tool written in Python. It ingests quantized ONNX graphs (from Nemo/Quantlab), formulates a memory-tiling CP problem, and emits ANSI C code for multiple embedded hardware targets (GAP8, Diana, Occamy, PULP variants).
- It is neither a web app nor a microservice: it’s a modular, plugin-based compiler/code-generator.

##### File structure
- Top-level CLI scripts and Docker helper (`network_generate.py`, `layer_generate.py`, `docker_utils/`).
- Core Python package `dory/` with subpackages:
- Frontend_frameworks: NEMO & Quantlab ONNX pattern matchers.
- Hardware_targets: one plugin per SoC family (Diana, Occamy, PULP/(GAP8, GAP9, etc.)).
- Parsers: graph converters (ONNX→DORY IR→HW IR→C).
- Utils/Templates_writer: Mako-based C code templates for layers, networks, Makefiles.
- Configuration files (`*.json` rules, HW_description.json, .yml CI).
- Tests and examples in `conftest.py`, `test_PULP.py`, `dory_examples/`.

##### Extract README insights
- Highlights a multi-stage flow: ONNX import → CP tiling (OR-Tools) → codegen
- External dependencies: mako, numpy, onnx, ortools, pulp-sdk / gap-sdk
- Docker image for environment reproducibility

##### Main components & interactions
a. Frontend Plugins
- NEMO Parser
- Quantlab Parser
→ transform ONNX into DORY graphnodes.
b. Core Engine
- DORY IR (DORY_node, Layer_node, HW_node)
- Constraint Programming Solver (OR-Tools) → computes L3/L2/L1 tiling parameters.
c. Parsers/Translators
- Parser_DORY_to_HW: adapts DORY IR to hardware-specific IR.
- Parser_HW_to_C: prepares for codegen.
d. Templates & Code Generation
- Templates_writer: layer, network, Makefile templates (Mako)
→ Merges IR + tiling results into C, header, Makefiles.
e. Hardware Backends (plugin-based)
- Diana_SoC & Diana_TVM
- Occamy
- PULP family (GAP8, GAP9, NE16, gvsoc, etc.)
→ each provides Parsers, Pattern_rewriter, Templates, Utils_files
f. Output
- Generated C project tree (+ pulp-nn submodule) ready to compile/deploy.
g. Docker Environment
- docker_utils scripts → Dockerfile → reproducible Python + SDK setup

ONNX Input → (1) Frontend → DORY IR → (2) CP Solver → DORY IR + tiling params → (3) Parser_DORY_to_HW → HW IR → (4) Parser_HW_to_C → Template Writers → C/Makefiles → Output directory

##### Architectural patterns & principles
- Plugin architecture: separate `Frontend_frameworks` and `Hardware_targets` directories—each can be extended independently.
- Pipeline (compiler-style) pattern: successive transforms from ONNX → IR → optimized IR → code.
- Template-based codegen (Mako) for flexibility and hardware-specific customization.
- Separation of concerns: parsing, optimization (tiling), codegen, and platform integration are decoupled.

##### Essential elements to capture
- All plugin directories under `dory/Frontend_frameworks` and `dory/Hardware_targets`.
- Parsers in `dory/Parsers`.
- Utils/Templates_writer module.
- Docker scripts and CI workflows.
- External dependencies block.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        ORTools["OR-Tools"]:::external
        Mako["Mako"]:::external
        NumPy["NumPy"]:::external
        ONNXLib["onnx"]:::external
        SDK["pulp-sdk / gap-sdk"]:::external
    end

    %% Input
    ONNX["ONNX Model Input"]:::input

    %% Frontend
    subgraph "Frontend Plugins" 
        direction TB
        NEMO_Parser["NEMO Parser"]:::frontend
        NEMO_Pattern["NEMO Pattern Rewriter"]:::frontend
        Quantlab_Parser["Quantlab Parser"]:::frontend
        Quantlab_Pattern["Quantlab Pattern Rewriter"]:::frontend
    end

    %% Core Engine
    subgraph "Core Engine" 
        direction TB
        Parser_ONNX["Parser_ONNX_to_DORY"]:::core
        DORY_IR["DORY IR\n(DORY_node, Layer_node,\nHW_node)"]:::core
        CPSolver["Constraint Programming Solver"]:::opt
    end

    %% Translators
    subgraph "IR Translators"
        direction TB
        Parser_DORY_HW["Parser_DORY_to_HW"]:::core
        HW_IR["Hardware-specific IR"]:::core
        Parser_HW_C["Parser_HW_to_C"]:::core
    end

    %% Code Generation
    subgraph "Template-based Code Generation" 
        direction TB
        TemplateWriter["TemplateWriter"]:::codegen
        Layer1D["Layer1D Templates"]:::codegen
        Layer2D["Layer2D Templates"]:::codegen
        NetworkT["Network Templates"]:::codegen
        MakefileT["Makefile Templates"]:::codegen
    end

    %% Hardware Targets
    subgraph "Hardware Targets Plugins" 
        direction TB
        subgraph "Diana"
            direction TB
            Diana_SoC["Diana_SoC Plugin"]:::plugin
            Diana_TVM["Diana_TVM Plugin"]:::plugin
        end
        Occamy["Occamy Plugin"]:::plugin
        subgraph "PULP Family"
            direction TB
            PULP_Common["PULP Common Plugin"]:::plugin
            PULP_GAP8["PULP GAP8 Plugin"]:::plugin
            PULP_GAP9["PULP GAP9 Plugin"]:::plugin
            PULP_NE16["PULP GAP9_NE16 Plugin"]:::plugin
            Other_PULP["Other PULP Targets"]:::plugin
        end
    end

    %% Docker / CI
    subgraph "Docker & CI"
        direction TB
        DockerUtils["docker_utils/"]:::infra
        Dockerfile["Dockerfile"]:::infra
        CI[".github/workflows/docker-image.yml"]:::infra
    end

    %% Output
    Output["Generated C Project"]:::output

    %% Flows
    ONNX -->|feeds| NEMO_Parser
    ONNX -->|feeds| Quantlab_Parser

    NEMO_Parser -->|rewrites| NEMO_Pattern
    Quantlab_Parser -->|rewrites| Quantlab_Pattern

    NEMO_Pattern -->|produces ONNX graph| Parser_ONNX
    Quantlab_Pattern -->|produces ONNX graph| Parser_ONNX

    Parser_ONNX -->|generates| DORY_IR
    DORY_IR -->|optimizes| CPSolver
    CPSolver -->|annotates tiling| DORY_IR

    DORY_IR -->|translates| Parser_DORY_HW
    Parser_DORY_HW -->|yields| HW_IR

    HW_IR -->|translates| Parser_HW_C
    Parser_HW_C -->|provides IR| TemplateWriter

    Parser_HW_C -->|depends on| Mako
    TemplateWriter -->|uses| Layer1D
    TemplateWriter -->|uses| Layer2D
    TemplateWriter -->|uses| NetworkT
    TemplateWriter -->|uses| MakefileT

    TemplateWriter -->|emits| Output

    %% Plugin dependencies
    Parser_DORY_HW -->|plugin boundary| Diana_SoC
    Parser_DORY_HW -->|plugin boundary| Diana_TVM
    Parser_DORY_HW -->|plugin boundary| Occamy
    Parser_DORY_HW -->|plugin boundary| PULP_Common
    Parser_DORY_HW -->|plugin boundary| PULP_GAP8
    Parser_DORY_HW -->|plugin boundary| PULP_GAP9
    Parser_DORY_HW -->|plugin boundary| PULP_NE16
    Parser_DORY_HW -->|plugin boundary| Other_PULP

    %% Docker dependencies
    network_generate.py & layer_generate.py -->|use| DockerUtils
    DockerUtils --> Dockerfile
    Dockerfile --> SDK
    CI --> Dockerfile

    %% External libs usage
    CPSolver --> ORTools
    Parser_ONNX --> ONNXLib
    TemplateWriter --> NumPy

    %% Click Events
    click NEMO_Parser "https://github.com/pulp-platform/dory/blob/master/dory/Frontend_frameworks/NEMO/Parser.py"
    click NEMO_Pattern "https://github.com/pulp-platform/dory/blob/master/dory/Frontend_frameworks/NEMO/Pattern_rewriter.py"
    click Quantlab_Parser "https://github.com/pulp-platform/dory/blob/master/dory/Frontend_frameworks/Quantlab/Parser.py"
    click Quantlab_Pattern "https://github.com/pulp-platform/dory/blob/master/dory/Frontend_frameworks/Quantlab/Pattern_rewriter.py"
    click Parser_ONNX "https://github.com/pulp-platform/dory/blob/master/dory/Parsers/Parser_ONNX_to_DORY.py"
    click DORY_IR "https://github.com/pulp-platform/dory/blob/master/dory/Parsers/DORY_node.py"
    click DORY_IR "https://github.com/pulp-platform/dory/blob/master/dory/Parsers/Layer_node.py"
    click DORY_IR "https://github.com/pulp-platform/dory/blob/master/dory/Parsers/HW_node.py"
    click Parser_DORY_HW "https://github.com/pulp-platform/dory/blob/master/dory/Parsers/Parser_DORY_to_HW.py"
    click Parser_HW_C "https://github.com/pulp-platform/dory/blob/master/dory/Parsers/Parser_HW_to_C.py"
    click TemplateWriter "https://github.com/pulp-platform/dory/blob/master/dory/Utils/Templates_writer/TemplateWriter.py"
    click Layer1D "https://github.com/pulp-platform/dory/blob/master/dory/Utils/Templates_writer/Layer1D_templates_writer.py"
    click Layer2D "https://github.com/pulp-platform/dory/blob/master/dory/Utils/Templates_writer/Layer2D_template_writer.py"
    click NetworkT "https://github.com/pulp-platform/dory/blob/master/dory/Utils/Templates_writer/Network_template_writer.py"
    click MakefileT "https://github.com/pulp-platform/dory/blob/master/dory/Utils/Templates_writer/Makefile_template_writer.py"
    click Diana_SoC "https://github.com/pulp-platform/dory/tree/master/dory/Hardware_targets/Diana/Diana_SoC/"
    click Diana_TVM "https://github.com/pulp-platform/dory/tree/master/dory/Hardware_targets/Diana/Diana_TVM/"
    click Occamy "https://github.com/pulp-platform/dory/tree/master/dory/Hardware_targets/Occamy/"
    click PULP_Common "https://github.com/pulp-platform/dory/tree/master/dory/Hardware_targets/PULP/Common/"
    click PULP_GAP8 "https://github.com/pulp-platform/dory/tree/master/dory/Hardware_targets/PULP/GAP8/"
    click PULP_GAP9 "https://github.com/pulp-platform/dory/tree/master/dory/Hardware_targets/PULP/GAP9/"
    click PULP_NE16 "https://github.com/pulp-platform/dory/tree/master/dory/Hardware_targets/PULP/GAP9_NE16/"
    click Other_PULP "https://github.com/pulp-platform/dory/tree/master/dory/Hardware_targets/PULP/"
    click DockerUtils "https://github.com/pulp-platform/dory/tree/master/docker_utils/"
    click Dockerfile "https://github.com/pulp-platform/dory/tree/master/Dockerfile"
    click CI "https://github.com/pulp-platform/dory/blob/master/.github/workflows/docker-image.yml"

    %% Styles
    classDef input fill:#f9f,stroke:#333,stroke-width:1px;
    classDef frontend fill:#bbf,stroke:#333,stroke-width:1px;
    classDef core fill:#8dd,stroke:#333,stroke-width:1px;
    classDef opt fill:#fea,stroke:#333,stroke-width:1px;
    classDef codegen fill:#ffb,stroke:#333,stroke-width:1px;
    classDef plugin fill:#bfb,stroke:#333,stroke-width:1px;
    classDef infra fill:#ddd,stroke:#333,stroke-width:1px;
    classDef external fill:#eee,stroke:#333,stroke-width:1px;
    classDef output fill:#cfc,stroke:#333,stroke-width:1px;
```
