ACPI 是一种全新的发现设备、 管理电源使用， 提供过去由 BIOS 管理的访问不同硬件的标准化方法。 让 ACPI 在各种系统上都能正确使用的工作一直在进行， 但许多主板的 ACPI 机器语言 (AML) 字节代码中的 bug， FreeBSD 的内核中资系统设计的不完善， 以及 Intel® ACPI-CA 解释器中的 bug 仍然不时会出现。
这份文档期望能够帮助您协助 FreeBSD ACPI 的维护人员来找到您所观察到的问题的根源， 并通过调试找到其解决方法。 感谢您阅读这份文档， 我们也希望能够解决您的系统上的问题。
Note: 在提交问题之前， 请确认您已经在运行最新的 BIOS 版本， 此外， 也包括嵌入式控制器的固件版本。
如果您希望提交一个问题， 请确保将下述信息法到 [email protected]:
问题行为的描述， 包括系统类型、型号，以及任何触发问题的相关信息。 另外， 请注意尽可能准确地描述这一问题是否对您是陌生的。
在 “boot -v” 之后得到的 dmesg(8) 输出， 以及任何在重现 bug 时出现的错误信息。
在禁用了 ACPI 之后的 “boot -v” 的 dmesg(8) 输出， 如果您发现禁用 ACPI 能够帮助消除问题。
来自 “sysctl hw.acpi” 的输出。 这也是找到您的系统所提供的功能的一种好办法。
能够得到您的 ACPI Source Language (ASL) 的 URL。 不要 把 ASL 直接发到邮件列表中， 因为它们可能非常大。 为了得到 ASL 您可以运行这个命令：
# acpidump -t -d > name-system.asl
(把 name 改为您的登录名， 并把 system 改为您的硬件制造商及其型号。 例如： njl-FooCo6000.asl)
许多开发者也会订阅 FreeBSD-CURRENT 邮件列表 但还是请发到 freebsd-acpi 这样它会被更多人看到。 请耐心等待， 因为我们都有全职的其他工作。 如果您的 bug 不是显而易见的， 我们可能会要求您通过 send-pr(1) 来提交一个 PR。 在输入 PR 时，请将同样的信息包含进去。 这将帮助我们来追踪和解决问题。 不要在给 freebsd-acpi 写信之前发送 PR 因为我们把它当作已知文体的备忘录而不是报告机制。 您的问题很可能已经被其他人报告过了。
ACPI 存在于采用 ia32 (x86)、 ia64 (安腾)、 以及 amd64 (AMD) 架构的所有现代计算机上。 完整的标准具有大量的各式功能， 包括 CPU 性能管理、 电源控制、 温度监控、 电池系统、 嵌入式控制器以及总线枚举。 绝大多数系统实现比完整标准的功能要少一些。 例如， 桌面系统通常只实现总线枚举部分， 而笔记本则通常支持降温和电源管理功能。 笔记本通常还提供休眠和唤醒支持， 并提供与此适应的复杂功能。
符合 ACPI 的系统中有许多组件。 BIOS 和芯片组制造商提供一些固定的表 (例如， FADT) 在存储器中， 以提供类似 APIC 映射 (用于 SMP)、 配置寄存器、 以及简单的配置值等等。 另外， 一个字节代码 (bytecode) 表 (系统区别描述表 DSDT) 则提供了通过树状命名空间来指定设备及其功能的方法。
ACPI 驱动必须要处理固定表， 实现字节码解释器， 并修改驱动程序和内核， 以接受来自 ACPI 子系统的信息。 对于 FreeBSD， Intel 提供了一个解释器 (ACPI-CA)， 它在 Linux 和 NetBSD 也可以使用。 ACPI-CA 源代码可以在 src/sys/contrib/dev/acpica 找到。 用于在 FreeBSD 中允许 ACPI-CA 正确运转的代码则在 src/sys/dev/acpica/Osd。 最后， 用于实现 ACPI 设备的驱动可以在 src/sys/dev/acpica 找到。
为了使 ACPI 正常工作， 它的每一部分都必须工作正常。 这里是一些常见的问题， 按照出现的频繁程度顺序排序， 并提供了一些绕过或修正它们的方法。
ACPI 提供了三种休眠到 RAM (STR) 的状态， S1-S3， 以及一个休眠到磁盘的状态 (STD)， 称作 S4。 S5 是 “软关机” 同时也是系统接好电源但没有开机时的正常状态。 S4 实际上可以用两种不同的方法来实现。 S4BIOS 是一种由 BIOS 辅助的挂起到磁盘方法， 而 S4OS 则是完全由操作系统实现的。
可以使用 sysctl hw.acpi 来查看与休眠有关的项目。 这里是我的 Thinkpad 上得到的结果。
hw.acpi.supported_sleep_state: S3 S4 S5
hw.acpi.s4bios: 0
这表示我可以使用 acpiconf -s 来测试 S3， S4OS， 以及 S5。 如果 s4bios 是一 (1)， 则可以使用 S4BIOS 来代替 S4 OS。
当测试休眠/唤醒时， 从 S1 开始， 如果它被支持的话。 这个状态是最可能正常工作的状态， 因为它不需要太多的驱动支持。 没有人实现 S2 但如果您有它的支持， 则应该和 S1 类似。 下一件值得尝试的是 S3。 这是最深的 STR 状态， 并需要一系列驱动的支持才能够正常地重新初始化您的硬件。 如果您在唤醒系统时遇到问题， 请不要吝惜发邮件给 freebsd-acpi 邮件列表， 尽管不要指望问题一定会很快解决， 因为有许多驱动程序/硬件需要进行更多的测试和改进。
为了帮助隔离问题， 请在内核中删去尽可能多的驱动。 如果这样做能够解决问题， 请尝试逐个加载驱动直到问题再次出现。 通常预编译的驱动程序如 nvidia.ko、 X11 显示驱动， 以及 USB 的问题最多， 而以太网卡的驱动则通常工作的很好。 如果您能够通过加载和卸载驱动使系统正常工作， 您可以通过将适当的命令放到 /etc/rc.suspend 和 /etc/rc.resume 来将这个过程自动化。 在这两个文件中有一个注释掉的卸载和加载驱动程序的例子供您参考。 另外您还可以将 hw.acpi.reset_video 设置为零 (0)， 如果您的显示在唤醒之后显得很混乱。 此外您还可以尝试更长或更短的 hw.acpi.sleep_delay 值看看是否有所助益。
另一件值得一试的事情是使用一个比较新的包含 ACPI 支持的 Linux 发行版来试试看他们的 休眠/唤醒 功能是否在同样的硬件上能够正常工作。 如果在 Linux 下正常， 则很可能是 FreeBSD 驱动程序的问题， 而隔离问题并找到存在问题的驱动有助于解决它。 需要注意的是 ACPI 的维护人员通常并不维护其他驱动 (例如 声音、 ATA， 等等) 因此如果最终发现是驱动的问题最好还是发到 freebsd-current 邮件列表并发给驱动程序的维护者。 如果您喜欢冒险， 则可以加一些 printf(3) 到有问题的驱动中， 以找到它的恢复功能发生问题的位置。
最后， 试试看禁用 ACPI 并代之以启用 APM。 如果 休眠/唤醒 能够在 APM 下正常工作， 使用 APM 可能会更好， 特别是对于较老的硬件 (2000年以前)。 硬件制造商需要一些时间来让老硬件的 ACPI 工作正常， 而 ACPI 的问题十之八九是 BIOS 中的毛病引发的。
绝大多数系统停止响应是由于未能及时响应中断或发生了中断风暴导致的。 芯片组有很多问题最终会溯源到 BIOS 如何在引导系统之前配置中断， APIC (MADT) 表的正确性， 以及 系统控制中断 (SCI) 如何路由。
通过察看 vmstat -i 的输出中包括 acpi0 的那一行可以区分中断风暴和未能及时响应中断。 如果每秒计数器增长的速度多于一两个， 则您是遇到了中断风暴。 如果系统停止了响应， 您可以尝试停止内核并进入 DDB (在控制台上按 CTRL+ALT+ESC) 并输入 show interrupts。
处理中断问题的救命稻草是尝试禁用 APIC 支持， 这是通过在 loader.conf 中加入 hint.apic.0.disabled="1" 完成的。
崩溃对于 ACPI 是比较罕见的情况， 如果发现， 将会非常重视并很快修复。 您要做的第一件事是设法隔离出能够重现崩溃 (如果可能的话) 的操作并获取一份调用队战。 请启用 options DDB 并设置串行控制台 (参见 Section 20.6.5.3) 或配置一个 dump(8) 分区。 您将在 DDB 中通过 tr 得到调用队战。 如果您只能用手抄的方法记录它， 一定要记下头五 (5) 行和最后五 (5) 行。
然后， 尝试通过在启动时禁用 ACPI 来隔离故障。 如果这样做能够正常工作， 请通过设置 debug.acpi.disable 的那组数值来隔离具体是哪个 ACPI 子系统的问题。 请参见 acpi(4) 联机手册中给出的那些例子。
首先请尝试在 loader.conf(5) 中设置 hw.acpi.disable_on_poweroff=“0”。 这将让 ACPI 不再在关机过程中禁用一些事件。 基于同样的原因， 一些系统需要把这个值设置为 “1” (这是默认值)。 这通常能够修复在休眠或关机时立即再次启动的问题。
如果您有 ACPI 的其他问题 (同 docking station 协同工作、 无法检测设备， 等等)， 请把描述发给邮件列表； 不过， 这些问题也有可能和 ACPI 中尚未完成的部分有关， 它们可能需要时间才能被实现。 请保持耐心， 并准备测试我们可能会发给您的补丁。
最常见的问题是 BIOS 制造商提供的不正确 (甚至完全错误的!) 字节代码。 这通常会以类似下面这样的内核消息显示在控制台上：
ACPI-1287: *** Error: Method execution failed [\\_SB_.PCI0.LPC0.FIGD._STA] \\ (Node 0xc3f6d160), AE_NOT_FOUND
通常您可以通过将 BIOS 升级到最新版本来解决这类问题。 绝大多数控制台消息是无害的， 但如果您有其他问题例如电池工作不正常， 则从 AML 开始查找问题将是一条捷径。 字节代码， 或常说的 AML， 是从一种称作 ASL 语言的原代码编译得到的结果。 AML 在 DSDT 表中。 要得到您系统的 ASL， 需要使用 acpidump(8)。 您应该使用 -t (显示固定表的内容) 和 -d (将 AML 反汇编成 ASL) 两个选项。 参考 如何提交调试信息 一节以获得示范用法。
您可以检查的第一件事是重新编译 ASL 来看看是否有错误。 警告通常都可以忽略， 而错误通常会使导致 ACPI 无法正常工作的原因。 要编译您的 ASL， 使用下面的命令：
# iasl your.asl
我们的长期目标是让每一个人都能够在不需要任何用户干预的情况下使用 ACPI。 然而， 目前我们仍然在开发绕过 BIOS 制造商常见错误的方法。 Microsoft 解释器 (acpi.sys 和 acpiec.sys) 并不会严格地检查是否遵守了标准， 因此许多只在 Windows 中测试 ACPI 的 BIOS 制造商很可能永远不会修正他们的 ASL。 我们希望不断地找出并用文档说明 Microsoft 的解释器到底允许那些不标准的行为， 并在 FreeBSD 进行对应的修改使它能够正常工作而不需要用户修正 ASL。 作为一项临时缓解问题的方法， 并帮助我们确认其行为， 您可以手工修正 ASL。 如果这样能够解决问题， 请把新旧 ASL 的 diff(1) 发给我们， 这样我们就有可能绕过 ACPI-CA 中的错误行为， 从而不再需要您来手工修正。
下面是一些常见的错误信息， 它们的原因， 以及如何修正。
某些 AML 假定世界是由不同版本的 Windows 组成的。 您可以让 FreeBSD 声称自己是任意 OS 来看一看是否能够修正问题。 比较简单的办法是设置 hw.acpi.osname=“Windows 2001” 到 /boot/loader.conf 中， 或使用您在 ASL 中找到的其他字符串。
一些方法可能没按照标准要求的那样显式地返回值。 尽管 ACPI-CA 无法处理它， 但 FreeBSD 提供了一个绕过它并允许其暗含地返回值的方法。 您也可以增加一个显式的 Return 语句， 如果您知道那里需要返回一个值的话。 要强制 iasl 编译 ASL， 需要使用 -f 标志。
在定制 your.asl 之后， 您可以通过下面的命令编译它：
# iasl your.asl
可以使用 -f 标志来强制创建 AML， 即使在编译过程中发生了错误。 请注意某些错误 (例如， 缺少 Return 语句) 会自动被解释器忽略掉。
DSDT.aml 是 iasl 命令的默认输出文件名。 可以加载它来取代您 BIOS 中存在问题的副本 (它仍然存在于闪存中)， 其方法是按下面的说明编辑 /boot/loader.conf：
acpi_dsdt_load="YES" acpi_dsdt_name="/boot/DSDT.aml"
一定要把您的 DSDT.aml 复制到 /boot 目录中。
ACPI 驱动程序提供了非常灵活的调试机制。 这允许您指定一组子系统， 以及所需要的详细信息。 需要调试的子系统可以按 “layers(层)” 来指定， 并分为 ACPI-CA 组件 (ACPI_ALL_COMPONENTS) 和 ACPI 硬件支持 (ACPI_ALL_DRIVERS)。 调试输出的详细程度可以通过 “level(详细度)” 来指定， 其范围是 ACPI_LV_ERROR (只报告错误) 到 ACPI_LV_VERBOSE (显示所有)。 “level” 是一个位掩码因此可以一次设置多个选项， 中间用空格分开。 实际使用中您应该考虑使用串行控制台来记录输出， 如果它太长以至于冲掉了控制台消息缓冲的话。 不同的层和输出详细度的完整列表可以在 acpi(4) 联机手册中找到。
调试输出默认并不开启。 要起用它， 您需要在内核设置中添加 options ACPI_DEBUG， 如果您的内核中编入了 ACPI 的话。 您还可以在 /etc/make.conf 中加入 ACPI_DEBUG=1 来在全局起用它。 如果它只是模块， 您可以用下面的方法来重新编译 acpi.ko：
# cd /sys/modules/acpi/acpi && make clean && make ACPI_DEBUG=1
安装 acpi.ko 到 /boot/kernel 并把所需的详细度和层在 loader.conf 中指定。 这个例子讲起用所有 ACPI-CA 组件以及所有 ACPI 硬件驱动 (CPU、 LID， 等等) 的消息。 只输出错误信息， 也就是最低的详细度。
debug.acpi.layer="ACPI_ALL_COMPONENTS ACPI_ALL_DRIVERS" debug.acpi.level="ACPI_LV_ERROR"
如果您需要的信息是由某个特定的事件触发的 (比如说， 休眠之后的唤醒)， 您可以不修改 loader.conf 而转而使用 sysctl 来在启动和为那个事件准备系统之后再指定层和详细度。 这些 sysctl 的名字和 loader.conf 中的一致。
关于 ACPI 的更多信息可以从下面这些地方找到：
ACPI 邮件列表存档 http://lists.freebsd.org/pipermail/freebsd-acpi/
旧的 ACPI 邮件列表存档 http://home.jp.FreeBSD.org/mail-list/acpi-jp/
The ACPI 2.0 标准 http://acpi.info/spec.htm
FreeBSD 手册页: acpi(4), acpi_thermal(4), acpidump(8), iasl(8), acpidb(8)
DSDT 调试资源. (使用 Compaq 作为例子但通常情况下都很有用。)