From 8d85a4585e058d439153eebb7f7fd661e9cbc539 Mon Sep 17 00:00:00 2001 From: Keith Wiles Date: Tue, 5 May 2026 13:36:13 -0500 Subject: [PATCH] docs: add CLAUDE.md for project guidance and build instructions Signed-off-by: Keith Wiles --- CLAUDE.md | 127 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 127 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..03bb157d --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,127 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +CNDP (Cloud Native Data Plane) is a collection of userspace libraries for accelerating packet processing in cloud applications. It leverages AF_XDP for direct kernel-bypass packet delivery to userspace — simpler than DPDK (no hugepages, no custom drivers, no PCI bus scanning). Version: 25.08.0. + +## Build Commands + +The build system is **Meson + Ninja**, wrapped by a top-level `Makefile` that calls `tools/cne-build.sh`. + +```bash +make # Release build (builddir/) +make debug # Debug build +make debugopt # Debug with -O2 +make rebuild # Clean + rebuild +make install # Install to usr/local +make uninstall +make clean + +# Feature toggles (passed as environment variables to make) +make tcp=1 build # Enable experimental TCP support +make ipv6=1 build # Enable experimental IPv6 +make static_build=1 build # Build static libraries +make V=1 build # Verbose output + +make docs # Generate Doxygen API docs +make rust-app # Build Rust language bindings +make oci-image # Build Docker image +``` + +Direct meson/ninja usage: +```bash +meson setup builddir # Initial configure +ninja -C builddir # Build +sudo ninja -C builddir install # Install +``` + +## Running Tests + +Tests require root (AF_XDP socket creation). The test harness is `builddir/test/testcne/test-cne`. + +```bash +# Run the short CI suite +meson test -C builddir --suite short + +# Run all tests +meson test -C builddir + +# Run a single named test +sudo ./builddir/test/testcne/test-cne -- mempool +sudo ./builddir/test/testcne/test-cne -- ring +sudo ./builddir/test/testcne/test-cne -- mbuf +``` + +Available test names (65+): `acl`, `cne_register`, `cthread`, `dsa`, `fib`, `fib6`, `graph`, `hash`, `hmap`, `ibroker`, `idlemgr`, `jcfg`, `kvargs`, `log`, `loop`, `mbuf`, `mempool`, `meter`, `metrics`, `mmap`, `msgchan`, `pkt`, `pktcpy`, `pktdev`, `rib`, `rib6`, `ring`, `tailqs`, `thread`, `timer`, `txbuff`, `uid`, `vec`, `xskdev`. + +## Code Style and Linting + +```bash +# Install pre-commit hooks (run once) +pip install pre-commit && pre-commit install + +# Run all hooks manually +pre-commit run --all-files + +# Format a single file +clang-format -i --style=file +``` + +- **C formatting**: clang-format, LLVM-based style, 100-character column limit (see `.clang-format`) +- **YAML**: yamllint (see `.yamllint.yaml`) +- **Spelling**: codespell (see `cndp-codespell.precommit-toml`) +- Pre-commit runs clang-format automatically on commit; CI enforces it via `.github/workflows/pre-commit.yml` + +## Architecture + +### Core Subsystems + +**I/O Layer** (`lib/core/pmds/`, `lib/core/xskdev/`, `lib/core/pktdev/`): AF_XDP packet device abstraction. `xskdev` is the low-level AF_XDP interface; `pktdev` is the higher-level device API used by applications. PMDs (Poll Mode Drivers) in `pmds/` include `af_xdp`, `memif`, and `null` backends. + +**Memory Management** (`lib/core/mempool/`, `lib/core/pktmbuf/`, `lib/core/ring/`, `lib/core/mmap/`): Zero-copy packet buffer lifecycle. `pktmbuf` wraps raw memory into structured packet buffers; `mempool` provides per-lcore object pools; `ring` is the lockless MPMC queue used throughout. + +**Network Stack** (`lib/cnet/`): Optional full userspace TCP/IP stack (27 subdirectories). Enabled at build time via `tcp=1` and `ipv6=1`. Provides channels, TCBs, routes, ARP, and socket-like APIs. + +**Data Structures** (`lib/core/hash/`, `lib/core/fib/`, `lib/core/rib/`, `lib/core/acl/`, `lib/core/graph/`): High-performance lookup structures. `graph` is a node-based packet processing pipeline (similar to DPDK's rte_graph). + +**System Abstraction** (`lib/core/osal/`): OS abstraction (thread affinity, timers, CPU topology). Provides `cne_lcore` thread model. + +**Utilities** (`lib/core/kvargs/`, `lib/core/log/`, `lib/core/metrics/`, `lib/core/msgchan/`, `lib/core/idlemgr/`, `lib/core/timer/`): Support libraries used across core and applications. + +### Language Bindings + +**Rust** (`lang/rs/`): Cargo workspace with two crates: +- `bindings/cne-sys/` — raw `bindgen`-generated FFI to the C library +- `apis/cne/` — safe high-level Rust API wrapping `cne-sys` +- Examples: `echo_server`, `fwd`, `loopback`, `wireguard` + +**Go** (`lang/go/`): Work-in-progress Go bindings. + +### Application Pattern + +Applications (in `examples/`) follow this pattern: +1. Parse JSON config (`jcfg`) defining lports, threads, and lcore assignments +2. Initialize `pktdev` ports +3. Launch per-lcore threads via the `cne` framework +4. Process packets in tight loops using `pktmbuf` / `graph` nodes + +### Configuration + +Runtime configuration uses JSON files (parsed by `lib/core/jcfg/`). See examples in `examples/*/` for `.jsonc` config files showing lport, thread, and lcore setup. + +## CI/CD + +GitHub Actions workflows: +- `smoke.yml` — build + `meson test --suite short` on every PR +- `cppcheck.yaml` — static analysis +- `pre-commit.yml` — formatting enforcement +- `rust-build.yml` — Rust bindings build +- `docker.yml` — container image builds + +## Key Dependencies + +Required: `libbsd`, `libelf`, `libjson-c`, `libnl-3`, `libnuma`, `libpcap` +Optional: `libxdp`/`libbpf` (enhanced AF_XDP), `libdlb` (Intel DLB), `picotls`+`quicly` (QUIC examples) +Build tools: Meson ≥ 1.5.0, Ninja, GCC/Clang with C11 support, Python 3