v0.2.1: add developer quick links, reverse engineering artifacts section, clarify VF 88 is not conservative

Author: SHANAjam

README.md

@@ -5,7 +5,9 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![CI](https://github.com/SHANAjam/rtx5090-xbar-control/actions/workflows/ci.yml/badge.svg)](https://github.com/SHANAjam/rtx5090-xbar-control/actions/workflows/ci.yml)
 
-**中文版**：[README.zh-CN.md](README.zh-CN.md) · **技术文档**：[English](docs/TECHNICAL_NOTES.md) / [中文](docs/TECHNICAL_NOTES.zh-CN.md)
+**中文版**：[README.zh-CN.md](README.zh-CN.md)
+
+**👨‍💻 Developers, jump straight to:** [Technical Notes (EN)](docs/TECHNICAL_NOTES.md) · [技术说明 (中文)](docs/TECHNICAL_NOTES.zh-CN.md)
 
 ---
 
@@ -110,7 +112,9 @@ VF     : start at +88 MHz (tune per card)
 ```
 
 - `VF +88 MHz` means adding an 88 MHz frequency offset to the selected XBAR V/F points.
+- **88 MHz is not a "conservative" value.** It was a starting point on the author's card.
 - Different cards / VBIOS / cooling may need different values.
+- If you want to be more conservative, start with **+44 MHz or 0 MHz**.
 - If unstable, lower XBAR first.
 
 ---

README.zh-CN.md

@@ -5,7 +5,9 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![CI](https://github.com/SHANAjam/rtx5090-xbar-control/actions/workflows/ci.yml/badge.svg)](https://github.com/SHANAjam/rtx5090-xbar-control/actions/workflows/ci.yml)
 
-**English**：[README.md](README.md) · **技术文档**：[English](docs/TECHNICAL_NOTES.md) / [中文](docs/TECHNICAL_NOTES.zh-CN.md)
+**English**：[README.md](README.md)
+
+**👨‍💻 开发者直达：** [技术说明 (中文)](docs/TECHNICAL_NOTES.zh-CN.md) · [Technical Notes (EN)](docs/TECHNICAL_NOTES.md)
 
 ---
 
@@ -110,7 +112,9 @@ VF     ：从 +88 MHz 开始试（每张卡单独调）
 ```
 
 - `VF +88 MHz` 表示给选中的 XBAR V/F 点额外加 88 MHz 频率偏移。
+- **88 MHz 不是“保守值”**，只是作者机器上的起点。
 - 不同显卡 / VBIOS / 散热需要不同值。
+- 想更保守可以从 **+44 MHz 或 0 MHz** 开始。
 - 不稳定就先降低 XBAR。
 
 ---

docs/TECHNICAL_NOTES.md

@@ -12,8 +12,13 @@
   - [3.3 V/F points](#33-vf-points)
   - [3.4 PERF limits](#34-perf-limits)
   - [3.5 L2 stability test](#35-l2-stability-test)
-- [4. Dynamic layout adaptation](#4-dynamic-layout-adaptation)
-- [5. Driver validation matrix](#5-driver-validation-matrix)
+- [4. Reverse engineering process and artifacts](#4-reverse-engineering-process-and-artifacts)
+- [5. Dynamic layout adaptation](#5-dynamic-layout-adaptation)
+- [6. Driver validation matrix](#6-driver-validation-matrix)
+- [7. Debugging](#7-debugging)
+- [8. Adding support for a new driver](#8-adding-support-for-a-new-driver)
+- [9. References](#9-references)
+- [10. Known limitations](#10-known-limitations)
 - [6. Debugging](#6-debugging)
 - [7. Adding support for a new driver](#7-adding-support-for-a-new-driver)
 - [8. References](#8-references)
@@ -106,7 +111,37 @@ docs/
 - Uses random L2 reads over a 32 MiB buffer and atomic mismatch counting.
 - Integrated as `l2-test`.
 
-## 4. Dynamic layout adaptation
+## 4. Reverse engineering process and artifacts
+
+The disassembly process is documented through:
+
+- Static table parsing (`scripts/validate_nvapi_drivers.py`)
+- Offset derivation (`scripts/derive_nvapi_offsets.py`)
+- Capstone disassembly tool (`scripts/disasm_nvapi.py`)
+- Raw disassembly artifacts in [`docs/reverse/`](reverse/)
+
+The key steps were:
+
+1. Locate the NvAPI static ID table (`{u64 ptr, u32 id, u32 pad}`).
+2. Resolve wrapper stubs and real implementations.
+3. Disassemble the real functions and identify version checks.
+4. Map buffer writes to structure fields.
+5. Cross-validate across R572..R610.
+
+Raw files include:
+
+```text
+docs/reverse/lookup_102f50_full_61088.txt
+docs/reverse/get_info_real_full_61088.txt
+docs/reverse/get_control_real_full_61088.txt
+docs/reverse/set_control_real_full_61088.txt
+docs/reverse/clk_get_61088.txt
+docs/reverse/vf_status_61088.txt
+docs/reverse/vf_get_61088.txt
+docs/reverse/rtx5090_gameready_direct_links.txt
+```
+
+## 5. Dynamic layout adaptation
 
 The program no longer relies on per-card hardcoded layout for:
 
@@ -118,7 +153,7 @@ The program no longer relies on per-card hardcoded layout for:
 
 Remaining constants are NvAPI structure field offsets (e.g. `+0x114`, `+0x38`). They are API-structure-level and were verified across R572..R610.
 
-## 5. Driver validation matrix
+## 6. Driver validation matrix
 
 Validated driver versions (desktop and selected notebook):
 
@@ -140,7 +175,7 @@ Scripts:
 python scripts/run_full_validation.py
 ```
 
-## 6. Debugging
+## 7. Debugging
 
 ```powershell
 python run.py --verbose --log-file debug.log status
@@ -160,7 +195,7 @@ If `probe` fails:
 - Do **not** use `--force-driver`.
 - Collect `probe` output and report it.
 
-## 7. Adding support for a new driver
+## 8. Adding support for a new driver
 
 1. Obtain `nvapi64.dll` or `nvapi64_impl.dll` from the driver package.
 2. Run:
@@ -171,15 +206,15 @@ If `probe` fails:
 3. If all checks pass, add the version prefix to `driver_check.VALIDATED_DRIVER_PREFIXES`.
 4. If a check fails, reverse-engineer the new layout and update this document.
 
-## 8. References
+## 9. References
 
 - LACT issue #1147: https://github.com/ilya-zlobintsev/LACT/issues/1147
 - LACT PR #1158: https://github.com/ilya-zlobintsev/LACT/pull/1158
 - LACT issue #1159: https://github.com/ilya-zlobintsev/LACT/issues/1159
 - NVIDIA/open-gpu-kernel-modules#1266: https://github.com/NVIDIA/open-gpu-kernel-modules/issues/1266
 - mVolt+: https://github.com/b00nz/mVolt
 
-## 9. Known limitations
+## 10. Known limitations
 
 - Physical MSVDD direct read is not implemented.
 - PERF limits SET is not exposed.

docs/TECHNICAL_NOTES.zh-CN.md

@@ -12,12 +12,13 @@
   - [3.3 V/F 点](#33-vf-点)
   - [3.4 PERF limits](#34-perf-limits)
   - [3.5 L2 稳定性测试](#35-l2-稳定性测试)
-- [4. 动态布局适配](#4-动态布局适配)
-- [5. 驱动验证矩阵](#5-驱动验证矩阵)
-- [6. 调试](#6-调试)
-- [7. 如何支持新驱动](#7-如何支持新驱动)
-- [8. 参考链接](#8-参考链接)
-- [9. 已知限制](#9-已知限制)
+- [4. 反汇编过程与产物](#4-反汇编过程与产物)
+- [5. 动态布局适配](#5-动态布局适配)
+- [6. 驱动验证矩阵](#6-驱动验证矩阵)
+- [7. 调试](#7-调试)
+- [8. 如何支持新驱动](#8-如何支持新驱动)
+- [9. 参考链接](#9-参考链接)
+- [10. 已知限制](#10-已知限制)
 
 ## 1. 项目结构
 
@@ -106,7 +107,37 @@ docs/
 - 使用 32 MiB 缓冲区随机 L2 读取 + 原子错误计数。
 - 集成命令：`l2-test`。
 
-## 4. 动态布局适配
+## 4. 反汇编过程与产物
+
+反汇编过程通过以下内容记录：
+
+- 静态表解析：`scripts/validate_nvapi_drivers.py`
+- 偏移推导：`scripts/derive_nvapi_offsets.py`
+- Capstone 反汇编工具：`scripts/disasm_nvapi.py`
+- 原始反汇编产物：[`docs/reverse/`](reverse/)
+
+关键步骤：
+
+1. 定位 NvAPI 静态 ID 表（`{u64 ptr, u32 id, u32 pad}`）。
+2. 解析 wrapper 与真实实现。
+3. 反汇编真实函数并识别版本检查。
+4. 将 buffer 写入映射到结构体字段。
+5. 跨 R572..R610 交叉验证。
+
+原始文件包括：
+
+```text
+docs/reverse/lookup_102f50_full_61088.txt
+docs/reverse/get_info_real_full_61088.txt
+docs/reverse/get_control_real_full_61088.txt
+docs/reverse/set_control_real_full_61088.txt
+docs/reverse/clk_get_61088.txt
+docs/reverse/vf_status_61088.txt
+docs/reverse/vf_get_61088.txt
+docs/reverse/rtx5090_gameready_direct_links.txt
+```
+
+## 5. 动态布局适配
 
 程序已不再依赖以下硬编码：
 
@@ -118,7 +149,7 @@ docs/
 
 剩余常量是 NvAPI 结构体字段偏移（如 `+0x114`、`+0x38`），属于 API 结构定义，已在 R572..R610 验证一致。
 
-## 5. 驱动验证矩阵
+## 6. 驱动验证矩阵
 
 已验证驱动版本（桌面 + 部分笔记本）：
 
@@ -140,7 +171,7 @@ docs/
 python scripts/run_full_validation.py
 ```
 
-## 6. 调试
+## 7. 调试
 
 ```powershell
 python run.py --verbose --log-file debug.log status
@@ -160,7 +191,7 @@ python run.py perf --json
 - **不要**使用 `--force-driver`。
 - 收集 `probe` 输出并反馈。
 
-## 7. 如何支持新驱动
+## 8. 如何支持新驱动
 
 1. 从驱动包获取 `nvapi64.dll` 或 `nvapi64_impl.dll`。
 2. 运行：
@@ -171,15 +202,15 @@ python run.py perf --json
 3. 全部通过后，把版本前缀加入 `driver_check.VALIDATED_DRIVER_PREFIXES`。
 4. 如果有失败项，需要重新逆向布局并更新本文档。
 
-## 8. 参考链接
+## 9. 参考链接
 
 - LACT issue #1147：https://github.com/ilya-zlobintsev/LACT/issues/1147
 - LACT PR #1158：https://github.com/ilya-zlobintsev/LACT/pull/1158
 - LACT issue #1159：https://github.com/ilya-zlobintsev/LACT/issues/1159
 - NVIDIA/open-gpu-kernel-modules#1266：https://github.com/NVIDIA/open-gpu-kernel-modules/issues/1266
 - mVolt+：https://github.com/b00nz/mVolt
 
-## 9. 已知限制
+## 10. 已知限制
 
 - 物理 MSVDD 直接读取未实现。
 - PERF limits SET 未暴露。