zx_system_suspend_enter

Summary

TODO(https://fxbug.dev/42182545): Document exact behavior and interface as it iterates.

Declaration

#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);

Description

zx_system_suspend_enter suspends task execution on all online processors until the absolute time given by resume_deadline. Task execution is resumed on all online processors and the call to zx_system_suspend_enter returns when the resume deadline expires. Offline processor states are not affected.

Wake Source Reports

Requesting reports.

In order to better understand the specific reasons why the system eventually left the suspended state, the user may request a "wake source report". A wake source report consists of two pieces, a header and a vector of wake source report entries. To request a report, users must pass (at least) a pointer to a zx_wake_source_report_header_t. However practically speaking, in order to be useful, they should also pass a buffer for receiving report entries as well. In addition to a pointer to an array of zx_wake_source_report_entry_ts, users must specify the length of the array using the num_entries field, and also pass a pointer to a uint32_t (actual_entries) which will be used to communicate the actual number of entries in the user's buffer that the kernel wrote to.

The life-cycle of a report entry.

After a wake source in the system first becomes signaled, it will be reported to users the next time zx_system_suspend_enter is called and a report is requested (and there is sufficient space in the user provided entry buffer). Subsequent calls to zx_system_suspend_enter will continue to report this same entry, but with the ZX_SYSTEM_WAKE_REPORT_ENTRY_FLAG_PREVIOUSLY_REPORTED flag set, until the wake source finally becomes acknowledged. Once signaled, wake sources will always be reported to users at least once, even if they are acknowledged and re-signaled multiple times. Fields in the entry structure will inform the user of:

  • The time at which the wake source was first signaled.
  • The time at which the wake source was most recently signaled.
  • The time at which the wake source was most recently acknowledged (if any).
  • The number of times the wake source became signaled since the last report.

The wake source will continue to be present in requested reports until it has finally been both reported, and acknowledged.

Requesting a report without suspending.

Users who wish to obtain a wake source report, but do not actually wish to enter suspend, may pass the ZX_SYSTEM_SUSPEND_OPTION_REPORT_ONLY flag in the options for the syscall. The call will behave as it normally does, however it will make no attempt to suspend. Instead, it will simply unwind from that point, generating a report on the way out.

Discarding acknowledged events.

Users who are not interested in receiving wake report entries for sources which had been signaled, but already acknowledged before the call to zx_system_suspend_enter, may pass the ZX_SYSTEM_SUSPEND_OPTION_DISCARD bit in the options field when calling zx_system_suspend_enter. At the start of the suspend operation, any wake report entry for a wake source which has not been reported, but is currently not signaled (i.e. acknowledged) will be discarded as if it had already been reported.

Reporting the Deadline Wake Source.

When a call to zx_system_suspend_enter is made with a resume_deadline in the future, and the system enters suspend only to be woken by the deadline timer, this will be reported to the user in the form of a special wake report entry. This entry's koid field will contain the value ZX_KOID_KERNEL. This wake source is automatically acknowledged by the kernel; no special user-mode actions need to be taken to manage the deadline wake source.

Destruction of wake sources.

When a wake source created by user-mode is destroyed, it is implicitly acknowledged so that it cannot prevent the system from entering suspend. Additionally, if there is a wake report entry waiting to be reported for the destroyed wake source, it will immediately be removed from the set of wake report entries waiting to be reported.

Return value

ZX_OK when resume_deadline expires and the system resumes.

Errors

ZX_ERR_BAD_HANDLE resource is not a valid handle.

ZX_ERR_WRONG_TYPE resource is not resource kind ZX_RSRC_KIND_SYSTEM.

ZX_ERR_OUT_OF_RANGE resource is not in the range [ZX_RSRC_SYSTEM_CPU_BASE, ZX_RSRC_SYSTEM_CPU_BASE+1).

options uint64;