rocm - SKILL.md Agent Skill

name: rocm description: | AMD ROCm runtime, OpenCL, and GPU compute support via system packages. Use when working with AMD GPU computing, ROCm, HIP, OpenCL, or AMD GPU passthrough in containers.

rocm -- AMD ROCm runtime and OpenCL

Candy Properties

Property	Value
Install files	`charly.yml`

Environment Variables

Variable	Value
`ROCM_PATH`	`/usr`

Runtime Environment (auto-detected)

Variable	Source	Example
`HSA_OVERRIDE_GFX_VERSION`	KFD topology sysfs	`10.3.0` (RDNA2), `11.0.0` (RDNA3)
`DRINODE`	DRM render node enumeration	`/dev/dri/renderD128` (typical), `/dev/dri/renderD129` (multi-GPU)

Both variables are not baked into the candy — they are auto-detected from host state at runtime and injected as container environment variables via appendAutoDetectedEnv() in charly/devices.go. The same function is called by charly config, charly start, and charly shell, so interactive shells and deployed services see the identical env set.

HSA_OVERRIDE_GFX_VERSION is read from /sys/class/kfd/kfd/topology/nodes/*/properties (gfx_target_version field).
DRINODE is selected by walking /dev/dri/renderD* and picking the node that matches the AMD PCI device exposed to the container.

Override either with -e HSA_OVERRIDE_GFX_VERSION=X.Y.Z or -e DRINODE=/dev/dri/renderD129. See /charly-core:charly-doctor (Hardware Detection) for how the probe runs on the host side, and /charly-distros:nvidia (DRINODE Auto-Injection) for the NVIDIA counterpart using the same mechanism.

Security

security:
  group_add:
    - keep-groups

Uses keep-groups to preserve host supplementary groups (video, render) inside the container. This is the standard approach across all candies -- Podman's keep-groups is mutually exclusive with explicit group names.

Packages

RPM (Fedora system repos): rocm-hip-runtime, rocm-opencl, rocm-clinfo, rocm-smi

Host Requirements

AMD GPU support requires:

/dev/kfd device (auto-detected by charly)
/dev/dri/renderD* render nodes (auto-detected)
User in video and render groups (charly udev status to check)
amdgpu kernel driver loaded

Run charly doctor to verify detection. Run charly udev install to set up device permissions.

Usage

# charly.yml -- standalone AMD GPU image
my-amd-app:
  base: fedora
  candy:
    - rocm
    - my-app

Verification

# Check AMD GPU detected on host
charly doctor | grep "AMD GPU"

# Verify inside container
charly shell my-amd-app -c "clinfo --list"
charly shell my-amd-app -c "rocm-smi"
charly shell my-amd-app -c "echo \$HSA_OVERRIDE_GFX_VERSION"

Related Candies

/charly-distros:nvidia -- NVIDIA GPU counterpart (runtime libs + CDI), shares appendAutoDetectedEnv() DRINODE injection
/charly-distros:cuda -- NVIDIA CUDA toolkit (stacked on nvidia)
/charly-languages:python-ml -- ML Python environment (currently depends on cuda; ROCm equivalent is a future direction)

Related Commands

/charly-core:charly-doctor -- Host AMD GPU detection (/dev/kfd, render nodes, driver status)
/charly-core:shell -- Interactive shells receive the same auto-detected HSA_OVERRIDE_GFX_VERSION + DRINODE envs
/charly-automation:udev -- Device permission management for /dev/kfd and /dev/dri/renderD*
/charly-core:charly-config -- Runtime GPU env injection at deployment time (same auto-detect path)
/charly-core:start -- Runtime GPU env injection at service start time

Used In Boxes

Not directly used in any current box definition. Available as a standalone candy for AMD GPU support. The NVIDIA base image (/charly-distros:nvidia) is the currently-shipped GPU box; an AMD counterpart can be composed by substituting this candy.

When to Use This Skill

Use when the user asks about:

AMD GPU support in containers
ROCm, HIP, or OpenCL setup
/dev/kfd device access
HSA_OVERRIDE_GFX_VERSION configuration
AMD GPU passthrough or compute
The rocm candy or AMD GPU computing
Comparing AMD vs NVIDIA GPU support

/charly-image:layer — candy authoring reference (charly.yml schema, task verbs, service declarations)
/charly-check:check — declarative testing (check: block, charly check box, charly check live)