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：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 的能源單位是由 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。

實作

Kernel

必須實作新的系統呼叫，並以新的資源 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 存取權必須受處理器可用性限制。目前，一般介面的需求和範圍大多是猜測。 最後，我們選擇採用窄介面，以確保實作相當容易，並將未來變更提案介面的成本降到最低。

既有技術和參考資料

zx_system_powerctl 使用 cmd 呼叫的系統呼叫會使用 RAPL Power Limit 和 Power Info MSR，操控 CPU 電源層級。ZX_SYSTEM_POWERCTL_X86_SET_PKG_PL1用於驗證這個系統呼叫的資源具有 ZX_RSRC_KIND_SYSTEM 資源種類，且以 ZX_RSRC_SYSTEM_POWER_BASE 為基礎。