[gcc r12-1462] [Ada] Clarify the semantics of signed intrinsic shift operations

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

https://gcc.gnu.org/g:688fb8553bd589d6cfc71de467f38ae725199da9

commit r12-1462-g688fb8553bd589d6cfc71de467f38ae725199da9
Author: Yannick Moy <moy@adacore.com>
Date:   Fri Feb 5 15:19:57 2021 +0100

    [Ada] Clarify the semantics of signed intrinsic shift operations
    
    gcc/ada/
    
            * doc/gnat_rm/intrinsic_subprograms.rst: More details on shift
            operations for signed types. Also add the missing Import and
            Convention on the example.
            * gnat_rm.texi: Regenerate.

Diff:
---
 gcc/ada/doc/gnat_rm/intrinsic_subprograms.rst | 14 ++++++++------
 gcc/ada/gnat_rm.texi                          | 14 ++++++++------
 2 files changed, 16 insertions(+), 12 deletions(-)

diff --git a/gcc/ada/doc/gnat_rm/intrinsic_subprograms.rst b/gcc/ada/doc/gnat_rm/intrinsic_subprograms.rst
index e448816572f..355b1399b2f 100644
--- a/gcc/ada/doc/gnat_rm/intrinsic_subprograms.rst
+++ b/gcc/ada/doc/gnat_rm/intrinsic_subprograms.rst
@@ -203,7 +203,8 @@ type (signed or modular), as in this example:
 
      function Shift_Left
        (Value  : T;
-        Amount : Natural) return T;
+        Amount : Natural) return T
+     with Import, Convention => Intrinsic;
 
 
 The function name must be one of
@@ -215,11 +216,12 @@ The result type must be the same as the type of ``Value``.
 The shift amount must be Natural.
 The formal parameter names can be anything.
 
-A more convenient way of providing these shift operators is to use
-the Provide_Shift_Operators pragma, which provides the function declarations
-and corresponding pragma Import's for all five shift functions. Note that in
-using these provided shift operations, shifts performed on negative numbers
-will result in modification of the sign bit.
+A more convenient way of providing these shift operators is to use the
+Provide_Shift_Operators pragma, which provides the function declarations and
+corresponding pragma Import's for all five shift functions. For signed types
+the semantics of these operators is to interpret the bitwise result of the
+corresponding operator for modular type. In particular, shifting a negative
+number may change its sign bit to positive.
 
 .. _Source_Location:
 
diff --git a/gcc/ada/gnat_rm.texi b/gcc/ada/gnat_rm.texi
index 68729da05df..8f0a370f684 100644
--- a/gcc/ada/gnat_rm.texi
+++ b/gcc/ada/gnat_rm.texi
@@ -17917,7 +17917,8 @@ type (signed or modular), as in this example:
 @example
 function Shift_Left
   (Value  : T;
-   Amount : Natural) return T;
+   Amount : Natural) return T
+with Import, Convention => Intrinsic;
 @end example
 
 The function name must be one of
@@ -17929,11 +17930,12 @@ The result type must be the same as the type of @code{Value}.
 The shift amount must be Natural.
 The formal parameter names can be anything.
 
-A more convenient way of providing these shift operators is to use
-the Provide_Shift_Operators pragma, which provides the function declarations
-and corresponding pragma Import's for all five shift functions. Note that in
-using these provided shift operations, shifts performed on negative numbers
-will result in modification of the sign bit.
+A more convenient way of providing these shift operators is to use the
+Provide_Shift_Operators pragma, which provides the function declarations and
+corresponding pragma Import's for all five shift functions. For signed types
+the semantics of these operators is to interpret the bitwise result of the
+corresponding operator for modular type. In particular, shifting a negative
+number may change its sign bit to positive.
 
 @node Source_Location,,Shifts and Rotates,Intrinsic Subprograms
 @anchor{gnat_rm/intrinsic_subprograms source-location}@anchor{274}@anchor{gnat_rm/intrinsic_subprograms id13}@anchor{275}