cuframes/docs/requirements.md

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-<key> фиксированно ≤ 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.

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:

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/<org>/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:<other-container-name> для 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):

# 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

Production deployment matrix (v0.1.0)

Что подтверждено в 24h+ production run:

Слой	Версия	Comments
NVIDIA driver	555+	минимум для CUDA 12 user runtime
CUDA toolkit (build)	12.4 (Debian 12 / Ubuntu 22.04) либо 13.0 (Ubuntu 24.04)	toolkit для builder image, не runtime
GPU	RTX 5090 (sm_120)	проверено; раньше — sm_75 минимум
Builder OS	Ubuntu 22.04 (glibc 2.35)	forward-compat с Debian 12 runtime
Runtime OS (Frigate)	Debian 12 (glibc 2.36)	base image Frigate stable-tensorrt
Runtime OS (cctv-backend)	Ubuntu 22.04 либо Debian 12	matched с builder
Docker	29.1.x	для buildx
docker buildx	v0.34.0+	apt install docker-buildx-plugin либо manual install из GH releases
nvidia-container-toolkit	1.14+	для runtime: nvidia

Docker namespace requirements (cross-container CUDA IPC)

Для consumer'а который подключается к publisher'у в другом container'е:

Что нужно	Как настроить
/dev/shm shared (header + ring metadata)	ipc: container:<publisher> либо ipc: shareable у publisher + same у consumer
/proc visibility (CUDA IPC peer validation)	pid: container:<publisher>
/run/cuframes/*.sock доступен	volume mount cuframes_sock:/run/cuframes:ro
GPU access	runtime: nvidia + NVIDIA_VISIBLE_DEVICES=all
Socket file permissions	user: root либо chmod в publisher

Все 5 должны быть выполнены. Подробности — docs/troubleshooting.md.

Special case: s6-overlay containers (Frigate, linuxserver.io stack): pid: share невозможен — s6-overlay требует PID 1. Workaround: только ipc: + race window connect. См. troubleshooting.

Дополнительный target matrix будет в CI после Phase 4 (см. ROADMAP.md).