RFC-0203：推出「zx_system_energy_info」

摘要

本 RFC 提出一種機制，讓使用者空間代理程式可與核心互動，在支援 Running Average Power Limit (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 處理器支援 MSR 介面，與 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。

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_X86_SET_PKG_PL1 呼叫的 zx_system_powerctl 系統呼叫會使用 RAPL Power Limit 和 Power Info MSR 操控 CPU 電源等級。用於驗證此系統呼叫的資源，具有資源類型 ZX_RSRC_KIND_SYSTEM 和基礎 ZX_RSRC_SYSTEM_POWER_BASE。