RFC-0203：引入了 `zx_system_energy_info`

RFC-0203：引入“zx_system_energy_info”
状态已接受
领域
  • 内核
  • 电源
说明

用于与内核通信以访问能耗信息的接口。
问题
Gerrit 更改
  • 762927
作者
审核人
提交日期（年-月-日）2022-11-18
审核日期（年-月-日）2022-12-15

修改此 RFC

修改 RFC 元数据

总结

此 RFC 提出了一种机制，用户空间代理可通过该机制与内核进行交互，以访问支持运行平均功率限制 (RAPL) 接口的平台上一组电源网域的功耗信息。

设计初衷

对于笔记本电脑来说，能效和能耗是关键的设计元素，而笔记本电脑不会永久与电源相连。X86 RAPL 是现代 X86 CPU 上的一个接口，可使用硬件性能计数器和 I/O 模型准确估算一组电源域的功耗。如果有一种机制可以使能耗信息在内核之外访问，我们就可以构建面向开发者和舰队跟踪的工具，以符合人体工学的方式检查设备上的运行时功耗，这有助于在开发过程中优化功耗并识别整个舰队的功耗回归。

设计

背景

Intel x86 RAPL MSR

在 RAPL 中，平台被划分为多个领域，用于精细报告和控制。RAPL 域是在物理上有意义的电源管理域。平台中可用的特定 RAPL 域因处理器系列/型号而异，包括：

  • PSys：整个 SoC。
  • 软件包：处理器芯片（所有内核、集成图形、缓存、内存控制器）。
  • Power Plane PP0：所有处理器核心和私有缓存。
  • 电源平面 PP1：非核心中特定设备的电源平面，通常是集成式 GPU。
  • 内存：连接到集成内存控制器的 DRAM。

RAPL 接口由非架构 MSR 组成。每个 RAPL 网域都支持下面一组功能，其中一些功能是可选的，如下所述：

  • Power Limit：用于指定功率限制、时间窗口、锁定位、夹位等的 MSR 接口。
  • Energy Status：提供能耗信息的耗电计量接口。
  • Perf Status（可选）：提供因功率限制而导致性能影响（回归）的接口。它被定义为一个时长指标，用于测量相应网域中的功率限制效果。时长的含义因网域而异。
  • Power Info（可选）：用于提供有关指定领域的参数范围、最小功率、最大功率等的接口。
  • Policy（可选）：4 位优先级信息，用于提示硬件在父网域中的子网域之间分配预算。

上述每项功能都需要特定的单位才能进行描述。单元显示在只读 MSR_RAPL_POWER_UNIT MSR 中。系统会为每个单位提供缩放比例，以使呈现的信息在有限数量的位内有意义。

跨不同网域存储能耗信息的 MSR 是只读 Energy Status MSR：

  • MSR_PLATFORM_ENERGY_STATUS (0x0000064d)
  • MSR_PKG_ENERGY_STATUS (0x00000611)
  • MSR_DRAM_ENERGY_STATUS (0x00000619)
  • MSR_PP0_ENERGY_STATUS (0x00000639)
  • MSR_PP1_ENERGY_STATUS (0x00000641)

以上 MSR 的能量单位由 MSR_RAPL_POWER_UNIT 的 Energy Status Units 字段指定。

Energy Status MSR 仅支持有限范围的处理器系列/型号。访问非架构 MSR 的代码如果在不支持该 MSR 的处理器上执行，会生成异常。下面列出了支持每个 MSR 的处理器型号（并非详尽无遗）：

MSR_PLATFORM_ENERGY_STATUS 可在以下处理器上使用：

  • Skylake，系列：6，型号：0x4e、0x5e
  • Kaby Lake，系列：6，型号：0x8e、0x9e
  • Cannon Lake，系列：6，型号：0x66

MSR_PKG_ENERGY_STATUS 可在以下处理器上使用：

  • Sandy Bridge，系列：6，型号：0x2a，0x2d
  • Ivy Bridge，系列：6，型号：0x3a、0x3e
  • Haswell，系列：6，型号：0x3c、0x3f、0x45、0x46
  • Broadwell，系列：6，型号：0x3d、0x47、0x56、0x4f
  • Skylake，系列：6，型号：0x4e、0x5e
  • Kaby Lake，系列：6，型号：0x8e、0x9e
  • Skylake X/SP，系列：6，型号：0x55
  • Cannon Lake，系列：6，型号：0x66
  • Ice Lake-SP，系列：6，型号：0x6a

MSR_DRAM_ENERGY_STATUS 可在以下处理器上使用：

  • Haswell，系列：6，型号：0x3c、0x3f、0x45、0x46
  • Broadwell，系列：6，型号：0x3d、0x47、0x56、0x4f
  • Skylake，系列：6，型号：0x4e、0x5e
  • Kaby Lake，系列：6，型号：0x8e、0x9e
  • Skylake X/SP，系列：6，型号：0x55
  • Cannon Lake，系列：6，型号：0x66
  • Ice Lake-SP，系列：6，型号：0x6a

MSR_PP0_ENERGY_STATUS 可在以下处理器上使用：

  • Sandy Bridge，系列：6，型号：0x2a，0x2d
  • Ivy Bridge，系列：6，型号：0x3a、0x3e
  • Haswell，系列：6，型号：0x3c、0x3f、0x45、0x46
  • Broadwell，系列：6，型号：0x3d、0x47、0x56、0x4f
  • Skylake，系列：6，型号：0x4e、0x5e
  • Kaby Lake，系列：6，型号：0x8e、0x9e
  • Skylake X/SP，系列：6，型号：0x55
  • Cannon Lake，系列：6，型号：0x66
  • Ice Lake-SP，系列：6，型号：0x6a

MSR_PP1_ENERGY_STATUS 可在以下处理器上使用：

  • Skylake，系列：6，型号：0x4e、0x5e
  • Kaby Lake，系列：6，型号：0x8e、0x9e
  • Cannon Lake，系列：6，型号：0x66

AMD x86 RAPL MSR

最新的 AMD 处理器支持与 Intel RAPL MSR 半兼容的 MSR 接口。支持的 RAPL MSR 具有相同的内容，但 MSR 编号不同。具体而言，AMD Zen（系列：0x17、0x19）处理器支持以下 Energy Status MSR：

  • MSR_AMD_CORE_ENERGY_STATUS (0xc001029a)

    • 相当于 Power Plane PP0 网域的 Intel MSR_PP0_ENERGY_STATUS。

  • MSR_AMD_PKG_ENERGY_STATUS (0xc001029b)

    • 相当于 Package 网域的 Intel MSR_PKG_ENERGY_STATUS。

Syscall：zx_system_energy_info

签名

此系统调用允许用户空间代理访问存储在指定电源域的 RAPL MSR 中的能耗信息：

zx_status_t zx_system_energy_info(
    zx_handle_t resource,
    uint32_t domain,
    uint64_t* energy_uj
);

其参数为：

resource：向此调用授予权限的资源。必须为 ZX_RSRC_SYSTEM_ENERGY_INFO_BASE（专门为此 API 引入的新资源），否则调用将失败。

domain：此调用引用的 RAPL 网域。它使用以下任一值来指定 RAPL 网域：

  • ZX_ENERGY_X64_PLATFORM_DOMAIN
  • ZX_ENERGY_X64_PKG_DOMAIN
  • ZX_ENERGY_X64_DRAM_DOMAIN
  • ZX_ENERGY_X64_PP0_DOMAIN
  • ZX_ENERGY_X64_PP1_DOMAIN

上述域将在方案实现时定义。域决定了写入 energy_uj 的内容，如下所述。

energy_uj：如果调用成功，那么在返回时，energy_uj 会包含以 uj 为单位的能耗值。能量值取决于存储在指定网域的 Energy Status MSR 中的值以及 MSR_RAPL_POWER_UNIT 的 Energy Status Units 字段中存储的单位。如果调用失败，则未指定其值。

错误情况

ZX_ERR_NOT_SUPPORTED

  • 处理器不是受支持的 x86-64 处理器。

  • 处理器是受支持的 x86-64 处理器，但此处理器不支持指定网域的 Energy Status MSR。

  • 处理器是受支持的 x86-64 处理器，指定网域的 Energy Status MSR 在此处理器上可用，但未启用读取操作。

ZX_ERR_BAD_HANDLE

  • 资源不是有效的句柄。

ZX_ERR_WRONG_TYPE

  • 资源不是有效的资源句柄，或者不是 ZX_RSRC_KIND_SYSTEM 种类。

ZX_ERR_INVALID_ARGS

  • domain 不是以下值之一：

    • ZX_ENERGY_X64_PLATFORM_DOMAIN
    • ZX_ENERGY_X64_PKG_DOMAIN
    • ZX_ENERGY_X64_DRAM_DOMAIN
    • ZX_ENERGY_X64_PP0_DOMAIN
    • ZX_ENERGY_X64_PP1_DOMAIN

  • energy_uj 是无效的指针。

ZX_ERR_OUT_OF_RANGE

  • 资源的种类为 ZX_RSRC_KIND_SYSTEM，但不等于 ZX_RSRC_SYSTEM_ENERGY_INFO_BASE。

实现

内核

必须实现新的系统调用，并受新资源 ZX_RSRC_SYSTEM_ENERGY_INFO_BASE 控制。Fuchsia 内核已有 API，可使用 CPUID 查询制造商 ID 和处理器签名/ID。DisplayFamily 和 DisplayModel 已映射到各种 x86 处理器的处理器 ID，可用于确定 MSR 的可用性。

组件管理器

新协议 EnergyInfoResource 必须定义，并且必须由组件管理器实现，以提供 ZX_RSRC_SYSTEM_ENERGY_INFO_BASE 资源。这遵循控制系统调用的资源的现有模式。

性能

对性能没有影响。新的系统调用只需处理少量数据，因此所需时间可以忽略不计。

安全注意事项

系统调用受新资源句柄 ZX_RSRC_SYSTEM_ENERGY_INFO_BASE 控制。这项保护措施解决了恶意干扰内核的问题。

隐私注意事项

此方案对隐私权没有有意义的影响。

测试

  • 可以添加单元测试，以验证返回的 energy_uj 是否从 MSR 中存储的值正确转换。

文档

Zircon 系统调用文档将会更新，以包含新的 API。

缺点、替代方案和未知情况

考虑了更通用的接口，例如 zx_get_msr 系统调用，它允许将其他有用的 MSR 功能分离开来。但是，非架构 MSR 访问需要受其在处理器上的可用性控制。此时，更通用的接口的要求和范围主要是靠猜测。最终，我们选择了窄接口，以便使实现相当容易，并且将来对建议的接口进行更改所付出的成本相对较小。

早期技术和参考资料

使用 cmd 调用的 zx_system_powerctl 系统调用 ZX_SYSTEM_POWERCTL_X86_SET_PKG_PL1 使用 RAPL Power Limit 和 Power Info MSR 操控 CPU 功率水平。用于验证此系统调用的资源具有具有基本 ZX_RSRC_SYSTEM_POWER_BASE 的资源种类 ZX_RSRC_KIND_SYSTEM。