Documentation/arch/arm64/gcs.rst

Source file repositories/reference/linux-study-clean/Documentation/arch/arm64/gcs.rst

File Facts

System
Linux kernel
Corpus path
Documentation/arch/arm64/gcs.rst
Extension
.rst
Size
9026 bytes
Lines
228
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

===============================================
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_HWCAP 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}.

Annotation

Implementation Notes