From: Alexandre Oliva <ol...@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
