OSCL-LXR linux-6.0.1/​Documentation/​arm64/​memory-tagging-extension.rst	Source navigation Diff markup Identifier search General search
	Version: linux-6.0.1 spark-3.0.0 hadoop-3.2.0-src hadoop-3.3.0-src spark-2.4.7 linux-4.15.13 hadoop-2.7.4-src Revert   Change

 ===============================================
 Memory Tagging Extension (MTE) in AArch64 Linux
 ===============================================
 
 Authors: Vincenzo Frascino <vincenzo.frascino@arm.com>
          Catalin Marinas <catalin.marinas@arm.com>
 
 Date: 2020-02-25
 
 This document describes the provision of the Memory Tagging Extension
 functionality in AArch64 Linux.
 
 Introduction
 ============
 
 ARMv8.5 based processors introduce the Memory Tagging Extension (MTE)
 feature. MTE is built on top of the ARMv8.0 virtual address tagging TBI
 (Top Byte Ignore) feature and allows software to access a 4-bit
 allocation tag for each 16-byte granule in the physical address space.
 Such memory range must be mapped with the Normal-Tagged memory
 attribute. A logical tag is derived from bits 59-56 of the virtual
 address used for the memory access. A CPU with MTE enabled will compare
 the logical tag against the allocation tag and potentially raise an
 exception on mismatch, subject to system registers configuration.
 
 Userspace Support
 =================
 
 When ``CONFIG_ARM64_MTE`` is selected and Memory Tagging Extension is
 supported by the hardware, the kernel advertises the feature to
 userspace via ``HWCAP2_MTE``.
 
 PROT_MTE
 --------
 
 To access the allocation tags, a user process must enable the Tagged
 memory attribute on an address range using a new ``prot`` flag for
 ``mmap()`` and ``mprotect()``:
 
 ``PROT_MTE`` - Pages allow access to the MTE allocation tags.
 
 The allocation tag is set to 0 when such pages are first mapped in the
 user address space and preserved on copy-on-write. ``MAP_SHARED`` is
 supported and the allocation tags can be shared between processes.
 
 **Note**: ``PROT_MTE`` is only supported on ``MAP_ANONYMOUS`` and
 RAM-based file mappings (``tmpfs``, ``memfd``). Passing it to other
 types of mapping will result in ``-EINVAL`` returned by these system
 calls.
 
 **Note**: The ``PROT_MTE`` flag (and corresponding memory type) cannot
 be cleared by ``mprotect()``.
 
 **Note**: ``madvise()`` memory ranges with ``MADV_DONTNEED`` and
 ``MADV_FREE`` may have the allocation tags cleared (set to 0) at any
 point after the system call.
 
 Tag Check Faults
 ----------------
 
 When ``PROT_MTE`` is enabled on an address range and a mismatch between
 the logical and allocation tags occurs on access, there are three
 configurable behaviours:
 
 - *Ignore* - This is the default mode. The CPU (and kernel) ignores the
   tag check fault.
 
 - *Synchronous* - The kernel raises a ``SIGSEGV`` synchronously, with
   ``.si_code = SEGV_MTESERR`` and ``.si_addr = <fault-address>``. The
   memory access is not performed. If ``SIGSEGV`` is ignored or blocked
   by the offending thread, the containing process is terminated with a
   ``coredump``.
 
 - *Asynchronous* - The kernel raises a ``SIGSEGV``, in the offending
   thread, asynchronously following one or multiple tag check faults,
   with ``.si_code = SEGV_MTEAERR`` and ``.si_addr = 0`` (the faulting
   address is unknown).
 
 - *Asymmetric* - Reads are handled as for synchronous mode while writes
   are handled as for asynchronous mode.
 
 The user can select the above modes, per thread, using the
 ``prctl(PR_SET_TAGGED_ADDR_CTRL, flags, 0, 0, 0)`` system call where ``flags``
 contains any number of the following values in the ``PR_MTE_TCF_MASK``
 bit-field:
 
 - ``PR_MTE_TCF_NONE``  - *Ignore* tag check faults
                          (ignored if combined with other options)
 - ``PR_MTE_TCF_SYNC``  - *Synchronous* tag check fault mode
 - ``PR_MTE_TCF_ASYNC`` - *Asynchronous* tag check fault mode
 
 If no modes are specified, tag check faults are ignored. If a single
 mode is specified, the program will run in that mode. If multiple
 modes are specified, the mode is selected as described in the "Per-CPU
 preferred tag checking modes" section below.
 
 The current tag check fault configuration can be read using the
 ``prctl(PR_GET_TAGGED_ADDR_CTRL, 0, 0, 0, 0)`` system call. If
 multiple modes were requested then all will be reported.
 
 Tag checking can also be disabled for a user thread by setting the
 ``PSTATE.TCO`` bit with ``MSR TCO, #1``.
 
 **Note**: Signal handlers are always invoked with ``PSTATE.TCO = 0``,
 irrespective of the interrupted context. ``PSTATE.TCO`` is restored on
 ``sigreturn()``.
 
 **Note**: There are no *match-all* logical tags available for user
 applications.
 
 **Note**: Kernel accesses to the user address space (e.g. ``read()``
 system call) are not checked if the user thread tag checking mode is
 ``PR_MTE_TCF_NONE`` or ``PR_MTE_TCF_ASYNC``. If the tag checking mode is
 ``PR_MTE_TCF_SYNC``, the kernel makes a best effort to check its user
 address accesses, however it cannot always guarantee it. Kernel accesses
 to user addresses are always performed with an effective ``PSTATE.TCO``
 value of zero, regardless of the user configuration.
 
 Excluding Tags in the ``IRG``, ``ADDG`` and ``SUBG`` instructions
 -----------------------------------------------------------------
 
 The architecture allows excluding certain tags to be randomly generated
 via the ``GCR_EL1.Exclude`` register bit-field. By default, Linux
 excludes all tags other than 0. A user thread can enable specific tags
 in the randomly generated set using the ``prctl(PR_SET_TAGGED_ADDR_CTRL,
 flags, 0, 0, 0)`` system call where ``flags`` contains the tags bitmap
 in the ``PR_MTE_TAG_MASK`` bit-field.
 
 **Note**: The hardware uses an exclude mask but the ``prctl()``
 interface provides an include mask. An include mask of ``0`` (exclusion
 mask ``0xffff``) results in the CPU always generating tag ``0``.
 
 Per-CPU preferred tag checking mode
 -----------------------------------
 
 On some CPUs the performance of MTE in stricter tag checking modes
 is similar to that of less strict tag checking modes. This makes it
 worthwhile to enable stricter checks on those CPUs when a less strict
 checking mode is requested, in order to gain the error detection
 benefits of the stricter checks without the performance downsides. To
 support this scenario, a privileged user may configure a stricter
 tag checking mode as the CPU's preferred tag checking mode.
 
 The preferred tag checking mode for each CPU is controlled by
 ``/sys/devices/system/cpu/cpu<N>/mte_tcf_preferred``, to which a
 privileged user may write the value ``async``, ``sync`` or ``asymm``.  The
 default preferred mode for each CPU is ``async``.
 
 To allow a program to potentially run in the CPU's preferred tag
 checking mode, the user program may set multiple tag check fault mode
 bits in the ``flags`` argument to the ``prctl(PR_SET_TAGGED_ADDR_CTRL,
 flags, 0, 0, 0)`` system call. If both synchronous and asynchronous
 modes are requested then asymmetric mode may also be selected by the
 kernel. If the CPU's preferred tag checking mode is in the task's set
 of provided tag checking modes, that mode will be selected. Otherwise,
 one of the modes in the task's mode will be selected by the kernel
 from the task's mode set using the preference order:
 
         1. Asynchronous
         2. Asymmetric
         3. Synchronous
 
 Note that there is no way for userspace to request multiple modes and
 also disable asymmetric mode.
 
 Initial process state
 ---------------------
 
 On ``execve()``, the new process has the following configuration:
 
 - ``PR_TAGGED_ADDR_ENABLE`` set to 0 (disabled)
 - No tag checking modes are selected (tag check faults ignored)
 - ``PR_MTE_TAG_MASK`` set to 0 (all tags excluded)
 - ``PSTATE.TCO`` set to 0
 - ``PROT_MTE`` not set on any of the initial memory maps
 
 On ``fork()``, the new process inherits the parent's configuration and
 memory map attributes with the exception of the ``madvise()`` ranges
 with ``MADV_WIPEONFORK`` which will have the data and tags cleared (set
 to 0).
 
 The ``ptrace()`` interface
 --------------------------
 
 ``PTRACE_PEEKMTETAGS`` and ``PTRACE_POKEMTETAGS`` allow a tracer to read
 the tags from or set the tags to a tracee's address space. The
 ``ptrace()`` system call is invoked as ``ptrace(request, pid, addr,
 data)`` where:
 
 - ``request`` - one of ``PTRACE_PEEKMTETAGS`` or ``PTRACE_POKEMTETAGS``.
 - ``pid`` - the tracee's PID.
 - ``addr`` - address in the tracee's address space.
 - ``data`` - pointer to a ``struct iovec`` where ``iov_base`` points to
   a buffer of ``iov_len`` length in the tracer's address space.
 
 The tags in the tracer's ``iov_base`` buffer are represented as one
 4-bit tag per byte and correspond to a 16-byte MTE tag granule in the
 tracee's address space.
 
 **Note**: If ``addr`` is not aligned to a 16-byte granule, the kernel
 will use the corresponding aligned address.
 
 ``ptrace()`` return value:
 
 - 0 - tags were copied, the tracer's ``iov_len`` was updated to the
   number of tags transferred. This may be smaller than the requested
   ``iov_len`` if the requested address range in the tracee's or the
   tracer's space cannot be accessed or does not have valid tags.
 - ``-EPERM`` - the specified process cannot be traced.
 - ``-EIO`` - the tracee's address range cannot be accessed (e.g. invalid
   address) and no tags copied. ``iov_len`` not updated.
 - ``-EFAULT`` - fault on accessing the tracer's memory (``struct iovec``
   or ``iov_base`` buffer) and no tags copied. ``iov_len`` not updated.
 - ``-EOPNOTSUPP`` - the tracee's address does not have valid tags (never
   mapped with the ``PROT_MTE`` flag). ``iov_len`` not updated.
 
 **Note**: There are no transient errors for the requests above, so user
 programs should not retry in case of a non-zero system call return.
 
 ``PTRACE_GETREGSET`` and ``PTRACE_SETREGSET`` with ``addr ==
 ``NT_ARM_TAGGED_ADDR_CTRL`` allow ``ptrace()`` access to the tagged
 address ABI control and MTE configuration of a process as per the
 ``prctl()`` options described in
 Documentation/arm64/tagged-address-abi.rst and above. The corresponding
 ``regset`` is 1 element of 8 bytes (``sizeof(long))``).
 
 Core dump support
 -----------------
 
 The allocation tags for user memory mapped with ``PROT_MTE`` are dumped
 in the core file as additional ``PT_AARCH64_MEMTAG_MTE`` segments. The
 program header for such segment is defined as:
 
 :``p_type``: ``PT_AARCH64_MEMTAG_MTE``
 :``p_flags``: 0
 :``p_offset``: segment file offset
 :``p_vaddr``: segment virtual address, same as the corresponding
   ``PT_LOAD`` segment
 :``p_paddr``: 0
 :``p_filesz``: segment size in file, calculated as ``p_mem_sz / 32``
   (two 4-bit tags cover 32 bytes of memory)
 :``p_memsz``: segment size in memory, same as the corresponding
   ``PT_LOAD`` segment
 :``p_align``: 0
 
 The tags are stored in the core file at ``p_offset`` as two 4-bit tags
 in a byte. With the tag granule of 16 bytes, a 4K page requires 128
 bytes in the core file.
 
 Example of correct usage
 ========================
 
 *MTE Example code*
 
 .. code-block:: c
 
     /*
      * To be compiled with -march=armv8.5-a+memtag
      */
     #include <errno.h>
     #include <stdint.h>
     #include <stdio.h>
     #include <stdlib.h>
     #include <unistd.h>
     #include <sys/auxv.h>
     #include <sys/mman.h>
     #include <sys/prctl.h>
 
     /*
      * From arch/arm64/include/uapi/asm/hwcap.h
      */
     #define HWCAP2_MTE              (1 << 18)
 
     /*
      * From arch/arm64/include/uapi/asm/mman.h
      */
     #define PROT_MTE                 0x20
 
     /*
      * From include/uapi/linux/prctl.h
      */
     #define PR_SET_TAGGED_ADDR_CTRL 55
     #define PR_GET_TAGGED_ADDR_CTRL 56
     # define PR_TAGGED_ADDR_ENABLE  (1UL << 0)
     # define PR_MTE_TCF_SHIFT       1
     # define PR_MTE_TCF_NONE        (0UL << PR_MTE_TCF_SHIFT)
     # define PR_MTE_TCF_SYNC        (1UL << PR_MTE_TCF_SHIFT)
     # define PR_MTE_TCF_ASYNC       (2UL << PR_MTE_TCF_SHIFT)
     # define PR_MTE_TCF_MASK        (3UL << PR_MTE_TCF_SHIFT)
     # define PR_MTE_TAG_SHIFT       3
     # define PR_MTE_TAG_MASK        (0xffffUL << PR_MTE_TAG_SHIFT)
 
     /*
      * Insert a random logical tag into the given pointer.
      */
     #define insert_random_tag(ptr) ({                       \
             uint64_t __val;                                 \
             asm("irg %0, %1" : "=r" (__val) : "r" (ptr));   \
             __val;                                          \
     })
 
     /*
      * Set the allocation tag on the destination address.
      */
     #define set_tag(tagged_addr) do {                                      \
             asm volatile("stg %0, [%0]" : : "r" (tagged_addr) : "memory"); \
     } while (0)
 
     int main()
     {
             unsigned char *a;
             unsigned long page_sz = sysconf(_SC_PAGESIZE);
             unsigned long hwcap2 = getauxval(AT_HWCAP2);
 
             /* check if MTE is present */
             if (!(hwcap2 & HWCAP2_MTE))
                     return EXIT_FAILURE;
 
             /*
              * Enable the tagged address ABI, synchronous or asynchronous MTE
              * tag check faults (based on per-CPU preference) and allow all
              * non-zero tags in the randomly generated set.
              */
             if (prctl(PR_SET_TAGGED_ADDR_CTRL,
                       PR_TAGGED_ADDR_ENABLE | PR_MTE_TCF_SYNC | PR_MTE_TCF_ASYNC |
                       (0xfffe << PR_MTE_TAG_SHIFT),
                       0, 0, 0)) {
                     perror("prctl() failed");
                     return EXIT_FAILURE;
             }
 
             a = mmap(0, page_sz, PROT_READ | PROT_WRITE,
                      MAP_PRIVATE | MAP_ANONYMOUS, -1, 0);
             if (a == MAP_FAILED) {
                     perror("mmap() failed");
                     return EXIT_FAILURE;
             }
 
             /*
              * Enable MTE on the above anonymous mmap. The flag could be passed
              * directly to mmap() and skip this step.
              */
             if (mprotect(a, page_sz, PROT_READ | PROT_WRITE | PROT_MTE)) {
                     perror("mprotect() failed");
                     return EXIT_FAILURE;
             }
 
             /* access with the default tag (0) */
             a[0] = 1;
             a[1] = 2;
 
             printf("a[0] = %hhu a[1] = %hhu\n", a[0], a[1]);
 
             /* set the logical and allocation tags */
             a = (unsigned char *)insert_random_tag(a);
             set_tag(a);
 
             printf("%p\n", a);
 
             /* non-zero tag access */
             a[0] = 3;
             printf("a[0] = %hhu a[1] = %hhu\n", a[0], a[1]);
 
             /*
              * If MTE is enabled correctly the next instruction will generate an
              * exception.
              */
             printf("Expecting SIGSEGV...\n");
             a[16] = 0xdd;
 
             /* this should not be printed in the PR_MTE_TCF_SYNC mode */
             printf("...haven't got one\n");
 
             return EXIT_FAILURE;
     }

This page was automatically generated by the 2.1.0 LXR engine. The LXR team