[v3,23/23] doc: Add plain text readme for using GCS

Message ID 20241023083920.466015-24-yury.khrustalev@arm.com
State Under Review
Delegated to: Wilco Dijkstra
Headers
Series aarch64: Add support for Guarded Control Stack extension |

Checks

Context Check Description
redhat-pt-bot/TryBot-apply_patch success Patch applied to master at the time it was sent
linaro-tcwg-bot/tcwg_glibc_build--master-aarch64 success Build passed
redhat-pt-bot/TryBot-32bit success Build for i686
linaro-tcwg-bot/tcwg_glibc_check--master-aarch64 success Test passed
linaro-tcwg-bot/tcwg_glibc_build--master-arm success Build passed
linaro-tcwg-bot/tcwg_glibc_check--master-arm success Test passed

Commit Message

Yury Khrustalev Oct. 23, 2024, 8:39 a.m. UTC
  From: Szabolcs Nagy <szabolcs.nagy@arm.com>

TODO: this is just for the arm/gcs branch while it is being developed
---
 README | 68 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 68 insertions(+)
  

Patch

diff --git a/README b/README
index 2e360eb70a..24a8ac4adf 100644
--- a/README
+++ b/README
@@ -1,3 +1,71 @@ 
+this branch contains experimental GCS support (not ABI stable)
+
+source and branches
+-------------------
+
+binutils-gdb: upstream-git users/ARM/gcs-binutils-gdb-master
+gcc (trunk): upstream-git vendors/ARM/gcs
+	note: gcc vendor branches need setup https://gcc.gnu.org/gitwrite.html#vendor
+glibc: upstream-git arm/gcs
+linux: https://git.kernel.org/pub/scm/linux/kernel/git/arm64/linux.git for-next/gcs
+fvp fast model can be used for testing
+
+toolchain build
+---------------
+
+two options:
+
+(1) branch-protect by default
+  configure gcc with --enable-standard-branch-protection
+  and build glibc normally
+
+(2) do not branch-protect by default, require explicit cflags
+  configure gcc with
+    CFLAGS_FOR_TARGET='-O2 -mbranch-protection=standard'
+    CXXFLAGS_FOR_TARGET='-O2 -mbranch-protection=standard'
+  and configure glibc with
+    CFLAGS='-g -O2 -mbranch-protection=standard'
+  build user code with
+    CFLAGS+=-mbranch-protection=standard
+    (equivalent to -mbranch-protection=bti+pac+gcs)
+
+linking
+-------
+
+use ldflags:
+
+-z gcs={always,never,implicit}
+  always: force GCS marking on
+  never: force GCS marking off
+  implicit: mark output if all inputs are marked (default)
+
+-z gcs-report={none,warning,error}
+  none: silent (default)
+  warning: when output is marked, unmarked input is a warning
+  error: when output is marked, unmarked input is an error
+
+runtime
+-------
+
+run with environment var
+
+  GLIBC_TUNABLES=glibc.cpu.aarch64_gcs=1:glibc.cpu.aarch64_gcs_policy=2
+
+by default both tunables are 0, the meaning is
+
+glibc.cpu.aarch64_gcs_policy=0:
+  GCS is enabled if glibc.cpu.aarch64_gcs is set
+glibc.cpu.aarch64_gcs_policy=1:
+  GCS is enabled if glibc.cpu.aarch64_gcs is set and binary is marked
+  if GCS is enabled an incompatible dlopen is an error
+glibc.cpu.aarch64_gcs_policy=2:
+  GCS is enabled if glibc.cpu.aarch64_gcs is set
+  if GCS is enabled any incompatible binary is an error
+
+
+original readme
+---------------
+
 This directory contains the sources of the GNU C Library.
 See the file "version.h" for what release version you have.