zx_bti_pin

摘要

固定页面并授予设备访问权限。

声明

#include <zircon/syscalls.h>

zx_status_t zx_bti_pin(zx_handle_t handle,
                       uint32_t options,
                       zx_handle_t vmo,
                       uint64_t offset,
                       uint64_t size,
                       zx_paddr_t* addrs,
                       size_t num_addrs,
                       zx_handle_t* pmt);

说明

zx_bti_pin() 会固定 VMO 的页面（即阻止这些页面被停用） （具有 zx_vmo_op_range()）并授予硬件 通过 BTI 表示交易 ID、访问这些页面的权限、 使用 options 中指定的权限。

offset 必须与页面边界对齐。

options 是一个位字段，可以包含一个或多个 ZX_BTI_PERM_READ、 ZX_BTI_PERM_WRITE、ZX_BTI_PERM_EXECUTE、ZX_BTI_COMPRESS和 ZX_BTI_CONTIGUOUS。为使调用成功，vmo 必须包含 与 options 中设置的权限标志对应的读/写权限。 （注意：ZX_BTI_PERM_EXECUTE 需要 ZX_RIGHT_READ，而不是 ZX_RIGHT_EXECUTE。） 仅当通过以下方式分配 vmo 时，才允许 ZX_BTI_CONTIGUOUS： zx_vmo_create_contiguous() 或 zx_vmo_create_physical()。 ZX_BTI_COMPRESS 和 ZX_BTI_CONTIGUOUS 是互斥的。

如果 vmo 中的范围由 offset 且 size 包含非承诺 成功调用此函数将生成这些页面 所有承诺失败时，无法确定它们是否已被 投入。

addrs 将使用请求的 VMO 页面。系统可能会将这些地址提供给发出内存的设备 使用与 BTI 关联的硬件交易 ID 进行交易。通过 返回的地址数量取决于 ZX_BTI_COMPRESS 还是 已指定 ZX_BTI_CONTIGUOUS 个选项。地址数量将为 1 个 三种可能性：

  1. 如果二者都未设置，则每页一个文件 (size / PAGE_SIZE)。
  2. 如果设置了 ZX_BTI_COMPRESS，则设为 size / minimum-contiguity，向上舍入 （每个地址表示一次最小连续字节运行， 如果 size 不是 最小连续性）。可以保证返回的所有地址 请注意，最小连续性易于发现 经由zx_object_get_info()。
  3. 如果设置了 ZX_BTI_CONTIGUOUS，则为内存起始位置的单个地址。

num_addrs 是 addrs 数组中的条目数。这是一个错误， num_addrs 的值，以便与上面计算的值不匹配。

PMT 会保留对关联 VMO 的引用，因此底层 VMO 不会被 会被销毁，直到 PMT 取消固定为止。

可以固定可调整大小的 VMO。如果对 zx_vmo_set_size() 的调用会舍弃， 则调用将会失败。

选项

  • ZX_BTI_PERM_READ、ZX_BTI_PERM_WRITE 和 ZX_BTI_PERM_EXECUTE 定义 允许硬件总线事务发起程序的访问类型 使用。
  • ZX_BTI_COMPRESS 会使返回的地址列表每包含 1 个条目 最小连续字节块，而不是每个 PAGE_SIZE 一个字节。

权限

handle 的类型必须为 ZX_OBJ_TYPE_BTI 且包含 ZX_RIGHT_MAP。

vmo 的类型必须为 ZX_OBJ_TYPE_VMO 且包含 ZX_RIGHT_MAP。

如果options和ZX_BTI_PERM_READ 和 vmo 的类型必须为 ZX_OBJ_TYPE_VMO 且包含 ZX_RIGHT_READ。

如果options和ZX_BTI_PERM_WRITE 和 vmo 的类型必须为 ZX_OBJ_TYPE_VMO 且包含 ZX_RIGHT_WRITE。

如果options和ZX_BTI_PERM_EXECUTE 和 vmo 的类型必须为 ZX_OBJ_TYPE_VMO 且包含 ZX_RIGHT_READ。

返回值

成功后，zx_bti_pin() 会返回 ZX_OK。容器的设备物理地址 请求的 VMO 页面将用 addrs 写入。已创建的“已固定”的句柄 内存令牌通过 pmt 返回。当不再需要 PMT 时， zx_pmt_unpin()。

如果失败，则返回负的错误值。

错误

ZX_ERR_BAD_HANDLE handle 或 vmo 不是有效的句柄。

ZX_ERR_WRONG_TYPE handle 不是 BTI 句柄，或 vmo 不是 VMO 标识名。

ZX_ERR_ACCESS_DENIED handle 或 vmo 没有 ZX_RIGHT_MAP， 或 options 包含的权限标志对应于 vmo 的某个权限 不包含。

ZX_ERR_INVALID_ARGS options 为 0 或包含未定义的标志 addrs 或 pmt 不是有效指针，num_addrs 与 所返回的条目数，或者 offset 或 size 页面对齐方式。

ZX_ERR_OUT_OF_RANGE offset + size超出了 vmo 的边界。

ZX_ERR_UNAVAILABLE（临时）所请求的范围中至少有一个网页 目前无法固定。

ZX_ERR_NO_MEMORY 因内存不足而失败。没有什么好办法 处理此（不太可能）错误。在未来的版本中，此错误将不再出现 出现时间更长。

另请参阅