[gcc r12-2203] [Ada] Add paragraph about representation changes and Scalar_Storage_Order

[Pierre-Marie de Rodat <pmderodat@gcc.gnu.org>]

https://gcc.gnu.org/g:2a847e8c8fa3523ac8bfb3e20600dce6addcd7f9

commit r12-2203-g2a847e8c8fa3523ac8bfb3e20600dce6addcd7f9
Author: Eric Botcazou <ebotcazou@adacore.com>
Date:   Thu Jun 10 10:21:46 2021 +0200

    [Ada] Add paragraph about representation changes and Scalar_Storage_Order
    
    gcc/ada/
    
            * doc/gnat_rm/implementation_defined_attributes.rst
            (Scalar_Storage_Order): Add paragraph about representation
            changes.
            * gnat_rm.texi: Regenerate.

Diff:
---
 .../gnat_rm/implementation_defined_attributes.rst  | 40 ++++++++++++++++++++++
 gcc/ada/gnat_rm.texi                               | 40 ++++++++++++++++++++++
 2 files changed, 80 insertions(+)

diff --git a/gcc/ada/doc/gnat_rm/implementation_defined_attributes.rst b/gcc/ada/doc/gnat_rm/implementation_defined_attributes.rst
index 0df103bf618..665170c4c7e 100644
--- a/gcc/ada/doc/gnat_rm/implementation_defined_attributes.rst
+++ b/gcc/ada/doc/gnat_rm/implementation_defined_attributes.rst
@@ -1057,6 +1057,46 @@ If a component of ``T`` is itself of a record or array type, the specfied
 attribute definition clause must be provided for the component type as well
 if desired.
 
+Representation changes that explicitly or implicitly toggle the scalar storage
+order are not supported and may result in erroneous execution of the program,
+except when performed by means of an instance of ``Ada.Unchecked_Conversion``.
+
+In particular, overlays are not supported and a warning is given for them:
+
+.. code-block:: ada
+
+     type Rec_LE is record
+        I : Integer;
+     end record;
+
+     for Rec_LE use record
+        I at 0 range 0 .. 31;
+     end record;
+
+     for Rec_LE'Bit_Order use System.Low_Order_First;
+     for Rec_LE'Scalar_Storage_Order use System.Low_Order_First;
+
+     type Rec_BE is record
+        I : Integer;
+     end record;
+
+     for Rec_BE use record
+        I at 0 range 0 .. 31;
+     end record;
+
+     for Rec_BE'Bit_Order use System.High_Order_First;
+     for Rec_BE'Scalar_Storage_Order use System.High_Order_First;
+
+     R_LE : Rec_LE;
+
+     R_BE : Rec_BE;
+     for R_BE'Address use R_LE'Address;
+
+``warning: overlay changes scalar storage order [enabled by default]``
+
+In most cases, such representation changes ought to be replaced by an
+instantiation of a function or procedure provided by ``GNAT.Byte_Swapping``.
+
 Note that the scalar storage order only affects the in-memory data
 representation. It has no effect on the representation used by stream
 attributes.
diff --git a/gcc/ada/gnat_rm.texi b/gcc/ada/gnat_rm.texi
index 19d6f334aac..c0ccfe4b2cf 100644
--- a/gcc/ada/gnat_rm.texi
+++ b/gcc/ada/gnat_rm.texi
@@ -11442,6 +11442,46 @@ If a component of @code{T} is itself of a record or array type, the specfied
 attribute definition clause must be provided for the component type as well
 if desired.
 
+Representation changes that explicitly or implicitly toggle the scalar storage
+order are not supported and may result in erroneous execution of the program,
+except when performed by means of an instance of @code{Ada.Unchecked_Conversion}.
+
+In particular, overlays are not supported and a warning is given for them:
+
+@example
+type Rec_LE is record
+   I : Integer;
+end record;
+
+for Rec_LE use record
+   I at 0 range 0 .. 31;
+end record;
+
+for Rec_LE'Bit_Order use System.Low_Order_First;
+for Rec_LE'Scalar_Storage_Order use System.Low_Order_First;
+
+type Rec_BE is record
+   I : Integer;
+end record;
+
+for Rec_BE use record
+   I at 0 range 0 .. 31;
+end record;
+
+for Rec_BE'Bit_Order use System.High_Order_First;
+for Rec_BE'Scalar_Storage_Order use System.High_Order_First;
+
+R_LE : Rec_LE;
+
+R_BE : Rec_BE;
+for R_BE'Address use R_LE'Address;
+@end example
+
+@code{warning: overlay changes scalar storage order [enabled by default]}
+
+In most cases, such representation changes ought to be replaced by an
+instantiation of a function or procedure provided by @code{GNAT.Byte_Swapping}.
+
 Note that the scalar storage order only affects the in-memory data
 representation. It has no effect on the representation used by stream
 attributes.