[gcc r13-831] [Ada] Tweaks to hardening docs

[gcc r13-831] [Ada] Tweaks to hardening docs

[Pierre-Marie de Rodat]

https://gcc.gnu.org/g:33dec214f0270ac86c445e08c32843b73e44fb23

commit r13-831-g33dec214f0270ac86c445e08c32843b73e44fb23
Author: Alexandre Oliva <oliva@adacore.com>
Date:   Thu Apr 21 00:17:28 2022 -0300

    [Ada] 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.
    
    gcc/ada/
    
            * 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.
            * gnat_rm.texi: Regenerate.

Diff:
---
 .../doc/gnat_rm/security_hardening_features.rst    | 55 +++++++++++++++++-----
 gcc/ada/gnat_rm.texi                               | 49 ++++++++++++++-----
 2 files changed, 79 insertions(+), 25 deletions(-)

diff --git a/gcc/ada/doc/gnat_rm/security_hardening_features.rst b/gcc/ada/doc/gnat_rm/security_hardening_features.rst
index 8c4c1f64a4e..0631a53df9b 100644
--- a/gcc/ada/doc/gnat_rm/security_hardening_features.rst
+++ b/gcc/ada/doc/gnat_rm/security_hardening_features.rst
@@ -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 :switch:`-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)`.
+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
@@ -162,6 +176,10 @@ 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.
+
 
 .. Hardened Booleans:
 
@@ -177,6 +195,7 @@ alternative representations, using representation clauses:
    for HBool use (16#5a#, 16#a5#);
    for HBool'Size use 8;
 
+
 When validity checking is enabled, the compiler will check that
 variables of such types hold values corresponding to the selected
 representations.
@@ -196,8 +215,14 @@ checked even when compiling with :switch:`-gnatVT`.
 
    pragma Machine_Attribute (HBool, "hardbool");
 
+
 Note that :switch:`-gnatVn` will disable even ``hardbool`` testing.
 
+Analogous behavior is available as a GCC extension to the C and
+Objective C programming languages, through the ``hardbool`` attribute.
+For usage and more details on that attribute, see :title:`Using the
+GNU Compiler Collection (GCC)`.
+
 
 .. Control Flow Redundancy:
 
@@ -243,3 +268,7 @@ disabled altogether.
 The instrumentation for hardening with control flow redundancy can be
 observed in dump files generated by the command-line option
 :switch:`-fdump-tree-hardcfr`.
+
+For more details on the control flow redundancy command-line options,
+see :title:`Using the GNU Compiler Collection (GCC)`.  These options
+can be used with other programming languages supported by GCC.
diff --git a/gcc/ada/gnat_rm.texi b/gcc/ada/gnat_rm.texi
index bf7c532a714..434bd3c8e61 100644
--- a/gcc/ada/gnat_rm.texi
+++ b/gcc/ada/gnat_rm.texi
@@ -21,7 +21,7 @@
 
 @copying
 @quotation
-GNAT Reference Manual , Apr 22, 2022
+GNAT Reference Manual , May 24, 2022
 
 AdaCore
 
@@ -28920,8 +28920,9 @@ pragma Machine_Attribute (Bar, "zero_call_used_regs", "all");
 --  Before returning, Bar scrubs all call-clobbered registers.
 @end example
 
-For usage and more details on the command-line option, and on the
-@code{zero_call_used_regs} attribute, see @cite{Using the GNU Compiler Collection (GCC)}.
+For usage and more details on the command-line option, on the
+@code{zero_call_used_regs} attribute, and on their use with other
+programming languages, see @cite{Using the GNU Compiler Collection (GCC)}.
 
 @c Stack Scrubbing:
 
@@ -28933,13 +28934,16 @@ For usage and more details on the command-line option, and on the
 GNAT can generate code to zero-out stack frames used by subprograms.
 
 It can be activated with the @code{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.)
 
 @example
 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");
@@ -28949,12 +28953,15 @@ pragma Machine_Attribute (Bar, "strub", "internal");
 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.
 @end example
 
 There are also @code{-fstrub} command-line options to control
 default settings.  For usage and more details on the command-line
-option, and on the @code{strub} attribute, see @cite{Using the GNU Compiler Collection (GCC)}.
+option, on the @code{strub} attribute, and their use with other
+programming languages, see @cite{Using the GNU Compiler Collection (GCC)}.
 
 Note that Ada secondary stacks are not scrubbed.  The restriction
 @code{No_Secondary_Stack} avoids their use, and thus their accidental
@@ -28967,16 +28974,19 @@ there is no way to express an access-to-strub type otherwise.
 access type designates a non-strub type.
 
 @example
-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.
 @end example
 
 Every access-to-subprogram type, renaming, and overriding and
@@ -28993,6 +29003,9 @@ type TBar is access procedure;
 
 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));
@@ -29049,6 +29062,10 @@ 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
+@cite{Using the GNU Compiler Collection (GCC)}.  These options can
+be used with other programming languages supported by GCC.
+
 @c Hardened Booleans:
 
 @node Hardened Booleans,Control Flow Redundancy,Hardened Conditionals,Security Hardening Features
@@ -29086,6 +29103,10 @@ pragma Machine_Attribute (HBool, "hardbool");
 
 Note that @code{-gnatVn} will disable even @code{hardbool} testing.
 
+Analogous behavior is available as a GCC extension to the C and
+Objective C programming languages, through the @code{hardbool} attribute.
+For usage and more details on that attribute, see @cite{Using the GNU Compiler Collection (GCC)}.
+
 @c Control Flow Redundancy:
 
 @node Control Flow Redundancy,,Hardened Booleans,Security Hardening Features
@@ -29133,6 +29154,10 @@ The instrumentation for hardening with control flow redundancy can be
 observed in dump files generated by the command-line option
 @code{-fdump-tree-hardcfr}.
 
+For more details on the control flow redundancy command-line options,
+see @cite{Using the GNU Compiler Collection (GCC)}.  These options
+can be used with other programming languages supported by GCC.
+
 @node Obsolescent Features,Compatibility and Porting Guide,Security Hardening Features,Top
 @anchor{gnat_rm/obsolescent_features doc}@anchor{447}@anchor{gnat_rm/obsolescent_features id1}@anchor{448}@anchor{gnat_rm/obsolescent_features obsolescent-features}@anchor{16}
 @chapter Obsolescent Features