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 175 additions and 96 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>
* exp_ch4.adb (Tagged_Membership): Fix regression silently
......
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:
......
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}
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