RFC-0203：引入了 `zx_system_energy_info`

摘要

此 RFC 提出了一种机制，使用户空间代理可通过该机制 通过内核访问一系列电源的能耗信息， 域。

设计初衷

能效和能耗是笔记本电脑设计的关键因素 它们不会永久绑定到电源。X86 RAPL 是 采用现代 X86 CPU，可准确估算一系列设备的能耗 硬件性能计数器和 I/O 模型，为域提供支持。如果我们 一种使能耗信息可在 Google Cloud 之外 因此，我们可以构建面向开发者的工具和舰队跟踪工具， 以符合人体工程学的方式在设备上运行时功耗，这对于 优化开发过程中的功耗以及识别功耗衰退 在整个舰队中部署

设计

背景

Intel x86 RAPL MSR

在 RAPL 中，平台可分为多个领域，用于提供精细的报告和 控制。RAPL 域是对电源管理具有实际意义的域。 平台中可用的特定 RAPL 域因处理方而异 系列/模型，包括：

• PSys：整个 SoC。
• 软件包：处理器芯片（所有内核、集成显卡、缓存、内存） 控制器）。
• Power Plane PP0：所有处理器核心和私有缓存。
• Power Plane PP1：Uncore 中特定设备的电源平面， 通常是集成式 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 的能量单位由以下项的 Energy Status Units 字段指定： MSR_RAPL_POWER_UNIT。

有限范围内的处理器支持 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。支持的 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，这是专为 否则调用将失败。

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 内核已包含用于查询制造商 ID 和处理器的 API 使用 CPUID 签名/ID。DisplayFamily 和 DisplayModel 已映射到 各种 x86 处理器的处理器 ID，并可用于确定 MSR 的可用性。

组件管理器

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

性能

对性能没有已知的影响。新的系统调用只需要一个可忽略不计的 因为只需处理少量数据即可。

安全注意事项

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

隐私注意事项

此方案对隐私保护没有任何实质性的影响。

测试

• 可以添加单元测试，以验证返回的 energy_uj 是否已转换 正确生成。

文档

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

缺点、替代方案和未知问题

考虑了更通用的接口，例如 zx_get_msr 系统调用， 可以推广其他有用的 MSR 功能。然而，非架构 MSR 访问需要受其在处理器上的可用性控制。要求 此时，更为通用的接口的范围主要是凭空猜测。 最终，我们采用了狭窄的界面，以确保实现公平 而且将来对提议界面进行更改的成本相对较低。

先验技术和参考资料

使用 cmd 调用了 zx_system_powerctl 系统调用 ZX_SYSTEM_POWERCTL_X86_SET_PKG_PL1 使用 RAPL Power Limit 和 Power Info MSR。用于验证此内容的资源 系统调用具有基础资源种类 ZX_RSRC_KIND_SYSTEM ZX_RSRC_SYSTEM_POWER_BASE。