From: Sandra Loosemore Date: Thu, 6 Nov 2025 22:30:44 +0000 (+0000) Subject: AArch64, ARM: Clean up documentation of -mbranch-protection. X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=eb88c84cf75405f0904867372b31fee09cb565bf;p=thirdparty%2Fgcc.git AArch64, ARM: Clean up documentation of -mbranch-protection. While working on other things, I noticed that the documentation for the -mbranch-protection= option was pretty garbled on both aarch64 and arm targets, with incorrect markup, too much syntax crammed into the option summary, and confusion about what the values "+leaf" modifier can apply to. I rewrote it to list all the valid option values explicitly in the option description, checking this against the implementation. gcc/ChangeLog * doc/invoke.texi (AArch64 Options): Clean up description of -mbranch-protection= argument. (ARM Options): Likewise. --- diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi index 07a21fd7fc9..de38cab887a 100644 --- a/gcc/doc/invoke.texi +++ b/gcc/doc/invoke.texi @@ -838,8 +838,7 @@ Objective-C and Objective-C++ Dialects}. -mlow-precision-recip-sqrt -mlow-precision-sqrt -mlow-precision-div -mpc-relative-literal-loads -msign-return-address=@var{scope} --mbranch-protection=@var{none}|@var{standard}|@var{pac-ret}[+@var{leaf} -+@var{b-key}]|@var{bti}|@var{gcs} +-mbranch-protection=@var{features} -mharden-sls=@var{opts} -march=@var{name} -mcpu=@var{name} -mtune=@var{name} -moverride=@var{string} -mverbose-cost-dump @@ -919,8 +918,7 @@ Objective-C and Objective-C++ Dialects}. -mfix-cmse-cve-2021-35465 -mstack-protector-guard=@var{guard} -mstack-protector-guard-offset=@var{offset} -mfdpic --mbranch-protection=@var{none}|@var{standard}|@var{pac-ret}[+@var{leaf}] -[+@var{bti}]|@var{bti}[+@var{pac-ret}[+@var{leaf}]]} +-mbranch-protection=@var{features}} @emph{AVR Options} (@ref{AVR Options}) @gccoptlist{-mmcu=@var{mcu} -mabsdata -maccumulate-args -mcvt @@ -22551,19 +22549,28 @@ default value is @samp{none}. This option has been deprecated by -mbranch-protection. @opindex mbranch-protection -@item -mbranch-protection=@var{none}|@var{standard}|@var{pac-ret}[+@var{leaf}+@var{b-key}]|@var{bti}|@var{gcs} +@item -mbranch-protection=@var{features} Select the branch protection features to use. +@var{features} can have one of the following forms: + @samp{none} is the default and turns off all types of branch protection. + @samp{standard} turns on all types of branch protection features. If a feature has additional tuning options, then @samp{standard} sets it to its standard level. -@samp{pac-ret[+@var{leaf}]} turns on return address signing to its standard + +@samp{pac-ret} turns on return address signing to its standard level: signing functions that save the return address to memory (non-leaf -functions will practically always do this) using the a-key. The optional -argument @samp{leaf} can be used to extend the signing to include leaf -functions. The optional argument @samp{b-key} can be used to sign the functions -with the B-key instead of the A-key. +functions practically always do this) using the A-key. + +@samp{pac-ret+leaf} extends the @samp{pac-ret} signing to include leaf +functions. + +@samp{pac-ret+b-key} or @samp{pac-ret+leaf+b-key} can be used to +sign the functions with the B-key instead of the A-key. + @samp{bti} turns on branch target identification mechanism. + @samp{gcs} turns on guarded control stack compatible code generation. @opindex mharden-sls @@ -25028,24 +25035,33 @@ build the Linux kernel using the same (@code{arm-*-uclinuxfdpiceabi}) toolchain as the one used to build the userland programs. @opindex mbranch-protection -@item -mbranch-protection=@var{none}|@var{standard}|@var{pac-ret}[+@var{leaf}][+@var{bti}]|@var{bti}[+@var{pac-ret}[+@var{leaf}]] +@item -mbranch-protection=@var{features} + Enable branch protection features (armv8.1-m.main only). -@samp{none} generate code without branch protection or return address + +@var{features} can have one of the following forms: + +@samp{none} generates code without branch protection or return address signing. -@samp{standard[+@var{leaf}]} generate code with all branch protection + +@samp{standard} generates code with all branch protection features enabled at their standard level. -@samp{pac-ret[+@var{leaf}]} generate code with return address signing + +@samp{pac-ret} generates code with return address signing set to its standard level, which is to sign all functions that save the return address to memory. -@samp{leaf} When return address signing is enabled, also sign leaf + +@samp{pac-ret+leaf} extends the @samp{pac-ret} signing to include leaf functions even if they do not write the return address to memory. -+@samp{bti} Add landing-pad instructions at the permitted targets of + +@samp{bti} adds landing-pad instructions at the permitted targets of indirect branch instructions. -If the @samp{+pacbti} architecture extension is not enabled, then all +If support for the @samp{+pacbti} architecture extension is not enabled +(e.g. via @option{-march=}), then all branch protection and return address signing operations are constrained to use only the instructions defined in the -architectural-NOP space. The generated code will remain +architectural-NOP space. The generated code remains backwards-compatible with earlier versions of the architecture, but the additional security can be enabled at run time on processors that support the @samp{PACBTI} extension.