zx_system_suspend_enter

摘要

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 时在 Options 字段中传递 ZX_SYSTEM_SUSPEND_OPTION_DISCARD 位。在挂起操作开始时，系统会丢弃尚未报告但当前未发出信号（即已确认）的唤醒源的所有唤醒报告条目，就像这些条目已被报告一样。

报告截止时间唤醒源。

如果将来使用 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 options 包含未知选项，或 ZX_SYSTEM_SUSPEND_OPTION_DEEP 与任何其他选项组合使用。

options uint64;