# thustorage/term architecture

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

- Interactive diagram: https://gitdiagram.com/thustorage/term
- Repository: https://github.com/thustorage/term

## Overview

##### Project type and purpose
- TeRM is a systems‐level research artifact that extends RDMA‐attached memory by transparently paging cold pages out to SSD.
- It comprises a patched kernel driver for RDMA NICs, a userspace shared library (libterm/libpdp) that LD_PRELOADs into RDMA apps, the original RDMA applications (octopus, xstore), a memcached metadata service, and an experimental harness (ae/).

##### File structure
- Top‐level directories:
- ae/ – Artifact Evaluation: scripts, experiment drivers, generated binaries
- app/ – Sample RDMA applications (octopus, xstore) with bug fixes
- driver/ – Patches and prebuilt archives for the RDMA/NIC kernel module
- libterm/ – Userspace library (libpdp.so) and micro‐kernel module (kmod) source
- Key patterns:
- Hooking/interposition (LD_PRELOAD) in libpdp.so to override ibverbs calls
- Kernel module patch for on‐demand paging (ODP) and SSD back‐end
- Experiment automation via shell and Python scripts in ae/scripts
- Configuration:
- CMakeLists.txt for building libterm
- TOML and XML under ae/bin and app for workload configs
- Shell scripts for memcached reset, CPU affinity, driver build

##### Insights from the README
- Architecture described:
- Client RDMA programs mmap an SSD device and register it as an ODP MR
- libpdp.so intercepts ibv_reg_mr and transparently pages to SSD via the patched driver
- Memcached synchronizes cluster metadata (addresses, ports)
- Dependencies: OFED driver, memcached, Boost/Glog/GFlags libs
- Usage: LD_PRELOAD, environment vars (PDP_server_mmap_dev, PDP_is_server, etc.)

##### Detail
- Component’s role and interfaces
- Experiment harness separately to indicate where benchmarking and automation occur

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User-space Components"
        direction TB
        Apps["RDMA Applications<br/>(octopus, xstore)"]:::userspace
        click Apps "https://github.com/thustorage/term/tree/main/app/"
        Libpdp["libpdp.so (Userspace PDAPI library)"]:::userspace
        click Libpdp "https://github.com/thustorage/term/tree/main/libterm/ibverbs-pdp/"
        Ae["Artifact Evaluation Framework (ae/)"]:::userspace
        click Ae "https://github.com/thustorage/term/tree/main/ae/"
    end

    subgraph "Kernel-space Components"
        direction TB
        Driver["Patched RDMA Driver<br/>(PDP kmod)"]:::kernel
        click Driver "https://github.com/thustorage/term/tree/main/libterm/kmod/"
        click Driver "https://github.com/thustorage/term/tree/main/driver/"
    end

    subgraph "Hardware Components"
        direction TB
        NIC["RDMA NIC"]:::hardware
        SSD["SSD Device"]:::hardware
    end

    Memcached["Memcached Service"]:::meta
    click Memcached "https://github.com/thustorage/term/blob/main/ae/scripts/reset-memc.sh"

    Apps -->|"LD_PRELOAD: ibv_reg_mr, ibv_post_send"| Libpdp
    Libpdp -->|"syscall / ibdev"| Driver
    Driver -->|"RDMA"| NIC
    Driver -->|"block I/O"| SSD
    Apps -->|"TCP/UDP"| Memcached
    Libpdp -->|"TCP/UDP"| Memcached
    Driver -->|"TCP/UDP"| Memcached
    Ae -->|"automation"| Apps
    Ae -->|"automation"| Libpdp
    Ae -->|"automation"| Driver

    classDef userspace fill:#9f6,stroke:#393,stroke-width:1px
    classDef kernel fill:#6cf,stroke:#039,stroke-width:1px
    classDef hardware fill:#ccc,stroke:#666,stroke-width:1px
    classDef meta fill:#f96,stroke:#c60,stroke-width:1px
```
