zx_bti_pin
名称
bti_pin —— 固定内存页面,并授权设备访问它们
概要
#include <zircon/syscalls.h>
zx_status_t zx_bti_pin(zx_handle_t bti, uint32_t options,
zx_handle_t vmo, uint64_t offset, uint64_t size,
zx_paddr_t* addrs, size_t addrs_count,
zx_handle_t* pmt);
描述
bti_pin() 固定VMO页面(即阻止它们通过 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中设置的权限标志相对应的READ/WRITE/EXECUTE权限。 仅当vmo通过zx_vmo_create_contiguous() 或zx_vmo_create_physical() 分配时,才可使用ZX_BTI_CONTIGUOUS。 ZX_BTI_COMPRESS和ZX_BTI_CONTIGUOUS是互斥的,不可同时出现。
如果offset和size指定的vmo的范围内包含非提交页面,在成功调用后将同时导致这些页面被提交。 如果调用失败时,它们是否被提交未定义。
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对齐的。 这里需要注意的是,minimum-contiguity可通过 object_get_info() 获得。 3) 如果设置了ZX_BTI_CONTIGUOU标志位,则是从起始地址处开始的单一地址。
addrs_count是addrs的数组项数量。 addrs_count与上面计算的值不匹配将产生错误。
选项
- ZX_BTI_PERM_READ,ZX_BTI_PERM_WRITE和ZX_BTI_PERM_EXECUTE定义了硬件总线事务发起者允许使用的访问类型。
- ZX_BTI_COMPRESS使返回的地址列表在每minimum-contiguity字节块中包含一个项,而不是每PAGE_SIZE字节一个。
权限
TODO(ZX-2399)
返回值
调用成功时,bti_pin() 返回ZX_OK。 请求的VMO页面的设备物理地址将写入addrs中,并通过pmt返回新创建的表示固定内存令牌的句柄。 当不再需要PMT时,应调用pmt_unpin() 取消固定。
如果调用失败,则返回负的错误码。
错误码
ZX_ERR_BAD_HANDLE:bti或vmo是无效句柄。
ZX_ERR_WRONG_TYPE:bti不是BTI类型句柄或vmo不是VMO类型句柄。
ZX_ERR_ACCESS_DENIED:bti或vmo没有ZX_RIGHT_MAP权限,或者options包含的权限在vmo中没有对应的标志。
ZX_ERR_INVALID_ARGS:下列情况之一:options为0或包含未定义的标志;addrs或pmt是无效指针;addrs_count与返回的项数不同;offset或size不是页面对齐整型。
ZX_ERR_OUT_OF_RANGE:offset+size超出了vmo的范围。
ZX_ERR_UNAVAILABLE:无法固定请求范围内的至少一个页面(临时性)。
ZX_ERR_NO_MEMORY:由于内存不足导致的失败。而用户空间无法处理这个(不太可能发生的)错误。在将来的构建版本中,将不再出现此错误。