Skip to content

R
riscv-gcc-1
Commit 156187ef by Hristian Kirtchev Committed by Pierre-Marie de Rodat
Options

[Ada] In-place initialization for Initialize_Scalars 

Update the documentation of pragma Initialize_Scalars in the GNAT
Reference Manual.

2019-07-08  Hristian Kirtchev  <kirtchev@adacore.com>

gcc/ada/

	* doc/gnat_rm/implementation_defined_pragmas.rst:
	Update the documentation of pragma Initialize_Scalars.
	* gnat_rm.texi: Regenerate.

From-SVN: r273220
parent fa2538c7
Showing with 180 additions and 101 deletions
gcc/ada/ChangeLog
2019-07-08 Hristian Kirtchev <kirtchev@adacore.com>
* doc/gnat_rm/implementation_defined_pragmas.rst:
Update the documentation of pragma Initialize_Scalars.
* gnat_rm.texi: Regenerate.
2019-07-08 Javier Miranda <miranda@adacore.com> 2019-07-08 Javier Miranda <miranda@adacore.com>
* exp_ch4.adb (Tagged_Membership): Fix regression silently * exp_ch4.adb (Tagged_Membership): Fix regression silently
......
gcc/ada/doc/gnat_rm/implementation_defined_pragmas.rst
...@@ -2999,58 +2999,87 @@ Syntax: ...@@ -2999,58 +2999,87 @@ Syntax:
.. code-block:: ada .. code-block:: ada
pragma Initialize_Scalars; pragma Initialize_Scalars
[ ( TYPE_VALUE_PAIR {, TYPE_VALUE_PAIR} ) ];
This pragma is similar to ``Normalize_Scalars`` conceptually but has TYPE_VALUE_PAIR ::=
two important differences. First, there is no requirement for the pragma SCALAR_TYPE => static_EXPRESSION
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, SCALAR_TYPE :=
without needing to recompile the run-time library. Short_Float
| Float
In the case where some units are compiled with the pragma, and some without, | Long_Float
then a declaration of a variable where the type is defined in package | Long_Long_Flat
Standard or is locally declared will always be subject to initialization, | Signed_8
as will any declaration of a scalar variable. For composite variables, | Signed_16
whether the variable is initialized may also depend on whether the package | Signed_32
in which the type of the variable is declared is compiled with the pragma. | Signed_64
| Unsigned_8
The other important difference is that you can control the value used | Unsigned_16
for initializing scalar objects. At bind time, you can select several | Unsigned_32
options for initialization. You can | Unsigned_64
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 This pragma is similar to ``Normalize_Scalars`` conceptually but has two
sizes). You can also initialize with high or important differences.
low values, or with a specified bit pattern. See the GNAT
User's Guide for binder options for specifying these cases. 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
This means that you can compile a program, and then without having to the application units of a partition, without needing to recompile the run-time
recompile the program, you can run it with different values being used library. In the case where some units are compiled with the pragma, and some
for initializing otherwise uninitialized values, to test if your program without, then a declaration of a variable where the type is defined in package
behavior depends on the choice. Of course the behavior should not change, Standard or is locally declared will always be subject to initialization, as
and if it does, then most likely you have an incorrect reference to an will any declaration of a scalar variable. For composite variables, whether the
uninitialized value. 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. The other important difference is that the programmer can control the value
See the GNAT User's Guide for details. used for initializing scalar objects. This effect can be achieved in several
different ways:
Note that pragma ``Initialize_Scalars`` is particularly useful in
conjunction with the enhanced validity checking that is now provided * At compile time, the programmer can specify the invalid value for a
in GNAT, which checks for invalid values under more conditions. particular family of scalar types using the optional arguments of the pragma.
Using this feature (see description of the *-gnatV* flag in the
GNAT User's Guide) in conjunction with The compile-time approach is intended to optimize the generated code for the
pragma ``Initialize_Scalars`` pragma, by possibly using fast operations such as ``memset``.
provides a powerful new tool to assist in the detection of problems
caused by uninitialized variables. * At bind time, the programmer has several options:
Note: the use of ``Initialize_Scalars`` has a fairly extensive * Initialization with invalid values (similar to Normalize_Scalars, though
effect on the generated code. This may cause your code to be for Initialize_Scalars it is not always possible to determine the invalid
substantially larger. It may also cause an increase in the amount values in complex cases like signed component fields with nonstandard
of stack required, so it is probably a good idea to turn on stack sizes).
checking (see description of stack checking in the GNAT
User's Guide) when using this pragma. * 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: 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: .. _Pragma-Initializes:
......
gcc/ada/gnat_rm.texi
...@@ -4441,58 +4441,102 @@ in the SPARK 2014 Reference Manual, section 7.1.6. ...@@ -4441,58 +4441,102 @@ in the SPARK 2014 Reference Manual, section 7.1.6.
Syntax: Syntax:
@example @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 @end example
This pragma is similar to @code{Normalize_Scalars} conceptually but has This pragma is similar to @code{Normalize_Scalars} conceptually but has two
two important differences. First, there is no requirement for the pragma important differences.
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, First, there is no requirement for the pragma to be used uniformly in all units
without needing to recompile the run-time library. 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
In the case where some units are compiled with the pragma, and some without, library. In the case where some units are compiled with the pragma, and some
then a declaration of a variable where the type is defined in package 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, Standard or is locally declared will always be subject to initialization, as
as will any declaration of a scalar variable. For composite variables, will any declaration of a scalar variable. For composite variables, whether the
whether the variable is initialized may also depend on whether the package variable is initialized may also depend on whether the package in which the
in which the type of the variable is declared is compiled with the pragma. type of the variable is declared is compiled with the pragma.
The other important difference is that you can control the value used The other important difference is that the programmer can control the value
for initializing scalar objects. At bind time, you can select several used for initializing scalar objects. This effect can be achieved in several
options for initialization. You can different ways:
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 @itemize *
sizes). You can also initialize with high or
low values, or with a specified bit pattern. See the GNAT @item
User's Guide for binder options for specifying these cases. At compile time, the programmer can specify the invalid value for a
particular family of scalar types using the optional arguments of the pragma.
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 The compile-time approach is intended to optimize the generated code for the
for initializing otherwise uninitialized values, to test if your program pragma, by possibly using fast operations such as @code{memset}.
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 @item
uninitialized value. At bind time, the programmer has several options:
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. @itemize *
See the GNAT User's Guide for details.
@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 Note: the use of @code{Initialize_Scalars} has a fairly extensive effect on the
conjunction with the enhanced validity checking that is now provided generated code. This may cause your code to be substantially larger. It may
in GNAT, which checks for invalid values under more conditions. also cause an increase in the amount of stack required, so it is probably a
Using this feature (see description of the @emph{-gnatV} flag in the good idea to turn on stack checking (see description of stack checking in the
GNAT User's Guide) in conjunction with GNAT User's Guide) when using this pragma.
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.
@node Pragma Initializes,Pragma Inline_Always,Pragma Initialize_Scalars,Implementation Defined Pragmas @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} @anchor{gnat_rm/implementation_defined_pragmas pragma-initializes}@anchor{83}@anchor{gnat_rm/implementation_defined_pragmas id17}@anchor{84}
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment