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_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 位。在挂起操作开始时，任何尚未报告但当前未发出信号（即未确认）的唤醒源的任何唤醒报告条目都将被舍弃，就好像它已被报告一样。

报告截止时间唤醒源。

当对 zx_system_suspend_enter 的调用包含未来的 resume_deadline，并且系统进入挂起状态，仅在截止时间计时器唤醒时才恢复，系统会以特殊唤醒报告条目的形式向用户报告此情况。相应条目的 koid 字段将包含值 ZX_KOID_KERNEL。内核会自动确认此唤醒源；无需采取特殊的用户模式操作来管理截止时间唤醒源。

销毁唤醒源。

当用户模式创建的唤醒源被销毁时，系统会隐式确认该唤醒源，以便它不会阻止系统进入挂起状态。此外，如果存在等待报告的已销毁唤醒源的唤醒报告条目，则会立即从等待报告的唤醒报告条目集中移除该条目。

返回值

当 resume_deadline 过期且系统恢复时。ZX_OK

错误

ZX_ERR_BAD_HANDLE 资源不是有效的句柄。

ZX_ERR_WRONG_TYPE 资源不是资源种类 ZX_RSRC_KIND_SYSTEM。

ZX_ERR_OUT_OF_RANGE resource 不在 [ZX_RSRC_SYSTEM_CPU_BASE, ZX_RSRC_SYSTEM_CPU_BASE+1) 范围内。

options uint64;