# opendataplane/odp architecture

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

- Interactive diagram: https://gitdiagram.com/opendataplane/odp
- Repository: https://github.com/opendataplane/odp

## Overview

##### Project type and purpose
- This is OpenDataPlane (ODP), a C-language SDK and runtime library that provides a portable, high-performance data-plane abstraction for packet processing across multiple CPU architectures and platforms.
- It is not a web application or microservice; it is a core library (libodp) plus helper library (libodphelper), examples, and a comprehensive test suite.

##### High-level architecture and file-structure analysis
- Top-level components/directories:
- /odp/api – public C headers defining the ODP API (abstract data-plane functions)
- /odp/api/abi-default + include/odp/api/spec + include/odp/arch/* – ABI and architecture-specific interfaces
- arch/… – architecture-agnostic API dispatch stubs
- platform/linux-generic/… – core implementation of ODP functionality, subdivided into modules (atomic, packet, event, crypto, pktio, scheduler, timer, traffic_mngr, etc.) and platform drivers (DPDK, pcap, socket, etc.)
- helper/ – utility library implementing CLI tools, checksum routines, thread/process helpers (libodphelper)
- example/ – sample applications demonstrating how to link and call the public ODP API
- test/ & platform/linux-generic/test/ – unit, validation, and performance tests organized by API module and example
- scripts/, .github/, Makefile.am, configure.ac, m4/ – build and CI infrastructure

##### Key relationships and data flows
- Application code (user or example/test) links against libodp and libodphelper.
- At runtime, application calls a function in the ODP API header (e.g., odp_queue_deq()).
- API call is forwarded through a generic dispatcher stub in arch/ that selects the platform implementation.
- Platform implementation (in platform/linux-generic/) invokes the chosen driver (e.g., pktio/pcap.c or pktio/dpdk.c for packet I/O) or core module (atomic, crypto, event).
- Architecture-specific inlines/ABI files in include/odp/api/abi-default or include/odp/arch/* provide optimized implementations per architecture.
- Helper library functions provide non-API services (CLI, debug, checksums) and are statically or dynamically linked.
- Build system (bootstrap → configure → make) invokes autotools, configures modules and external dependencies (OpenSSL, DPDK, libconfig), compiles architecture and platform files, and assembles libodp, libodphelper, examples, and tests.
- CI pipelines and GitHub actions orchestrate multi-architecture builds, code style checks, coverage, and deployment of Doxygen docs.

##### Important architectural patterns and design principles
- Layered modularity: public API → dispatcher → core modules → drivers
- Pluggable backends: pktio, crypto, scheduler choices are selected at configure-time
- ABI/architecture separation: generic API in headers with architecture-specific inline overrides
- Clear separation of concerns: helper utilities separated from core data-plane logic
- Extensive testing: unit, validation, and performance tests ensure API conformance across platforms

##### Elements
- Clear labels: “Application”, “ODP API”, “Dispatcher (arch)”, “Core Modules”, “Drivers”, “Helper Lib”
- Application → ODP API → Dispatcher → Core Module → Driver
- Build system → compiles and links all layers
- CI pipeline → triggers build system and test suite

a. A stack of 4 layers (Application, API, Implementation, Drivers).
b. In the Application layer, place “Examples/Tests” and “User App”.
e. In the Implementation layer, subdivide into named modules (atomic, packet/pktio, event, crypto, queue, scheduler, timer, traffic_mngr).
f. In the Drivers layer, place “pktio backends (DPDK, pcap, socket, null)”, “crypto backends (OpenSSL, IPsecMB, Null)”, “platform services (shmem, CPU info)”.

## Diagram (Mermaid)

```mermaid
graph TB

    %% Application Layer
    subgraph "Application Layer"
        EX["Example Applications"]:::app
        TA["Test Suites"]:::app
        UA["User Applications"]:::app
    end

    %% API Layer
    subgraph "API Layer"
        API["Public API\ninclude/odp/api"]:::api
        ABI["ABI Default Interfaces\ninclude/odp/api/abi-default"]:::api
        SPEC["API Spec Interfaces\ninclude/odp/api/spec"]:::api
    end

    %% Dispatch & Core Modules Layer
    subgraph "Dispatch & Core Modules"
        DISPATCH["Dispatcher (arch stubs)\ninclude/odp/arch"]:::impl
        subgraph "Core Modules"
            AT["Atomic Module\nodp_atomic_api.c"]:::impl
            EV["Event Module\nodp_event_api.c"]:::impl
            PK["Packet Module\nodp_packet_io_api.c"]:::impl
            CR["Crypto Module\nodp_crypto_api.c"]:::impl
            SC["Scheduler Module\nodp_schedule_api.c"]:::impl
            TI["Timer Module\nodp_timer_api.c"]:::impl
            TM["Traffic Mngr\nodp_traffic_mngr.c"]:::impl
        end
    end

    %% Drivers & Third-Party Layer
    subgraph "Drivers & Third-Party"
        PKTIO["Packet I/O Drivers\nplatform/linux-generic/pktio"]:::driver
        CRYPTO["Crypto Backends\nplatform/linux-generic"]:::driver
        PLAT["Platform Services\nshmem, CPU info"]:::driver
    end

    %% Helper Library
    HELPER["Helper Library\nhelper/"]:::impl

    %% Build & CI
    subgraph "Infrastructure"
        BUILD["Build System\nbootstrap, configure.ac, Makefile.am, m4/, scripts/"]:::build
        CI["CI Pipeline\n.github/workflows, .github/actions"]:::build
    end

    %% Connections
    EX -->|calls| API
    TA -->|calls| API
    UA -->|calls| API

    API -->|forwards to| DISPATCH
    ABI -->|provides overrides| DISPATCH
    SPEC -->|defines interfaces| API

    DISPATCH --> AT
    DISPATCH --> EV
    DISPATCH --> PK
    DISPATCH --> CR
    DISPATCH --> SC
    DISPATCH --> TI
    DISPATCH --> TM

    PK -->|uses| PKTIO
    CR -->|uses| CRYPTO

    HELPER --> EX
    HELPER --> UA

    BUILD --> API
    BUILD --> DISPATCH
    BUILD --> AT
    BUILD --> EV
    BUILD --> PK
    BUILD --> CR
    BUILD --> SC
    BUILD --> TI
    BUILD --> TM
    BUILD --> PKTIO
    BUILD --> CRYPTO
    BUILD --> HELPER

    CI --> BUILD
    CI --> TA

    %% Click Events
    click EX "https://github.com/opendataplane/odp/tree/master/example/"
    click TA "https://github.com/opendataplane/odp/tree/master/test/validation/api"
    click API "https://github.com/opendataplane/odp/tree/master/include/odp/api"
    click ABI "https://github.com/opendataplane/odp/tree/master/include/odp/api/abi-default"
    click SPEC "https://github.com/opendataplane/odp/tree/master/include/odp/api/spec"
    click DISPATCH "https://github.com/opendataplane/odp/tree/master/include/odp/arch"
    click AT "https://github.com/opendataplane/odp/blob/master/platform/linux-generic/odp_atomic_api.c"
    click EV "https://github.com/opendataplane/odp/blob/master/platform/linux-generic/odp_event_api.c"
    click PK "https://github.com/opendataplane/odp/blob/master/platform/linux-generic/odp_packet_io_api.c"
    click CR "https://github.com/opendataplane/odp/blob/master/platform/linux-generic/odp_crypto_api.c"
    click SC "https://github.com/opendataplane/odp/blob/master/platform/linux-generic/odp_schedule_api.c"
    click TI "https://github.com/opendataplane/odp/blob/master/platform/linux-generic/odp_timer_api.c"
    click TM "https://github.com/opendataplane/odp/blob/master/platform/linux-generic/odp_traffic_mngr.c"
    click PKTIO "https://github.com/opendataplane/odp/tree/master/platform/linux-generic/pktio"
    click CRYPTO "https://github.com/opendataplane/odp/tree/master/platform/linux-generic"
    click HELPER "https://github.com/opendataplane/odp/tree/master/helper/"
    click BUILD "https://github.com/opendataplane/odp/tree/master/scripts/"
    click CI "https://github.com/opendataplane/odp/tree/master/.github/workflows"

    %% Styles
    classDef api fill:#D0E6FA,stroke:#0B5394,color:#0B5394;
    classDef impl fill:#DFF2D8,stroke:#38761D,color:#38761D;
    classDef driver fill:#FEF3C3,stroke:#BF9000,color:#BF9000;
    classDef build fill:#E7E6E6,stroke:#666666,color:#666666;
    classDef app fill:#F2E2FF,stroke:#7D3C98,color:#7D3C98;
```
