zx_bti_pin

Summary

Pin pages and grant devices access to them.

Declaration

#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);

Description

zx_bti_pin() pins pages of a VMO (i.e. prevents them from being decommitted with zx_vmo_op_range()) 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, ZX_BTI_COMPRESS, and ZX_BTI_CONTIGUOUS. In order for the call to succeed, vmo must have the READ/WRITE rights corresponding to the permissions flags set in options. (Note: ZX_BTI_PERM_EXECUTE requires ZX_RIGHT_READ, not ZX_RIGHT_EXECUTE.) ZX_BTI_CONTIGUOUS is only allowed if vmo was allocated via zx_vmo_create_contiguous() or zx_vmo_create_physical(). ZX_BTI_COMPRESS and ZX_BTI_CONTIGUOUS are mutually exclusive.

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 or ZX_BTI_CONTIGUOUS options were given. The number of addresses will be one of three possibilities:

  1. If neither is set, one per page (size / PAGE_SIZE).
  2. If ZX_BTI_COMPRESS is set, size / minimum-contiguity, rounded up (each address representing a run of minimum-contiguity run of bytes, with the last one being potentially short if size is not a multiple of minimum-contiguity). It is guaranteed that all returned addresses will be minimum-contiguity-aligned. Note that minimum-contiguity is discoverable via zx_object_get_info().
  3. If ZX_BTI_CONTIGUOUS is set, the single address of the start of the memory.

num_addrs is the number of entries in the addrs array. It is an error for num_addrs to not match the value calculated above.

The PMT retains a reference to the associated VMO, so the underlying VMO won't be destroyed until the PMT is unpinned.

Resizable VMOs can be pinned. If a call to zx_vmo_set_size() would discard pinned pages, that call will fail.

Options

  • ZX_BTI_PERM_READ, ZX_BTI_PERM_WRITE, and ZX_BTI_PERM_EXECUTE define the access types that the hardware bus transaction initiator will be allowed to use.
  • ZX_BTI_COMPRESS causes the returned address list to contain one entry per block of minimum-contiguity bytes, rather than one per PAGE_SIZE.

Rights

handle must be of type ZX_OBJ_TYPE_BTI and have ZX_RIGHT_MAP.

vmo must be of type ZX_OBJ_TYPE_VMO and have ZX_RIGHT_MAP.

If options & ZX_BTI_PERM_READ, vmo must be of type ZX_OBJ_TYPE_VMO and have ZX_RIGHT_READ.

If options & ZX_BTI_PERM_WRITE, vmo must be of type ZX_OBJ_TYPE_VMO and have ZX_RIGHT_WRITE.

If options & ZX_BTI_PERM_EXECUTE, vmo must be of type ZX_OBJ_TYPE_VMO and have ZX_RIGHT_READ.

Return value

On success, zx_bti_pin() returns ZX_OK. The device-physical addresses of the requested VMO pages will be written in addrs. A handle to the created Pinned Memory Token is returned via pmt. When the PMT is no longer needed, zx_pmt_unpin() should be invoked.

In the event of failure, a negative error value is returned.

Errors

ZX_ERR_BAD_HANDLE handle or vmo is not a valid handle.

ZX_ERR_WRONG_TYPE handle is not a BTI handle or vmo is not a VMO handle.

ZX_ERR_ACCESS_DENIED handle 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, either addrs or pmt is not a valid pointer, num_addrs is not the same as the number of entries that would be returned, num_addrs is too large or offset or size is not page-aligned.

ZX_ERR_OUT_OF_RANGE offset + size is out of the bounds of vmo.

ZX_ERR_UNAVAILABLE (Temporary) At least one page in the requested range could not be pinned at this time.

ZX_ERR_NO_MEMORY Failure due to lack of memory. There is no good way for userspace to handle this (unlikely) error. In a future build this error will no longer occur.

See also