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

sivan-shani · 2025-07-01T12:38:11Z

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.

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.

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.

smithp35 · 2025-07-01T16:16:11Z

lld/docs/ld.lld.1

@@ -953,6 +958,15 @@ 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. A set GCS bit indicates that the object file supports the Guarded Control Stack security feature.


I think it would be better to say

Specify how the GNU_PROPERTY_AARCH64_FEATURE_1_GCS feature bit is set in the output ELF file. When set this declares that the ELF file supports the Guarded Control Stack (GCS) security feature.

ack, wording improved

smithp35 · 2025-07-01T16:19:23Z

lld/docs/ld.lld.1

+.It Cm gcs Ns = Ns Ar [implicit|never|always]
+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.


From looking at noseparate-code above. I suggest
(default) feature bit is inferred from the input object marking.

I've suggested feature bit rather than GCS bit as we've used the full GNU_PROPERTY_AARCH64_FEATURE_1_GCS feature bit above.

ack, wording improved

smithp35 · 2025-07-01T16:20:48Z

lld/docs/ld.lld.1

+.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.


I suggest
clears the feature bit regardless of input object marking.

ack, wording improved

sivan-shani · 2025-07-02T10:44:11Z

Comments handled

smithp35

Nearly there. I think if we can use the same wording as on bti-report and cet-report then we're good.

smithp35 · 2025-07-02T13:11:50Z

lld/docs/ld.lld.1

+.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, missing property will be reported as a warning or an error.


Apologies for being a pain. A couple of nits on this line:

I meant (default) at the start of the line. However, looking at bti-report and cet-report above it is probably better to follow the convention and use "is the default," . It was probably that originally; sorry for the noise.

The comma after otherwise looks to be in the wrong position [1]. I think we should follow the wording of bit-report and cet-report.

is the default, linker will not report the missing property otherwise will be reported as a warning or an error.

[1] If I were rewriting with a comma I'd say "report the missing propery, otherwise it will be reported as a warning or an error." However best to stay consistent with the existing wording.

ack, also for gcs using (default)

…mments.

sivan-shani · 2025-07-02T14:18:47Z

Comments handled (indicating default option and alignment with other report options)

smithp35

LGTM thanks for the updates. Please leave a few days before merging to give @MaskRay a chance to comment.

llvmbot · 2025-07-02T14:35:25Z

@llvm/pr-subscribers-lld

Author: SivanShani-Arm (sivan-shani)

Changes

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.

Full diff: https://github.com/llvm/llvm-project/pull/146522.diff

1 Files Affected:

(modified) lld/docs/ld.lld.1 (+14)

diff --git a/lld/docs/ld.lld.1 b/lld/docs/ld.lld.1
index 7edc522b4f6a4..49efc1269e7f2 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
@@ -953,6 +958,15 @@ disallows overlap.
 .It Cm shstk
 x86 only, use shadow stack.
 .Pp
+.It Cm gcs Ns = Ns Ar [implicit|never|always]
+Specifies how the GNU_PROPERTY_AARCH64_FEATURE_1_GCS bit is set in the output ELF file. When set, it indicates support for the Guarded Control Stack (GCS) security feature.
+.Cm implicit
+(default) GCS feature bit is inferred from the input object marking.
+.Cm never
+clears the GCS feature bit regardless of input object markings.
+.Cm always
+set the GCS feature bit regardless of input object markings.
+.Pp
 .It Cm stack-size Ns = Ns Ar size
 Set the main thread's stack size to
 .Ar size .

MaskRay · 2025-07-02T16:43:26Z

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.


GNU_PROPERTY_AARCH64_FEATURE_1_* properties need to use .Cm

ack, handled.

MaskRay · 2025-07-02T16:43:39Z

lld/docs/ld.lld.1

@@ -953,6 +958,15 @@ disallows overlap.
 .It Cm shstk
 x86 only, use shadow stack.
 .Pp
+.It Cm gcs Ns = Ns Ar [implicit|never|always]
+Specifies how the GNU_PROPERTY_AARCH64_FEATURE_1_GCS bit is set in the output ELF file. When set, it indicates support for the Guarded Control Stack (GCS) security feature.


Use .Cm GNU_PROPERTY_AARCH64_FEATURE_1_GCS

ack, handled.

MaskRay · 2025-07-02T16:45:56Z

lld/docs/ld.lld.1

+.It Cm gcs Ns = Ns Ar [implicit|never|always]
+Specifies how the GNU_PROPERTY_AARCH64_FEATURE_1_GCS bit is set in the output ELF file. When set, it indicates support for the Guarded Control Stack (GCS) security feature.
+.Cm implicit
+(default) GCS feature bit is inferred from the input object marking.


input object marking is vague. I'd emphasize relocatable files. Perhaps something like

When all relocatable files contain a .note.gnu.property section containing the GNU_PROPERTY_AARCH64_FEATURE_1_GCS bit

ack, handled.

sivan-shani · 2025-07-03T09:48:31Z

Comments handled (Add .Cm, use 'relocatable files')

DanielKristofKiss

LGTM, let's see what other reviewers says.

DanielKristofKiss · 2025-07-02T09:13:27Z

lld/docs/ld.lld.1

 .Cm implicit
-is the default, where the GCS bit is inferred from the input objects.
+is the (default) GCS feature bit is inferred from the input object marking.


reads as "is the GCS feature bit is inferred... "

Suggested change

is the (default) GCS feature bit is inferred from the input object marking.

is the default. GCS feature bit is inferred from the input object marking.

Above is outdated, I believe that new version does not suffer from same ambiguity.

DanielKristofKiss · 2025-07-02T09:14:13Z

lld/docs/ld.lld.1

 .Cm always
-enables the GCS bit regardless of input markings.
+set the GCS feature bit regardless of input object markings.


Suggested change

set the GCS feature bit regardless of input object markings.

sets the GCS feature bit regardless of input object markings.

ack, changed set->sets

DanielKristofKiss · 2025-07-02T09:19:08Z

lld/docs/ld.lld.1

@@ -801,7 +801,7 @@ is the default, linker will not report the missing property otherwise will be re
 .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.
+is the (default) linker will not report the missing property otherwise, missing property will be reported as a warning or an error.


without the comma the sentence is strange to me.

Here we might want to keep the wording as is, same as it is for

bti-report cet-report

Which are the same flag type and has the exact same wording.

MaskRay · 2025-07-04T18:56:17Z

lld/docs/ld.lld.1

+.Cm GNU_PROPERTY_AARCH64_FEATURE_1_GCS
+bit is set in the output ELF file. When set, it indicates support for the Guarded Control Stack (GCS) security feature.
+.Cm implicit
+(default) The GCS feature bit is set if all input relocatable files have a .note.gnu.property section containing the GNU_PROPERTY_AARCH64_FEATURE_1_GCS bit.


.note.gnu.property also needs Cm

sivan-shani · 2025-07-05T09:03:20Z

[Apologies, Will be away for 5 weeks, response will be delayed]

sivan-shani added 2 commits July 1, 2025 13:24

sivan-shani requested review from ostannard, DanielKristofKiss and smithp35 July 1, 2025 12:39

smithp35 reviewed Jul 1, 2025

View reviewed changes

[LLD][Docs] Improve wording and clarity in response to review comments

0129664

smithp35 reviewed Jul 2, 2025

View reviewed changes

[LLD][Docs] Align indication of 'default' option, respnd to review co…

68b2552

…mments.

smithp35 approved these changes Jul 2, 2025

View reviewed changes

sivan-shani marked this pull request as ready for review July 2, 2025 14:34

llvmbot added the lld label Jul 2, 2025

MaskRay reviewed Jul 2, 2025

View reviewed changes

[LLD][Docs] Add .Cm, use 'relocatable files' respond to review comments.

9640c1f

DanielKristofKiss approved these changes Jul 3, 2025

View reviewed changes

MaskRay approved these changes Jul 4, 2025

View reviewed changes

	is the (default) GCS feature bit is inferred from the input object marking.
	is the default. GCS feature bit is inferred from the input object marking.

	set the GCS feature bit regardless of input object markings.
	sets the GCS feature bit regardless of input object markings.

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

Are you sure you want to change the base?

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

Conversation

sivan-shani commented Jul 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sivan-shani commented Jul 2, 2025

Uh oh!

smithp35 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sivan-shani commented Jul 2, 2025

Uh oh!

smithp35 left a comment

Choose a reason for hiding this comment

Uh oh!

llvmbot commented Jul 2, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sivan-shani Jul 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sivan-shani commented Jul 3, 2025

Uh oh!

DanielKristofKiss left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sivan-shani Jul 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sivan-shani Jul 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sivan-shani commented Jul 5, 2025

Uh oh!

Uh oh!

sivan-shani commented Jul 1, 2025 •

edited

Loading

sivan-shani Jul 3, 2025 •

edited

Loading

sivan-shani Jul 4, 2025 •

edited

Loading

sivan-shani Jul 4, 2025 •

edited

Loading