摘要

TODO(https://fxbug.dev/42182545)：記錄確切行為和介面，因為它會疊代。

宣告

#include <zircon/syscalls-next.h>

zx_status_t zx_system_suspend_enter(zx_handle_t resource,
                                    zx_instant_boot_t resume_deadline,
                                    uint64_t options,
                                    zx_wake_source_report_header_t* out_header,
                                    zx_wake_source_report_entry_t* out_entries,
                                    uint32_t num_entries,
                                    uint32_t* actual_entries);

說明

zx_system_suspend_enter 會暫停所有線上處理器的工作執行，直到 resume_deadline 指定的絕對時間為止。所有線上處理器都會恢復執行工作，並在恢復期限到期時傳回 zx_system_suspend_enter 呼叫。離線處理器狀態不受影響。

深度暫停

使用者可以在選項中傳遞 ZX_SYSTEM_SUSPEND_OPTION_DEEP 旗標，要求系統進入深度暫停狀態 (如果支援)。在不支援深度暫停的裝置上要求深度暫停，並不會造成錯誤 (呼叫的行為會像未指定任何選項一樣)。ZX_SYSTEM_SUSPEND_OPTION_DEEP 不得與任何其他選項合併使用。

喚醒來源報表

正在索取報表。

為了進一步瞭解系統最終離開暫停狀態的具體原因，使用者可以要求「喚醒來源報告」。喚醒來源報表包含兩個部分：標頭和喚醒來源報表項目向量。如要要求報表，使用者必須至少傳遞指向 zx_wake_source_report_header_t 的指標。不過，實際上，為了發揮作用，他們也應傳遞緩衝區，以便接收報表項目。除了指向 zx_wake_source_report_entry_t 陣列的指標外，使用者還必須使用 num_entries 欄位指定陣列長度，並將指標傳遞至 uint32_t (actual_entries)，用於傳達核心寫入的使用者緩衝區中的實際項目數量。

報表項目的生命週期。

系統中的喚醒來源首次收到信號後，下次呼叫 zx_system_suspend_enter 並要求報告時，系統就會向使用者回報 (且使用者提供的項目緩衝區有足夠空間)。後續對 zx_system_suspend_enter 的呼叫會繼續回報這個項目，但會設定 ZX_SYSTEM_WAKE_REPORT_ENTRY_FLAG_PREVIOUSLY_REPORTED 旗標，直到喚醒來源最終獲得確認。一旦發出信號，系統一律會向使用者回報喚醒來源至少一次，即使這些來源已確認並多次重新發出信號也一樣。項目結構中的欄位會向使用者提供下列資訊：

• 首次收到喚醒來源信號的時間。
• 最近一次收到喚醒來源信號的時間。
• 上次確認喚醒來源的時間 (如有)。
• 自上次回報以來，喚醒來源發出信號的次數。

喚醒來源會持續出現在要求的報告中，直到回報並確認為止。

要求報表，但不暫停。

如果使用者想取得喚醒來源報表，但不想實際進入暫停狀態，可以在系統呼叫的選項中傳遞 ZX_SYSTEM_SUSPEND_OPTION_REPORT_ONLY 旗標。呼叫會照常運作，但不會嘗試暫停。而是會從該點開始回溯，並在過程中產生報表。

捨棄已確認的事件。

如果使用者不想接收已發出信號，但在呼叫 zx_system_suspend_enter 之前已確認的來源喚醒報告項目，可以在呼叫 zx_system_suspend_enter 時，在選項欄位中傳遞 ZX_SYSTEM_SUSPEND_OPTION_DISCARD 位元。在暫停作業開始時，任何未回報但目前未發出信號 (即已確認) 的喚醒來源喚醒報告項目，都會被捨棄，就像已經回報過一樣。

回報 Deadline Wake Source。

如果日後使用 resume_deadline 呼叫 zx_system_suspend_enter，且系統進入暫停狀態，但只會由期限計時器喚醒，系統會以特殊喚醒報告項目的形式向使用者回報。這個項目的 koid 欄位會包含 ZX_KOID_KERNEL 值。核心會自動確認這個喚醒來源，因此不需要採取特殊的使用者模式動作，即可管理期限喚醒來源。

破壞喚醒來源。

當使用者模式建立的喚醒來源遭到刪除時，系統會隱含確認，因此無法防止系統進入暫停狀態。此外，如果已刪除的喚醒來源有待回報的喚醒報告項目，系統會立即從待回報的喚醒報告項目組合中移除該項目。

傳回值

ZX_OK：resume_deadline 到期且系統恢復時。

錯誤

ZX_ERR_BAD_HANDLE 資源不是有效的控制代碼。

ZX_ERR_WRONG_TYPE 資源並非ZX_RSRC_KIND_SYSTEM資源種類。

ZX_ERR_OUT_OF_RANGE 資源不在 [ZX_RSRC_SYSTEM_CPU_BASE, ZX_RSRC_SYSTEM_CPU_BASE+1) 範圍內。

ZX_ERR_INVALID_ARGS 選項包含不明選項，或ZX_SYSTEM_SUSPEND_OPTION_DEEP與任何其他選項合併。

options uint64;