1# zx_bti_pin 2 3## NAME 4 5<!-- Updated by update-docs-from-abigen, do not edit. --> 6 7bti_pin - pin pages and grant devices access to them 8 9## SYNOPSIS 10 11<!-- Updated by update-docs-from-abigen, do not edit. --> 12 13``` 14#include <zircon/syscalls.h> 15 16zx_status_t zx_bti_pin(zx_handle_t handle, 17 uint32_t options, 18 zx_handle_t vmo, 19 uint64_t offset, 20 uint64_t size, 21 zx_paddr_t* addrs, 22 size_t addrs_count, 23 zx_handle_t* pmt); 24``` 25 26## DESCRIPTION 27 28`zx_bti_pin()` pins pages of a VMO (i.e. prevents them from being decommitted 29with [`zx_vmo_op_range()`]) and grants the hardware 30transaction ID represented by the BTI the ability to access these pages, 31with the permissions specified in *options*. 32 33*offset* must be aligned to page boundaries. 34 35*options* is a bitfield that may contain one or more of **ZX_BTI_PERM_READ**, 36**ZX_BTI_PERM_WRITE**, **ZX_BTI_PERM_EXECUTE**, **ZX_BTI_COMPRESS**, and 37**ZX_BTI_CONTIGUOUS**. In order for the call to succeed, *vmo* must have the 38READ/WRITE rights corresponding to the permissions flags set in *options*. 39(Note: **ZX_BTI_PERM_EXECUTE** requires **ZX_RIGHT_READ**, not **ZX_RIGHT_EXECUTE**.) 40**ZX_BTI_CONTIGUOUS** is only allowed if *vmo* was allocated via 41[`zx_vmo_create_contiguous()`] or [`zx_vmo_create_physical()`]. 42**ZX_BTI_COMPRESS** and **ZX_BTI_CONTIGUOUS** are mutually exclusive. 43 44If the range in *vmo* specified by *offset* and *size* contains non-committed 45pages, a successful invocation of this function will result in those pages 46having been committed. On failure, it is undefined whether they have been 47committed. 48 49*addrs* will be populated with the device-physical addresses of the requested 50VMO pages. These addresses may be given to devices that issue memory 51transactions with the hardware transaction ID associated with the BTI. The 52number of addresses returned depends on whether the **ZX_BTI_COMPRESS** or 53**ZX_BTI_CONTIGUOUS** options were given. It number of addresses will be either 541) If neither is set, one per page (`size*/*PAGE_SIZE`) 552) If **ZX_BTI_COMPRESS** is set, `size/minimum-contiguity`, rounded up 56 (each address representing a run of *minimum-contiguity* run of bytes, 57 with the last one being potentially short if *size* is not a multiple of 58 *minimum-contiguity*). It is guaranteed that all returned addresses will be 59 *minimum-contiguity*-aligned. Note that *minimum-contiguity* is discoverable 60 via [`zx_object_get_info()`]. 613) If **ZX_BTI_CONTIGUOUS** is set, the single address of the start of the memory. 62 63*addrs_count* is the number of entries in the *addrs* array. It is an error for 64*addrs_count* to not match the value calculated above. 65 66## OPTIONS 67 68- **ZX_BTI_PERM_READ**, **ZX_BTI_PERM_WRITE**, and **ZX_BTI_PERM_EXECUTE** define 69 the access types that the hardware bus transaction initiator will be allowed 70 to use. 71- **ZX_BTI_COMPRESS** causes the returned address list to contain one entry per 72 block of *minimum-contiguity* bytes, rather than one per *PAGE_SIZE*. 73 74## RIGHTS 75 76<!-- Updated by update-docs-from-abigen, do not edit. --> 77 78*handle* must be of type **ZX_OBJ_TYPE_BTI** and have **ZX_RIGHT_MAP**. 79 80*vmo* must be of type **ZX_OBJ_TYPE_VMO** and have **ZX_RIGHT_MAP**. 81 82If *options* & **ZX_BTI_PERM_READ**, *vmo* must be of type **ZX_OBJ_TYPE_VMO** and have **ZX_RIGHT_READ**. 83 84If *options* & **ZX_BTI_PERM_WRITE**, *vmo* must be of type **ZX_OBJ_TYPE_VMO** and have **ZX_RIGHT_WRITE**. 85 86If *options* & **ZX_BTI_PERM_EXECUTE**, *vmo* must be of type **ZX_OBJ_TYPE_VMO** and have **ZX_RIGHT_READ**. 87 88## RETURN VALUE 89 90On success, `zx_bti_pin()` returns **ZX_OK**. The device-physical addresses of the 91requested VMO pages will be written in *addrs*. A handle to the created Pinned 92Memory Token is returned via *pmt*. When the PMT is no longer needed, 93[`zx_pmt_unpin()`] should be invoked. 94 95In the event of failure, a negative error value is returned. 96 97## ERRORS 98 99**ZX_ERR_BAD_HANDLE** *handle* or *vmo* is not a valid handle. 100 101**ZX_ERR_WRONG_TYPE** *handle* is not a BTI handle or *vmo* is not a VMO handle. 102 103**ZX_ERR_ACCESS_DENIED** *handle* or *vmo* does not have the **ZX_RIGHT_MAP**, or 104*options* contained a permissions flag corresponding to a right that *vmo* does not have. 105 106**ZX_ERR_INVALID_ARGS** *options* is 0 or contains an undefined flag, either *addrs* or *pmt* 107is not a valid pointer, *addrs_count* is not the same as the number of entries that would be 108returned, or *offset* or *size* is not page-aligned. 109 110**ZX_ERR_OUT_OF_RANGE** *offset* + *size* is out of the bounds of *vmo*. 111 112**ZX_ERR_UNAVAILABLE** (Temporary) At least one page in the requested range could 113not be pinned at this time. 114 115**ZX_ERR_NO_MEMORY** Failure due to lack of memory. 116There is no good way for userspace to handle this (unlikely) error. 117In a future build this error will no longer occur. 118 119## SEE ALSO 120 121 - [`zx_bti_create()`] 122 - [`zx_object_get_info()`] 123 - [`zx_pmt_unpin()`] 124 125<!-- References updated by update-docs-from-abigen, do not edit. --> 126 127[`zx_bti_create()`]: bti_create.md 128[`zx_object_get_info()`]: object_get_info.md 129[`zx_pmt_unpin()`]: pmt_unpin.md 130[`zx_vmo_create_contiguous()`]: vmo_create_contiguous.md 131[`zx_vmo_create_physical()`]: vmo_create_physical.md 132[`zx_vmo_op_range()`]: vmo_op_range.md 133