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
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 the exception of
49   ``brk()``, ``mmap()`` and the ``new_address`` argument to
50   ``mremap()`` as these have the potential to alias with existing
51   user addresses.
52
53   NOTE: This behaviour changed in v5.6 and so some earlier kernels may
54   incorrectly accept valid tagged pointers for the ``brk()``,
55   ``mmap()`` and ``mremap()`` system calls.
56
572. User addresses accessed by the kernel (e.g. ``write()``). This ABI
58   relaxation is disabled by default and the application thread needs to
59   explicitly enable it via ``prctl()`` as follows:
60
61   - ``PR_SET_TAGGED_ADDR_CTRL``: enable or disable the AArch64 Tagged
62     Address ABI for the calling thread.
63
64     The ``(unsigned int) arg2`` argument is a bit mask describing the
65     control mode used:
66
67     - ``PR_TAGGED_ADDR_ENABLE``: enable AArch64 Tagged Address ABI.
68       Default status is disabled.
69
70     Arguments ``arg3``, ``arg4``, and ``arg5`` must be 0.
71
72   - ``PR_GET_TAGGED_ADDR_CTRL``: get the status of the AArch64 Tagged
73     Address ABI for the calling thread.
74
75     Arguments ``arg2``, ``arg3``, ``arg4``, and ``arg5`` must be 0.
76
77   The ABI properties described above are thread-scoped, inherited on
78   clone() and fork() and cleared on exec().
79
80   Calling ``prctl(PR_SET_TAGGED_ADDR_CTRL, PR_TAGGED_ADDR_ENABLE, 0, 0, 0)``
81   returns ``-EINVAL`` if the AArch64 Tagged Address ABI is globally
82   disabled by ``sysctl abi.tagged_addr_disabled=1``. The default
83   ``sysctl abi.tagged_addr_disabled`` configuration is 0.
84
85When the AArch64 Tagged Address ABI is enabled for a thread, the
86following behaviours are guaranteed:
87
88- All syscalls except the cases mentioned in section 3 can accept any
89  valid tagged pointer.
90
91- The syscall behaviour is undefined for invalid tagged pointers: it may
92  result in an error code being returned, a (fatal) signal being raised,
93  or other modes of failure.
94
95- The syscall behaviour for a valid tagged pointer is the same as for
96  the corresponding untagged pointer.
97
98
99A definition of the meaning of tagged pointers on AArch64 can be found
100in Documentation/arm64/tagged-pointers.rst.
101
1023. AArch64 Tagged Address ABI Exceptions
103-----------------------------------------
104
105The following system call parameters must be untagged regardless of the
106ABI relaxation:
107
108- ``prctl()`` other than pointers to user data either passed directly or
109  indirectly as arguments to be accessed by the kernel.
110
111- ``ioctl()`` other than pointers to user data either passed directly or
112  indirectly as arguments to be accessed by the kernel.
113
114- ``shmat()`` and ``shmdt()``.
115
116Any attempt to use non-zero tagged pointers may result in an error code
117being returned, a (fatal) signal being raised, or other modes of
118failure.
119
1204. Example of correct usage
121---------------------------
122.. code-block:: c
123
124   #include <stdlib.h>
125   #include <string.h>
126   #include <unistd.h>
127   #include <sys/mman.h>
128   #include <sys/prctl.h>
129
130   #define PR_SET_TAGGED_ADDR_CTRL	55
131   #define PR_TAGGED_ADDR_ENABLE	(1UL << 0)
132
133   #define TAG_SHIFT		56
134
135   int main(void)
136   {
137   	int tbi_enabled = 0;
138   	unsigned long tag = 0;
139   	char *ptr;
140
141   	/* check/enable the tagged address ABI */
142   	if (!prctl(PR_SET_TAGGED_ADDR_CTRL, PR_TAGGED_ADDR_ENABLE, 0, 0, 0))
143   		tbi_enabled = 1;
144
145   	/* memory allocation */
146   	ptr = mmap(NULL, sysconf(_SC_PAGE_SIZE), PROT_READ | PROT_WRITE,
147   		   MAP_PRIVATE | MAP_ANONYMOUS, -1, 0);
148   	if (ptr == MAP_FAILED)
149   		return 1;
150
151   	/* set a non-zero tag if the ABI is available */
152   	if (tbi_enabled)
153   		tag = rand() & 0xff;
154   	ptr = (char *)((unsigned long)ptr | (tag << TAG_SHIFT));
155
156   	/* memory access to a tagged address */
157   	strcpy(ptr, "tagged pointer\n");
158
159   	/* syscall with a tagged pointer */
160   	write(1, ptr, strlen(ptr));
161
162   	return 0;
163   }
164