# intel/qatlib architecture

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

- Interactive diagram: https://gitdiagram.com/intel/qatlib
- Repository: https://github.com/intel/qatlib

## Overview

##### Project Type & Purpose
- This is a low-level, system-library project (Intel QATlib) that provides hardware-accelerated crypto and compression services via user-space libraries and a management daemon. It is _not_ a web or full-stack app but a hardware offload integration toolkit.

##### High-Level Architecture Components
a. User-Space Applications & Samples
- Your production code or sample programs (quickassist/lookaside/.../sample_code) that call the QAT API.
b. libqat (Access Layer)
- Implements the QuickAssist API (crypto + compression) in C under quickassist/lookaside/access_layer.
- Divided into _common_ utilities, _crypto_ modules (sym/asym), _compression_ modules (dc), _direct_ transport (VFIO), controller, and firmware‐loading stubs.
c. libusdm (User-Space DMA/Mem)
- Manages hugepage allocation, pinning, IOMMU mappings (utilities/libusdm_drv).
d. OS Abstraction Layer (OSAL)
- Uniform threading, atomics, mutexes, logging, service helpers, kernel-proxy IPC (utilities/osal).
e. qatmgr Daemon
- A service (Systemd unit template under utilities/service) that enumerates devices, configures rings, manages PF/VF assignments, and publishes capabilities to clients.
f. Kernel-Space & Hardware
- VFIO driver + in-tree QAT kernel module exposed via /dev/vfio and PF/VF IOCTLs.
- On-card firmware loaded by the driver.
- QAT accelerator ASIC on PCIe bus.

##### Relationships & Data Flows
- Applications → link against → libqat API
- libqat → uses → libusdm for buffer allocation & mapping
- libqat → uses → OSAL for threading, mutex, logging, user-kernel proxy
- libqat → issues I/O via → VFIO ioctl to QAT kernel driver
- Kernel driver → schedules requests → hardware queues → ASIC
- Hardware → processes → returns completions → kernel → libqat callbacks
- qatmgr ↔ kernel driver: control plane for ring→service mapping, device reset, heartbeat
- Applications ↔ qatmgr: _optional_ for dynamic re-configuration or status queries

##### Architectural Patterns & Principles
- Layered design: API layer (libqat) → abstraction layer (OSAL) → transport layer (VFIO) → kernel → hardware
- Modular separation: crypto vs compression vs memory mgmt vs control plane
- Plugin-style firmware loading and service registration (controller interfaces)
- Daemon for out-of-band device management (qatmgr)

##### Key Technologies & Files
- Autotools build (configure.ac, Makefile.am) – for context only.
- quickassist/include: Public headers (cpa.h, cpa_dev.h).
- quickassist/lookaside/access_layer: core logic & transport.
- utilities/libusdm_drv: memory management.
- utilities/osal: cross-platform abstractions.
- utilities/qat_mgr: daemon logic.
- service unit (.service.in) & init script.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User-Space Applications
    subgraph "User-Space Applications"
        SampleApps["Sample Applications\n(sample_code)"]:::userlib
    end

    %% QATlib Libraries
    subgraph "QATlib Libraries"
        PublicHeaders["Public API Headers\n(cpa.h, cpa_dev.h)"]:::userlib
        LibQAT["libqat Access Layer"]:::userlib
        Crypto["Crypto Engine\n(cpaCySymPerformOp)"]:::userlib
        Compression["Compression Engine"]:::userlib
        DirectTransport["Direct Transport\n(VFIO)"]:::userlib
        FirmwareStubs["Firmware Loader Stubs"]:::userlib
        LibUSDM["libusdm Memory Management"]:::userlib
        OSAL["OS Abstraction Layer\n(threading, IPC)"]:::userlib
    end

    %% Kernel-Space
    subgraph "Kernel-Space"
        VFIO["VFIO Driver (/dev/vfio)"]:::kernel
        QATKernel["QAT Kernel Module"]:::kernel
    end

    %% Hardware
    subgraph "Hardware"
        ASIC["QAT Accelerator ASIC"]:::hardware
    end

    %% Control Plane Daemon
    subgraph "Control Plane Daemon"
        qatmgr["qatmgr Daemon"]:::daemon
        Systemd["Systemd Unit\n(qat.service.in)"]:::daemon
        InitScript["Init Script\n(qat_init.sh.in)"]:::daemon
    end

    %% Data Plane Flows
    SampleApps -->|"link against"| LibQAT
    SampleApps -->|"includes headers"| PublicHeaders

    LibQAT -->|"uses DMA buffers"| LibUSDM
    LibQAT -->|"uses threading/IPC"| OSAL
    LibQAT -->|"issues ioctl/VFIO"| VFIO
    LibQAT -->|"cpaCySymPerformOp()"| Crypto
    LibQAT -->|"compression APIs"| Compression
    LibQAT -->|"loads firmware"| FirmwareStubs
    LibQAT -->|"direct transport"| DirectTransport

    VFIO -->|"ioctl/VFIO"| QATKernel
    QATKernel -->|"schedules requests"| ASIC
    ASIC -->|"returns completions"| QATKernel
    QATKernel -->|"callback completions"| LibQAT

    %% Control Plane Flows
    qatmgr -->|"control plane (ring config)"| QATKernel
    qatmgr -->|"status queries (optional)"| SampleApps
    Systemd -->|"installs service"| qatmgr
    InitScript -->|"initializes service"| qatmgr

    %% Click Events
    click SampleApps "https://github.com/intel/qatlib/tree/main/quickassist/lookaside/access_layer/src/sample_code"
    click LibQAT "https://github.com/intel/qatlib/tree/main/quickassist/lookaside/access_layer"
    click Crypto "https://github.com/intel/qatlib/tree/main/quickassist/lookaside/access_layer/src/common/crypto"
    click Compression "https://github.com/intel/qatlib/tree/main/quickassist/lookaside/access_layer/src/common/compression"
    click DirectTransport "https://github.com/intel/qatlib/tree/main/quickassist/lookaside/access_layer/src/qat_direct/vfio"
    click PublicHeaders "https://github.com/intel/qatlib/tree/main/quickassist/include"
    click FirmwareStubs "https://github.com/intel/qatlib/tree/main/quickassist/lookaside/firmware"
    click LibUSDM "https://github.com/intel/qatlib/tree/main/quickassist/utilities/libusdm_drv"
    click OSAL "https://github.com/intel/qatlib/tree/main/quickassist/utilities/osal"
    click qatmgr "https://github.com/intel/qatlib/blob/main/quickassist/utilities/qat_mgr/qat_mgr.c"
    click Systemd "https://github.com/intel/qatlib/blob/main/quickassist/utilities/service/qat/qat.service.in"
    click InitScript "https://github.com/intel/qatlib/blob/main/quickassist/utilities/service/qat/qat_init.sh.in"

    %% Styles
    classDef userlib fill:#cce5ff,stroke:#333,stroke-width:1px;
    classDef kernel fill:#d4edda,stroke:#333,stroke-width:1px;
    classDef hardware fill:#f0f0f0,stroke:#333,stroke-width:1px;
    classDef daemon fill:#fff3cd,stroke:#333,stroke-width:1px;
```
