zx_guest_set_trap

摘要

在访客中设置一个陷阱。

声明

#include <zircon/syscalls.h>

zx_status_t zx_guest_set_trap(zx_handle_t handle,
                              uint32_t kind,
                              zx_vaddr_t addr,
                              size_t size,
                              zx_handle_t port_handle,
                              uint64_t key);

说明

zx_guest_set_trap() 在客户机内设置 trap，这会在发生以下情况时生成数据包： 在由 addr 定义的地址范围内存在由 vCPU 进行的访问，并且 size，在 kind 定义的地址空间内。

kind 可以是 ZX_GUEST_TRAP_BELL、ZX_GUEST_TRAP_MEM 或 ZX_GUEST_TRAP_IO。如果 ZX_GUEST_TRAP_BELL 或 ZX_GUEST_TRAP_MEM 那么 addr 和 size 都必须与页面对齐。 ZX_GUEST_TRAP_BELL 是一个异步 trap，并且 ZX_GUEST_TRAP_MEM 和 ZX_GUEST_TRAP_IO 是同步 trap。

同步 trap 数据包将通过 zx_vcpu_enter() 传送， 异步陷阱的数据包将通过 port_handle 传递。

对于同步 trap，port_handle 必须为 ZX_HANDLE_INVALID。对于 异步 trap port_handle 必须有效，并且 trap 的数据包将是 每次触发 trap 时通过 port_handle 传递。固定数量 的数据包数量是每个 trap 预分配的。如果所有数据包都耗尽 导致 trap 的 vCPU 的执行将暂停。如果至少一个 数据包已移出队列，则 vCPU 的执行将恢复。要将数据包从 port_handle，请使用 zx_port_wait()。多个线程可能会使用 zx_port_wait()，用于将数据包移出队列，从而使用线程池 处理 trap。

key 用于设置 zx_port_packet_t 中的键字段，并可用于 区分不同陷阱的数据包。

ZX_GUEST_TRAP_BELL 是一种定义门铃的陷阱。如果有 对 trap 指定的内存区域的访问，则会生成数据包。 不提取与访问权限关联的指令。数据包将 然后通过 port_handle 异步传递。

如需确定生成数据包的是哪种陷阱，请使用 ZX_PKT_TYPE_GUEST_MEM、ZX_PKT_TYPE_GUEST_IO、ZX_PKT_TYPE_GUEST_BELL、 和 ZX_PKT_TYPE_GUEST_VCPU。ZX_PKT_TYPE_GUEST_VCPU 是一个特殊数据包， 并非由陷阱导致的，这表示访客要求启动 额外的 vCPU 数量

权限

handle 的类型必须为 ZX_OBJ_TYPE_GUEST 且包含 ZX_RIGHT_WRITE。

port_handle 的类型必须为 ZX_OBJ_TYPE_PORT 且包含 ZX_RIGHT_WRITE。

返回值

如果成功，zx_guest_set_trap() 会返回 ZX_OK。如果失败，错误值为 返回。

错误

ZX_ERR_ACCESS_DENIED handle 或 port_handle 没有 右边ZX_RIGHT_WRITE。

ZX_ERR_ALREADY_EXISTS 已存在与以下项交互的 kind 陷阱 addr 和 size。

ZX_ERR_BAD_HANDLE handle 或 port_handle 是无效的句柄。

ZX_ERR_INVALID_ARGS kind 不是有效的地址空间，或者 ZX_GUEST_TRAP_MEM 是通过 port_handle 指定的。

ZX_ERR_NO_MEMORY 因内存不足而失败。 用户空间没有好办法处理这种（不太可能）错误。 在将来的版本中，此错误不会再发生。

ZX_ERR_OUT_OF_RANGE addr 和 size 指定的区域不在 地址空间 kind 的有效边界内。

ZX_ERR_WRONG_TYPE handle 不是客户机的句柄，或 port_handle 而不是端口的句柄

备注

ZX_GUEST_TRAP_BELL 与 ZX_GUEST_TRAP_MEM 共享相同的地址空间。

在 x86-64 上，如果 kind 为 ZX_GUEST_TRAP_BELL 或 ZX_GUEST_TRAP_MEM 且 addr 是本地 APIC 的地址，那么 size 必须等同于 网页。这是由于在请求 trap 时映射一个特殊页面 本地 APIC 的地址。这使我们能够充分利用 加速。

另请参阅