[lld] [LLD][Docs] Document -z gcs= option in the man page (PR #146522)

[via llvm-commits]

https://github.com/sivan-shani created https://github.com/llvm/llvm-project/pull/146522

Add documentation for the -z gcs= option to the LLD man page. This flag controls how the GCS bit is set in the output:

    implicit (default): inferred from input objects
    never: GCS bit is never set
    always: GCS bit is always set

Clarifies behavior for users and aligns the man page with existing functionality.


>From cce8b24fc4fab4e4614e0f641180cf7b9146e499 Mon Sep 17 00:00:00 2001
From: Sivan Shani <sivan.shani at arm.com>
Date: Tue, 1 Jul 2025 11:35:50 +0100
Subject: [PATCH 1/2] [LLD][Docs] Document `-z gcs` option in the man page

Add documentation for the `-z gcs` option to the LLD man page. This flag controls how the GCS bit is set in the output:

- implicit (default): inferred from input objects
- never: GCS bit is never set
- always: GCS bit is always set

Clarifies behavior for users and aligns the man page with existing functionality.
---
 lld/docs/ld.lld.1 | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/lld/docs/ld.lld.1 b/lld/docs/ld.lld.1
index 7edc522b4f6a4..7028927cb6d84 100644
--- a/lld/docs/ld.lld.1
+++ b/lld/docs/ld.lld.1
@@ -953,6 +953,16 @@ disallows overlap.
 .It Cm shstk
 x86 only, use shadow stack.
 .Pp
+.It Cm gcs Ns = Ns Ar [implicit|never|always]
+Specify how the GCS bit is set. Set GCS bit indicates object file that supports Guarded Control Stack.
+Specify how the GCS bit is set. A set GCS bit indicates that the object file supports the Guarded Control Stack security feature.
+.Cm implicit
+is the default, where the GCS bit is inferred from the input objects.
+.Cm never
+disables the GCS bit regardless of input markings.
+.Cm always
+enables the GCS bit regardless of input markings.
+.Pp
 .It Cm stack-size Ns = Ns Ar size
 Set the main thread's stack size to
 .Ar size .

>From fb65d4ddcdd5077391e289331e313657fd5a6c09 Mon Sep 17 00:00:00 2001
From: Sivan Shani <sivan.shani at arm.com>
Date: Tue, 1 Jul 2025 13:35:35 +0100
Subject: [PATCH 2/2] [LLD][Docs] Document -z gcs= option in the man page

Add documentation for the -z gcs= option to the LLD man page. This flag controls how the GCS bit is set in the output:

- implicit (default): inferred from input objects
- never: GCS bit is never set
- always: GCS bit is always set

Clarifies behavior for users and aligns the man page with existing functionality.
---
 lld/docs/ld.lld.1 | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/lld/docs/ld.lld.1 b/lld/docs/ld.lld.1
index 7028927cb6d84..f9fb7a6dbb463 100644
--- a/lld/docs/ld.lld.1
+++ b/lld/docs/ld.lld.1
@@ -798,6 +798,11 @@ Specify how to report the missing GNU_PROPERTY_X86_FEATURE_1_IBT or GNU_PROPERTY
 .Cm none
 is the default, linker will not report the missing property otherwise will be reported as a warning or an error.
 .Pp
+.It Cm gcs-report Ns = Ns Ar [none|warning|error]
+Specify how to report missing GNU_PROPERTY_AARCH64_FEATURE_1_GCS property. GNU_PROPERTY_AARCH64_FEATURE_1_GCS indicates object file support for the Guarded Control Stack security feature.
+.Cm none
+is the default, linker will not report the missing property otherwise will be reported as a warning or an error.
+.Pp
 .It Cm dynamic-undefined-weak
 Make undefined weak symbols dynamic when the dynamic symbol table is present, if they are referenced from
 relocatable object files and not forced local by symbol visibility or versioning. Do not make them dynamic when
@@ -954,7 +959,6 @@ disallows overlap.
 x86 only, use shadow stack.
 .Pp
 .It Cm gcs Ns = Ns Ar [implicit|never|always]
-Specify how the GCS bit is set. Set GCS bit indicates object file that supports Guarded Control Stack.
 Specify how the GCS bit is set. A set GCS bit indicates that the object file supports the Guarded Control Stack security feature.
 .Cm implicit
 is the default, where the GCS bit is inferred from the input objects.