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 07a21fd7fc993589b9e14acfcd9789e860e0528b..de38cab887a563792a595056fb9888994b78a6df 100644 (file)
--- 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.