# pktgen/pktgen-dpdk architecture

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

- Interactive diagram: https://gitdiagram.com/pktgen/pktgen-dpdk
- Repository: https://github.com/pktgen/pktgen-dpdk

## Overview

##### Project Type and Purpose
- This is a high-performance, DPDK-powered traffic generator (“Pktgen”) written in C with an embedded Lua shell and a Python helper script (`tools/run.py`).
- It is not a web app but a CLI/networking tool comprising:
- Core packet-generation engine (app)
- Modular C libraries (`lib/cli`, `lib/common`, `lib/lua`, etc.)
- Scripting control (Lua + Python)
- Configuration files (in `cfg/`)

##### Key Top-Level Components
- app/               → main DPDK application (pktgen)
- lib/               → shared modules (CLI frontend, common utilities, Lua bindings, plugins)
- cfg/               → user configurations for interfaces, cores, themes
- tools/run.py       → Python wrapper to set up and launch pktgen with configs
- test/, examples/   → test scripts and sample code
- doc/               → documentation and Doxygen sources

##### Main Architectural Blocks
A. Packet Generator Engine (app/pktgen-*.c)
- Initializes DPDK EAL, allocates hugepages, binds PMDs
- Spawns per-port threads to generate/receive packets
- Implements multiple protocols (ARP, IPv4, TCP, UDP, etc.) via `pktgen-*.c` modules
B. CLI & Display Layer
- `lib/cli` provides line-editing, commands, autocomplete, history
- `pktgen-display.c` drives the terminal UI
C. Lua Scripting Layer
- Embedded Lua interpreter (`lib/lua`) exposes C API (`lua_dapi`, `lua_dpdk`, `lua_pktmbuf`, etc.)
- TCP control socket on port 22022 for remote scripting
D. Configuration Loader
- Python script `tools/run.py` reads `cfg/*.cfg`, sets up DPDK ports/cores, invokes `app/pktgen` with arguments
- In-app loader parses `.cfg` variables or external Lua scripts
E. Supporting Libraries
- `lib/common` – checksum, core info, port config, string utilities
- `lib/utils` – JSON, port lists, heap, IP parsing
- `lib/hmap`, `lib/vec` – data structures
- `lib/plugin` – plugin interface
F. External Interfaces
- Ethernet NICs via DPDK Poll Mode Drivers (PMDs)
- Remote TCP socket (Lua shell)
- Local terminal (CLI UI)
G. Documentation / Build / CI
- Meson build scripts (root `meson.build`, `app/meson.build`, etc.)
- GitHub Actions for lint/docs

##### Relationships and Data Flows
- Tools/run.py → (executes) → app/pktgen with CLI arguments & cfg files
- app/pktgen ↔ DPDK EAL ↔ NIC PMDs (data plane traffic)
- app/pktgen → lib/common, lib/utils, lib/cli for helper functions
- app/pktgen ↔ lib/lua for scripting commands
- External user → TCP socket → Lua shell → C API → packet engine
- CLI UI input → lib/cli → pktgen commands → modify generator state

##### Architectural Patterns & Design Principles
- Modular layering: core engine, CLI front-end, scripting API
- Plugin/extension points via `lib/plugin` and Lua hooks
- Separation of control plane (CLI/Lua/config) from data plane (DPDK packet loops)
- Build-time configuration using Meson

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Actors
    terminal["Local Terminal\n(CLI UI)"]:::external
    remote["Remote User"]:::external

    %% Control Plane
    tools["tools/run.py"]:::control
    cfg["cfg/*.cfg"]:::config

    %% Core Engine
    pktgen["Pktgen Core"]:::core

    subgraph "DPDK Stack"
        dpdk["DPDK EAL"]:::dpdk
        nics["NIC PMDs"]:::dpdk
    end

    %% Shared Libraries
    subgraph "Shared Libraries"
        common["lib/common"]:::libs
        utils["lib/utils"]:::libs
        hmap["lib/hmap"]:::libs
        vec["lib/vec"]:::libs
        plugin["lib/plugin"]:::libs
        cliLib["lib/cli"]:::control
        lualib["lib/lua"]:::control
    end

    %% Build, Docs, Tests
    meson["Meson Build & CI"]:::build
    doc["doc/"]:::docs
    tests["examples/ & test/"]:::docs

    %% Relationships - Control Flows
    terminal -->|CLI Input| cliLib -->|Commands| pktgen
    remote -->|TCP Socket 22022| lualib -->|Lua API Calls| pktgen
    tools -->|Startup & Args| pktgen
    cfg -->|Configuration| pktgen

    %% Relationships - Data Plane
    pktgen -->|Initializes| dpdk -->|Sends/Receives| nics

    %% Relationships - Libraries
    pktgen --> common
    pktgen --> utils
    pktgen --> hmap
    pktgen --> vec
    pktgen --> plugin
    pktgen --> cliLib
    pktgen --> lualib

    %% Build & Docs Integration
    meson --> pktgen
    meson --> common
    meson --> utils
    meson --> cliLib
    meson --> lualib
    doc -.-> meson
    tests -.-> meson

    %% Click Events
    click pktgen "https://github.com/pktgen/pktgen-dpdk/tree/main/app/"
    click dpdk "https://github.com/pktgen/pktgen-dpdk/blob/main/app/pktgen-main.c"
    click common "https://github.com/pktgen/pktgen-dpdk/tree/main/lib/common/"
    click utils "https://github.com/pktgen/pktgen-dpdk/tree/main/lib/utils/"
    click hmap "https://github.com/pktgen/pktgen-dpdk/tree/main/lib/hmap/"
    click vec "https://github.com/pktgen/pktgen-dpdk/tree/main/lib/vec/"
    click plugin "https://github.com/pktgen/pktgen-dpdk/tree/main/lib/plugin/"
    click cliLib "https://github.com/pktgen/pktgen-dpdk/tree/main/lib/cli/"
    click lualib "https://github.com/pktgen/pktgen-dpdk/tree/main/lib/lua/"
    click tools "https://github.com/pktgen/pktgen-dpdk/blob/main/tools/run.py"
    click cfg "https://github.com/pktgen/pktgen-dpdk/tree/main/cfg/"
    click meson "https://github.com/pktgen/pktgen-dpdk/blob/main/meson.build"
    click doc "https://github.com/pktgen/pktgen-dpdk/tree/main/doc/"
    click tests "https://github.com/pktgen/pktgen-dpdk/tree/main/examples/"

    %% Styles
    classDef external fill:#dddddd,stroke:#888,stroke-width:1px;
    classDef control fill:#c8e6c9,stroke:#2e7d32,stroke-width:1px;
    classDef config fill:#ffe0b2,stroke:#e65100,stroke-width:1px;
    classDef core fill:#ffccbc,stroke:#bf360c,stroke-width:2px;
    classDef dpdk fill:#b3e5fc,stroke:#01579b,stroke-width:1px;
    classDef libs fill:#fff9c4,stroke:#f9a825,stroke-width:1px;
    classDef build fill:#e1bee7,stroke:#6a1b9a,stroke-width:1px;
    classDef docs fill:#f8bbd0,stroke:#880e4f,stroke-width:1px;
```
