CbC/CbC_gcc: gcc/ada/doc/gnat_rm/implementation_defined

comparison gcc/ada/doc/gnat_rm/implementation_defined_pragmas.rst @ 145:1830386684a0

gcc-9.2.0

author	anatofuz
date	Thu, 13 Feb 2020 11:34:05 +0900
parents	84e7813d76e9
children

comparison

equal deleted inserted replaced

-:84e7813d76e9
+:1830386684a0
 This configuration pragma is a synonym for pragma Ada_12 and has the
 same syntax and effect.
+Pragma Aggregate_Individually_Assign
+====================================
+Syntax:
+.. code-block:: ada
+pragma Aggregate_Individually_Assign;
+Where possible, GNAT will store the binary representation of a record aggregate
+in memory for space and performance reasons. This configuration pragma changes
+this behavior so that record aggregates are instead always converted into
+individual assignment statements.
 Pragma Allow_Integer_Address
 ============================
 Syntax:
 the type of annotation.  GNAT verifies that it is an identifier, but does
 not otherwise analyze it. The second optional identifier is also left
 unanalyzed, and by convention is used to control the action of the tool to
 which the annotation is addressed.  The remaining ARG arguments
 can be either string literals or more generally expressions.
-String literals are assumed to be either of type
+String literals (and concatenations of string literals) are assumed to be
+either of type
 ``Standard.String`` or else ``Wide_String`` or ``Wide_Wide_String``
 depending on the character literals they contain.
 All other kinds of arguments are analyzed as expressions, and must be
 unambiguous. The last argument if present must have the identifier
 ``Entity`` and GNAT verifies that a local name is given.
 Syntax:
 .. code-block:: ada
-pragma Asynch_Readers [ (boolean_EXPRESSION) ];
+pragma Async_Readers [ (boolean_EXPRESSION) ];
 For the semantics of this pragma, see the entry for aspect ``Async_Readers`` in
 the SPARK 2014 Reference Manual, section 7.1.2.
 .. _Pragma-Async_Writers:
 Syntax:
 .. code-block:: ada
-pragma Asynch_Writers [ (boolean_EXPRESSION) ];
+pragma Async_Writers [ (boolean_EXPRESSION) ];
 For the semantics of this pragma, see the entry for aspect ``Async_Writers`` in
 the SPARK 2014 Reference Manual, section 7.1.2.
 Pragma Attribute_Definition
 The precondition ensures that one and only one of the case guards is
 satisfied on entry to the subprogram.
 The postcondition ensures that for the case guard that was True on entry,
-the corrresponding consequence is True on exit. Other consequence expressions
+the corresponding consequence is True on exit. Other consequence expressions
 are not evaluated.
 A precondition ``P`` and postcondition ``Q`` can also be
 expressed as contract cases:
 will be forced to all uppercase letters.  If ``Lowercase`` is specified,
 then the name will be forced to all lowercase letters.  A specification of
 ``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
 be used more locally to control individual Import/Export pragmas.
 Syntax:
 .. 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``. Note that such
-provides a powerful new tool to assist in the detection of problems
+optimizations require using values where the bytes all have the same binary
-caused by uninitialized variables.
+representation.
-Note: the use of ``Initialize_Scalars`` has a fairly extensive
+* At bind time, the programmer has several options:
-effect on the generated code. This may cause your code to be
-substantially larger. It may also cause an increase in the amount
+* Initialization with invalid values (similar to Normalize_Scalars, though
-of stack required, so it is probably a good idea to turn on stack
+for Initialize_Scalars it is not always possible to determine the invalid
-checking (see description of stack checking in the GNAT
+values in complex cases like signed component fields with nonstandard
-User's Guide) when using this pragma.
+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 specify 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
 ==================
 ``abort`` statement and stack overflow checking.
 Pragma ``Interrupt_State`` provides a general mechanism for overriding
 such uses of interrupts.  It subsumes the functionality of pragma
 ``Unreserve_All_Interrupts``.  Pragma ``Interrupt_State`` is not
-available on Windows or VMS.  On all other platforms than VxWorks,
+available on Windows.  On all other platforms than VxWorks,
 it applies to signals; on VxWorks, it applies to vectored hardware interrupts
 and may be used to mark interrupts required by the board support package
 as reserved.
 Interrupts can be in one of three states:
 This pragma may be specified for protected types or objects. It specifies that
 the implementation of protected operations must be implemented without locks.
 Compilation fails if the compiler cannot generate lock-free code for the
 operations.
+The current conditions required to support this pragma are:
+* Protected type declarations may not contain entries
+* Protected subprogram declarations may not have nonelementary parameters
+In addition, each protected subprogram body must satisfy:
+* May reference only one protected component
+* May not reference nonconstant entities outside the protected subprogram
+scope.
+* May not contain address representation items, allocators, or quantified
+expressions.
+* May not contain delay, goto, loop, or procedure-call statements.
+* May not contain exported and imported entities
+* May not dereferenced access values
+* Function calls and attribute references must be static
 Pragma Loop_Invariant
 =====================
 Syntax:
 ::
 pragma Machine_Attribute (
 [Entity         =>] LOCAL_NAME,
 [Attribute_Name =>] static_string_EXPRESSION
-[, [Info           =>] static_EXPRESSION] );
+[, [Info           =>] static_EXPRESSION {, static_EXPRESSION}] );
 Machine-dependent attributes can be specified for types and/or
 declarations.  This pragma is semantically equivalent to
 :samp:`__attribute__(({attribute_name}))` (if ``info`` is not
 specified) or :samp:`__attribute__(({attribute_name(info})))`
-in GNU C, where *attribute_name* is recognized by the
+or :samp:`__attribute__(({attribute_name(info,...})))` in GNU C,
-compiler middle-end or the ``TARGET_ATTRIBUTE_TABLE`` machine
+where *attribute_name* is recognized by the compiler middle-end
-specific macro.  A string literal for the optional parameter ``info``
+or the ``TARGET_ATTRIBUTE_TABLE`` machine specific macro.  Note
-is transformed into an identifier, which may make this pragma unusable
+that a string literal for the optional parameter ``info`` or the
-for some attributes.
+following ones is transformed by default into an identifier,
+which may make this pragma unusable for some attributes.
 For further information see :title:`GNU Compiler Collection (GCC) Internals`.
 Pragma Main
 ===========
 pragma Max_Entry_Queue (static_integer_EXPRESSION);
 This pragma is used to specify the maximum callers per entry queue for
 individual protected entries and entry families. It accepts a single
-positive integer as a parameter and must appear after the declaration
+integer (-1 or more) as a parameter and must appear after the declaration of an
-of an entry.
+entry.
+A value of -1 represents no additional restriction on queue length.
 Pragma No_Body
 ==============
 Syntax:
 This is particularly useful during maintenance when a package is modified in
 such a way that a body needed before is no longer needed. The provision of a
 dummy body with a No_Body pragma ensures that there is no interference from
 earlier versions of the package body.
+.. _Pragma-No_Caching:
+Pragma No_Caching
+=================
+Syntax:
+.. code-block:: ada
+pragma No_Caching [ (boolean_EXPRESSION) ];
+For the semantics of this pragma, see the entry for aspect ``No_Caching`` in
+the SPARK 2014 Reference Manual, section 7.1.2.
 Pragma No_Component_Reordering
 ==============================
 Syntax:
 statement sequence is a call to such a procedure.
 Note that in Ada 2005 mode, this pragma is part of the language. It is
 available in all earlier versions of Ada as an implementation-defined
 pragma.
-Pragma No_Run_Time
-==================
-Syntax:
-.. code-block:: ada
-pragma No_Run_Time;
-This is an obsolete configuration pragma that historically was used to
-set up a runtime library with no object code. It is now used only for
-internal testing. The pragma has been superseded by the reconfigurable
-runtime capability of GNAT.
 Pragma No_Strict_Aliasing
 =========================
 Syntax:
 file naming is controlled by Source_File_Name_Project pragmas, which are
 usually supplied automatically by the project manager. A pragma
 Source_File_Name cannot appear after a :ref:`Pragma_Source_File_Name_Project`.
 For more details on the use of the ``Source_File_Name`` pragma, see the
-sections on ``Using Other File Names`` and `Alternative File Naming Schemes'
+sections on `Using Other File Names` and `Alternative File Naming Schemes`
 in the :title:`GNAT User's Guide`.
 ..  _Pragma_Source_File_Name_Project:
 Pragma Source_File_Name_Project
 $ gcc -c -gnatVim ...
 The form ALL_CHECKS activates all standard checks (its use is equivalent
-to the use of the :switch:`gnatva` switch.
+to the use of the :switch:`gnatVa` switch).
-The forms with ``Off`` and ``On``
+The forms with ``Off`` and ``On`` can be used to temporarily disable
-can be used to temporarily disable validity checks
+validity checks as shown in the following example:
-as shown in the following example:
 .. code-block:: ada
 pragma Validity_Checks ("c"); -- validity checks for copies
 pragma Validity_Checks (Off); -- turn off validity checks
 A := B;                       -- B will not be validity checked
 pragma Validity_Checks (On);  -- turn validity checks back on
 A := C;                       -- C will be validity checked
+.. _Pragma-Volatile:
 Pragma Volatile
 ===============
 Syntax:
 This is similar in effect to pragma Volatile, except that any reference to the
 object is guaranteed to be done only with instructions that read or write all
 the bits of the object. Furthermore, if the object is of a composite type,
-then any reference to a component of the object is guaranteed to read and/or
+then any reference to a subcomponent of the object is guaranteed to read
-write all the bits of the object.
+and/or write all the bits of the object.
 The intention is that this be suitable for use with memory-mapped I/O devices
 on some machines. Note that there are two important respects in which this is
 different from ``pragma Atomic``. First a reference to a ``Volatile_Full_Access``
 object is not a sequential action in the RM 9.10 sense and, therefore, does
 there is no guarantee that all the bits will be accessed if the reference
 is not to the whole object; the compiler is allowed (and generally will)
 access only part of the object in this case.
 It is not permissible to specify ``Atomic`` and ``Volatile_Full_Access`` for
-the same object.
+the same type or object.
 It is not permissible to specify ``Volatile_Full_Access`` for a composite
-(record or array) type or object that has at least one ``Aliased`` component.
+(record or array) type or object that has an ``Aliased`` subcomponent.
 .. _Pragma-Volatile_Function:
 Pragma Volatile_Function
 ========================
 pragma Warning_As_Error (static_string_EXPRESSION);
 This configuration pragma allows the programmer to specify a set
-of warnings that will be treated as errors. Any warning which
+of warnings that will be treated as errors. Any warning that
 matches the pattern given by the pragma argument will be treated
-as an error. This gives much more precise control that -gnatwe
+as an error. This gives more precise control than -gnatwe,
-which treats all warnings as errors.
+which treats warnings as errors.
-The pattern may contain asterisks, which match zero or more characters in
+This pragma can apply to regular warnings (messages enabled by -gnatw)
-the message. For example, you can use
+and to style warnings (messages that start with "(style)",
-``pragma Warning_As_Error ("bits of*unused")`` to treat the warning
+enabled by -gnaty).
-message ``warning: 960 bits of "a" unused`` as an error. No other regular
-expression notations are permitted. All characters other than asterisk in
+The pattern may contain asterisks, which match zero or more characters
-these three specific cases are treated as literal characters in the match.
+in the message. For example, you can use ``pragma Warning_As_Error
-The match is case insensitive, for example XYZ matches xyz.
+("bits of*unused")`` to treat the warning message ``warning: 960 bits of
+"a" unused`` as an error. All characters other than asterisk are treated
+as literal characters in the match. The match is case insensitive; for
+example XYZ matches xyz.
 Note that the pattern matches if it occurs anywhere within the warning
 message string (it is not necessary to put an asterisk at the start and
 the end of the message, since this is implied).
 Another possibility for the static_string_EXPRESSION which works whether
-or not error tags are enabled (*-gnatw.d*) is to use the
+or not error tags are enabled (*-gnatw.d*) is to use a single
 *-gnatw* tag string, enclosed in brackets,
-as shown in the example below, to treat a class of warnings as errors.
+as shown in the example below, to treat one category of warnings as errors.
+Note that if you want to treat multiple categories of warnings as errors,
+you can use multiple pragma Warning_As_Error.
 The above use of patterns to match the message applies only to warning
 messages generated by the front end. This pragma can also be applied to
 warnings provided by the back end and mentioned in :ref:`Pragma_Warnings`.
 By using a single full *-Wxxx* switch in the pragma, such warnings
 asterisks since this looks like an operator name. This form with three
 asterisks is similar in effect to specifying ``pragma Warnings (Off)`` except (if :switch:`-gnatw.w` is given) that a matching
 ``pragma Warnings (On, "***")`` will be required. This can be
 helpful in avoiding forgetting to turn warnings back on.
-Note: the debug flag :switch:`-gnatd.i` (``/NOWARNINGS_PRAGMAS`` in VMS) can be
+Note: the debug flag :switch:`-gnatd.i` can be
 used to cause the compiler to entirely ignore all WARNINGS pragmas. This can
 be useful in checking whether obsolete pragmas in existing programs are hiding
 real problems.
 Note: pragma Warnings does not affect the processing of style messages. See

Mercurial > hg > CbC > CbC_gcc

comparison gcc/ada/doc/gnat_rm/implementation_defined_pragmas.rst @ 145:1830386684a0