[gcc(refs/users/aoliva/heads/hard12)] Tweaks to hardening docs

[gcc(refs/users/aoliva/heads/hard12)] Tweaks to hardening docs

[Alexandre Oliva]

https://gcc.gnu.org/g:bb7b581a33794d3ea15bbd5bfd598a8743686fb5

commit bb7b581a33794d3ea15bbd5bfd598a8743686fb5
Author: Alexandre Oliva <oliva@adacore.com>
Date:   Fri May 6 05:34:05 2022 -0300

    Tweaks to hardening docs
    
    Mention when security hardening features are available in other
    languages.
    
    Expand the strub documentation a little, for clarity and completeness.
    
    Add missing 'aliased' and attribute to variables in strub example.
    
    for  gcc/ada/ChangeLog
    
            * doc/gnat_rm/security_hardening_features.rst: Mention
            availability in other languages when applicable.
            (Stack Scrubbing): Associate the attribute with types, expand
            some comments, fix the example involving access to variables.

Diff:
---
 .../doc/gnat_rm/security_hardening_features.rst    | 67 ++++++++++++++--------
 1 file changed, 43 insertions(+), 24 deletions(-)

diff --git a/gcc/ada/doc/gnat_rm/security_hardening_features.rst b/gcc/ada/doc/gnat_rm/security_hardening_features.rst
index bdcfd99ad86..bd42b08765a 100644
--- a/gcc/ada/doc/gnat_rm/security_hardening_features.rst
+++ b/gcc/ada/doc/gnat_rm/security_hardening_features.rst
@@ -15,7 +15,7 @@ Register Scrubbing
 GNAT can generate code to zero-out hardware registers before returning
 from a subprogram.
 
-It can be enabled with the *-fzero-call-used-regs* command line
+It can be enabled with the :switch:`-fzero-call-used-regs` command-line
 option, to affect all subprograms in a compilation, and with a
 :samp:`Machine_Attribute` pragma, to affect only specific subprograms.
 
@@ -31,9 +31,10 @@ option, to affect all subprograms in a compilation, and with a
      --  Before returning, Bar scrubs all call-clobbered registers.
 
 
-For usage and more details on the command line option, and on the
-``zero_call_used_regs`` attribute, see :title:`Using the GNU Compiler
-Collection (GCC)`.
+For usage and more details on the command-line option, on the
+``zero_call_used_regs`` attribute, and on their use with other
+programming languages, see :title:`Using the GNU Compiler Collection
+(GCC)`.
 
 
 .. Stack Scrubbing:
@@ -44,14 +45,17 @@ Stack Scrubbing
 GNAT can generate code to zero-out stack frames used by subprograms.
 
 It can be activated with the :samp:`Machine_Attribute` pragma, on
-specific subprograms and variables.
+specific subprograms and variables, or their types.  (This attribute
+always applies to a type, even when it is associated with a subprogram
+or a variable.)
 
 .. code-block:: ada
 
      function Foo returns Integer;
      pragma Machine_Attribute (Foo, "strub");
      --  Foo and its callers are modified so as to scrub the stack
-     --  space used by Foo after it returns.
+     --  space used by Foo after it returns.  Shorthand for:
+     --  pragma Machine_Attribute (Foo, "strub", "at-calls");
 
      procedure Bar;
      pragma Machine_Attribute (Bar, "strub", "internal");
@@ -61,13 +65,16 @@ specific subprograms and variables.
      Var : Integer;
      pragma Machine_Attribute (Var, "strub");
      --  Reading from Var in a subprogram enables stack scrubbing
-     --  of the stack space used by the subprogram.
+     --  of the stack space used by the subprogram.  Furthermore, if
+     --  Var is declared within a subprogram, this also enables
+     --  scrubbing of the stack space used by that subprogram.
 
 
-There are also *-fstrub* command line options to control default
-settings.  For usage and more details on the command line option, and
-on the ``strub`` attribute, see :title:`Using the GNU Compiler
-Collection (GCC)`.
+There are also :switch:`-fstrub` command-line options to control
+default settings.  For usage and more details on the command-line
+option, on the ``strub`` attribute, and their use with other
+programming languages, see :title:`Using the GNU Compiler Collection
+(GCC)`.
 
 Note that Ada secondary stacks are not scrubbed.  The restriction
 ``No_Secondary_Stack`` avoids their use, and thus their accidental
@@ -81,16 +88,19 @@ access type designates a non-strub type.
 
 .. code-block:: ada
 
-     VI : Integer;
+     VI : aliased Integer;
+     pragma Machine_Attribute (VI, "strub");
      XsVI : access Integer := VI'Access; -- Error.
      UXsVI : access Integer := VI'Unchecked_Access; -- OK,
-     -- UXsVI.all does not enable strub in the enclosing subprogram.
+     --  UXsVI does *not* enable strub in subprograms that
+     --  dereference it to obtain the UXsVI.all value.
 
      type Strub_Int is new Integer;
      pragma Machine_Attribute (Strub_Int, "strub");
-     VSI : Strub_Int;
-     XsVSI : access Strub_Int := VSI'Access; -- OK.
-     -- XsVSI.all enables strub in the enclosing subprogram.
+     VSI : aliased Strub_Int;
+     XsVSI : access Strub_Int := VSI'Access; -- OK,
+     --  VSI and XsVSI.all both enable strub in subprograms that
+     --  read their values.
 
 
 Every access-to-subprogram type, renaming, and overriding and
@@ -108,6 +118,9 @@ turned ``callable`` through such an explicit conversion:
 
      type TBar_Callable is access procedure;
      pragma Machine_Attribute (TBar_Callable, "strub", "callable");
+     --  The attribute modifies the procedure type, rather than the
+     --  access type, because of the extra argument after "strub",
+     --  only applicable to subprogram types.
 
      Bar_Callable_Ptr : constant TBar_Callable
 		:= TBar_Callable (TBar'(Bar'Access));
@@ -115,6 +128,7 @@ turned ``callable`` through such an explicit conversion:
      procedure Bar_Callable renames Bar_Callable_Ptr.all;
      pragma Machine_Attribute (Bar_Callable, "strub", "callable");
 
+
 Note that the renaming declaration is expanded to a full subprogram
 body, it won't be just an alias.  Only if it is inlined will it be as
 efficient as a call by dereferencing the access-to-subprogram constant
@@ -126,18 +140,18 @@ Bar_Callable_Ptr.
 Hardened Conditionals
 =====================
 
-GNAT can harden conditionals to protect against control flow attacks.
+GNAT can harden conditionals to protect against control-flow attacks.
 
 This is accomplished by two complementary transformations, each
 activated by a separate command-line option.
 
-The option *-fharden-compares* enables hardening of compares that
-compute results stored in variables, adding verification that the
+The option :switch:`-fharden-compares` enables hardening of compares
+that compute results stored in variables, adding verification that the
 reversed compare yields the opposite result.
 
-The option *-fharden-conditional-branches* enables hardening of
-compares that guard conditional branches, adding verification of the
-reversed compare to both execution paths.
+The option :switch:`-fharden-conditional-branches` enables hardening
+of compares that guard conditional branches, adding verification of
+the reversed compare to both execution paths.
 
 These transformations are introduced late in the compilation pipeline,
 long after boolean expressions are decomposed into separate compares,
@@ -155,8 +169,13 @@ options ensures that every compare that is neither optimized out nor
 optimized into implied conditionals will be hardened.
 
 The addition of reversed compares can be observed by enabling the dump
-files of the corresponding passes, through command line options
-*-fdump-tree-hardcmp* and *-fdump-tree-hardcbr*, respectively.
+files of the corresponding passes, through command-line options
+:switch:`-fdump-tree-hardcmp` and :switch:`-fdump-tree-hardcbr`,
+respectively.
 
 They are separate options, however, because of the significantly
 different performance impact of the hardening transformations.
+
+For usage and more details on the command-line options, see
+:title:`Using the GNU Compiler Collection (GCC)`.  These options can
+be used with other programming languages supported by GCC.