Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
104 lines (73 loc) · 2.97 KB

CONTRIBUTING.md

File metadata and controls

104 lines (73 loc) · 2.97 KB
Raw

Contributing

Thank you for your interest in BlueCache. This document describes how to build, test, and upstream changes.

Repository Structure

  • common/ — Shared host-DPU wire protocol (dma_transfer.h).
  • nixl-plugin/ — NIXL BLUE_CACHE backend plugin source.
  • blue-cache/ — BlueField DPU proxy service.
  • examples/ — Standalone C++ example and LMCache reference architecture.
  • scripts/ — patch_nixl.sh, build_all.sh, and helpers.
  • docs/ — Architecture and integration documentation.

Building blue-cache

Requirements:

  • BlueField DPU or cross-compilation toolchain
  • NVIDIA DOCA SDK
  • Installed NIXL (the DPU agent uses NIXL storage backends)
  • CMake ≥ 3.18
mkdir build && cd build
export DOCA_DIR=/opt/mellanox/doca
export NIXL_ROOT=/opt/nvidia/nvda_nixl
cmake .. -DBUILD_EXAMPLES=OFF
make -j$(nproc) blue-cache

Patching NIXL with the Plugin

The plugin is designed to be injected into a NIXL source tree:

./scripts/patch_nixl.sh /path/to/nixl/source

cd /path/to/nixl/source
meson setup build -Denable_plugins=BLUE_CACHE
ninja -C build

The script is idempotent. It copies plugin files, patches build files, and adds static-plugin registration.

Building Everything Together

./scripts/build_all.sh /path/to/nixl/source

This patches NIXL, builds it, then builds the DPU agent and examples.

Running Tests

Standalone host test tool (no NIXL required)

cd examples/standalone
./scripts/build_host.sh

# On DPU
./build-dpu/blue-cache -p 0000:03:00.0 -m 256 -q 4

# On Host
./build-host/examples/standalone/blue-cache-host -o push -p 0000:ba:00.0 -g 0 -f /tmp/test.bin -s 64
./build-host/examples/standalone/blue-cache-host -o pull -p 0000:ba:00.0 -g 0 -f /tmp/test.bin -O /tmp/test.out

NIXL C++ example

Build with -DBUILD_EXAMPLES=ON and run after the DPU agent is started:

./build/examples/cpp/nixl_blue_cache_example 0000:ba:00.0 /tmp/dpu_object.bin

Upstreaming to NIXL

When the plugin is ready for upstream NIXL:

  1. Ensure nixl-plugin/ and common/include/dma_transfer.h are up to date.
  2. Run ./scripts/patch_nixl.sh against a clean NIXL checkout.
  3. Review the diff in the NIXL tree.
  4. Create a NIXL PR containing:
    • Plugin source under src/plugins/blue_cache/
    • Build integration in meson.build and src/plugins/meson.build
    • Static plugin registration in src/core/nixl_plugin_manager.cpp
    • Tests under test/unit/plugins/blue_cache/ (when available)
    • Documentation updates

Code Style

  • C/C++: follow the existing NIXL style (4-space indentation, SPDX headers).
  • Shell scripts: use set -e, quote variables, and prefer #!/bin/bash.
  • Keep the wire protocol in common/include/dma_transfer.h in sync between host plugin and DPU agent.

Reporting Issues

Please open issues with:

  • Hardware platform (GPU, BlueField DPU, host PCI topology).
  • DOCA and NIXL versions.
  • Plugin parameters and DPU agent command line.
  • Relevant logs from both host and DPU.