zx_guest_set_trap

英文原文快照

名称

guest_set_trap —— 在客户虚拟机中设置陷入中断

概要

  1. #include <zircon/syscalls.h>
  2. #include <zircon/syscalls/port.h>
  4. zx_status_t zx_guest_set_trap(zx_handle_t guest, uint32_t kind, zx_vaddr_t addr,
  5.                               size_t len, zx_handle_t port, uint64_t key);

描述

guest_set_trap() 的功能是在客户虚拟机中设置一个陷入中断，当由addr和len定义的地址范围内的VCPU访问时，会在kind定义的地址空间内生成数据包。

如果指定了port，在每次触发陷入时，将通过port传递陷入数据包，但如果指定了ZX_HANDLE_INVALID，则将通过vcpu_resume() 传递数据包。 这提供了控制数据包是异步还是同步传送的手段。

在指定port时，每个陷入中断会预先分配固定数量的数据包。 如果所有数据包都已耗尽，则会暂停执行导致陷入的VCPU。 当至少有一个数据包出队时，VCPU将恢复执行。 要从port中使数据包出队，请使用port_wait()。 多个线程可以使用port_wait() 来使数据包出列，从而允许使用线程池来处理陷入。

key用于设置zx_port_packet_t内的key字段，可用于区分不同类型的陷入数据包。

kind的值可以是ZX_GUEST_TRAP_BELL，ZX_GUEST_TRAP_MEM或ZX_GUEST_TRAP_IO。 如果设置了ZX_GUEST_TRAP_BELL或ZX_GUEST_TRAP_MEM，则addr和len必须都是页对齐的。 如果设置了ZX_GUEST_TRAP_BELL，则必须指定port。 如果设置了ZX_GUEST_TRAP_MEM或ZX_GUEST_TRAP_IO，则port必须是ZX_HANDLE_INVALID。

ZX_GUEST_TRAP_BELL是一种定义“门铃”的陷入类型，表示如果发生对陷入指定的存储区域的访问，则生成不获取与访问相关联的指令的数据包。 而后该数据包将通过port传送。

要指定生成数据包的kind值，请使用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。

权限

TODO(ZX-2399)

返回值

guest_set_trap() 调用成功则返回ZX_OK。 如果调用失败，则返回负的错误码。

ERRORS

ZX_ERR_ACCESS_DENIED：guest或port没有ZX_RIGHT_WRITE权限。

ZX_ERR_ALREADY_EXISTS：已存在具有相同kind和addr值的陷入。

ZX_ERR_BAD_HANDLE：guest或port是无效句柄。

ZX_ERR_INVALID_ARGS：下列情况之一，kind不是有效的地址空间；addr或len不符合kind的要求；len为0；或kind的值是ZX_GUEST_TRAP_MEM，但指定了port。

ZX_ERR_NO_MEMORY：由于内存不足导致的失败。而用户空间无法处理这个（不太可能发生的）错误。在将来的构建版本中，将不再出现此错误。

ZX_ERR_OUT_OF_RANGE： addr和len指定的内存区域超出了kind所允许的地址空间的有效范围。 ZX_ERR_WRONG_TYPE：guest不是虚拟机类型句柄，或者port不是端口类型句柄。

注释

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

在x86-64上，如果kind是ZX_GUEST_TRAP_BELL或ZX_GUEST_TRAP_MEM类型，且addr是本地APIC的地址，则len必须等于页面的大小。 这是由于在本地APIC的地址发生陷入请求时需要映射的特殊页面。这也使得我们可利用硬件的加速。

另见

guest_create, port_create, port_wait, vcpu_create, vcpu_resume, vcpu_interrupt, vcpu_read_state, vcpu_write_state.