[COMMITED] ada: stack scrubbing: exemplify codegen changes

["Marc Poulhiès" <poulhies@adacore.com>]

From: Alexandre Oliva <oliva@adacore.com>

gcc/ada/

	* doc/gnat_rm/security_hardening_features.rst: Add examples of
	codegen changes in stack scrubbing.
	* gnat_rm.texi: Regenerate.

Tested on x86_64-pc-linux-gnu, committed on master.

---
 .../gnat_rm/security_hardening_features.rst   | 52 ++++++++++++++++++
 gcc/ada/gnat_rm.texi                          | 53 ++++++++++++++++++-
 2 files changed, 103 insertions(+), 2 deletions(-)

diff --git a/gcc/ada/doc/gnat_rm/security_hardening_features.rst b/gcc/ada/doc/gnat_rm/security_hardening_features.rst
index f5fdc8e46b4..e36d47517dc 100644
--- a/gcc/ada/doc/gnat_rm/security_hardening_features.rst
+++ b/gcc/ada/doc/gnat_rm/security_hardening_features.rst
@@ -74,6 +74,58 @@ or a variable.)
      --  scrubbing of the stack space used by that subprogram.
 
 
+Given these declarations, Foo has its type and body modified as
+follows:
+
+.. code-block:: ada
+
+     function Foo (<WaterMark> : in out System.Address) returns Integer
+     is
+       --  ...
+     begin
+       <__strub_update> (<WaterMark>);  --  Updates the stack WaterMark.
+       --  ...
+     end;
+
+
+whereas its callers are modified from:
+
+.. code-block:: ada
+
+     X := Foo;
+
+to:
+
+.. code-block:: ada
+
+     declare
+       <WaterMark> : System.Address;
+     begin
+       <__strub_enter> (<WaterMark>);  -- Initialize <WaterMark>.
+       X := Foo (<WaterMark>);
+       <__strub_leave> (<WaterMark>);  -- Scrubs stack up to <WaterMark>.
+     end;
+
+
+As for Bar, because it is strubbed in internal mode, its callers are
+not modified.  Its definition is modified roughly as follows:
+
+.. code-block:: ada
+
+     procedure Bar is
+       <WaterMark> : System.Address;
+       procedure Strubbed_Bar (<WaterMark> : in out System.Address) is
+       begin
+         <__strub_update> (<WaterMark>);  --  Updates the stack WaterMark.
+         -- original Bar body.
+       end Strubbed_Bar;
+     begin
+       <__strub_enter> (<WaterMark>);  -- Initialize <WaterMark>.
+       Strubbed_Bar (<WaterMark>);
+       <__strub_leave> (<WaterMark>);  -- Scrubs stack up to <WaterMark>.
+     end Bar;
+
+
 There are also :switch:`-fstrub={choice}` command-line options to
 control default settings.  For usage and more details on the
 command-line options, on the ``strub`` attribute, and their use with
diff --git a/gcc/ada/gnat_rm.texi b/gcc/ada/gnat_rm.texi
index 64f2e796d8a..ff1845661a4 100644
--- a/gcc/ada/gnat_rm.texi
+++ b/gcc/ada/gnat_rm.texi
@@ -3,7 +3,7 @@
 @setfilename gnat_rm.info
 @documentencoding UTF-8
 @ifinfo
-@*Generated by Sphinx 5.1.1.@*
+@*Generated by Sphinx 5.2.3.@*
 @end ifinfo
 @settitle GNAT Reference Manual
 @defindex ge
@@ -19,7 +19,7 @@
 
 @copying
 @quotation
-GNAT Reference Manual , Sep 23, 2022
+GNAT Reference Manual , Oct 04, 2022
 
 AdaCore
 
@@ -28734,6 +28734,55 @@ pragma Machine_Attribute (Var, "strub");
 --  scrubbing of the stack space used by that subprogram.
 @end example
 
+Given these declarations, Foo has its type and body modified as
+follows:
+
+@example
+function Foo (<WaterMark> : in out System.Address) returns Integer
+is
+  --  ...
+begin
+  <__strub_update> (<WaterMark>);  --  Updates the stack WaterMark.
+  --  ...
+end;
+@end example
+
+whereas its callers are modified from:
+
+@example
+X := Foo;
+@end example
+
+to:
+
+@example
+declare
+  <WaterMark> : System.Address;
+begin
+  <__strub_enter> (<WaterMark>);  -- Initialize <WaterMark>.
+  X := Foo (<WaterMark>);
+  <__strub_leave> (<WaterMark>);  -- Scrubs stack up to <WaterMark>.
+end;
+@end example
+
+As for Bar, because it is strubbed in internal mode, its callers are
+not modified.  Its definition is modified roughly as follows:
+
+@example
+procedure Bar is
+  <WaterMark> : System.Address;
+  procedure Strubbed_Bar (<WaterMark> : in out System.Address) is
+  begin
+    <__strub_update> (<WaterMark>);  --  Updates the stack WaterMark.
+    -- original Bar body.
+  end Strubbed_Bar;
+begin
+  <__strub_enter> (<WaterMark>);  -- Initialize <WaterMark>.
+  Strubbed_Bar (<WaterMark>);
+  <__strub_leave> (<WaterMark>);  -- Scrubs stack up to <WaterMark>.
+end Bar;
+@end example
+
 There are also @code{-fstrub=`choice'} command-line options to
 control default settings.  For usage and more details on the
 command-line options, on the @code{strub} attribute, and their use with
-- 
2.34.1