From dc478c7cdacee9e5e9a6bc8f7f60707e02dafeb0 Mon Sep 17 00:00:00 2001 From: Evgeny Demchenko Date: Thu, 14 May 2026 23:11:30 +0100 Subject: [PATCH] docs: system requirements (hardware, software, build, Docker, k8s) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit docs/requirements.md (220 строк): - Hardware: NVIDIA GPU CC ≥7.5 (Turing+), Linux x86_64, VRAM/RAM/CPU minimum - Software host: kernel ≥5.4, driver ≥525/555, glibc ≥2.31, Ubuntu/Debian/RHEL - Build deps: CUDA Toolkit ≥12.0, GCC 11+, CMake 3.20+, FFmpeg 4.4+ - Docker: nvidia-container-toolkit, --gpus, --ipc=shareable, --shm-size=2gb - Cross-container CUDA IPC: variant A (--ipc=container:X), variant B (host), k8s через emptyDir + shareProcessNamespace - Out-of-scope: AMD/Intel/macOS/Windows/WSL2/Jetson/multi-GPU/multi-host - Quick-check команды (nvidia-smi, uname, ldd, df /dev/shm) - Tested matrix (Phase 0): RTX 5090, driver 595, CUDA 13.0.88, Ubuntu 24.04 README.md обновлён: - Краткая таблица minimum vs recommended - Список не-поддерживаемых платформ - Ссылки на все docs/ файлы (architecture, protocol, requirements, benchmarks) --- README.md | 20 ++++- docs/requirements.md | 184 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 202 insertions(+), 2 deletions(-) create mode 100644 docs/requirements.md diff --git a/README.md b/README.md index 6009ceb..bbd3f5a 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,21 @@ Zero-copy sharing декодированных видеокадров между **Статус:** ⚠️ Design phase. Дизайн-спецификация готова, реализация в процессе. **Лицензия:** LGPL-2.1+ -**Платформы:** Linux, NVIDIA CUDA ≥ 12.0 + +## Минимальные требования + +| | Минимум | Рекомендуется | +|---|---|---| +| OS | Linux kernel ≥ 5.4 | Ubuntu 24.04 | +| GPU | NVIDIA с compute capability ≥ 7.5 (Turing+) | Ampere/Ada/Blackwell | +| NVIDIA driver | 525 (для CUDA 12) | 555+ (для CUDA 13) | +| CUDA Toolkit (build) | 12.0 | 13.0+ | +| GCC / Clang | 11 / 14 | 12+ / 17+ | +| CMake | 3.20 | 3.28+ | +| Docker | 24.x + nvidia-container-toolkit 1.14+ | — | + +**Не работает** на Windows, macOS, WSL2, AMD/Intel GPU, multi-GPU producer/consumer. +Подробно — [docs/requirements.md](docs/requirements.md). ## Идея в одну минуту @@ -59,7 +73,9 @@ while (auto frame = sub.next()) { ## Документация - [docs/architecture.md](docs/architecture.md) — полный design document -- [docs/protocol.md](docs/protocol.md) — wire protocol *(в разработке)* +- [docs/protocol.md](docs/protocol.md) — bit-exact wire protocol spec +- [docs/requirements.md](docs/requirements.md) — system requirements (hardware, software, build, Docker, k8s) +- [docs/benchmarks-phase0.md](docs/benchmarks-phase0.md) — Phase 0 latency/throughput measurements - [docs/quickstart.md](docs/quickstart.md) — *(в разработке)* ## Why diff --git a/docs/requirements.md b/docs/requirements.md new file mode 100644 index 0000000..c5df387 --- /dev/null +++ b/docs/requirements.md @@ -0,0 +1,184 @@ +# System Requirements + +Минимальные требования для использования cuframes — как для **сборки**, так и +для **runtime**. Если что-то из этого не выполняется — библиотека либо не +скомпилируется, либо не запустится. + +## 1. Hardware + +### GPU + +- **NVIDIA GPU** (vendor lock — CUDA IPC is NVIDIA-specific) +- **Compute Capability ≥ 7.5** (Turing или новее) + - Поддерживается: RTX 20xx / 30xx / 40xx / 50xx, Quadro RTX, A-серия (A40/A100), H-серия (H100), GH200 + - Не поддерживается: Pascal (GTX 10xx, P100) и старше — CUDA 13 drop'нул support + - На границе: Volta (V100, Titan V) — sm_70, технически CUDA 13 deprecates, но `cudaIpc*` API работает +- **CUDA IPC support** — все GPU с CC ≥ 3.0 имеют CUDA IPC, но мы ограничены CUDA 13 toolkit'ом +- **Single GPU per producer/consumer pair** — CUDA IPC handles **не работают** между разными devices. Если у вас 2× GPU и публикуете на GPU 0, consumer должен быть на GPU 0 +- **Linux only** — CUDA IPC использует POSIX shared memory + Unix domain sockets. На Windows не работает (даже WSL2 — untested, скорее всего не работает из-за hypervisor isolation) + +### VRAM + +Зависит от использования: + +| Setup | Минимум VRAM | +|---|---| +| 1 камера FullHD NV12, ring=2 | **~10 MB** (2 × 3MB frame + overhead) | +| 1 камера 4K NV12, ring=4 | **~50 MB** | +| 16 камер FullHD NV12, ring=4 | **~200 MB** | +| 16 камер 4K NV12, ring=4 | **~800 MB** | + +Это **только** для cuframes ring buffers. Add VRAM для самого decoder'а +(FFmpeg/NVDEC), inference моделей и т.д. + +Для domashno-CCTV setup'а (16 камер) на RTX 3060 12GB / 4060 16GB / 5090 32GB — +**с большим запасом**. + +### RAM + +- **~64 MB** host memory на publisher + ~10 MB на subscriber +- POSIX shared memory `/dev/shm/cuframes-` фиксированно ≤ 8 KB +- Unix socket buffers — kernel-managed, ~32 KB + +Реально библиотека «бесплатна» по RAM. CUDA driver сам потребляет ~200 MB. + +### CPU + +- Любой x86_64 (CUDA не работает на ARM кроме Jetson — отдельная история) +- Никаких специальных требований к ядрам — hot-path не CPU-bound +- Минимум 2 cores рекомендуется (один для main thread, один для async subscriber thread) + +## 2. Software (host system) + +### Operating System + +- **Linux** (kernel ≥ 5.4) +- Tested distros: + - Ubuntu 22.04 LTS (CUDA 12.x) + - Ubuntu 24.04 LTS (CUDA 13.x) — **рекомендуется** + - Debian 12 (bookworm) + - RHEL 9 / Rocky Linux 9 +- Не поддерживается: Alpine (musl-libc вместо glibc — несовместимо с NVIDIA libs) + +### NVIDIA Driver + +- **Driver ≥ 555** для CUDA 13 runtime (рекомендуется) +- **Driver ≥ 525** для CUDA 12 runtime (минимум — если используете старый toolkit) +- Tested: + - 555.x, 565.x, 575.x, 595.x — известно работают + +Driver version и CUDA runtime — отдельные вещи. cuframes использует CUDA runtime +API (`cudart`), который linked в нашу .so, а driver обеспечивает kernel-level +CUDA. См. [NVIDIA compat table](https://docs.nvidia.com/deploy/cuda-compatibility/). + +### Userspace + +- **glibc ≥ 2.31** (Ubuntu 20.04+, Debian 11+) +- **CUDA Toolkit 12.0+** (для сборки) — 13.0+ рекомендуется +- POSIX shared memory (`/dev/shm`) — mount'нут как tmpfs, обычно по умолчанию +- POSIX threads (`pthread`) — обычно есть везде + +## 3. Software (build-time) + +Для **сборки cuframes** из исходников (если не используете готовые Docker +images / .deb пакеты): + +| Tool | Минимум | Рекомендуется | +|---|---|---| +| CUDA Toolkit | 12.0 | **13.0+** (содержит `cudaIpc*` improvements) | +| GCC | 11 (для C++17) | 12+ | +| Clang | 14 | 17+ | +| CMake | 3.20 | 3.28+ | +| Ninja | (опционально, любая) | | +| pkg-config | любая | | +| Python | 3.10 (для bindings, Phase 3+) | 3.12 | +| FFmpeg | 4.4 (для filter, Phase 2+) | **7.x** (target) | + +Build dependencies устанавливаются через apt: + +```bash +sudo apt install build-essential cmake ninja-build pkg-config \ + nvidia-cuda-toolkit nvidia-cuda-dev \ + libavcodec-dev libavformat-dev libavutil-dev libavfilter-dev +``` + +## 4. Docker (опционально, рекомендуется) + +Если используете готовые images (`ghcr.io//cuframes-ffmpeg:N` или +`cuframes-frigate:0.17`) или dev-контейнер: + +| Component | Минимум | +|---|---| +| Docker Engine | 24.x | +| nvidia-container-toolkit | 1.14+ | +| docker compose | v2.20+ | + +Container setup требования: +- `--gpus all` (или specific `--gpus device=0`) +- `--ipc=shareable` (для cross-container CUDA IPC) или `--ipc=host` +- `--shm-size=2gb` (default 64 MB не хватит для CUDA IPC handles) +- Bind-mount `/run/cuframes` для Unix sockets + +См. `docker/README.md` для готовых compose-файлов. + +### Cross-container CUDA IPC + +Чтобы producer в одном container'е делился frame'ами с consumer в другом: +- Оба container'а должны быть в **одном IPC namespace**: + - Variant A: `--ipc=container:` для secondary + - Variant B: `--ipc=host` (менее изолировано) +- Оба должны видеть тот же `--gpus` device +- `/run/cuframes` должен быть shared (volume) между ними +- `/dev/shm` — каждый container имеет свой, но через IPC namespace memory-region shareable + +Kubernetes: +- Поды должны быть в одном Pod (sidecars), shared `volumeMounts: emptyDir` для `/run/cuframes` +- IPC namespace — pod-level `shareProcessNamespace: true` + `hostIPC: true` для cross-pod (security implications) + +## 5. Не поддерживается + +Явно out-of-scope для v0.1: + +| | Почему | +|---|---| +| AMD GPU (ROCm) | Аналог HIP IPC существует, но API отличается. Возможный roadmap для v1.x | +| Intel GPU (Arc / Xe) | Нет аналога CUDA IPC в Level Zero (на 2026-05) | +| Windows | CUDA IPC использует POSIX SHM + Unix sockets — Linux primitives | +| macOS | Apple deprecated NVIDIA support с Mojave; CUDA not available | +| WSL2 | CUDA IPC через WSL hypervisor — недокументированное поведение, untested | +| Jetson | Имеет CUDA, но cross-process через NVMM (другой API); может работать но not tested | +| Multi-GPU | producer и consumer должны быть на одном CUDA device — CUDA IPC ограничение | +| Multi-host | CUDA IPC localhost-only; RDMA / GPUDirect — другой scope | + +## 6. Quick check + +Проверить совместимость хоста (требует только bash + nvidia-smi): + +```bash +# CUDA driver и compute capability +nvidia-smi --query-gpu=name,driver_version,compute_cap --format=csv,noheader + +# Минимум: driver ≥ 525 (CUDA 12) или ≥ 555 (CUDA 13) +# compute_cap ≥ 7.5 + +# Linux kernel +uname -r # ≥ 5.4 + +# glibc +ldd --version | head -1 # ≥ 2.31 + +# /dev/shm size (для CUDA IPC handles) +df -h /dev/shm # минимум 256 MB свободно +``` + +## 7. Тестировано на + +Phase 0 PoC (2026-05-14): +- **Hardware:** NVIDIA RTX 5090 (Blackwell, sm_120, 32 GB), Intel/AMD CPU x86_64 +- **Driver:** 595.58.03 +- **CUDA:** 13.0.88 (внутри dev container на базе `nvidia/cuda:13.0.3-cudnn-devel-ubuntu24.04`) +- **OS host:** Ubuntu 24.04, kernel 6.17.x +- **Docker:** 29.1.3 с nvidia-container-runtime +- **Container:** Ubuntu 24.04 + GCC 13 + Clang + CMake 3.28 + Ninja + +Дополнительный target matrix будет в CI после Phase 4.