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 中指定）。

偏移必须与页面边界对齐。

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。）只有在通过 zx_vmo_create_contiguous() 或 zx_vmo_create_physical() 分配了 vmo 时，才允许使用 ZX_BTI_CONTIGUOUS。ZX_BTI_COMPRESS 和 ZX_BTI_CONTIGUOUS 是互斥的。

如果 vmo 中由 offset 和 size 指定的范围包含未提交的页面，则成功调用此函数会导致这些页面提交。如果失败，则无法确定这些操作是否已提交。

addrs 将填充请求的 VMO 页面的设备物理地址。这些地址可提供给发出内存事务且具有与 BTI 关联的硬件事务 ID 的设备。返回的地址数量取决于是否提供了 ZX_BTI_COMPRESS 或 ZX_BTI_CONTIGUOUS 选项。地址数量将是以下三种情况之一：

  1. 如果未设置这两个值，则为每页一个 (size / PAGE_SIZE)。
  2. 如果设置了 ZX_BTI_COMPRESS，则为 size / minimum-contiguity（向上取整；每个地址代表一组 minimum-contiguity 字节，如果 size 不是 minimum-contiguity 的倍数，则最后一个地址可能会较短）。系统保证所有返回的地址都将采用最小连续性对齐方式。请注意，minimum-contiguity 可通过 zx_object_get_info() 发现。
  3. 如果设置了 ZX_BTI_CONTIGUOUS，则为内存起始地址的单个地址。

num_addrs 是 addrs 数组中的条目数。如果 num_addrs 与上面计算的值不符，则表示存在错误。

PMT 会保留对关联的 VMO 的引用，因此在 PMT 取消固定之前，底层 VMO 不会被销毁。

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

选项

  • ZX_BTI_PERM_READ、ZX_BTI_PERM_WRITE 和 ZX_BTI_PERM_EXECUTE 用于定义硬件总线事务发起方将被允许使用的访问类型。
  • ZX_BTI_COMPRESS 会导致返回的地址列表中每 minimum-contiguity 字节块包含一个条目，而不是每 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 不是有效的 handle。

ZX_ERR_WRONG_TYPE 句柄不是 BTI 句柄，或者 vmo 不是 VMO 句柄。

ZX_ERR_ACCESS_DENIED handle 或 vmo 没有 ZX_RIGHT_MAP，或者 options 包含与 vmo 不具备的权限对应的权限标志。

ZX_ERR_INVALID_ARGS options 为 0 或包含未定义的标志，addrs 或 pmt 不是有效的指针，num_addrs 与要返回的条目数量不一致，num_addrs 过大，或者 offset 或 size 未对齐到页面。

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

ZX_ERR_UNAVAILABLE（暂时性）目前无法固定请求范围内的至少 1 个网页。

ZX_ERR_NO_MEMORY 因内存不足而失败。用户空间没有很好的方式来处理这种（不太可能发生的）错误。在未来的 build 中，此错误将不再出现。

另请参阅