RFC-0203：引入了 `zx_system_energy_info`

摘要

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

设计初衷

能效和能耗是笔记本电脑（并非永久连接到电源）的关键设计元素。X86 RAPL 是新型 X86 CPU 上的一种接口，可使用硬件性能计数器和 I/O 模型准确估算一组功耗域的能耗。如果我们有一种机制可以让用户在内核之外访问能耗信息，则可以构建面向开发者的工具和车队跟踪工具，以人体工学的方式检查设备上的运行时功耗，这对优化开发期间的功耗足迹和识别整个车队的功耗回归非常有用。

设计

背景

Intel x86 RAPL MSR

在 RAPL 中，平台会被划分为多个网域，以便进行精细的报告和控制。RAPL 域是具有实际意义的电源管理域。平台中提供的具体 RAPL 域因处理器系列/型号而异，包括：

• PSys：整个 SoC。
• 封装：处理器芯片（所有核心、集成显卡、缓存、内存控制器）。
• 电源平面 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。

系统调用：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 内核已经提供了使用 CPUID 查询制造商 ID 和处理器签名/ID 的 API。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_X86_SET_PKG_PL1 调用的 zx_system_powerctl 系统调用会使用 RAPL Power Limit 和 Power Info MSR 来操控 CPU 功耗级别。用于验证此系统调用的资源具有资源类型 ZX_RSRC_KIND_SYSTEM 和基准 ZX_RSRC_SYSTEM_POWER_BASE。