摘要

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_wake_source_report_header_t。不過，就實務而言，如要發揮效用，這些函式也應傳遞緩衝區，以接收報表項目。除了陣列的指標外，使用者也必須使用 num_entries 欄位指定陣列長度，並傳遞 uint32_t 的指標 (actual_entries)，用於傳達核心寫入使用者緩衝區的實際項目數。zx_wake_source_report_entry_t

報表項目的生命週期。

系統中喚醒來源首次發出信號後，下次呼叫 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 位元。在暫停作業開始時，系統會捨棄任何尚未回報但目前未發出信號 (即已確認) 的喚醒來源喚醒報告項目，如同該項目已回報一樣。

回報期限喚醒來源。

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

破壞喚醒來源。

當使用者模式建立的喚醒來源遭到毀損時，系統會隱含確認，因此不會阻止系統進入暫停狀態。此外，如果待回報的喚醒報告項目是針對已毀損的喚醒來源，系統會立即從待回報的喚醒報告項目集中移除該項目。

傳回值

ZX_OK，當 resume_deadline 到期且系統恢復時。

錯誤

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

ZX_ERR_WRONG_TYPE resource 不是資源種類 ZX_RSRC_KIND_SYSTEM。

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

options uint64;