摘要
TODO(https://fxbug.dev/42108078)
宣告
#include <zircon/syscalls.h>
zx_status_t zx_system_powerctl(zx_handle_t resource,
uint32_t cmd,
const zx_system_powerctl_arg_t* arg);
說明
zx_system_powerctl 會根據 cmd 的值變更系統的電源狀態。視系統對於所用架構的支援等級而定，Zircon 可能無法將系統進入指定電源狀態。
「arg」是結構的選用指標，用於提供要執行指令的進一步資訊。
指令
ZX_SYSTEM_POWERCTL_ENABLE_ALL_CPUS
將所有處理器核心設為使用中。
arg 類型：n/a
ZX_SYSTEM_POWERCTL_DISABLE_ALL_CPUS_BUT_PRIMARY
僅將主要 CPU 設為使用中。
arg 類型：n/a
ZX_SYSTEM_POWERCTL_ACPI_TRANSITION_S_STATE
僅適用於 x86-64。
目前僅支援轉換至 S3 狀態。
呼叫這個 Syscall 之前，應先採取下列步驟：
1. 輸入 ACPICA 非競賽模式
2. 關閉次要 CPU
3. 執行 _PTS 控制方法 4. (選用) 執行 _SST 控制項方法。5. 清除 ACPI 喚醒狀態位元註冊
6. 停用所有 ACPI GPE
7. 已啟用所有 ACPI 喚醒 GPE
arg 類型：zx_system_powerctl_arg_t，只有 acpi_transition_s_state 聯集元素視為有效的。
struct {
uint8_t target_s_state; // Value between 1 and 5 indicating which S-state
uint8_t sleep_type_a; // Value from ACPI VM (SLP_TYPa)
uint8_t sleep_type_b; // Value from ACPI VM (SLP_TYPb)
} acpi_transition_s_state;
如果目標 S 狀態不在 1 到 5 的範圍內，則傳回 ZX_ERR_INVALID_ARGS。
如果不支援轉換至目標 S 狀態，則傳回 ZX_ERR_NOT_SUPPORTED。
如果目標 S 狀態不是 5，且次要 CPU 未關閉，則傳回 ZX_ERR_BAD_STATE。
如果資源不足以執行執行緒，則會傳回 ZX_ERR_NO_MEMORY。
如果 S 狀態轉換失敗，則傳回 ZX_ERR_INTERNAL。
ZX_SYSTEM_POWERCTL_X86_SET_PKG_PL1
僅適用於 x86-64。
將 CPU 設為電源等級 1。
arg 類型：zx_system_powerctl_arg_t，只有 x86_power_limit 聯集元素視為有效。
struct {
uint32_t power_limit; // PL1 value in milliwatts
uint32_t time_window; // PL1 time window in microseconds
uint8_t clamp; // PL1 clamping enable
uint8_t enable; // PL1 enable
uint8_t padding2[2];
} x86_power_limit;
ZX_SYSTEM_POWERCTL_REBOOT
重新啟動系統，控制應執行任何相關的韌體和系統啟動載入程式。
arg 類型：n/a
ZX_SYSTEM_POWERCTL_REBOOT_BOOTLOADER
重新啟動系統，但停止在系統啟動載入程式中停止，而不是載入作業系統。
arg 類型：n/a
ZX_SYSTEM_POWERCTL_REBOOT_RECOVERY
重新啟動系統，但載入復原作業系統，而非主要 OS。
arg 類型：n/a
ZX_SYSTEM_POWERCTL_SHUTDOWN
關閉系統。
arg 類型：n/a
ZX_SYSTEM_POWERCTL_ACK_KERNEL_INITIATED_REBOOT
如果核心希望重新啟動系統，使用者空間在可供重新啟動時會使用。
arg 類型：n/a
如果核心先前未發出要重新啟動的信號，則傳回 ZX_ERR_BAD_STATE。
權限
resource 必須具有基礎 ZX_RSRC_SYSTEM_POWER_BASE 的資源類型 ZX_RSRC_KIND_SYSTEM。
傳回值
ZX_OK
錯誤
提供無法辨識的 cmd 值時，傳回 ZX_ERR_INVALID_ARGS。
另請參閱
TODO(https://fxbug.dev/42108078)