5b81437637
- 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>
49 lines
3.2 KiB
Markdown
49 lines
3.2 KiB
Markdown
# CLAUDE.md — AI Assistant Context
|
|
|
|
Optimization toolkit for AMD Strix Halo (Ryzen AI MAX+ 395, Radeon 8060S gfx1151, 64 GB unified memory) on Fedora 43. Pure bash scripts with inline Python for JSON handling and GRUB editing. See [README.md](README.md) for user-facing commands.
|
|
|
|
## Architecture
|
|
|
|
`bin/` dispatchers → `scripts/` implementations → `lib/` shared libraries. All scripts source libs in order: `common.sh` → `detect.sh` → `format.sh`. Runtime data goes to `data/` (gitignored). Full details in [docs/architecture.md](docs/architecture.md).
|
|
|
|
## Safety Rules
|
|
|
|
- **`scripts/optimize/kernel-params.sh`** modifies `/etc/default/grub` — requires root, backs up to `data/backups/` first. Always maintain the Python-with-env-vars pattern for GRUB editing (no shell variable interpolation into Python code).
|
|
- **`scripts/optimize/tuned-profile.sh`** and **`rollback.sh`** require root and save previous state for rollback.
|
|
- **`data/backups/`** contains GRUB backups and tuned profile snapshots — never delete these.
|
|
- Optimization scripts that require root check `$EUID` at the top and exit immediately if not root.
|
|
- All Python blocks receive data via environment variables (`os.environ`), never via shell interpolation into Python source. This prevents injection. **Do not revert to `'''$var'''` or `"$var"` patterns inside Python heredocs.**
|
|
|
|
## Key Technical Details
|
|
|
|
- **GPU sysfs**: Auto-detected by `find_gpu_card()` in `lib/detect.sh` (matches vendor `0x1002`). Falls back to first card with `mem_info_vram_total`.
|
|
- **Memory recommendations**: `recommended_gttsize_mib()` in `detect.sh` computes from total physical RAM = visible RAM + dedicated VRAM (the VRAM is still physical memory). Floor at 1 GiB.
|
|
- **Kernel param detection**: `detect_kernel_param()` uses word-boundary-anchored regex to avoid `iommu` matching `amd_iommu`.
|
|
- **Benchmark invocation**: `toolbox run -c NAME -- [env ROCBLAS_USE_HIPBLASLT=1] /path/to/llama-bench -ngl 99 -mmp 0 -fa 1 -r N`. ENV_ARGS passed as a proper bash array (not string splitting).
|
|
- **llama-bench output**: Pipe-delimited table. Python parser at fixed column indices (parts[8]=test, parts[9]=t/s). Format changes upstream would break parsing.
|
|
- **ROCm for gfx1151**: `ROCBLAS_USE_HIPBLASLT=1`, `HSA_OVERRIDE_GFX_VERSION=11.5.1`.
|
|
- **Fedora GRUB**: Prefers `grubby` (BLS) over `grub2-mkconfig`. Both paths are handled.
|
|
|
|
## Conventions
|
|
|
|
- `set -euo pipefail` in every executable script
|
|
- `snake_case` function names, `UPPER_CASE` for constants and loop variables
|
|
- 4-space indentation, no tabs
|
|
- `lib/` files are sourced (no shebang enforcement), but include `#!/usr/bin/env bash` for editor support
|
|
- Colors gated on `[[ -t 1 ]]` (disabled when piped)
|
|
- `bc` used for float math; `python3` for JSON and GRUB editing only
|
|
|
|
## Validating Changes
|
|
|
|
```bash
|
|
make audit # Quick check — shows system status with pass/fail indicators
|
|
make verify # 9-point optimization checklist
|
|
bin/audit --json | python3 -m json.tool # Verify JSON output is valid
|
|
```
|
|
|
|
## External Resources
|
|
|
|
All external links are centralized in [docs/references.md](docs/references.md). Key ones:
|
|
- AMD ROCm Strix Halo guide (kernel params, GTT configuration)
|
|
- Donato Capitella toolboxes (container images, benchmarks, VRAM estimator)
|