From 75243e86956cc408f31249737d94ce45b4bb9aff Mon Sep 17 00:00:00 2001 From: Yuxin Chen Date: Fri, 10 Jul 2026 09:39:40 +0000 Subject: [PATCH] docs: polish README first screen for discoverability and conversion MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rewrite the top of the README (above Project Structure) to give the project a stronger first impression for visitors arriving from search / social / awesome-lists: - Title + one-line tagline with SEO keywords (NVLink, GPU, bandwidth, NVIDIA, multi-GPU, LLM/HPC clusters). - Badges: CI, MIT license, stars, platform β€” signals the project is alive and legit. - A 'Why?' block positioning against nvidia-smi (no per-link NVLink throughput) and dcgmi (heavyweight), framing the pain point. - A concise Features list highlighting the differentiators added recently (bidir full-duplex, all-pairs sweep, CSV/JSON, GPU filter, 81 tests). - A Demo block with real output from an 8x H20 run (verbose monitor, bidir 730 GiB/s, all-pairs summary) plus a note inviting a terminal recording. - A 3-line Quick start (install-deps, make monitor, run) so visitors can try in seconds. Removed the now-redundant later '## Features' section (its content is covered and improved by the new first-screen list and the per-tool Usage sections). Repo metadata (description + 12 topics) set separately via gh repo edit so the project shows up in GitHub topic/search pages. Signed-off-by: staryxchen --- README.md | 73 +++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 50 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 9b79b67..dcd9b9d 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,55 @@ -# πŸš€ NVLink Monitor +# πŸš€ NvLinkMonitor -A comprehensive toolkit for monitoring and testing NVIDIA NVLink bandwidth and status. This project consists of two main components: +**Real-time per-link NVLink bandwidth monitor + inter-GPU P2P benchmark for NVIDIA multi-GPU systems.** A lightweight C++ toolkit for validating NVLink connectivity and diagnosing link saturation on AI-training and HPC clusters. -- πŸ“Š **NVLink Monitor**: A real-time monitoring tool for NVLink bandwidth -- ⚑ **NVLink Bandwidth Test**: A performance testing tool for NVLink bandwidth measurement +[![CI](https://github.com/staryxchen/NvLinkMonitor/actions/workflows/ci.yml/badge.svg)](https://github.com/staryxchen/NvLinkMonitor/actions/workflows/ci.yml) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +![Stars](https://img.shields.io/github/stars/staryxchen/NvLinkMonitor?style=social) +![Platform](https://img.shields.io/badge/platform-Linux%20x86__64-blue) + +> **Why?** `nvidia-smi` shows GPU utilization but not per-link NVLink throughput. `dcgmi` is heavyweight to deploy. This tool gives you a single dependency-light binary that reports per-link TX/RX bandwidth in real time β€” plus a built-in inter-GPU copy benchmark (`cudaMemcpy` or `__global__` kernel, unidir or **bidir full-duplex**) to generate load and validate topology. Ideal for bring-up of multi-GPU LLM training nodes. + +## ✨ Features + +- πŸ“Š **Per-link NVLink bandwidth monitoring** via NVML β€” the monitor is a single g++ binary, no CUDA toolkit needed +- ⚑ **Inter-GPU P2P benchmark** β€” copy-engine memcpy or `__global__` kernel, unidirectional or **bidirectional** (aggregate full-duplex bandwidth) +- πŸ•ΈοΈ **All-pairs topology sweep** β€” test every GPU pair, skip unsupported, print a summary +- πŸ€– **Machine-readable output** β€” `--format csv|json`, status on stderr so stdout stays clean for pipes +- 🎯 **GPU filtering** β€” `--gpus 0,1,3` to focus on a subset +- πŸ§ͺ **81 unit tests**, CI-gated clang-format; pure-logic paths build and test without a GPU + +## πŸ–ΌοΈ Demo + +```text +$ sudo ./build/nvlink_monitor --verbose ++--- NvLink Monitor (Detailed) --- 2026-07-10 08:29:06 ---+ +GPU 0 (18 links) Total RX: 368.4 GiB/s, TX: 368.4 GiB/s + Link 0 RX: 20.5 GiB/s, TX: 20.5 GiB/s + Link 1 RX: 20.5 GiB/s, TX: 20.5 GiB/s + ... + +$ ./build/nvlink_bw_test --direction bidir -s 0 -d 1 + β€’ Direction: bidir (aggregate) + β”œβ”€ Average bandwidth: 730.06 GiB/s # ~2Γ— unidir (368.76) β†’ full-duplex + +$ ./build/nvlink_bw_test --all-pairs -i 20 -b 500 +═══════════ All-Pairs Summary ═══════════ + GPU 0 ↔ GPU 1: 364.13 GiB/s avg + GPU 0 ↔ GPU 2: 363.10 GiB/s avg + ... +``` + +> πŸ“Ή A terminal recording ([asciinema](https://asciinema.org/) / [terminalizer](https://github.com/faressoft/terminalizer)) makes a great first impression β€” consider embedding one here. + +## ⚑ Quick start + +```bash +./install-deps.sh # NVML headers (+ CUDA toolkit only for the benchmark) +make monitor # monitor only: g++, no CUDA toolkit needed +sudo ./build/nvlink_monitor --verbose +``` + +--- ## Project Structure @@ -220,25 +266,6 @@ A performance testing tool for measuring NVLink bandwidth between GPUs. ./build/nvlink_bw_test --all-pairs --direction bidir -i 20 -b 500 ``` -## ✨ Features - -### πŸ“Š NVLink Monitor Features: -- Real-time NVLink bandwidth monitoring -- Individual link bandwidth tracking -- Continuous and single-shot monitoring modes -- Configurable monitoring intervals -- File output support - -### ⚑ NVLink Bandwidth Test Features: -- Inter-GPU memory copy performance testing -- Two copy methods: `cudaMemcpyDeviceToDevice` (copy engine) and `__global__` kernel (SM load/stores over P2P) -- Configurable buffer sizes and iteration counts -- Source and destination GPU selection -- One untimed warmup copy before the timed loop (primes the CUDA context / copy engine / kernel launch path so the first timed iteration is not skewed by one-time setup) -- Bidirectional mode (`--direction bidir`): concurrent both-direction copies on per-GPU streams, reporting aggregate full-duplex bandwidth -- All-pairs topology sweep (`--all-pairs`): tests every i