Skip to content

R
riscv-gcc-1
Commit e4779ba4 by Arnaud Charlet
Options

Updaate documentation. 

From-SVN: r230317
parent 90b510e4
Showing with 141 additions and 94 deletions
gcc/ada/doc/gnat_rm/compatibility_and_porting_guide.rst
......@@ -471,8 +471,8 @@ Elaboration order
The implementation can choose any elaboration order consistent with the unit
dependency relationship. This freedom means that some orders can result in
Program_Error being raised due to an 'Access Before Elaboration': an attempt
to invoke a subprogram its body has been elaborated, or to instantiate a
generic before the generic body has been elaborated. By default GNAT
to invoke a subprogram before its body has been elaborated, or to instantiate
a generic before the generic body has been elaborated. By default GNAT
attempts to choose a safe order (one that will not encounter access before
elaboration problems) by implicitly inserting `Elaborate` or
`Elaborate_All` pragmas where
......
gcc/ada/doc/gnat_rm/implementation_defined_pragmas.rst
......@@ -283,18 +283,7 @@ The string argument, if given, is the message that will be associated
with the exception occurrence if the exception is raised. If no second
argument is given, the default message is `file`:`nnn`,
where `file` is the name of the source file containing the assert,
and `nnn` is the line number of the assert. A pragma is not a
statement, so if a statement sequence contains nothing but a pragma
assert, then a null statement is required in addition, as in:
.. code-block:: ada
...
if J > 3 then
pragma Assert (K > 3, "Bad value for K");
null;
end if;
and `nnn` is the line number of the assert.
Note that, as with the `if` statement to which it is equivalent, the
type of the expression is either `Standard.Boolean`, or any type derived
......@@ -4600,14 +4589,14 @@ Syntax:
.. code-block:: ada
pragma Profile (Ravenscar | Restricted | Rational);
pragma Profile (Ravenscar | Restricted | Rational | GNAT_Extended_Ravenscar);
This pragma is standard in Ada 2005, but is available in all earlier
versions of Ada as an implementation-defined pragma. This is a
configuration pragma that establishes a set of configuration pragmas
that depend on the argument. `Ravenscar` is standard in Ada 2005.
The other two possibilities (`Restricted` or `Rational`)
The other possibilities (`Restricted`, `Rational`, `GNAT_Extended_Ravenscar`)
are implementation-defined. The set of configuration pragmas
is defined in the following sections.
......@@ -4720,6 +4709,20 @@ is defined in the following sections.
automatically causes the use of a simplified,
more efficient version of the tasking run-time library.
* Pragma Profile (GNAT_Extended_Ravenscar)
This profile corresponds to a GNAT specific extension of the
Ravenscar profile. The profile may change in the future although
only in a compatible way: some restrictions may be removed or
relaxed. It is defined as a variation of the Ravenscar profile.
The ``No_Implicit_Heap_Allocations`` restriction has been replaced
by ``No_Implicit_Task_Allocations`` and
``No_Implicit_Protected_Object_Allocations``.
The ``Simple_Barriers`` restriction has been replaced by
``Pure_Barriers``.
* Pragma Profile (Restricted)
This profile corresponds to the GNAT restricted run time. It
......@@ -6047,8 +6050,8 @@ Syntax:
This pragma specifies that the specified entity, which must be
a variable declared in a library level package, is to be marked as
"Thread Local Storage" (`TLS`). On systems supporting this (which
include Solaris, GNU/Linux and VxWorks 6), this causes each thread
(and hence each Ada task) to see a distinct copy of the variable.
include Windows, Solaris, GNU/Linux and VxWorks 6), this causes each
thread (and hence each Ada task) to see a distinct copy of the variable.
The variable may not have default initialization, and if there is
an explicit initialization, it must be either `null` for an
......
gcc/ada/doc/gnat_rm/representation_clauses_and_pragmas.rst
......@@ -1662,11 +1662,10 @@ or alternatively, using the form recommended by the RM:
for B'Address use Addr;
In both of these cases, `A`
and `B` become aliased to one another via the
address clause. This use of address clauses to overlay
variables, achieving an effect similar to unchecked
conversion was erroneous in Ada 83, but in Ada 95 and Ada 2005
In both of these cases, `A` and `B` become aliased to one another
via the address clause. This use of address clauses to overlay
variables, achieving an effect similar to unchecked conversion
was erroneous in Ada 83, but in Ada 95 and Ada 2005
the effect is implementation defined. Furthermore, the
Ada RM specifically recommends that in a situation
like this, `B` should be subject to the following
......@@ -1677,10 +1676,14 @@ implementation advice (RM 13.3(19)):
optimizations based on assumptions of no aliases."
GNAT follows this recommendation, and goes further by also applying
this recommendation to the overlaid variable (`A`
in the above example) in this case. This means that the overlay
works "as expected", in that a modification to one of the variables
will affect the value of the other.
this recommendation to the overlaid variable (`A` in the above example)
in this case. This means that the overlay works "as expected", in that
a modification to one of the variables will affect the value of the other.
More generally, GNAT interprets this recommendation conservatively for
address clauses: in the cases other than overlays, it considers that the
object is effectively subject to pragma `Volatile` and implements the
associated semantics.
Note that when address clause overlays are used in this way, there is an
issue of unintentional initialization, as shown by this example:
......@@ -1803,12 +1806,9 @@ operations, for example:
Temp.A := 32;
Mem := Temp;
For a full access (reference or modification) of the variable (Mem) in
this case, as in the above examples, GNAT guarantees that the entire atomic
word will be accessed. It is not clear whether the RM requires this. For
example in the above, can the compiler reference only the Mem.A field as
an optimization? Whatever the answer to this question is, GNAT makes the
guarantee that for such a reference, the entire word is read or written.
For a full access (reference or modification) of the variable (Mem) in this
case, as in the above examples, GNAT guarantees that the entire atomic word
will be accessed, in accordance with the RM C.6(15) clause.
A problem arises with a component access such as:
......@@ -1834,6 +1834,9 @@ a warning in such a case:
It is best to be explicit in this situation, by either declaring the
components to be atomic if you want the byte store, or explicitly writing
the full word access sequence if that is what the hardware requires.
Alternatively, if the full word access sequence is required, GNAT also
provides the pragma `Volatile_Full_Access` which can be used in lieu of
pragma `Atomic` and will give the additional guarantee.
.. _Effect_of_Convention_on_Representation:
......
gcc/ada/doc/gnat_rm/standard_and_implementation_defined_restrictions.rst
......@@ -461,14 +461,14 @@ scalar components.
No_Implicit_Protected_Object_Allocations
----------------------------------------
.. index: No_Implicit_Protected_Object_Allocations
.. index:: No_Implicit_Protected_Object_Allocations
[GNAT] No constructs are allowed to cause implicit heap allocation of a
protected object.
No_Implicit_Task_Allocations
----------------------------
.. index: No_Implicit_Task_Allocations
.. index:: No_Implicit_Task_Allocations
[GNAT] No constructs are allowed to cause implicit heap allocation of a task.
......@@ -765,6 +765,29 @@ where ``Name`` is the fully qualified entity, for example ::
No_Use_Of_Entity => Ada.Text_IO.Put_Line
Pure_Barriers
-------------
.. index:: Pure_Barriers
[GNAT] This restriction ensures at compile time that protected entry
barriers are restricted to:
* simple boolean variables defined in the private part of the
protected type/object,
* constant declarations,
* named numbers,
* enumeration literals,
* integer literals,
* real literals,
* character literals,
* implicitly defined comparison operators,
* uses of the Standard."not" operator,
* short-circuit operator
This restriction is a relaxation of the Simple_Barriers restriction,
but still ensures absence of side effects, exceptions, and recursion
during the evaluation of the barriers.
Simple_Barriers
---------------
.. index:: Simple_Barriers
......@@ -858,7 +881,7 @@ code generation. If it is used in conjunction with "semantics only"
checking, then some cases of violations may be missed.
No_Dynamic_Sized_Objects
--------------
------------------------
.. index:: No_Dynamic_Sized_Objects
[GNAT] This restriction disallows certain constructs that might lead to the
......
gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst
......@@ -1928,23 +1928,25 @@ Alphabetical List of All Switches
*3* Eliminate intermediate overflows (`ELIMINATED`)
===== ===============================================================
If only one digit appears then it applies to all
If only one digit appears, then it applies to all
cases; if two digits are given, then the first applies outside
assertions, and the second within assertions.
assertions, pre/postconditions, and type invariants, and the second
applies within assertions, pre/postconditions, and type invariants.
If no digits follow the *-gnato*, then it is equivalent to
*-gnato11*,
causing all intermediate overflows to be handled in strict mode.
causing all intermediate overflows to be handled in strict
mode.
This switch also causes arithmetic overflow checking to be performed
(as though `pragma Unsuppress (Overflow_Mode)` had been specified.
(as though `pragma Unsuppress (Overflow_Mode)` had been specified).
The default if no option *-gnato* is given is that overflow handling
is in `STRICT` mode (computations done using the base type), and that
overflow checking is enabled.
Note that division by zero is a separate check that is not
controlled by this switch (division by zero checking is on by default).
controlled by this switch (divide-by-zero checking is on by default).
See also :ref:`Specifying_the_Desired_Mode`.
......@@ -4038,31 +4040,64 @@ Debugging and Assertion Control
.. index:: Assert
.. index:: Debug
.. index:: Assertions
.. index:: Precondition
.. index:: Postcondition
.. index:: Type invariants
.. index:: Subtype predicates
The `-gnata` option is equivalent to the following Assertion_Policy pragma::
pragma Assertion_Policy (Check);
Which is a shorthand for::
pragma Assertion_Policy
(Assert => Check,
Static_Predicate => Check,
Dynamic_Predicate => Check,
Pre => Check,
Pre'Class => Check,
Post => Check,
Post'Class => Check,
Type_Invariant => Check,
Type_Invariant'Class => Check);
The pragmas `Assert` and `Debug` normally have no effect and
are ignored. This switch, where :samp:`a` stands for assert, causes
`Assert` and `Debug` pragmas to be activated.
pragmas `Assert` and `Debug` to be activated. This switch also
causes preconditions, postconditions, subtype predicates, and
type invariants to be activated.
The pragmas have the form::
pragma Assert (<Boolean-expression> [, <static-string-expression>])
pragma Debug (<procedure call>)
pragma Type_Invariant (<type-local-name>, <Boolean-expression>)
pragma Predicate (<type-local-name>, <Boolean-expression>)
pragma Precondition (<Boolean-expression>, <string-expression>)
pragma Postcondition (<Boolean-expression>, <string-expression>)
The aspects have the form::
with [Pre|Post|Type_Invariant|Dynamic_Predicate|Static_Predicate]
=> <Boolean-expression>;
The `Assert` pragma causes `Boolean-expression` to be tested.
If the result is `True`, the pragma has no effect (other than
possible side effects from evaluating the expression). If the result is
`False`, the exception `Assert_Failure` declared in the package
`System.Assertions` is
raised (passing `static-string-expression`, if present, as the
message associated with the exception). If no string expression is
given the default is a string giving the file name and line number
of the pragma.
`System.Assertions` is raised (passing `static-string-expression`, if
present, as the message associated with the exception). If no string
expression is given, the default is a string containing the file name and
line number of the pragma.
The `Debug` pragma causes `procedure` to be called. Note that
`pragma Debug` may appear within a declaration sequence, allowing
debugging procedures to be called between declarations.
For the aspect specification, the `<Boolean-expression>` is evaluated.
If the result is `True`, the aspect has no effect. If the result
is `False`, the exception `Assert_Failure` is raised.
.. _Validity_Checking:
......@@ -4871,11 +4906,11 @@ Run-Time Checks
.. index:: Checks, stack overflow checking
By default, the following checks are suppressed: integer overflow
checks, stack overflow checks, and checks for access before
elaboration on subprogram calls. All other checks, including range
checks and array bounds checks, are turned on by default. The
following *gcc* switches refine this default behavior.
By default, the following checks are suppressed: stack overflow
checks, and checks for access before elaboration on subprogram
calls. All other checks, including overflow checks, range checks and
array bounds checks, are turned on by default. The following *gcc*
switches refine this default behavior.
.. index:: -gnatp (gcc)
......@@ -5003,13 +5038,8 @@ following *gcc* switches refine this default behavior.
checking is also quite expensive in time and space, since in general it
requires the use of double length arithmetic.
Note again that the default is *-gnato00*,
so overflow checking is not performed in default mode. This means that out of
the box, with the default settings, GNAT does not do all the checks
expected from the language description in the Ada Reference Manual.
If you want all constraint checks to be performed, as described in this Manual,
then you must explicitly use the *-gnato??*
switch either on the *gnatmake* or *gcc* command.
Note again that the default is *-gnato11* (equivalent to *-gnato1*),
so overflow checking is performed in STRICT mode by default.
.. index:: -gnatE (gcc)
......@@ -6897,7 +6927,7 @@ Here are some examples of `gnatbind` invovations:
Linking with *gnatlink*
=======================
.. index: ! gnatlink
.. index:: ! gnatlink
This chapter discusses *gnatlink*, a tool that links
an Ada program and builds an executable file. This utility
......
gcc/ada/doc/gnat_ugn/gnat_and_program_execution.rst
......@@ -1447,26 +1447,20 @@ some guidelines on debugging optimized code.
Controlling Run-Time Checks
^^^^^^^^^^^^^^^^^^^^^^^^^^^
By default, GNAT generates all run-time checks, except integer overflow
checks, stack overflow checks, and checks for access before elaboration on
subprogram calls. The latter are not required in default mode, because all
By default, GNAT generates all run-time checks, except stack overflow
checks, and checks for access before elaboration on subprogram
calls. The latter are not required in default mode, because all
necessary checking is done at compile time.
.. index:: -gnatp (gcc)
.. index:: -gnato (gcc)
Two gnat switches, *-gnatp* and *-gnato* allow this default to
be modified. See :ref:`Run-Time_Checks`.
The gnat switch, *-gnatp* allows this default to be modified. See
:ref:`Run-Time_Checks`.
Our experience is that the default is suitable for most development
purposes.
We treat integer overflow specially because these
are quite expensive and in our experience are not as important as other
run-time checks in the development process. Note that division by zero
is not considered an overflow check, and divide by zero checks are
generated where required by default.
Elaboration checks are off by default, and also not needed by default, since
GNAT uses a static elaboration analysis approach that avoids the need for
run-time checking. This manual contains a full chapter discussing the issue
......@@ -1942,11 +1936,9 @@ contain a single nested loop, if it can be vectorized when considered alone:
The vectorizable operations depend on the targeted SIMD instruction set, but
the adding and some of the multiplying operators are generally supported, as
well as the logical operators for modular types. Note that, in the former
case, enabling overflow checks, for example with *-gnato*, totally
disables vectorization. The other checks are not supposed to have the same
definitive effect, although compiling with *-gnatp* might well reveal
cases where some checks do thwart vectorization.
well as the logical operators for modular types. Note that compiling
with *-gnatp* might well reveal cases where some checks do thwart
vectorization.
Type conversions may also prevent vectorization if they involve semantics that
are not directly supported by the code generator or the SIMD instruction set.
......@@ -3197,10 +3189,6 @@ If no digits follow the *-gnato*, then it is equivalent to
causing all intermediate operations to be computed using the base
type (`STRICT` mode).
In addition to setting the mode used for computation of intermediate
results, the `-gnato` switch also enables overflow checking (which
is suppressed by default). It thus combines the effect of using
a pragma `Overflow_Mode` and pragma `Unsuppress`.
.. _Default_Settings:
......
gcc/ada/doc/gnat_ugn/gnat_project_manager.rst
......@@ -259,7 +259,7 @@ There are several ways of defining source directories:
file names for the roots of these undesirable directory subtrees.
.. code-block: ada-project
.. code-block:: gpr
for Source_Dirs use ("./**");
for Ignore_Source_Sub_Dirs use (".svn");
......@@ -270,7 +270,7 @@ the project file at the toplevel directory rather than mixed with the sources,
we will create the following file
.. code-block: ada-project
.. code-block:: gpr
build.gpr
project Build is
......@@ -420,7 +420,7 @@ the project directory, that is the directory containing the project file.
For our example, we can specify the object dir in this way:
.. code-block: ada-project
.. code-block:: gpr
project Build is
for Source_Dirs use ("common");
......@@ -452,7 +452,7 @@ In the case of the example, let's place the executable in the root
of the hierarchy, ie the same directory as :file:`build.gpr`. Hence
the project file is now
.. code-block: ada-project
.. code-block:: gpr
project Build is
for Source_Dirs use ("common");
......@@ -489,7 +489,7 @@ command line when invoking a builder, and editors like
*GPS* will be able to create extra menus to spawn or debug the
corresponding executables.
.. code-block: ada-project
.. code-block:: gpr
project Build is
for Source_Dirs use ("common");
......@@ -557,7 +557,7 @@ Our example project file can be extended with the following empty packages. At
this stage, they could all be omitted since they are empty, but they show which
packages would be involved in the build process.
.. code-block: ada-project
.. code-block:: gpr
project Build is
for Source_Dirs use ("common");
......@@ -603,7 +603,7 @@ Several attributes can be used to specify the switches:
*-O2*, and the resulting project file is as follows
(only the `Compiler` package is shown):
.. code-block: ada-project
.. code-block:: gpr
package Compiler is
for Default_Switches ("Ada") use ("-O2");
......@@ -621,7 +621,7 @@ Several attributes can be used to specify the switches:
switches defined by *Default_Switches*. Our project file would
become:
.. code-block: ada-project
.. code-block:: gpr
package Compiler is
......@@ -634,7 +634,7 @@ Several attributes can be used to specify the switches:
`Switches` may take a pattern as an index, such as in:
.. code-block: ada-project
.. code-block:: gpr
package Compiler is
for Default_Switches ("Ada")
......@@ -1793,7 +1793,7 @@ but, for some reason, cannot be rebuilt. For instance, it is the case when some
of the library sources are not available. Such library projects need to use the
`Externally_Built` attribute as in the example below:
.. code-block: ada-project
.. code-block:: gpr
library project Extern_Lib is
for Languages use ("Ada", "C");
......@@ -3180,7 +3180,7 @@ The following packages are currently supported in project files
or given a file name to find out its language for proper processing.
See :ref:`Naming_Schemes`.
.. only: PRO or GPL
.. only:: PRO or GPL
*Pretty_Printer*
This package specifies the options used when calling the formatting tool
......
gcc/ada/doc/gnat_ugn/platform_specific_information.rst
......@@ -2186,7 +2186,7 @@ binding you need to use a project file, and adding a single with_clause
will give you full access to the Win32Ada binding sources and ensure
that the proper libraries are passed to the linker.
.. code-block:: ada-project
.. code-block:: gpr
with "win32ada";
project P is
......@@ -2213,7 +2213,7 @@ To use the wPOSIX binding you need to use a project file, and adding
a single with_clause will give you full access to the wPOSIX binding
sources and ensure that the proper libraries are passed to the linker.
.. code-block:: ada-project
.. code-block:: gpr
with "wposix";
project P is
......
gcc/ada/doc/gnat_ugn/the_gnat_compilation_model.rst
......@@ -3629,7 +3629,7 @@ Convention identifiers are recognized by GNAT:
to perform dimensional checks:
.. code-block: ada
.. code-block:: ada
type Distance is new Long_Float;
type Time is new Long_Float;
......
gcc/ada/gnat_rm.texi
This source diff could not be displayed because it is too large. You can view the blob instead.
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