fix(docs): address review findings — accuracy, consistency, completeness
- architecture.md: fix kernel param math to match actual computed values, use cardN placeholder in sysfs paths, clarify system_ram_kb is OS-visible - benchmarking.md: normalize flags to -ngl 99 / -mmp 0 (matching code), add llama-rocm7-nightlies backend - CLAUDE.md: clarify HSA_OVERRIDE_GFX_VERSION is set in containers not scripts, fix lib sourcing description, specify which scripts need root - detect.sh: document detect_cpu_cores returns threads not cores - troubleshooting.md: add link to references.md - README.md: remove unsupported Fedora 42 claim, describe configs/ content Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Felipe Cardoso
@@ -25,7 +25,7 @@ data/ Runtime output (gitignored)
|
||||
docs/ Documentation
|
||||
```
|
||||
|
||||
Every script sources libs in order: `common.sh` → `detect.sh` → `format.sh`. `format.sh` depends on color variables defined in `common.sh`.
|
||||
Scripts source libs as needed: always `common.sh` first, then `detect.sh` for hardware detection, then `format.sh` for formatted output. Not all scripts need all three — `rollback.sh` only needs `common.sh`, for example. `format.sh` depends on color variables defined in `common.sh`.
|
||||
|
||||
## Data Flow
|
||||
|
||||
@@ -54,33 +54,40 @@ AMD Strix Halo shares physical RAM between CPU and GPU. Two allocation mechanism
|
||||
|
||||
**Optimal for LLM workloads**: Minimize VRAM (0.5 GiB), maximize GTT (~60 GiB on 64 GB system). The GPU borrows memory when needed and releases it when idle.
|
||||
|
||||
### Kernel Parameter Math (64 GB system)
|
||||
### Kernel Parameter Math
|
||||
|
||||
The formula (using integer GiB arithmetic):
|
||||
|
||||
```
|
||||
Total physical RAM: 64 GiB
|
||||
OS reserve: 4 GiB
|
||||
Available for GTT: 60 GiB = 61440 MiB
|
||||
|
||||
amdgpu.gttsize = 60 * 1024 = 61440 (MiB)
|
||||
ttm.pages_limit = 60 * 1024 * 256 = 15728640 (4K pages)
|
||||
iommu = pt (passthrough, lower latency)
|
||||
total_physical_gib = (visible_ram + dedicated_vram) / 1024 / 1024 (integer division)
|
||||
gtt_gib = total_physical_gib - 4 (4 GiB OS reserve)
|
||||
amdgpu.gttsize = gtt_gib * 1024 (MiB)
|
||||
ttm.pages_limit = amdgpu.gttsize * 256 (4K pages)
|
||||
iommu = pt (passthrough)
|
||||
```
|
||||
|
||||
The toolkit computes these dynamically via `recommended_gttsize_mib()` and `recommended_pages_limit()` in `lib/detect.sh`, based on detected total physical RAM (visible + VRAM).
|
||||
Actual values depend on how the OS reports memory. On a 64 GB HP ZBook with 32 GB dedicated VRAM:
|
||||
|
||||
```
|
||||
visible_ram ≈ 31.1 GiB, vram = 32 GiB → total ≈ 63 GiB (integer: 59 GiB GTT)
|
||||
amdgpu.gttsize = 60416, ttm.pages_limit = 15466496
|
||||
```
|
||||
|
||||
Run `make audit` to see the exact computed values for your system. The toolkit computes these dynamically via `recommended_gttsize_mib()` and `recommended_pages_limit()` in `lib/detect.sh`.
|
||||
|
||||
### Sysfs Paths
|
||||
|
||||
Card number is auto-detected by `find_gpu_card()` in `lib/detect.sh` (matches AMD vendor ID `0x1002`, falls back to first card with `mem_info_vram_total`). Below uses `cardN` as placeholder:
|
||||
|
||||
| Path | Content |
|
||||
|------|---------|
|
||||
| `/sys/class/drm/card1/device/mem_info_vram_total` | Dedicated VRAM in bytes |
|
||||
| `/sys/class/drm/card1/device/mem_info_vram_used` | VRAM currently in use |
|
||||
| `/sys/class/drm/card1/device/mem_info_gtt_total` | GTT allocation in bytes |
|
||||
| `/sys/class/drm/card1/device/mem_info_gtt_used` | GTT currently in use |
|
||||
| `/sys/class/drm/card1/device/gpu_busy_percent` | GPU utilization 0-100 |
|
||||
| `/sys/class/drm/card1/device/hwmon/hwmon*/temp1_input` | Temperature in millidegrees C |
|
||||
| `/sys/class/drm/card1/device/hwmon/hwmon*/power1_average` | Power in microwatts |
|
||||
|
||||
Card number is auto-detected by `find_gpu_card()` (matches AMD vendor ID `0x1002`).
|
||||
| `/sys/class/drm/cardN/device/mem_info_vram_total` | Dedicated VRAM in bytes |
|
||||
| `/sys/class/drm/cardN/device/mem_info_vram_used` | VRAM currently in use |
|
||||
| `/sys/class/drm/cardN/device/mem_info_gtt_total` | GTT allocation in bytes |
|
||||
| `/sys/class/drm/cardN/device/mem_info_gtt_used` | GTT currently in use |
|
||||
| `/sys/class/drm/cardN/device/gpu_busy_percent` | GPU utilization 0-100 |
|
||||
| `/sys/class/drm/cardN/device/hwmon/hwmon*/temp1_input` | Temperature in millidegrees C |
|
||||
| `/sys/class/drm/cardN/device/hwmon/hwmon*/power1_average` | Power in microwatts |
|
||||
|
||||
## JSON Output Schemas
|
||||
|
||||
@@ -89,7 +96,7 @@ Card number is auto-detected by `find_gpu_card()` (matches AMD vendor ID `0x1002
|
||||
```json
|
||||
{
|
||||
"timestamp": "20260325-120000",
|
||||
"hardware": { "cpu_model": "...", "cpu_cores": 16, "cpu_threads": 32, "gpu_name": "...", "gpu_device_id": "1586", "system_ram_kb": 32609248 },
|
||||
"hardware": { "cpu_model": "...", "cpu_cores": 16, "cpu_threads": 32, "gpu_name": "...", "gpu_device_id": "1586", "system_ram_kb": 32609248 }, // OS-visible RAM (excludes dedicated VRAM)
|
||||
"memory": { "vram_total_bytes": 0, "vram_used_bytes": 0, "gtt_total_bytes": 0, "gtt_used_bytes": 0, "recommended_gttsize_mib": 0, "recommended_pages_limit": 0 },
|
||||
"kernel": { "version": "...", "cmdline": "...", "param_iommu": "", "param_gttsize": "", "param_pages_limit": "" },
|
||||
"firmware": "...", "tuned_profile": "...", "rocm_version": "...",
|
||||
|
||||
@@ -32,7 +32,7 @@ Results are in **tokens/second (t/s)**. Higher is better.
|
||||
- `-ub SIZE` — micro-batch size (512 for Vulkan, 2048 for ROCm)
|
||||
- `-r 3` — 3 repetitions (long-context tests are slow)
|
||||
|
||||
The `-fa 1 --no-mmap -ngl 999` flags are **mandatory** on Strix Halo to avoid crashes.
|
||||
The `-fa 1 -mmp 0 -ngl 99` flags are **mandatory** on Strix Halo to avoid crashes (`-fa 1` = flash attention, `-mmp 0` = no memory mapping, `-ngl 99` = all layers on GPU).
|
||||
|
||||
## Available Backends
|
||||
|
||||
@@ -42,6 +42,7 @@ The `-fa 1 --no-mmap -ngl 999` flags are **mandatory** on Strix Halo to avoid cr
|
||||
| `llama-vulkan-amdvlk` | AMDVLK | Vulkan | Fastest when it works, 2GB buffer limit |
|
||||
| `llama-rocm-6.4.4` | ROCm 6.4.4 | HIP | Proven stable |
|
||||
| `llama-rocm-7.2` | ROCm 7.2 | HIP | Latest, compiler fixes applied |
|
||||
| `llama-rocm7-nightlies` | ROCm 7 nightly | HIP | Experimental/development builds |
|
||||
|
||||
Containers are from [kyuz0/amd-strix-halo-toolboxes](https://github.com/kyuz0/amd-strix-halo-toolboxes). Set up with `make benchmark-setup`.
|
||||
|
||||
|
||||
@@ -94,3 +94,7 @@ 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](optimization.md) for the full rollback procedure.
|
||||
|
||||
## Further Resources
|
||||
|
||||
For external tool documentation, upstream bug trackers, and community resources, see [docs/references.md](references.md).
|
||||
|
||||
Reference in New Issue
Block a user