[COMMITED] ada: hardened conditionals: 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 hardened conditionals.
	* gnat_rm.texi: Regenerate.

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

---
 .../gnat_rm/security_hardening_features.rst   | 51 ++++++++++++++++++-
 gcc/ada/gnat_rm.texi                          | 47 ++++++++++++++++-
 2 files changed, 94 insertions(+), 4 deletions(-)

diff --git a/gcc/ada/doc/gnat_rm/security_hardening_features.rst b/gcc/ada/doc/gnat_rm/security_hardening_features.rst
index d8ea849c032..d7c02b94f36 100644
--- a/gcc/ada/doc/gnat_rm/security_hardening_features.rst
+++ b/gcc/ada/doc/gnat_rm/security_hardening_features.rst
@@ -203,11 +203,58 @@ activated by a separate command-line option.
 
 The option :switch:`-fharden-compares` enables hardening of compares
 that compute results stored in variables, adding verification that the
-reversed compare yields the opposite result.
+reversed compare yields the opposite result, turning:
+
+.. code-block:: ada
+
+    B := X = Y;
+
+
+into:
+
+.. code-block:: ada
+
+    B := X = Y;
+    declare
+      NotB : Boolean := X /= Y; -- Computed independently of B.
+    begin
+      if B = NotB then
+        <__builtin_trap>;
+      end if;
+    end;
+
 
 The option :switch:`-fharden-conditional-branches` enables hardening
 of compares that guard conditional branches, adding verification of
-the reversed compare to both execution paths.
+the reversed compare to both execution paths, turning:
+
+.. code-block:: ada
+
+    if X = Y then
+      X := Z + 1;
+    else
+      Y := Z - 1;
+    end if;
+
+
+into:
+
+.. code-block:: ada
+
+    if X = Y then
+      if X /= Y then -- Computed independently of X = Y.
+        <__builtin_trap>;
+      end if;
+      X := Z + 1;
+    else
+      if X /= Y then -- Computed independently of X = Y.
+        null;
+      else
+        <__builtin_trap>;
+      end if;
+      Y := Z - 1;
+    end if;
+
 
 These transformations are introduced late in the compilation pipeline,
 long after boolean expressions are decomposed into separate compares,
diff --git a/gcc/ada/gnat_rm.texi b/gcc/ada/gnat_rm.texi
index dad0092713e..e13dba037ff 100644
--- a/gcc/ada/gnat_rm.texi
+++ b/gcc/ada/gnat_rm.texi
@@ -28858,11 +28858,54 @@ activated by a separate command-line option.
 
 The option @code{-fharden-compares} enables hardening of compares
 that compute results stored in variables, adding verification that the
-reversed compare yields the opposite result.
+reversed compare yields the opposite result, turning:
+
+@example
+B := X = Y;
+@end example
+
+into:
+
+@example
+B := X = Y;
+declare
+  NotB : Boolean := X /= Y; -- Computed independently of B.
+begin
+  if B = NotB then
+    <__builtin_trap>;
+  end if;
+end;
+@end example
 
 The option @code{-fharden-conditional-branches} enables hardening
 of compares that guard conditional branches, adding verification of
-the reversed compare to both execution paths.
+the reversed compare to both execution paths, turning:
+
+@example
+if X = Y then
+  X := Z + 1;
+else
+  Y := Z - 1;
+end if;
+@end example
+
+into:
+
+@example
+if X = Y then
+  if X /= Y then -- Computed independently of X = Y.
+    <__builtin_trap>;
+  end if;
+  X := Z + 1;
+else
+  if X /= Y then -- Computed independently of X = Y.
+    null;
+  else
+    <__builtin_trap>;
+  end if;
+  Y := Z - 1;
+end if;
+@end example
 
 These transformations are introduced late in the compilation pipeline,
 long after boolean expressions are decomposed into separate compares,
-- 
2.34.1