更新源码

2026-04-04 18:13:40 +08:00
parent 2e20b8e2c5
commit beed35ec13
31 changed files with 1632 additions and 209 deletions
--- a/docs/windows/HARDWARE_ID_DRIVER_MAP_Windows.md
+++ b/docs/windows/HARDWARE_ID_DRIVER_MAP_Windows.md
@@ -0,0 +1,107 @@
+# Windows：设备管理器 Hardware ID → 驱动包映射（Kaisa / Chromebox 10 代）
+
+本文面向 **Coreboot + Windows** 下的音频排障：把「设备管理器里看到的 Hardware ID / 实例 ID」**对应到应装哪一类驱动包**，以及**不要用**哪类通用包。
+
+> 采集样例（真实硬件）见 `collected/audio_topology_windows_DESKTOP-56TM6AL_20260213_205300.txt`。  
+> 安装顺序与故障现象仍见 [OPERATION_Windows_Audio.md](OPERATION_Windows_Audio.md)。
+
+---
+
+## 一、如何拿到 Hardware ID（务必复制完整）
+
+1. **设备管理器** → 找到目标设备（音频相关多在「声音、视频和游戏控制器」）。
+2. 右键 → **属性** → **详细信息**。
+3. 下拉属性选 **硬件 Id** 或 **设备实例路径**（两者都建议各复制一份）。
+4. 若设备在「其他设备」或带黄色感叹号，同样复制 **Hardware Id**。
+
+**PowerShell 快速导出（可选，管理员）**：
+
+```powershell
+Get-PnpDevice -Class Media,AudioEndpoint -ErrorAction SilentlyContinue |
+  Select-Object Status, FriendlyName, InstanceId |
+  Format-Table -AutoSize
+```
+
+---
+
+## 二、ID 形态速查（先认前缀再选包）
+
+| 前缀 / 形态 | 通常含义 | 驱动来源倾向 |
+|-------------|----------|----------------|
+| `PCI\VEN_8086&DEV_...` | Intel 设备（含 HD Audio 控制器、部分 DSP 相关） | **Inbox Intel** 或 **CoolStar 包内 Intel 组件**（以机型页为准） |
+| `PCI\VEN_10EC&DEV_...` | Realtek PCI 设备（多为网卡等，非本机 3.5mm codec） | 一般 **不是** 3.5mm 耳机路径 |
+| `HDAUDIO\FUNC_01&VEN_8086&DEV_...` | Intel **HD Audio 函数**（常见为 **显示器音频 / HDMI Audio**） | 多为 **Intel 显示器音频**（系统自带或 Intel 更新），一般 **不是** CoolStar 主战场 |
+| `ACPI\10EC5682\...` | ACPI 枚举的 **Realtek ALC5682（I2S）** | **CoolStar 包内 Realtek ALC5682 I2S**（或同机型说明中的 I2S 驱动） |
+| `CSAUDIO\...` | **CoolStar 自定义 SOF 音频栈** | **CoolStar SOF Audio (WDM)** 对应驱动包；若 Error 需按 CoolStar 顺序重装 |
+| `SWD\MMDEVAPI\{...}` | **音频端点**（扬声器/耳机/显示器名称） | **不是物理驱动**，由上层驱动枚举；排障时看 **Media 类设备** 的 ID |
+
+---
+
+## 三、本仓库实测样例（Kaisa，与采集文件一致）
+
+以下 **InstanceId** 与 `collected/audio_topology_windows_*.txt` 中一致，可作为「设备名 ↔ ID ↔ 驱动包类型」的锚点。
+
+### 1) CoolStar SOF Audio (WDM) — 常为 3.5mm 路径关键依赖
+
+| 项目 | 值 |
+|------|-----|
+| **友好名称** | CoolStar SOF Audio (WDM) |
+| **实例 ID（示例）** | `CSAUDIO\ADSP&CTLR_VEN_8086&CTLR_DEV_02C8\4&...&268435456` |
+| **含义** | CoolStar 提供的 **SOF/ADSP** 栈；`CTLR_VEN_8086&CTLR_DEV_02C8` 表示与 **Intel 控制器设备** 绑定。 |
+| **应对驱动包** | **CoolStar 包内「SOF Audio / Intel SOF/I2S」类组件**（具体 INF 名随版本变，以机型页与包内 readme 为准）。 |
+| **常见故障** | 设备管理器显示 **Error** 时，易出现「ALC5682 显示 OK 但无声音」——优先 **消除该 Error** 再处理 ALC5682。 |
+
+### 2) Realtek ALC5682 I2S Audio — 耳机 Codec
+
+| 项目 | 值 |
+|------|-----|
+| **友好名称** | Realtek ALC5682 I2S Audio |
+| **硬件 ID（示例）** | `ACPI\10EC5682\0`（即 **10EC:5682**） |
+| **含义** | **Realtek ALC5682** 走 **I2S**，不是桌面机常见的 HDA PCI 声卡。 |
+| **应对驱动包** | **CoolStar 包内「ALC5682 I2S」**（或同文档命名的 Realtek I2S 驱动）。 |
+| **不要用** | 网上通用 **Realtek UAD / 台式机 OEM** 安装包强行覆盖（ACPI/I2S 与 Chromebox 不一致）。 |
+
+### 3) 英特尔(R) 显示器音频 — HDMI 正常时常无需再动
+
+| 项目 | 值 |
+|------|-----|
+| **友好名称** | 英特尔(R) 显示器音频 |
+| **实例 ID（示例）** | `HDAUDIO\FUNC_01&VEN_8086&DEV_280B&SUBSYS_80860101&REV_1000\4&...&02` |
+| **含义** | Intel **HD Audio 节点**，`DEV_280B` 对应 **Display Audio** 一类设备。 |
+| **应对驱动包** | 通常 **Windows 自带 / Intel 显卡驱动附带** 即可；若已 OK，**不要**为修 3.5mm 去乱换通用 Realtek。 |
+
+### 4) CoolStar HD Audio（PCI 类）
+
+采集文件中存在 **CoolStar HD Audio**（`PCI\VEN_...`，内容截断）。一般对应 **CoolStar 包内 HD Audio 总线/控制器** 部分，安装顺序上常 **先于或与 SOF 协同**，以 **CoolStar 机型页 README** 为准。
+
+---
+
+## 四、映射表（按「你看到的 ID」→「该装哪类包」）
+
+| 你在 Hardware Id / 实例 ID 里看到 | 应优先找的驱动包类型（CoolStar / Chrultrabook） |
+|-----------------------------------|-----------------------------------------------|
+| `CSAUDIO\...` | **SOF / ADSP（CoolStar SOF Audio）** |
+| `ACPI\10EC5682...` 或含 `10EC5682` | **Realtek ALC5682 I2S** |
+| `HDAUDIO\...VEN_8086&DEV_280B...` | **Intel 显示器音频**（HDMI）；**一般不是** 3.5mm 根因 |
+| `PCI\VEN_8086&DEV_02C8...`（若出现在音频控制器相关设备上） | 与 **Intel 音频控制器** 相关；**配合 CoolStar SOF 包** 安装/更新 |
+| 仅有 `SWD\MMDEVAPI\{...}` | **端点**；请回到 **Media** 类设备查 `CSAUDIO` / `ACPI\10EC5682` |
+
+---
+
+## 五、与 `pnputil` 对照（可选）
+
+若需确认某台机器上 **哪个 INF 已安装**、便于冲突排查：
+
+```cmd
+pnputil /enum-drivers | findstr /i "coolstar realtek intel sof"
+```
+
+（输出因系统语言与驱动版本而异；把可疑 `oem*.inf` 与设备管理器里驱动版本对照即可。）
+
+---
+
+## 六、参考
+
+- 操作步骤（安装顺序、Error 处理）：[OPERATION_Windows_Audio.md](OPERATION_Windows_Audio.md)
+- 三平台对比：[ANALYSIS_Audio.md](../../audio_topology/ANALYSIS_Audio.md)
+- Chrultrabook 安装后音频：<https://docs.chrultrabook.com/docs/installing/post-install.html>
--- a/docs/windows/OPERATION_Windows_Audio.md
+++ b/docs/windows/OPERATION_Windows_Audio.md
@@ -0,0 +1,93 @@
+# Windows 音频修复说明（Chromebox 10 代 / Kaisa）
+
+针对 **Coreboot 刷机后**：HDMI（英特尔显示器音频）正常，**3.5mm / Realtek ALC5682 I2S 无声、无插拔提示** 的情况。与 Linux 问题相反，修法依赖 **CoolStar / Chrultrabook 驱动栈**，不是桌面机通用 Realtek 安装包。
+
+分析背景见 [ANALYSIS_Audio.md](../../audio_topology/ANALYSIS_Audio.md)；采集样例见 `audio_topology/collected/audio_topology_windows_*.txt`。
+
+**Hardware ID → 驱动包类型映射**（按设备管理器里的 `CSAUDIO\...` / `ACPI\10EC5682\...` / `HDAUDIO\...VEN_8086&DEV_280B...` 等对号入座）：见 [HARDWARE_ID_DRIVER_MAP_Windows.md](HARDWARE_ID_DRIVER_MAP_Windows.md)。
+
+---
+
+## 现象与要点（对照设备管理器）
+
+| 设备 | 常见状态 | 含义 |
+|------|----------|------|
+| **英特尔(R) 显示器音频** | OK | HDMI 走 HDA，一般无需再动 |
+| **Realtek ALC5682 I2S Audio** | OK 但无声 | I2S codec 驱动已挂，但路由或与 SOF 协同异常 |
+| **CoolStar SOF Audio (WDM)** | **Error** | 不少机型上 **3.5mm 依赖 SOF 相关栈**；此处报错时，容易出现「ALC5682 看似正常却不出声」 |
+
+**结论**：优先消除 **CoolStar SOF Audio** 错误，再按官方顺序重装 **ALC5682 I2S**，不要单独用网上下载的通用 Realtek 安装程序覆盖。
+
+---
+
+## 一、准备
+
+1. 确认机型为 **Kaisa（puff 系）** 或与你主板一致的 Chrultrabook 条目。
+2. 准备 **CoolStar 驱动**：从购买授权时提供的 **驱动门户** 或 [CoolStar Chromebook Windows](https://coolstar.org/chromebook/windows-install.html) 机型页获取 **当前推荐版本**（包内通常含 HD Audio、SOF、I2S 等）。
+3. 备份当前系统或创建还原点。
+
+---
+
+## 二、推荐安装顺序（概要）
+
+具体以 **Chrultrabook Post-install** 与 **CoolStar 包内 readme** 为准，常见顺序为：
+
+1. 安装/更新 **CoolStar HD Audio**（若包内要求）。
+2. 安装/更新 **CoolStar SOF Audio (Intel/I2S)**（需有效授权时按说明激活）。
+3. 安装/更新 **Realtek ALC5682 I2S**（多在同一个包或后续步骤中）。
+4. **重启**后再测 3.5mm。
+
+参考：[Chrultrabook Post-install 音频](https://docs.chrultrabook.com/docs/installing/post-install.html)。
+
+---
+
+## 三、设备管理器排查
+
+### 1. 处理 CoolStar SOF Audio (WDM) 的 Error
+
+1. **属性 → 常规**：记录 **错误代码**（如 10、43 等）与文字说明。
+2. **属性 → 驱动程序**：
+   - **更新驱动**：指向 CoolStar 解压目录（**不要让 Windows 自动搜索互联网**）。
+   - 若无效：**卸载设备**（可选勾选「删除此设备的驱动程序软件」）→ 重启 → 用 **「操作 → 扫描检测硬件改动」** 或重新运行 CoolStar 安装程序。
+3. 仍 Error：到 [Chrultrabook 论坛](https://forum.chrultrabook.com/) 搜索 **机型名 + SOF + 错误码**；或向 CoolStar 支持提交工单（附 `pnputil` / 设备实例 ID）。
+
+### 2. Realtek ALC5682 I2S Audio
+
+1. 在 SOF 设备已正常或至少安装流程完整执行后，对 **ALC5682** 再执行一次 **更新驱动**（指定 CoolStar 目录）。
+2. 必要时 **卸载 ALC5682** → 重启 → 再安装，避免残留旧 `oem*.inf` 冲突。
+3. 不要用 **Alienware/台式机** 等通用 Realtek UAD 包——ACPI/I2S 与 Chromebox 不一致。
+
+---
+
+## 四、系统侧检查
+
+1. **设置 → 系统 → 声音**：默认输出选 **耳机 / Realtek / 模拟**（勿只选「显示器音频」）。
+2. 确认 **Windows Audio**、**Windows Audio Endpoint Builder** 服务为「正在运行」。
+3. 运行 **声音疑难解答**，排除应用独占或静音。
+
+---
+
+## 五、仍无声时
+
+1. **事件查看器**：应用程序和服务日志 → Microsoft → Windows → Audio 相关项，查看与插拔、驱动加载有关的错误时间是否与重装一致。
+2. **论坛**：带关键字 **Kaisa / puff、ALC5682、headphone、jack、CSAUDIO** 检索；同板卡已有解决方案时直接复现步骤。
+3. **插孔检测 / 注册表**：属进阶（README **W4**），仅在确认驱动版本与 SOF 状态正常后、且论坛有明确指引时再改，避免系统不稳定。
+
+---
+
+## 六、与仓库任务对应
+
+| README | 内容 |
+|--------|------|
+| **W1–W2** | 本机驱动需求与芯片确认（ALC5682 I2S + CoolStar SOF） |
+| **W3** | 按上文消除 Error、重装 I2S、设默认设备 |
+| **W4** | 插拔提示：依赖 HDA/codec 与 jack 检测，多在驱动与 DDI 正确后恢复 |
+
+---
+
+## 参考链接
+
+- <https://docs.chrultrabook.com/docs/installing/post-install.html>
+- <https://forum.chrultrabook.com/>
+- <https://coolstar.org/chromebook/windows-install.html>
+- 对比分析：[ANALYSIS_Audio.md](../../audio_topology/ANALYSIS_Audio.md)