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 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/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 126Any attempt to use non-zero tagged pointers may result in an error code 127being returned, a (fatal) signal being raised, or other modes of 128failure. 129 1304. Example of correct usage 131--------------------------- 132.. code-block:: c 133 134 #include <stdlib.h> 135 #include <string.h> 136 #include <unistd.h> 137 #include <sys/mman.h> 138 #include <sys/prctl.h> 139 140 #define PR_SET_TAGGED_ADDR_CTRL 55 141 #define PR_TAGGED_ADDR_ENABLE (1UL << 0) 142 143 #define TAG_SHIFT 56 144 145 int main(void) 146 { 147 int tbi_enabled = 0; 148 unsigned long tag = 0; 149 char *ptr; 150 151 /* check/enable the tagged address ABI */ 152 if (!prctl(PR_SET_TAGGED_ADDR_CTRL, PR_TAGGED_ADDR_ENABLE, 0, 0, 0)) 153 tbi_enabled = 1; 154 155 /* memory allocation */ 156 ptr = mmap(NULL, sysconf(_SC_PAGE_SIZE), PROT_READ | PROT_WRITE, 157 MAP_PRIVATE | MAP_ANONYMOUS, -1, 0); 158 if (ptr == MAP_FAILED) 159 return 1; 160 161 /* set a non-zero tag if the ABI is available */ 162 if (tbi_enabled) 163 tag = rand() & 0xff; 164 ptr = (char *)((unsigned long)ptr | (tag << TAG_SHIFT)); 165 166 /* memory access to a tagged address */ 167 strcpy(ptr, "tagged pointer\n"); 168 169 /* syscall with a tagged pointer */ 170 write(1, ptr, strlen(ptr)); 171 172 return 0; 173 } 174