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