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