main/syscalls/system_suspend_enter.md

<!--
Copyright 2023 The Fuchsia Authors. All rights reserved.
Use of this source code is governed by a BSD-style license that can be
found in the LICENSE file.

DO NOT EDIT. Generated from FIDL library zx by zither, a Fuchsia platform tool.

See //docs/reference/syscalls/README.md#documentation-generation for
regeneration instructions.
-->

# zx_system_suspend_enter

# Summary

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

## Declaration

```c
#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_t`s, 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;