Documentation/arch/arm64/tagged-address-abi.rst

Source file repositories/reference/linux-study-clean/Documentation/arch/arm64/tagged-address-abi.rst

File Facts

System
Linux kernel
Corpus path
Documentation/arch/arm64/tagged-address-abi.rst
Extension
.rst
Size
6173 bytes
Lines
180
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

==========================
AArch64 TAGGED ADDRESS ABI
==========================

Authors: Vincenzo Frascino <vincenzo.frascino@arm.com>
         Catalin Marinas <catalin.marinas@arm.com>

Date: 21 August 2019

This document describes the usage and semantics of the Tagged Address
ABI on AArch64 Linux.

1. Introduction
---------------

On AArch64 the ``TCR_EL1.TBI0`` bit is set by default, allowing
userspace (EL0) to perform memory accesses through 64-bit pointers with
a non-zero top byte. This document describes the relaxation of the
syscall ABI that allows userspace to pass certain tagged pointers to
kernel syscalls.

2. AArch64 Tagged Address ABI
-----------------------------

From the kernel syscall interface perspective and for the purposes of
this document, a "valid tagged pointer" is a pointer with a potentially
non-zero top-byte that references an address in the user process address
space obtained in one of the following ways:

- ``mmap()`` syscall where either:

  - flags have the ``MAP_ANONYMOUS`` bit set or
  - the file descriptor refers to a regular file (including those
    returned by ``memfd_create()``) or ``/dev/zero``

- ``brk()`` syscall (i.e. the heap area between the initial location of
  the program break at process creation and its current location).

- any memory mapped by the kernel in the address space of the process
  during creation and with the same restrictions as for ``mmap()`` above
  (e.g. data, bss, stack).

The AArch64 Tagged Address ABI has two stages of relaxation depending on
how the user addresses are used by the kernel:

1. User addresses not accessed by the kernel but used for address space
   management (e.g. ``mprotect()``, ``madvise()``). The use of valid
   tagged pointers in this context is allowed with these exceptions:

   - ``brk()``, ``mmap()`` and the ``new_address`` argument to
     ``mremap()`` as these have the potential to alias with existing
     user addresses.

     NOTE: This behaviour changed in v5.6 and so some earlier kernels may
     incorrectly accept valid tagged pointers for the ``brk()``,
     ``mmap()`` and ``mremap()`` system calls.

   - The ``range.start``, ``start`` and ``dst`` arguments to the
     ``UFFDIO_*`` ``ioctl()``s used on a file descriptor obtained from
     ``userfaultfd()``, as fault addresses subsequently obtained by reading
     the file descriptor will be untagged, which may otherwise confuse
     tag-unaware programs.

     NOTE: This behaviour changed in v5.14 and so some earlier kernels may
     incorrectly accept valid tagged pointers for this system call.

2. User addresses accessed by the kernel (e.g. ``write()``). This ABI
   relaxation is disabled by default and the application thread needs to
   explicitly enable it via ``prctl()`` as follows:

Annotation

Implementation Notes