tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
1==========================
2AArch64 TAGGED ADDRESS ABI
3==========================
4
5Authors: Vincenzo Frascino <vincenzo.frascino@arm.com>
6 Catalin Marinas <catalin.marinas@arm.com>
7
8Date: 21 August 2019
9
10This document describes the usage and semantics of the Tagged Address
11ABI on AArch64 Linux.
12
131. Introduction
14---------------
15
16On AArch64 the ``TCR_EL1.TBI0`` bit is set by default, allowing
17userspace (EL0) to perform memory accesses through 64-bit pointers with
18a non-zero top byte. This document describes the relaxation of the
19syscall ABI that allows userspace to pass certain tagged pointers to
20kernel syscalls.
21
222. AArch64 Tagged Address ABI
23-----------------------------
24
25From the kernel syscall interface perspective and for the purposes of
26this document, a "valid tagged pointer" is a pointer with a potentially
27non-zero top-byte that references an address in the user process address
28space obtained in one of the following ways:
29
30- ``mmap()`` syscall where either:
31
32 - flags have the ``MAP_ANONYMOUS`` bit set or
33 - the file descriptor refers to a regular file (including those
34 returned by ``memfd_create()``) or ``/dev/zero``
35
36- ``brk()`` syscall (i.e. the heap area between the initial location of
37 the program break at process creation and its current location).
38
39- any memory mapped by the kernel in the address space of the process
40 during creation and with the same restrictions as for ``mmap()`` above
41 (e.g. data, bss, stack).
42
43The AArch64 Tagged Address ABI has two stages of relaxation depending on
44how the user addresses are used by the kernel:
45
461. User addresses not accessed by the kernel but used for address space
47 management (e.g. ``mprotect()``, ``madvise()``). The use of valid
48 tagged pointers in this context is allowed with these exceptions:
49
50 - ``brk()``, ``mmap()`` and the ``new_address`` argument to
51 ``mremap()`` as these have the potential to alias with existing
52 user addresses.
53
54 NOTE: This behaviour changed in v5.6 and so some earlier kernels may
55 incorrectly accept valid tagged pointers for the ``brk()``,
56 ``mmap()`` and ``mremap()`` system calls.
57
58 - The ``range.start``, ``start`` and ``dst`` arguments to the
59 ``UFFDIO_*`` ``ioctl()``s used on a file descriptor obtained from
60 ``userfaultfd()``, as fault addresses subsequently obtained by reading
61 the file descriptor will be untagged, which may otherwise confuse
62 tag-unaware programs.
63
64 NOTE: This behaviour changed in v5.14 and so some earlier kernels may
65 incorrectly accept valid tagged pointers for this system call.
66
672. User addresses accessed by the kernel (e.g. ``write()``). This ABI
68 relaxation is disabled by default and the application thread needs to
69 explicitly enable it via ``prctl()`` as follows:
70
71 - ``PR_SET_TAGGED_ADDR_CTRL``: enable or disable the AArch64 Tagged
72 Address ABI for the calling thread.
73
74 The ``(unsigned int) arg2`` argument is a bit mask describing the
75 control mode used:
76
77 - ``PR_TAGGED_ADDR_ENABLE``: enable AArch64 Tagged Address ABI.
78 Default status is disabled.
79
80 Arguments ``arg3``, ``arg4``, and ``arg5`` must be 0.
81
82 - ``PR_GET_TAGGED_ADDR_CTRL``: get the status of the AArch64 Tagged
83 Address ABI for the calling thread.
84
85 Arguments ``arg2``, ``arg3``, ``arg4``, and ``arg5`` must be 0.
86
87 The ABI properties described above are thread-scoped, inherited on
88 clone() and fork() and cleared on exec().
89
90 Calling ``prctl(PR_SET_TAGGED_ADDR_CTRL, PR_TAGGED_ADDR_ENABLE, 0, 0, 0)``
91 returns ``-EINVAL`` if the AArch64 Tagged Address ABI is globally
92 disabled by ``sysctl abi.tagged_addr_disabled=1``. The default
93 ``sysctl abi.tagged_addr_disabled`` configuration is 0.
94
95When the AArch64 Tagged Address ABI is enabled for a thread, the
96following behaviours are guaranteed:
97
98- All syscalls except the cases mentioned in section 3 can accept any
99 valid tagged pointer.
100
101- The syscall behaviour is undefined for invalid tagged pointers: it may
102 result in an error code being returned, a (fatal) signal being raised,
103 or other modes of failure.
104
105- The syscall behaviour for a valid tagged pointer is the same as for
106 the corresponding untagged pointer.
107
108
109A definition of the meaning of tagged pointers on AArch64 can be found
110in Documentation/arch/arm64/tagged-pointers.rst.
111
1123. AArch64 Tagged Address ABI Exceptions
113-----------------------------------------
114
115The following system call parameters must be untagged regardless of the
116ABI relaxation:
117
118- ``prctl()`` other than pointers to user data either passed directly or
119 indirectly as arguments to be accessed by the kernel.
120
121- ``ioctl()`` other than pointers to user data either passed directly or
122 indirectly as arguments to be accessed by the kernel.
123
124- ``shmat()`` and ``shmdt()``.
125
126- ``brk()`` (since kernel v5.6).
127
128- ``mmap()`` (since kernel v5.6).
129
130- ``mremap()``, the ``new_address`` argument (since kernel v5.6).
131
132Any attempt to use non-zero tagged pointers may result in an error code
133being returned, a (fatal) signal being raised, or other modes of
134failure.
135
1364. Example of correct usage
137---------------------------
138.. code-block:: c
139
140 #include <stdlib.h>
141 #include <string.h>
142 #include <unistd.h>
143 #include <sys/mman.h>
144 #include <sys/prctl.h>
145
146 #define PR_SET_TAGGED_ADDR_CTRL 55
147 #define PR_TAGGED_ADDR_ENABLE (1UL << 0)
148
149 #define TAG_SHIFT 56
150
151 int main(void)
152 {
153 int tbi_enabled = 0;
154 unsigned long tag = 0;
155 char *ptr;
156
157 /* check/enable the tagged address ABI */
158 if (!prctl(PR_SET_TAGGED_ADDR_CTRL, PR_TAGGED_ADDR_ENABLE, 0, 0, 0))
159 tbi_enabled = 1;
160
161 /* memory allocation */
162 ptr = mmap(NULL, sysconf(_SC_PAGE_SIZE), PROT_READ | PROT_WRITE,
163 MAP_PRIVATE | MAP_ANONYMOUS, -1, 0);
164 if (ptr == MAP_FAILED)
165 return 1;
166
167 /* set a non-zero tag if the ABI is available */
168 if (tbi_enabled)
169 tag = rand() & 0xff;
170 ptr = (char *)((unsigned long)ptr | (tag << TAG_SHIFT));
171
172 /* memory access to a tagged address */
173 strcpy(ptr, "tagged pointer\n");
174
175 /* syscall with a tagged pointer */
176 write(1, ptr, strlen(ptr));
177
178 return 0;
179 }