From 156187ef87ef07d5004954785f4c0127e64d1a21 Mon Sep 17 00:00:00 2001 From: Hristian Kirtchev Date: Mon, 8 Jul 2019 08:14:36 +0000 Subject: [PATCH] [Ada] In-place initialization for Initialize_Scalars Update the documentation of pragma Initialize_Scalars in the GNAT Reference Manual. 2019-07-08 Hristian Kirtchev gcc/ada/ * doc/gnat_rm/implementation_defined_pragmas.rst: Update the documentation of pragma Initialize_Scalars. * gnat_rm.texi: Regenerate. From-SVN: r273220 --- gcc/ada/ChangeLog | 6 + .../implementation_defined_pragmas.rst | 121 +++++++++------ gcc/ada/gnat_rm.texi | 144 ++++++++++++------ 3 files changed, 175 insertions(+), 96 deletions(-) diff --git a/gcc/ada/ChangeLog b/gcc/ada/ChangeLog index 26927316f9e..badbe8f1a1b 100644 --- a/gcc/ada/ChangeLog +++ b/gcc/ada/ChangeLog @@ -1,3 +1,9 @@ +2019-07-08 Hristian Kirtchev + + * doc/gnat_rm/implementation_defined_pragmas.rst: + Update the documentation of pragma Initialize_Scalars. + * gnat_rm.texi: Regenerate. + 2019-07-08 Javier Miranda * exp_ch4.adb (Tagged_Membership): Fix regression silently diff --git a/gcc/ada/doc/gnat_rm/implementation_defined_pragmas.rst b/gcc/ada/doc/gnat_rm/implementation_defined_pragmas.rst index c2e4a4e9d58..dff7798ed7d 100644 --- a/gcc/ada/doc/gnat_rm/implementation_defined_pragmas.rst +++ b/gcc/ada/doc/gnat_rm/implementation_defined_pragmas.rst @@ -2432,7 +2432,7 @@ with Import and Export pragmas. There are two cases to consider: ``As_Is`` provides the normal default behavior in which the casing is taken from the string provided. -This pragma may appear anywhere that a pragma is valid. In particular, it +This pragma may appear anywhere that a pragma is valid. In particular, it can be used as a configuration pragma in the :file:`gnat.adc` file, in which case it applies to all subsequent compilations, or it can be used as a program unit pragma, in which case it only applies to the current unit, or it can @@ -2999,58 +2999,87 @@ Syntax: .. code-block:: ada - pragma Initialize_Scalars; + pragma Initialize_Scalars + [ ( TYPE_VALUE_PAIR {, TYPE_VALUE_PAIR} ) ]; + TYPE_VALUE_PAIR ::= + SCALAR_TYPE => static_EXPRESSION -This pragma is similar to ``Normalize_Scalars`` conceptually but has -two important differences. First, there is no requirement for the pragma -to be used uniformly in all units of a partition, in particular, it is fine -to use this just for some or all of the application units of a partition, -without needing to recompile the run-time library. + SCALAR_TYPE := + Short_Float + | Float + | Long_Float + | Long_Long_Flat + | Signed_8 + | Signed_16 + | Signed_32 + | Signed_64 + | Unsigned_8 + | Unsigned_16 + | Unsigned_32 + | Unsigned_64 -In the case where some units are compiled with the pragma, and some without, -then a declaration of a variable where the type is defined in package -Standard or is locally declared will always be subject to initialization, -as will any declaration of a scalar variable. For composite variables, -whether the variable is initialized may also depend on whether the package -in which the type of the variable is declared is compiled with the pragma. -The other important difference is that you can control the value used -for initializing scalar objects. At bind time, you can select several -options for initialization. You can -initialize with invalid values (similar to Normalize_Scalars, though for -Initialize_Scalars it is not always possible to determine the invalid -values in complex cases like signed component fields with non-standard -sizes). You can also initialize with high or -low values, or with a specified bit pattern. See the GNAT -User's Guide for binder options for specifying these cases. +This pragma is similar to ``Normalize_Scalars`` conceptually but has two +important differences. -This means that you can compile a program, and then without having to -recompile the program, you can run it with different values being used -for initializing otherwise uninitialized values, to test if your program -behavior depends on the choice. Of course the behavior should not change, -and if it does, then most likely you have an incorrect reference to an -uninitialized value. +First, there is no requirement for the pragma to be used uniformly in all units +of a partition. In particular, it is fine to use this just for some or all of +the application units of a partition, without needing to recompile the run-time +library. In the case where some units are compiled with the pragma, and some +without, then a declaration of a variable where the type is defined in package +Standard or is locally declared will always be subject to initialization, as +will any declaration of a scalar variable. For composite variables, whether the +variable is initialized may also depend on whether the package in which the +type of the variable is declared is compiled with the pragma. -It is even possible to change the value at execution time eliminating even -the need to rebind with a different switch using an environment variable. -See the GNAT User's Guide for details. +The other important difference is that the programmer can control the value +used for initializing scalar objects. This effect can be achieved in several +different ways: + +* At compile time, the programmer can specify the invalid value for a + particular family of scalar types using the optional arguments of the pragma. + + The compile-time approach is intended to optimize the generated code for the + pragma, by possibly using fast operations such as ``memset``. + +* At bind time, the programmer has several options: + + * Initialization with invalid values (similar to Normalize_Scalars, though + for Initialize_Scalars it is not always possible to determine the invalid + values in complex cases like signed component fields with nonstandard + sizes). + + * Initialization with high values. + + * Initialization with low values. + + * Initialization with a specific bit pattern. + + See the GNAT User's Guide for binder options for specifying these cases. + + The bind-time approach is intended to provide fast turnaround for testing + with different values, without having to recompile the program. + +* At execution time, the programmer can speify the invalid values using an + environment variable. See the GNAT User's Guide for details. + + The execution-time approach is intended to provide fast turnaround for + testing with different values, without having to recompile and rebind the + program. + +Note that pragma ``Initialize_Scalars`` is particularly useful in conjunction +with the enhanced validity checking that is now provided in GNAT, which checks +for invalid values under more conditions. Using this feature (see description +of the *-gnatV* flag in the GNAT User's Guide) in conjunction with pragma +``Initialize_Scalars`` provides a powerful new tool to assist in the detection +of problems caused by uninitialized variables. -Note that pragma ``Initialize_Scalars`` is particularly useful in -conjunction with the enhanced validity checking that is now provided -in GNAT, which checks for invalid values under more conditions. -Using this feature (see description of the *-gnatV* flag in the -GNAT User's Guide) in conjunction with -pragma ``Initialize_Scalars`` -provides a powerful new tool to assist in the detection of problems -caused by uninitialized variables. - -Note: the use of ``Initialize_Scalars`` has a fairly extensive -effect on the generated code. This may cause your code to be -substantially larger. It may also cause an increase in the amount -of stack required, so it is probably a good idea to turn on stack -checking (see description of stack checking in the GNAT -User's Guide) when using this pragma. +Note: the use of ``Initialize_Scalars`` has a fairly extensive effect on the +generated code. This may cause your code to be substantially larger. It may +also cause an increase in the amount of stack required, so it is probably a +good idea to turn on stack checking (see description of stack checking in the +GNAT User's Guide) when using this pragma. .. _Pragma-Initializes: diff --git a/gcc/ada/gnat_rm.texi b/gcc/ada/gnat_rm.texi index e67fb7beba4..b540e7bdd5d 100644 --- a/gcc/ada/gnat_rm.texi +++ b/gcc/ada/gnat_rm.texi @@ -3870,7 +3870,7 @@ then the name will be forced to all lowercase letters. A specification of taken from the string provided. @end itemize -This pragma may appear anywhere that a pragma is valid. In particular, it +This pragma may appear anywhere that a pragma is valid. In particular, it can be used as a configuration pragma in the @code{gnat.adc} file, in which case it applies to all subsequent compilations, or it can be used as a program unit pragma, in which case it only applies to the current unit, or it can @@ -4441,58 +4441,102 @@ in the SPARK 2014 Reference Manual, section 7.1.6. Syntax: @example -pragma Initialize_Scalars; +pragma Initialize_Scalars + [ ( TYPE_VALUE_PAIR @{, TYPE_VALUE_PAIR@} ) ]; + +TYPE_VALUE_PAIR ::= + SCALAR_TYPE => static_EXPRESSION + +SCALAR_TYPE := + Short_Float +| Float +| Long_Float +| Long_Long_Flat +| Signed_8 +| Signed_16 +| Signed_32 +| Signed_64 +| Unsigned_8 +| Unsigned_16 +| Unsigned_32 +| Unsigned_64 @end example -This pragma is similar to @code{Normalize_Scalars} conceptually but has -two important differences. First, there is no requirement for the pragma -to be used uniformly in all units of a partition, in particular, it is fine -to use this just for some or all of the application units of a partition, -without needing to recompile the run-time library. - -In the case where some units are compiled with the pragma, and some without, -then a declaration of a variable where the type is defined in package -Standard or is locally declared will always be subject to initialization, -as will any declaration of a scalar variable. For composite variables, -whether the variable is initialized may also depend on whether the package -in which the type of the variable is declared is compiled with the pragma. - -The other important difference is that you can control the value used -for initializing scalar objects. At bind time, you can select several -options for initialization. You can -initialize with invalid values (similar to Normalize_Scalars, though for -Initialize_Scalars it is not always possible to determine the invalid -values in complex cases like signed component fields with non-standard -sizes). You can also initialize with high or -low values, or with a specified bit pattern. See the GNAT -User's Guide for binder options for specifying these cases. - -This means that you can compile a program, and then without having to -recompile the program, you can run it with different values being used -for initializing otherwise uninitialized values, to test if your program -behavior depends on the choice. Of course the behavior should not change, -and if it does, then most likely you have an incorrect reference to an -uninitialized value. - -It is even possible to change the value at execution time eliminating even -the need to rebind with a different switch using an environment variable. -See the GNAT User's Guide for details. +This pragma is similar to @code{Normalize_Scalars} conceptually but has two +important differences. + +First, there is no requirement for the pragma to be used uniformly in all units +of a partition. In particular, it is fine to use this just for some or all of +the application units of a partition, without needing to recompile the run-time +library. In the case where some units are compiled with the pragma, and some +without, then a declaration of a variable where the type is defined in package +Standard or is locally declared will always be subject to initialization, as +will any declaration of a scalar variable. For composite variables, whether the +variable is initialized may also depend on whether the package in which the +type of the variable is declared is compiled with the pragma. + +The other important difference is that the programmer can control the value +used for initializing scalar objects. This effect can be achieved in several +different ways: + + +@itemize * + +@item +At compile time, the programmer can specify the invalid value for a +particular family of scalar types using the optional arguments of the pragma. + +The compile-time approach is intended to optimize the generated code for the +pragma, by possibly using fast operations such as @code{memset}. + +@item +At bind time, the programmer has several options: + + +@itemize * + +@item +Initialization with invalid values (similar to Normalize_Scalars, though +for Initialize_Scalars it is not always possible to determine the invalid +values in complex cases like signed component fields with nonstandard +sizes). + +@item +Initialization with high values. + +@item +Initialization with low values. + +@item +Initialization with a specific bit pattern. +@end itemize + +See the GNAT User's Guide for binder options for specifying these cases. + +The bind-time approach is intended to provide fast turnaround for testing +with different values, without having to recompile the program. + +@item +At execution time, the programmer can speify the invalid values using an +environment variable. See the GNAT User's Guide for details. + +The execution-time approach is intended to provide fast turnaround for +testing with different values, without having to recompile and rebind the +program. +@end itemize + +Note that pragma @code{Initialize_Scalars} is particularly useful in conjunction +with the enhanced validity checking that is now provided in GNAT, which checks +for invalid values under more conditions. Using this feature (see description +of the @emph{-gnatV} flag in the GNAT User's Guide) in conjunction with pragma +@code{Initialize_Scalars} provides a powerful new tool to assist in the detection +of problems caused by uninitialized variables. -Note that pragma @code{Initialize_Scalars} is particularly useful in -conjunction with the enhanced validity checking that is now provided -in GNAT, which checks for invalid values under more conditions. -Using this feature (see description of the @emph{-gnatV} flag in the -GNAT User's Guide) in conjunction with -pragma @code{Initialize_Scalars} -provides a powerful new tool to assist in the detection of problems -caused by uninitialized variables. - -Note: the use of @code{Initialize_Scalars} has a fairly extensive -effect on the generated code. This may cause your code to be -substantially larger. It may also cause an increase in the amount -of stack required, so it is probably a good idea to turn on stack -checking (see description of stack checking in the GNAT -User's Guide) when using this pragma. +Note: the use of @code{Initialize_Scalars} has a fairly extensive effect on the +generated code. This may cause your code to be substantially larger. It may +also cause an increase in the amount of stack required, so it is probably a +good idea to turn on stack checking (see description of stack checking in the +GNAT User's Guide) when using this pragma. @node Pragma Initializes,Pragma Inline_Always,Pragma Initialize_Scalars,Implementation Defined Pragmas @anchor{gnat_rm/implementation_defined_pragmas pragma-initializes}@anchor{83}@anchor{gnat_rm/implementation_defined_pragmas id17}@anchor{84} -- 2.30.2