Blamp26/boardcontrol

# boardcontrol     **快速链接：** [文档](#documentation) · [项目导航](#project-map) · [安全模型](#safety-model) · [路线图](#roadmap) 开源实验性替代方案，用于在 MSI `7A45` 系列主板上执行低级 LED 初始化控制，可替代 MSI Center / Mystic Light。 当前代码库是一个安全第一的研究 MVP。它对已知的寄存器级行为进行了建模，但尚未执行真实的硬件写入。 ## 文档 - [知识图谱](docs/KNOWLEDGE_MAP.md) - 架构、硬件路径、寄存器映射和安全模型。 - [安全模型](docs/SAFETY.md) - 安全规则、预检门控和写入策略。 - [受控写入设计](docs/CONTROLLED_WRITE_DESIGN.md) - 为未来 NCT 硬件写入计划的门控设计。 - [已测试环境](docs/TESTED_ENVIRONMENTS.md) - 已知的安全回归结果和目标测试状态。 - [MSI 7A45 只读测试计划](docs/MSI_7A45_READONLY_TEST_PLAN.md) - 首个真实目标只读验证清单。 - [MSI MS-7E75 研究笔记](docs/MSI_7E75_RESEARCH.md) - 针对采用 B850 GAMING PLUS WIFI PZ 主板的纯研究笔记。 - [MSI MS-7E75 研究计划](docs/MSI_7E75_RESEARCH_PLAN.md) - 在进行任何硬件探测之前的阶段性安全计划。 - [MSI MS-7E75 静态逆向工程笔记](docs/MSI_7E75_STATIC_RE.md) - 整合的 MSI Center / Mystic Light 模块静态发现与相关性映射。 - [MSI MS-7E75 配置文件选择静态笔记](docs/MSI_7E75_PROFILE_SELECTION_STATIC_RE.md) - 针对 MSI Center / Mystic Light 主板配置文件、区域和路径选择证据的静态搜索。 - [MSI MS-7E75 LEDKeeper2 静态笔记](docs/MSI_7E75_LEDKEEPER_STATIC_RE.md) - LEDKeeper2.exe 元数据、字符串、资源、配置文件/区域和调度候选的静态证据。 - [MSI MS-7E75 配置数据静态笔记](docs/MSI_7E75_PROFILE_DATA_STATIC_RE.md) - 显示 MS-7E75 区域记录的 Mystic Light 在线/配置文件数据的静态解码。 - [MSI MS-7E75 区域调用路径静态笔记](docs/MSI_7E75_ZONE_CALLPATH_STATIC_RE.md) - 静态的 MS-7E75 区域到 `Class_MB_800` / `MSI_800sLed` 辅助调用路径证据。 - [MSI MS-7E75 MB800 HID 静态笔记](docs/MSI_7E75_HID_MB800_STATIC_RE.md) - 针对 MB800 路径的静态 HID 包装器、设备打开以及 Gen1/Gen2 特征报告布局证据。 - [MSI MS-7E75 MsiHid 原生静态笔记](docs/MSI_7E75_MSIHID_STATIC_RE.md) - 针对 MB800 路径的原生 `MsiHid.dll` 设备过滤、打开和 `HidD_SetFeature` 包装器静态证据。 - [MSI MS-7E75 驱动引擎静态笔记](docs/MSI_7E75_DRIVER_ENGINE_STATIC_RE.md) - 直接的静态 Driver_Engine.dll 传输、服务、设备和 IOCTL 证据。 - [MSI MS-7E75 SMBus 引擎静态笔记](docs/MSI_7E75_SMBUS_ENGINE_STATIC_RE.md) - 静态的 SMBus_Engine.dll 事务和控制器选择证据。 - [MSI MS-7E75 RTK 桥接静态笔记](docs/MSI_7E75_RTK_BRIDGE_STATIC_RE.md) - 静态的 rtk_bridge.dll Realtek 桥接/设备句柄证据及 MS-7E75 相关性评估。 - [MSI MS-7E75 CPU 引擎静态笔记](docs/MSI_7E75_CPU_ENGINE_STATIC_RE.md) - 静态的 CPU_Engine.dll CPU 遥测/调优证据及 MS-7E75 相关性评估。 ## 项目导航 ``` flowchart LR App[MSI Center / Mystic Light] --> DLL[MBAPI / Driver Engine] DLL --> Driver[NTIOLib driver] Driver --> NCT[Nuvoton NCT6779D] Driver --> SMBus[Intel SMBus] NCT --> Init[7A45 LED init/reset] SMBus --> Renesas[Renesas LED controller 0x52] Renesas --> RGB[RGB / effects / modes] boardcontrol[boardcontrol Rust CLI] --> Doctor[doctor preflight] boardcontrol --> Trace[TraceBackend] boardcontrol --> ReadOnly[Linux read-only NCT reads] Doctor --> Safety[DMI + /proc/ioports + /dev/port checks] ReadOnly --> Allowlist[7A45 allowlist] ``` `boardcontrol` 目前实现了该映射中安全/只读的部分：trace 模拟、DMI 预检、芯片检测以及已加入允许列表的 NCT 寄存器读取。LED 写入/应用命令尚未实现。 plan 命令会计算 RMW 报告，但不会向硬件写入数据或更改 trace 后端的状态。 ## 项目状态 当前 MVP 状态： - Rust CLI - 用于安全序列模拟的 trace 后端 - 实验性 Linux 只读 Super I/O 芯片检测 - 暂无真实的 LED 硬件写入 - 仅支持 MSI 主板配置文件 `7A45` - 对 Nuvoton NCT6779D LED 初始化/重置序列进行了建模 - 包含安全的 RMW 允许列表逻辑 - 通过了 `cargo check`、`cargo test` 和 `cargo clippy -- -D warnings` ## 支持的硬件状态 | 主板 | Super I/O | Renesas SMBus | 状态 | | --- | --- | --- | --- | | `7A45` | `Nuvoton NCT6779D` | `0x52` | `Trace 模拟 + 实验性 Linux 只读芯片检测` | ## 架构 MSI 7A45 LED 控制路径： - 通过端口 `0x4E / 0x4F` 的 NCT6779D Super I/O - 通过 Intel SMBus 地址 `0x52` 的 Renesas LED 控制器 MVP 结构： - `TraceBackend` - 主板配置文件 - NCT 允许列表 - RMW 执行器 - CLI 命令 ## 安全模型 - 没有盲写操作 - 所有 NCT 写入都被建模为 read-modify-write - 每一个更改的位都必须由 `(LDN, REG, allowed_change_mask)` 允许 - 不支持未知主板 - 刻意暂未实现真实硬件写入 ``` new_value = (current & and_mask) | or_mask changed = current ^ new_value if changed & !allowed_change_mask != 0: block else: write ``` ## 当前 CLI ``` cargo run -- detect --board 7A45 cargo run -- nct init-7a45 --dry-run cargo run -- nct reset-led --dry-run cargo run -- nct plan-init-7a45 cargo run -- nct plan-reset-led ``` `--dry-run` 命令会首先打印规划报告，然后对 `TraceBackend` 执行相同的序列。 plan 命令仅计算 RMW 报告，甚至不会修改 trace 后端。 安全的 CI 冒烟测试仅涵盖 trace/规划命令，不访问硬件。 ## 测试命令 ``` cargo fmt cargo check cargo test cargo clippy -- -D warnings ``` ## 路线图 - [x] 仅 Trace 的 Rust CLI MVP - [x] 7A45 NCT 初始化/重置序列模型 - [x] 安全的 RMW 允许列表测试 - [x] Linux 只读 NCT6779D 芯片检测 - [x] Linux 只读允许列表内的 NCT 寄存器读取 - [x] 安全的 doctor/预检诊断 - [x] RMW 规划/报告层 - [x] 仅用于研究的 MS-7E75 DMI 检测 - [ ] 用于受控 NCT RMW 写入的 Linux `/dev/port` 后端 - [x] `/proc/ioports` 冲突检查 - [ ] Renesas SMBus 原始写入后端 - [ ] Renesas RGB/模式映射 - [ ] Windows 后端 ## 实验性只读硬件检测 ``` cargo run -- nct detect-chip --backend dev-port --confirm-read ``` 此命令仅执行 Super I/O 配置模式寄存器读取以进行芯片识别。它不执行 LED 初始化/重置写入。 仅限 Linux。需要访问 `/dev/port` 的权限。如果没有 `--confirm-read`，该命令将拒绝运行。 硬件读取命令受 Linux DMI 检查限制，预计仅在类似 MSI 7A45 的主机上运行。非目标系统（例如 Dell OptiPlex 机器）将在打开 `/dev/port` 之前被拒绝。 ## 安全诊断 ``` cargo run -- doctor ``` `doctor` 仅执行非侵入式的环境检查。它读取 DMI 和 `/proc/ioports`，检查 `/dev/port` 是否存在，并解释硬件读取命令是否会被阻止。它不会打开 `/dev/port`，也不会执行 Super I/O 端口 I/O。 ## 实验性允许列表寄存器读取 ``` cargo run -- nct read-reg --board 7A45 --backend dev-port --ldn 0x09 --reg 0xE0 --confirm-read ``` 此命令仅为选定的主板配置文件读取单个已加入允许列表的 NCT6779D 寄存器。它会拒绝未知的主板、不支持的芯片、未加入允许列表的寄存器，并且仅在显式使用 `--confirm-read` 后运行。 ## 法律 / 项目声明 本项目不包含 MSI 二进制文件、MSI 驱动程序、MSI 徽标或反编译的 MSI 源代码。它是一个独立的净室实现，基于观察到的硬件行为和寄存器级研究。

标签：Rust, SMBus, 主板驱动, 可视化界面, 文档结构分析, 硬件控制, 硬件逆向, 网络流量审计, 通知系统