[COMMITED] ada: hardened booleans: exemplify codegen changes

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

From: Alexandre Oliva <oliva@adacore.com>

Show the sort of code that is to be expected from using hardened
booleans in Ada code.  Mention that C traps instead of raising
exceptions.

gcc/ada/

	* doc/gnat_rm/security_hardening_features.rst: Add examples of
	codegen changes in hardened booleans. Mention that C traps where
	Ada raises exceptions.
	* gnat_rm.texi: Regenerate.

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

---
 .../gnat_rm/security_hardening_features.rst   | 29 ++++++++++++++++---
 gcc/ada/gnat_rm.texi                          | 26 +++++++++++++++--
 2 files changed, 48 insertions(+), 7 deletions(-)

diff --git a/gcc/ada/doc/gnat_rm/security_hardening_features.rst b/gcc/ada/doc/gnat_rm/security_hardening_features.rst
index e36d47517dc..d8ea849c032 100644
--- a/gcc/ada/doc/gnat_rm/security_hardening_features.rst
+++ b/gcc/ada/doc/gnat_rm/security_hardening_features.rst
@@ -265,19 +265,40 @@ further remove checks found to be redundant.
 For additional hardening, the ``hardbool`` :samp:`Machine_Attribute`
 pragma can be used to annotate boolean types with representation
 clauses, so that expressions of such types used as conditions are
-checked even when compiling with :switch:`-gnatVT`.
+checked even when compiling with :switch:`-gnatVT`:
 
 .. code-block:: ada
 
    pragma Machine_Attribute (HBool, "hardbool");
 
+   function To_Boolean (X : HBool) returns Boolean is (Boolean (X));
+
+
+is compiled roughly like:
+
+.. code-block:: ada
+
+   function To_Boolean (X : HBool) returns Boolean is
+   begin
+     if X not in True | False then
+       raise Constraint_Error;
+     elsif X in True then
+       return True;
+     else
+       return False;
+     end if;
+   end To_Boolean;
+
 
 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)`.
+Objective C programming languages, through the ``hardbool`` attribute,
+with the difference that, instead of raising a Constraint_Error
+exception, when a hardened boolean variable is found to hold a value
+that stands for neither True nor False, the program traps.  For usage
+and more details on that attribute, see :title:`Using the GNU Compiler
+Collection (GCC)`.
 
 
 .. Control Flow Redundancy:
diff --git a/gcc/ada/gnat_rm.texi b/gcc/ada/gnat_rm.texi
index ff1845661a4..dad0092713e 100644
--- a/gcc/ada/gnat_rm.texi
+++ b/gcc/ada/gnat_rm.texi
@@ -28920,17 +28920,37 @@ further remove checks found to be redundant.
 For additional hardening, the @code{hardbool} @code{Machine_Attribute}
 pragma can be used to annotate boolean types with representation
 clauses, so that expressions of such types used as conditions are
-checked even when compiling with @code{-gnatVT}.
+checked even when compiling with @code{-gnatVT}:
 
 @example
 pragma Machine_Attribute (HBool, "hardbool");
+
+function To_Boolean (X : HBool) returns Boolean is (Boolean (X));
+@end example
+
+is compiled roughly like:
+
+@example
+function To_Boolean (X : HBool) returns Boolean is
+begin
+  if X not in True | False then
+    raise Constraint_Error;
+  elsif X in True then
+    return True;
+  else
+    return False;
+  end if;
+end To_Boolean;
 @end example
 
 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)}.
+Objective C programming languages, through the @code{hardbool} attribute,
+with the difference that, instead of raising a Constraint_Error
+exception, when a hardened boolean variable is found to hold a value
+that stands for neither True nor False, the program traps.  For usage
+and more details on that attribute, see @cite{Using the GNU Compiler Collection (GCC)}.
 
 @c Control Flow Redundancy:
 
-- 
2.34.1