strix-halo-gmktec-evo-x2: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository Overview

This repository contains setup guides and configuration documentation for optimizing Ubuntu 24.04 on the GMKTEC EVO-X2 (AMD Ryzen AI Max+ 395 with Radeon 8060S) for LLM inference using llama.cpp with ROCm 7 RC and rocWMMA.

Hardware Context

Target System:

• CPU: AMD RYZEN AI MAX+ 395 w/ Radeon 8060S (32 threads)
• GPU: AMD Radeon Graphics (gfx1151, RDNA 3.5, 40 CUs, Strix Halo)
• RAM: 124 GiB system memory
• GPU Memory: 1 GB VRAM (framebuffer) + 128 GB GTT (unified compute memory)

Critical Understanding: For this APU, GTT (Graphics Translation Table) is the primary compute memory pool for LLM inference, not VRAM. The system has ~120GB available for inference workloads.

Key Setup Steps Reference

System Configuration (from ROADMAP.md)

Kernel Requirements:

• Minimum: Linux 6.16.9 (critical for >15GB VRAM access)
• Current: 6.17.0-1028-oem

Note: Kernel 6.17 broke the KFD kernel/userspace ABI against the ROCm 7.0-rc HSA runtime used by the old distrobox container below, causing llama-server to segfault in libhsa-runtime64.so (see LLAMA_ISSUES_SUMMARY.md). The fix was to move off distrobox and run ROCm 7.2 + llama.cpp natively on the host (see "Building and Running llama.cpp" below), which matches the host kernel's KFD ABI.

Essential Kernel Parameters:

amd_iommu=off amdgpu.gttsize=131072 ttm.pages_limit=31457280

Critical Modprobe Configuration (/etc/modprobe.d/amdgpu_llm_optimized.conf):

options amdgpu gttsize=122800
options ttm pages_limit=31457280
options ttm page_pool_size=31457280

GPU Access (Ubuntu-specific): Must create udev rules in /etc/udev/rules.d/99-amd-kfd.rules:

SUBSYSTEM=="kfd", GROUP="render", MODE="0666", OPTIONS+="last_rule"
SUBSYSTEM=="drm", KERNEL=="card[0-9]*", GROUP="render", MODE="0666", OPTIONS+="last_rule"
SUBSYSTEM=="drm", KERNEL=="renderD[0-9]*", GROUP="render", MODE="0666", OPTIONS+="last_rule"

The renderD[0-9]* rule is critical - without it, ROCm will fail with HSA_STATUS_ERROR_OUT_OF_RESOURCES.