Merge branches 'for-next/gcs', 'for-next/probes', 'for-next/asm-offsets',...

	arm64.nobti	[ARM64] Unconditionally disable Branch Target

			Identification support

	arm64.nogcs	[ARM64] Unconditionally disable Guarded Control Stack

			support

	arm64.nomops	[ARM64] Unconditionally disable Memory Copy and Memory

			Set instructions support

.. SPDX-License-Identifier: GPL-2.0

=====================================

Arm Confidential Compute Architecture

=====================================

Arm systems that support the Realm Management Extension (RME) contain

hardware to allow a VM guest to be run in a way which protects the code

and data of the guest from the hypervisor. It extends the older "two

world" model (Normal and Secure World) into four worlds: Normal, Secure,

Root and Realm. Linux can then also be run as a guest to a monitor

running in the Realm world.

The monitor running in the Realm world is known as the Realm Management

Monitor (RMM) and implements the Realm Management Monitor

specification[1]. The monitor acts a bit like a hypervisor (e.g. it runs

in EL2 and manages the stage 2 page tables etc of the guests running in

Realm world), however much of the control is handled by a hypervisor

running in the Normal World. The Normal World hypervisor uses the Realm

Management Interface (RMI) defined by the RMM specification to request

the RMM to perform operations (e.g. mapping memory or executing a vCPU).

The RMM defines an environment for guests where the address space (IPA)

is split into two. The lower half is protected - any memory that is

mapped in this half cannot be seen by the Normal World and the RMM

restricts what operations the Normal World can perform on this memory

(e.g. the Normal World cannot replace pages in this region without the

guest's cooperation). The upper half is shared, the Normal World is free

to make changes to the pages in this region, and is able to emulate MMIO

devices in this region too.

A guest running in a Realm may also communicate with the RMM using the

Realm Services Interface (RSI) to request changes in its environment or

to perform attestation about its environment. In particular it may

request that areas of the protected address space are transitioned

between 'RAM' and 'EMPTY' (in either direction). This allows a Realm

guest to give up memory to be returned to the Normal World, or to

request new memory from the Normal World.  Without an explicit request

from the Realm guest the RMM will otherwise prevent the Normal World

from making these changes.

Linux as a Realm Guest

----------------------

To run Linux as a guest within a Realm, the following must be provided

either by the VMM or by a `boot loader` run in the Realm before Linux:

 * All protected RAM described to Linux (by DT or ACPI) must be marked

   RIPAS RAM before handing control over to Linux.

 * MMIO devices must be either unprotected (e.g. emulated by the Normal

   World) or marked RIPAS DEV.

 * MMIO devices emulated by the Normal World and used very early in boot

   (specifically earlycon) must be specified in the upper half of IPA.

   For earlycon this can be done by specifying the address on the

   command line, e.g. with an IPA size of 33 bits and the base address

   of the emulated UART at 0x1000000: ``earlycon=uart,mmio,0x101000000``

 * Linux will use bounce buffers for communicating with unprotected

   devices. It will transition some protected memory to RIPAS EMPTY and

   expect to be able to access unprotected pages at the same IPA address

   but with the highest valid IPA bit set. The expectation is that the

   VMM will remove the physical pages from the protected mapping and

   provide those pages as unprotected pages.

References

----------

[1] https://developer.arm.com/documentation/den0137/

the RAM in the machine, or any other method the boot loader designer

sees fit.)

For Arm Confidential Compute Realms this includes ensuring that all

protected RAM has a Realm IPA state (RIPAS) of "RAM".

2. Setup the device tree

-------------------------

    - HFGRWR_EL2.nPIRE0_EL1 (bit 57) must be initialised to 0b1.

 - For CPUs with Guarded Control Stacks (FEAT_GCS):

  - GCSCR_EL1 must be initialised to 0.

  - GCSCRE0_EL1 must be initialised to 0.

  - If EL3 is present:

    - SCR_EL3.GCSEn (bit 39) must be initialised to 0b1.

  - If EL2 is present:

    - GCSCR_EL2 must be initialised to 0.

 - If the kernel is entered at EL1 and EL2 is present:

    - HCRX_EL2.GCSEn must be initialised to 0b1.

    - HFGITR_EL2.nGCSEPP (bit 59) must be initialised to 0b1.

    - HFGITR_EL2.nGCSSTR_EL1 (bit 58) must be initialised to 0b1.

    - HFGITR_EL2.nGCSPUSHM_EL1 (bit 57) must be initialised to 0b1.

    - HFGRTR_EL2.nGCS_EL1 (bit 53) must be initialised to 0b1.

    - HFGRTR_EL2.nGCS_EL0 (bit 52) must be initialised to 0b1.

    - HFGWTR_EL2.nGCS_EL1 (bit 53) must be initialised to 0b1.

    - HFGWTR_EL2.nGCS_EL0 (bit 52) must be initialised to 0b1.

The requirements described above for CPU mode, caches, MMUs, architected

timers, coherency and system registers apply to all CPUs.  All CPUs must

enter the kernel in the same exception level.  Where the values documented

kernel exposes the presence of these features to userspace through a set

of flags called hwcaps, exposed in the auxiliary vector.

Userspace software can test for features by acquiring the AT_HWCAP or

AT_HWCAP2 entry of the auxiliary vector, and testing whether the relevant

flags are set, e.g.::

Userspace software can test for features by acquiring the AT_HWCAP,

AT_HWCAP2 or AT_HWCAP3 entry of the auxiliary vector, and testing

whether the relevant flags are set, e.g.::

	bool floating_point_is_present(void)

	{

    ID_AA64ISAR1_EL1.GPI == 0b0001, as described by

    Documentation/arch/arm64/pointer-authentication.rst.

HWCAP_GCS

    Functionality implied by ID_AA64PFR1_EL1.GCS == 0b1, as

    described by Documentation/arch/arm64/gcs.rst.

HWCAP2_DCPODP

    Functionality implied by ID_AA64ISAR1_EL1.DPB == 0b0010.

===============================================

Guarded Control Stack support for AArch64 Linux

===============================================

This document outlines briefly the interface provided to userspace by Linux in

order to support use of the ARM Guarded Control Stack (GCS) feature.

This is an outline of the most important features and issues only and not

intended to be exhaustive.

1.  General

-----------

* GCS is an architecture feature intended to provide greater protection

  against return oriented programming (ROP) attacks and to simplify the

  implementation of features that need to collect stack traces such as

  profiling.

* When GCS is enabled a separate guarded control stack is maintained by the

  PE which is writeable only through specific GCS operations.  This

  stores the call stack only, when a procedure call instruction is

  performed the current PC is pushed onto the GCS and on RET the

  address in the LR is verified against that on the top of the GCS.

* When active the current GCS pointer is stored in the system register

  GCSPR_EL0.  This is readable by userspace but can only be updated

  via specific GCS instructions.

* The architecture provides instructions for switching between guarded

  control stacks with checks to ensure that the new stack is a valid

  target for switching.

* The functionality of GCS is similar to that provided by the x86 Shadow

  Stack feature, due to sharing of userspace interfaces the ABI refers to

  shadow stacks rather than GCS.

* Support for GCS is reported to userspace via HWCAP_GCS in the aux vector

  AT_HWCAP2 entry.

* GCS is enabled per thread.  While there is support for disabling GCS

  at runtime this should be done with great care.

* GCS memory access faults are reported as normal memory access faults.

* GCS specific errors (those reported with EC 0x2d) will be reported as

  SIGSEGV with a si_code of SEGV_CPERR (control protection error).

* GCS is supported only for AArch64.

* On systems where GCS is supported GCSPR_EL0 is always readable by EL0

  regardless of the GCS configuration for the thread.

* The architecture supports enabling GCS without verifying that return values

  in LR match those in the GCS, the LR will be ignored.  This is not supported

  by Linux.

2.  Enabling and disabling Guarded Control Stacks

-------------------------------------------------

* GCS is enabled and disabled for a thread via the PR_SET_SHADOW_STACK_STATUS

  prctl(), this takes a single flags argument specifying which GCS features

  should be used.

* When set PR_SHADOW_STACK_ENABLE flag allocates a Guarded Control Stack

  and enables GCS for the thread, enabling the functionality controlled by

  GCSCRE0_EL1.{nTR, RVCHKEN, PCRSEL}.

* When set the PR_SHADOW_STACK_PUSH flag enables the functionality controlled

  by GCSCRE0_EL1.PUSHMEn, allowing explicit GCS pushes.

* When set the PR_SHADOW_STACK_WRITE flag enables the functionality controlled

  by GCSCRE0_EL1.STREn, allowing explicit stores to the Guarded Control Stack.

* Any unknown flags will cause PR_SET_SHADOW_STACK_STATUS to return -EINVAL.

* PR_LOCK_SHADOW_STACK_STATUS is passed a bitmask of features with the same

  values as used for PR_SET_SHADOW_STACK_STATUS.  Any future changes to the

  status of the specified GCS mode bits will be rejected.

* PR_LOCK_SHADOW_STACK_STATUS allows any bit to be locked, this allows

  userspace to prevent changes to any future features.

* There is no support for a process to remove a lock that has been set for

  it.

* PR_SET_SHADOW_STACK_STATUS and PR_LOCK_SHADOW_STACK_STATUS affect only the

  thread that called them, any other running threads will be unaffected.

* New threads inherit the GCS configuration of the thread that created them.

* GCS is disabled on exec().

* The current GCS configuration for a thread may be read with the

  PR_GET_SHADOW_STACK_STATUS prctl(), this returns the same flags that

  are passed to PR_SET_SHADOW_STACK_STATUS.

* If GCS is disabled for a thread after having previously been enabled then

  the stack will remain allocated for the lifetime of the thread.  At present

  any attempt to reenable GCS for the thread will be rejected, this may be

  revisited in future.

* It should be noted that since enabling GCS will result in GCS becoming

  active immediately it is not normally possible to return from the function

  that invoked the prctl() that enabled GCS.  It is expected that the normal

  usage will be that GCS is enabled very early in execution of a program.

3.  Allocation of Guarded Control Stacks

----------------------------------------

* When GCS is enabled for a thread a new Guarded Control Stack will be

  allocated for it of half the standard stack size or 2 gigabytes,

  whichever is smaller.

* When a new thread is created by a thread which has GCS enabled then a

  new Guarded Control Stack will be allocated for the new thread with

  half the size of the standard stack.

* When a stack is allocated by enabling GCS or during thread creation then

  the top 8 bytes of the stack will be initialised to 0 and GCSPR_EL0 will

  be set to point to the address of this 0 value, this can be used to

  detect the top of the stack.

* Additional Guarded Control Stacks can be allocated using the

  map_shadow_stack() system call.

* Stacks allocated using map_shadow_stack() can optionally have an end of

  stack marker and cap placed at the top of the stack.  If the flag

  SHADOW_STACK_SET_TOKEN is specified a cap will be placed on the stack,

  if SHADOW_STACK_SET_MARKER is not specified the cap will be the top 8

  bytes of the stack and if it is specified then the cap will be the next

  8 bytes.  While specifying just SHADOW_STACK_SET_MARKER by itself is

  valid since the marker is all bits 0 it has no observable effect.

* Stacks allocated using map_shadow_stack() must have a size which is a

  multiple of 8 bytes larger than 8 bytes and must be 8 bytes aligned.

* An address can be specified to map_shadow_stack(), if one is provided then

  it must be aligned to a page boundary.

* When a thread is freed the Guarded Control Stack initially allocated for

  that thread will be freed.  Note carefully that if the stack has been

  switched this may not be the stack currently in use by the thread.

4.  Signal handling

--------------------

* A new signal frame record gcs_context encodes the current GCS mode and

  pointer for the interrupted context on signal delivery.  This will always

  be present on systems that support GCS.

* The record contains a flag field which reports the current GCS configuration

  for the interrupted context as PR_GET_SHADOW_STACK_STATUS would.

* The signal handler is run with the same GCS configuration as the interrupted

  context.

* When GCS is enabled for the interrupted thread a signal handling specific

  GCS cap token will be written to the GCS, this is an architectural GCS cap

  with the token type (bits 0..11) all clear.  The GCSPR_EL0 reported in the

  signal frame will point to this cap token.

* The signal handler will use the same GCS as the interrupted context.

* When GCS is enabled on signal entry a frame with the address of the signal

  return handler will be pushed onto the GCS, allowing return from the signal

  handler via RET as normal.  This will not be reported in the gcs_context in

  the signal frame.

5.  Signal return

-----------------

When returning from a signal handler:

* If there is a gcs_context record in the signal frame then the GCS flags

  and GCSPR_EL0 will be restored from that context prior to further

  validation.

* If there is no gcs_context record in the signal frame then the GCS

  configuration will be unchanged.

* If GCS is enabled on return from a signal handler then GCSPR_EL0 must

  point to a valid GCS signal cap record, this will be popped from the

  GCS prior to signal return.

* If the GCS configuration is locked when returning from a signal then any

  attempt to change the GCS configuration will be treated as an error.  This

  is true even if GCS was not enabled prior to signal entry.

* GCS may be disabled via signal return but any attempt to enable GCS via

  signal return will be rejected.

6.  ptrace extensions

---------------------

* A new regset NT_ARM_GCS is defined for use with PTRACE_GETREGSET and

  PTRACE_SETREGSET.

* The GCS mode, including enable and disable, may be configured via ptrace.

  If GCS is enabled via ptrace no new GCS will be allocated for the thread.

* Configuration via ptrace ignores locking of GCS mode bits.

7.  ELF coredump extensions

---------------------------

* NT_ARM_GCS notes will be added to each coredump for each thread of the

  dumped process.  The contents will be equivalent to the data that would

  have been read if a PTRACE_GETREGSET of the corresponding type were

  executed for each thread when the coredump was generated.

8.  /proc extensions

--------------------

* Guarded Control Stack pages will include "ss" in their VmFlags in

  /proc/<pid>/smaps.