# amzn/amzn-drivers architecture

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

- Interactive diagram: https://gitdiagram.com/amzn/amzn-drivers
- Repository: https://github.com/amzn/amzn-drivers

## Overview

##### Project type and purpose
- This is an open-source driver repository for AWS network and fabric adapters.
- It contains multiple platform-specific kernel modules (Linux and FreeBSD) and a user-space DPDK driver.
- It is not a typical client/server or web application, but a set of low-level components that interact directly with hardware.

##### File structure
- Top-level directories:
- kernel/linux/ena, kernel/linux/efa, kernel/linux/efa_nv_peermem
- kernel/fbsd/ena
- userspace/dpdk
- Each kernel directory contains sources, headers, build scripts (Makefile, CMakeLists, config, dkms, debian/rpm packaging).
- The userspace/dpdk directory contains backports, base code, meson.build—a DPDK Poll Mode Driver (PMD) for ENA.
- Configuration files (dkms.conf, configure.sh, intercept_cc.sh) show how modules are compiled and packaged.
- Licensing and READMEs in each component provide build/install instructions.

##### README for additional insights
- Lists four drivers: ENA (Linux/FreeBSD), EFA (Linux), EFA peer-memory (Linux), and the DPDK ENA PMD.

##### Elements
- Use rectangles for modules (ena.ko, efa.ko, PMD library).
- Use parallelograms for user-space drivers (DPDK PMD).
– Kernel-space (blue), user-space (green), packaging/build (orange), hardware (gray).
- Labels:

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Hardware Layer
    AWS_HW["AWS ENA/EFA NICs"]:::hardware

    %% OS Boundary
    subgraph "Host OS"
        direction TB
        Linux["Linux OS"]:::os
        FreeBSD["FreeBSD OS"]:::os
    end

    %% Kernel-space Modules and Shared Core
    subgraph "Kernel-space Modules" 
        direction TB
        subgraph "Linux Drivers"
            direction TB
            ENA_LK["ena.ko"]:::kernel
            EFA_LK["efa.ko"]:::kernel
            PEER_LK["efa_nv_peermem.ko"]:::kernel
            COM_LK["ena_com (common)"]:::kernel
        end
        subgraph "FreeBSD Drivers"
            direction TB
            ENA_FB["ena.ko"]:::kernel
            COM_FB["ena_com (common)"]:::kernel
        end
    end

    %% User-space DPDK Layer
    subgraph "User-space DPDK"
        direction TB
        PMD["ENA PMD Library"]:::userspace
        BACKPORTS["DPDK Backports"]:::userspace
        VFIO_PATCH["VFIO/UIO Patches"]:::userspace
    end

    %% Packaging & Build
    subgraph "Build & Packaging"
        direction TB
        DKMS["DKMS Config"]:::packaging
        CMAKE_EFA["EFA CMake"]:::packaging
        CMAKE_PEER["Peer-Memory CMake"]:::packaging
        RPM_ENA["ENA RPM"]:::packaging
        DEB_EFA["EFA Debian"]:::packaging
        DEB_PEER["Peer-Memory Debian"]:::packaging
    end

    %% Data Path
    AWS_HW -->|Data Path| ENA_LK
    AWS_HW -->|Data Path| EFA_LK
    AWS_HW -->|Data Path| PMD
    ENA_LK -->|Upcall| Linux
    EFA_LK -->|Upcall| Linux
    ENA_FB -->|Upcall| FreeBSD
    COM_LK -->|Shared Core| ENA_LK
    COM_LK -->|Shared Core| EFA_LK
    COM_LK -->|Shared Core| PEER_LK
    COM_FB -->|Shared Core| ENA_FB

    %% DPDK Data Path
    AWS_HW -->|VFIO/UIO| VFIO_PATCH
    VFIO_PATCH -->|Bind| PMD
    PMD -->|User App| Linux

    %% Control Path
    DKMS -.->|insmod/modprobe| ENA_LK
    DKMS -.->|insmod/modprobe| EFA_LK
    DKMS -.->|insmod/modprobe| PEER_LK
    Linux -->|sysfs/ethtool| ENA_LK
    Linux -->|sysfs/ethtool| EFA_LK

    %% Build Flows
    ENA_LK -->|source→build| DKMS
    ENA_LK -->|source→spec| RPM_ENA
    EFA_LK -->|source→cmake| CMAKE_EFA
    PEER_LK -->|source→cmake| CMAKE_PEER
    EFA_LK -->|debian scripts| DEB_EFA
    PEER_LK -->|debian scripts| DEB_PEER
    PMD -->|build| BACKPORTS

    %% Click Events
    click ENA_LK "https://github.com/amzn/amzn-drivers/tree/master/kernel/linux/ena"
    click ENA_FB "https://github.com/amzn/amzn-drivers/tree/master/kernel/fbsd/ena"
    click COM_LK "https://github.com/amzn/amzn-drivers/tree/master/kernel/linux/common/ena_com"
    click COM_FB "https://github.com/amzn/amzn-drivers/tree/master/kernel/fbsd/ena/ena-com"
    click EFA_LK "https://github.com/amzn/amzn-drivers/tree/master/kernel/linux/efa/src"
    click CMAKE_EFA "https://github.com/amzn/amzn-drivers/blob/master/kernel/linux/efa/CMakeLists.txt"
    click CMAKE_EFA "https://github.com/amzn/amzn-drivers/tree/master/kernel/linux/efa/conf/"
    click CMAKE_EFA "https://github.com/amzn/amzn-drivers/tree/master/kernel/linux/efa/debian/"
    click CMAKE_EFA "https://github.com/amzn/amzn-drivers/tree/master/kernel/linux/efa/rpm/"
    click PEER_LK "https://github.com/amzn/amzn-drivers/tree/master/kernel/linux/efa_nv_peermem/src"
    click CMAKE_PEER "https://github.com/amzn/amzn-drivers/blob/master/kernel/linux/efa_nv_peermem/CMakeLists.txt"
    click CMAKE_PEER "https://github.com/amzn/amzn-drivers/tree/master/kernel/linux/efa_nv_peermem/conf/"
    click CMAKE_PEER "https://github.com/amzn/amzn-drivers/tree/master/kernel/linux/efa_nv_peermem/debian/"
    click CMAKE_PEER "https://github.com/amzn/amzn-drivers/tree/master/kernel/linux/efa_nv_peermem/rpm/"
    click PMD "https://github.com/amzn/amzn-drivers/tree/master/userspace/dpdk/ena"
    click BACKPORTS "https://github.com/amzn/amzn-drivers/tree/master/userspace/dpdk/backports"
    click VFIO_PATCH "https://github.com/amzn/amzn-drivers/tree/master/userspace/dpdk/enav2-vfio-patch"
    click DKMS "https://github.com/amzn/amzn-drivers/blob/master/kernel/linux/ena/config/intercept_cc.sh"
    click DKMS "https://github.com/amzn/amzn-drivers/blob/master/kernel/linux/ena/configure.sh"
    click RPM_ENA "https://github.com/amzn/amzn-drivers/tree/master/kernel/linux/rpm"
    click DEB_EFA "https://github.com/amzn/amzn-drivers/tree/master/kernel/linux/efa/debian"
    click DEB_PEER "https://github.com/amzn/amzn-drivers/tree/master/kernel/linux/efa_nv_peermem/debian"

    %% Styles
    classDef hardware fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef os fill:#f0f0f0,stroke:#333,stroke-width:1px
    classDef kernel fill:#cce5ff,stroke:#004085,stroke-width:1px
    classDef userspace fill:#d4edda,stroke:#155724,stroke-width:1px
    classDef packaging fill:#fff3cd,stroke:#856404,stroke-width:1px
```
