Files

Felipe Cardoso 5b81437637 docs: add README, CLAUDE.md, AGENTS.md, and full docs/ suite

- README.md: project overview, quick start, command reference, workflow
- CLAUDE.md: AI safety rules, technical details, conventions
- AGENTS.md: agent workflows, file responsibility map, dependency matrix
- docs/architecture.md: script layers, data flow, unified memory, JSON schemas
- docs/optimization.md: step-by-step optimization walkthrough
- docs/benchmarking.md: methodology, test params, result interpretation
- docs/troubleshooting.md: common issues and fixes
- docs/references.md: centralized external links (single source of truth)
- docs/bios-vram-guide.md: add back-link to optimization workflow

Cross-linked non-redundantly: each doc owns one layer, others link to it.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-03-25 20:50:00 +01:00

3.0 KiB

Raw Blame History

Troubleshooting

Firmware: linux-firmware 20251125 Causes ROCm Crashes

Symptoms: Arbitrary crashes, instability, or mysterious failures with ROCm workloads.

Check: rpm -qa | grep linux-firmware

Fix: Downgrade to 20251111 or upgrade to 20260110+. After changing firmware:

sudo dracut -f --kver $(uname -r)

The toolkit checks this automatically — make audit shows firmware status.

amdgpu_top: Cargo Build Fails (gix-hash error)

Symptoms: error: Please set either the sha1 or sha256 feature flag during cargo install amdgpu_top.

Cause: Rust toolchain version incompatibility with the gix-hash dependency.

Fix: Use the pre-built RPM instead:

make monitor-install

The install script downloads the RPM from GitHub releases, bypassing cargo entirely.

Toolbox GPU Access Failure

Symptoms: llama-cli --list-devices shows no GPU inside a toolbox container.

Check: Device mappings when creating the toolbox:

Vulkan backends need: --device /dev/dri
ROCm backends need: --device /dev/dri --device /dev/kfd

Fix: Recreate the toolbox with correct device flags. The refresh-toolboxes.sh script handles this automatically.

Also ensure your user is in the video and render groups:

sudo usermod -aG video,render $USER

GRUB Changes Not Taking Effect

Symptoms: After make optimize-kernel and reboot, make audit still shows missing params.

Possible causes:

BLS (Boot Loader Spec): Modern Fedora uses BLS entries. The script uses grubby when available, but verify:
```
grubby --info=ALL | grep args
```

Wrong GRUB config path: Check which config is actually used:

cat /proc/cmdline    # what the kernel actually booted with
cat /etc/default/grub  # what the script modified

GRUB not regenerated: Manually regenerate:

sudo grub2-mkconfig -o /boot/grub2/grub.cfg

Memory Unchanged After BIOS Change

Symptoms: Changed VRAM in BIOS but make audit still shows 32 GiB.

Check:

cat /sys/class/drm/card1/device/mem_info_vram_total

Possible causes:

BIOS change not saved (verify by re-entering BIOS)
Wrong BIOS setting modified (look for "UMA Frame Buffer Size", not "Shared Memory")
Kernel params not applied (VRAM reduction requires kernel params to be useful)

Benchmark Failures

Symptoms: make benchmark-baseline reports "FAILED" for some backends.

Common fixes:

Ensure model exists: ls data/models/*.gguf
Check model fits in memory: small models (4B) for initial testing
Try llama-vulkan-radv first (most stable backend)
Check dmesg for GPU errors: dmesg | tail -30

Rollback

If optimization causes issues:

sudo make rollback

This restores the GRUB backup and previous tuned profile. BIOS changes must be reverted manually (F10 at boot). See docs/optimization.md for the full rollback procedure.

3.0 KiB Raw Blame History