# mellanox/libvma architecture

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

- Interactive diagram: https://gitdiagram.com/mellanox/libvma
- Repository: https://github.com/mellanox/libvma

## Overview

##### Main Components
- Core VMA Library: Represent the primary “libvma” component (located under src/vma) as the heart of the system. This includes submodules for configuration parsing, network protocol handlers (src/vma/proto), and socket forwarding (src/vma/sock).
- Hardware Interaction Modules: Highlight components involved in direct network device management and low-level I/O. For example:
– The “dev” directory (src/vma/dev) with various device managers (e.g., cq_mgr, qp_mgr, ring management, etc.)
– Infiniband (src/vma/ib) and related hardware abstraction for MLX5.
- Event Handling and I/O Multiplexing: Note the modules under “event” (src/vma/event) and “iomux” (src/vma/iomux) that implement event loops and system call wrappers (epoll, poll, etc.).
- Auxiliary Modules: Include supporting libraries like:
– State Machine (src/state_machine)
– Stats collection and logging (src/stats and src/vlogger)
– Utility functions (src/utils and src/vma/util)
- Build, Configuration, and Deployment Tools: Indicate the CI/CD configuration (in the .ci and .github directories), the build system (configure.ac, autogen.sh, Makefile.am files), and packaging scripts (e.g., debian and contrib directories).
- Tests Framework: Include test frameworks (tests/ folder containing gtest-based tests, latency, throughput, and various API and functionality tests) that validate the core functionality of the libvma.

##### Interactions and Relationships
- How components in the “event” and “iomux” modules interact with the underlying OS’s event mechanisms to facilitate asynchronous operations.
- Dependency paths from configuration parsing to device management, protocol handling, event processing, and logging/instrumentation.

##### Architectural Patterns and Design Principles
- Modularity: Emphasize the modular design—the separation among core libraries (libvma), supporting utilities (stats, state machine, logging), and device-specific implementations.
- Asynchronous and Event-Driven Design: Include the event multiplexer (iomux) and timeout/timer modules (event/timer_handler), which are key for high-performance message processing.

##### Relevant Technologies, Frameworks, and Libraries
- Standard Build Tools: Autotools (configure.ac, Makefile.am) and CI pipelines (Jenkins, GitHub Actions) as seen in the .ci and contrib directories.
- Testing Framework: gtest is used heavily (as shown in tests/gtest) along with various integration and latency tests.
- Low-Level Networking Libraries: Components related to Infiniband (src/vma/ib) and the lwIP stack (src/vma/lwip) are critical.

## Diagram (Mermaid)

```mermaid
flowchart TD
    External_App["External Application (Socket API)"]:::external

    LibVMA_Core["LibVMA Core"]:::core
    Config_C["Config Parser (C)"]:::core
    Config_H["Config Parser (H)"]:::core
    Protocol_Handlers["Protocol Handlers"]:::core
    Socket_Forwarding["Socket Forwarding"]:::core
    Event_Handling["Event Handling"]:::core
    IO_Multiplexing["I/O Multiplexing"]:::core
    State_Machine["State Machine"]:::core

    Utility_Functions["Utility Functions"]:::utility
    VMA_Utilities["VMA Utilities"]:::utility
    Stats_Collection["Stats Collection"]:::utility
    Logging["Logging"]:::utility

    Device_Management["Device Management"]:::hardware
    Infiniband_Support["Infiniband Support"]:::hardware
    lwIP_Stack["lwIP Stack"]:::hardware

    Build_Tools["Build Tools"]:::ci
    CI_CD["CI/CD & Deployment"]:::ci
    Tests_Framework["Tests Framework"]:::test

    %% Relationships
    External_App -->|"calls"| LibVMA_Core

    LibVMA_Core -->|"uses"| Config_C
    LibVMA_Core -->|"uses"| Config_H
    LibVMA_Core -->|"handles"| Protocol_Handlers
    LibVMA_Core -->|"forwards via"| Socket_Forwarding
    LibVMA_Core -->|"triggers"| Event_Handling
    LibVMA_Core -->|"triggers"| IO_Multiplexing
    LibVMA_Core -->|"controls"| State_Machine
    LibVMA_Core -->|"utilizes"| Utility_Functions
    LibVMA_Core -->|"utilizes"| VMA_Utilities
    LibVMA_Core -->|"reports to"| Stats_Collection
    LibVMA_Core -->|"logs with"| Logging
    LibVMA_Core -->|"integrates with"| Build_Tools
    LibVMA_Core -->|"integrates with"| CI_CD
    LibVMA_Core -->|"validated by"| Tests_Framework

    State_Machine -->|"manages"| Device_Management
    State_Machine -->|"manages"| Infiniband_Support
    State_Machine -->|"manages"| lwIP_Stack

    %% Click Events
    click LibVMA_Core "https://github.com/mellanox/libvma/tree/master/src/vma"
    click Config_C "https://github.com/mellanox/libvma/blob/master/src/vma/config_parser.c"
    click Config_H "https://github.com/mellanox/libvma/blob/master/src/vma/config_parser.h"
    click Protocol_Handlers "https://github.com/mellanox/libvma/tree/master/src/vma/proto"
    click Socket_Forwarding "https://github.com/mellanox/libvma/tree/master/src/vma/sock"
    click Event_Handling "https://github.com/mellanox/libvma/tree/master/src/vma/event"
    click IO_Multiplexing "https://github.com/mellanox/libvma/tree/master/src/vma/iomux"
    click State_Machine "https://github.com/mellanox/libvma/tree/master/src/state_machine"
    click Utility_Functions "https://github.com/mellanox/libvma/tree/master/src/utils"
    click VMA_Utilities "https://github.com/mellanox/libvma/tree/master/src/vma/util"
    click Stats_Collection "https://github.com/mellanox/libvma/tree/master/src/stats"
    click Logging "https://github.com/mellanox/libvma/tree/master/src/vlogger"
    click Device_Management "https://github.com/mellanox/libvma/tree/master/src/vma/dev"
    click Infiniband_Support "https://github.com/mellanox/libvma/tree/master/src/vma/ib"
    click lwIP_Stack "https://github.com/mellanox/libvma/tree/master/src/vma/lwip"
    click Build_Tools "https://github.com/mellanox/libvma/blob/master/configure.ac"
    click CI_CD "https://github.com/mellanox/libvma/blob/master/.ci"
    click Tests_Framework "https://github.com/mellanox/libvma/tree/master/tests"

    %% Class Definitions
    classDef external fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef core fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef utility fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef hardware fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef ci fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef test fill:#f8f9fa,stroke:#6c757d,stroke-width:2px;
```
