From: Yannick Moy <moy@adacore.com>
Date: Fri, 5 Feb 2021 14:19:57 +0000 (+0100)
Subject: [Ada] Clarify the semantics of signed intrinsic shift operations
X-Git-Tag: basepoints/gcc-13~6851
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=688fb8553bd589d6cfc71de467f38ae725199da9;p=thirdparty%2Fgcc.git

[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 --git a/gcc/ada/doc/gnat_rm/intrinsic_subprograms.rst b/gcc/ada/doc/gnat_rm/intrinsic_subprograms.rst
index e448816572fd..355b1399b2f8 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 68729da05df3..8f0a370f6842 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}