180 lines · plain
1==========================2AArch64 TAGGED ADDRESS ABI3==========================4 5Authors: Vincenzo Frascino <vincenzo.frascino@arm.com>6 Catalin Marinas <catalin.marinas@arm.com>7 8Date: 21 August 20199 10This document describes the usage and semantics of the Tagged Address11ABI on AArch64 Linux.12 131. Introduction14---------------15 16On AArch64 the ``TCR_EL1.TBI0`` bit is set by default, allowing17userspace (EL0) to perform memory accesses through 64-bit pointers with18a non-zero top byte. This document describes the relaxation of the19syscall ABI that allows userspace to pass certain tagged pointers to20kernel syscalls.21 222. AArch64 Tagged Address ABI23-----------------------------24 25From the kernel syscall interface perspective and for the purposes of26this document, a "valid tagged pointer" is a pointer with a potentially27non-zero top-byte that references an address in the user process address28space obtained in one of the following ways:29 30- ``mmap()`` syscall where either:31 32 - flags have the ``MAP_ANONYMOUS`` bit set or33 - the file descriptor refers to a regular file (including those34 returned by ``memfd_create()``) or ``/dev/zero``35 36- ``brk()`` syscall (i.e. the heap area between the initial location of37 the program break at process creation and its current location).38 39- any memory mapped by the kernel in the address space of the process40 during creation and with the same restrictions as for ``mmap()`` above41 (e.g. data, bss, stack).42 43The AArch64 Tagged Address ABI has two stages of relaxation depending on44how the user addresses are used by the kernel:45 461. User addresses not accessed by the kernel but used for address space47 management (e.g. ``mprotect()``, ``madvise()``). The use of valid48 tagged pointers in this context is allowed with these exceptions:49 50 - ``brk()``, ``mmap()`` and the ``new_address`` argument to51 ``mremap()`` as these have the potential to alias with existing52 user addresses.53 54 NOTE: This behaviour changed in v5.6 and so some earlier kernels may55 incorrectly accept valid tagged pointers for the ``brk()``,56 ``mmap()`` and ``mremap()`` system calls.57 58 - The ``range.start``, ``start`` and ``dst`` arguments to the59 ``UFFDIO_*`` ``ioctl()``s used on a file descriptor obtained from60 ``userfaultfd()``, as fault addresses subsequently obtained by reading61 the file descriptor will be untagged, which may otherwise confuse62 tag-unaware programs.63 64 NOTE: This behaviour changed in v5.14 and so some earlier kernels may65 incorrectly accept valid tagged pointers for this system call.66 672. User addresses accessed by the kernel (e.g. ``write()``). This ABI68 relaxation is disabled by default and the application thread needs to69 explicitly enable it via ``prctl()`` as follows:70 71 - ``PR_SET_TAGGED_ADDR_CTRL``: enable or disable the AArch64 Tagged72 Address ABI for the calling thread.73 74 The ``(unsigned int) arg2`` argument is a bit mask describing the75 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 Tagged83 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 on88 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 globally92 disabled by ``sysctl abi.tagged_addr_disabled=1``. The default93 ``sysctl abi.tagged_addr_disabled`` configuration is 0.94 95When the AArch64 Tagged Address ABI is enabled for a thread, the96following behaviours are guaranteed:97 98- All syscalls except the cases mentioned in section 3 can accept any99 valid tagged pointer.100 101- The syscall behaviour is undefined for invalid tagged pointers: it may102 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 for106 the corresponding untagged pointer.107 108 109A definition of the meaning of tagged pointers on AArch64 can be found110in Documentation/arch/arm64/tagged-pointers.rst.111 1123. AArch64 Tagged Address ABI Exceptions113-----------------------------------------114 115The following system call parameters must be untagged regardless of the116ABI relaxation:117 118- ``prctl()`` other than pointers to user data either passed directly or119 indirectly as arguments to be accessed by the kernel.120 121- ``ioctl()`` other than pointers to user data either passed directly or122 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 code133being returned, a (fatal) signal being raised, or other modes of134failure.135 1364. Example of correct usage137---------------------------138.. code-block:: c139 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 55147 #define PR_TAGGED_ADDR_ENABLE (1UL << 0)148 149 #define TAG_SHIFT 56150 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 }180