bti_pin - pin pages and grant devices access to them
#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);
bti_pin() pins pages of a VMO (i.e. prevents them from being decommitted) and grants the hardware transaction ID represented by the BTI the ability to access these pages, with the permissions specified in options.
offset must be aligned to page boundaries.
options is a bitfield that may contain one or more of ZX_BTI_PERM_READ, ZX_BTI_PERM_WRITE, ZX_BTI_PERM_EXECUTE, and ZX_BTI_COMPRESS. In order for the call to succeed, vmo must have the READ/WRITE/EXECUTE rights corresponding to the permissions flags set in options.
If the range in vmo specified by offset and size contains non-committed pages, a successful invocation of this function will result in those pages having been committed. On failure, it is undefined whether they have been committed.
addrs will be populated with the device-physical addresses of the requested VMO pages. These addresses may be given to devices that issue memory transactions with the hardware transaction ID associated with the BTI. The number of addresses returned depends on whether the ZX_BTI_COMPRESS option was given. It number of addresses will be either
Note that minimum-contiguity is discoverable via object_get_info().
On success, bti_pin() returns ZX_OK. The device-physical addresses of the requested VMO pages will be written in addrs.
In the event of failure, a negative error value is returned.
ZX_ERR_BAD_HANDLE bti or vmo is not a valid handle.
ZX_ERR_WRONG_TYPE bti is not a BTI handle or vmo is not a VMO handle.
ZX_ERR_ACCESS_DENIED bti or vmo does not have the ZX_RIGHT_MAP, or options contained a permissions flag corresponding to a right that vmo does not have.
ZX_ERR_INVALID_ARGS options is 0 or contains an undefined flag, or addrs is not a valid pointer, addrs_count is not the same as the number of entries that would be returned, or offset or size is not page-aligned.
ZX_ERR_ALREADY_BOUND The requested range contains a page already pinned by this BTI.
ZX_ERR_UNAVAILABLE (Temporary) At least one page in the requested range could not be pinned at this time.
ZX_ERR_NO_MEMORY (Temporary) Failure due to lack of memory.