gnat_rm.texi, [...]: Update documentation.

	* gnat_rm.texi, gnat_ugn.texi,
	doc/gnat_ugn/building_executable_programs_with_gnat.rst,
	doc/gnat_ugn/platform_specific_information.rst,
	doc/gnat_ugn/gnat_and_program_execution.rst,
	doc/gnat_ugn/gnat_utility_programs.rst,
	doc/gnat_ugn/the_gnat_compilation_model.rst,
	doc/gnat_rm/implementation_defined_attributes.rst,
	doc/gnat_rm/the_gnat_library.rst,
	doc/gnat_rm/implementation_defined_pragmas.rst,
	doc/gnat_rm/representation_clauses_and_pragmas.rst,
	doc/gnat_rm/implementation_of_specific_ada_features.rst,
	doc/gnat_rm/implementation_defined_aspects.rst,
	doc/gnat_rm/implementation_defined_characteristics.rst: Update
	documentation.

From-SVN: r247253

gcc/ada/ChangeLog

 2017-04-25  Arnaud Charlet  <charlet@adacore.com>
 
+	* gnat_rm.texi, gnat_ugn.texi,
+	doc/gnat_ugn/building_executable_programs_with_gnat.rst,
+	doc/gnat_ugn/platform_specific_information.rst,
+	doc/gnat_ugn/gnat_and_program_execution.rst,
+	doc/gnat_ugn/gnat_utility_programs.rst,
+	doc/gnat_ugn/the_gnat_compilation_model.rst,
+	doc/gnat_rm/implementation_defined_attributes.rst,
+	doc/gnat_rm/the_gnat_library.rst,
+	doc/gnat_rm/implementation_defined_pragmas.rst,
+	doc/gnat_rm/representation_clauses_and_pragmas.rst,
+	doc/gnat_rm/implementation_of_specific_ada_features.rst,
+	doc/gnat_rm/implementation_defined_aspects.rst,
+	doc/gnat_rm/implementation_defined_characteristics.rst: Update
+	documentation.
+
+2017-04-25  Arnaud Charlet  <charlet@adacore.com>
+
 	* exp_ch4.adb (Expand_N_Case_Expression): Emit error message when
 	generating C code on complex case expressions.
 

gcc/ada/doc/gnat_rm/implementation_defined_aspects.rst

@@ -66,8 +66,9 @@ Aspect Abstract_State
 
 This aspect is equivalent to :ref:`pragma Abstract_State<Pragma-Abstract_State>`.
 
-Annotate
-========
+Aspect Annotate
+===============
+
 .. index:: Annotate
 
 There are three forms of this aspect (where ID is an identifier,
@@ -147,7 +148,7 @@ used when doing formatted output of dimensioned quantities. The syntax is::
 
 
 This aspect can only be applied to a subtype whose parent type has
-a `Dimension_Systen` aspect. The aspect must specify values for
+a `Dimension_System` aspect. The aspect must specify values for
 all dimensions of the system. The rational values are the powers of the
 corresponding dimensions that are used by the compiler to verify that
 physical (numeric) computations are dimensionally consistent. For example,
@@ -361,7 +362,6 @@ This boolean aspect is equivalent to :ref:`pragma Lock_Free<Pragma-Lock_Free>`.
 
 Aspect Max_Queue_Length
 =======================
-
 .. index:: Max_Queue_Length
 
 This aspect is equivalent to :ref:`pragma Max_Queue_Length<Pragma-Max_Queue_Length>`.

gcc/ada/doc/gnat_rm/implementation_defined_attributes.rst

@@ -1168,7 +1168,7 @@ used in contexts (e.g., preelaborable packages) which require a
 static expression and where the function call could not be used
 (since the function call is always nonstatic, even if its
 argument is static). The argument must be in the range
--(2**(m-1) .. 2**m-1, where m is the memory size
+-(2**(m-1)) .. 2**m-1, where m is the memory size
 (typically 32 or 64). Negative values are intepreted in a
 modular manner (e.g., -1 means the same as 16#FFFF_FFFF# on
 a 32 bits machine).

gcc/ada/doc/gnat_rm/implementation_defined_characteristics.rst

@@ -986,13 +986,13 @@ The policy is the same as that of the underlying threads implementation.
   in a pragma `Locking_Policy`.  See D.3(4)."
 
 The two implementation defined policies permitted in GNAT are
-`Inheritance_Locking` and  `Conccurent_Readers_Locking`.  On
+`Inheritance_Locking` and  `Concurrent_Readers_Locking`. On
 targets that support the `Inheritance_Locking` policy, locking is
 implemented by inheritance, i.e., the task owning the lock operates
 at a priority equal to the highest priority of any task currently
 requesting the lock. On targets that support the
-`Conccurent_Readers_Locking` policy, locking is implemented with a
-read/write lock allowing multiple propected object functions to enter
+`Concurrent_Readers_Locking` policy, locking is implemented with a
+read/write lock allowing multiple protected object functions to enter
 concurrently.
 
 *

gcc/ada/doc/gnat_rm/implementation_defined_pragmas.rst

@@ -1203,9 +1203,9 @@ following is an example of use within a package spec:
   package Math_Functions is
      ...
      function Sqrt (Arg : Float) return Float;
-     pragma Contract_Cases ((Arg in 0 .. 99) => Sqrt'Result < 10,
-                            Arg >= 100       => Sqrt'Result >= 10,
-                            others           => Sqrt'Result = 0);
+     pragma Contract_Cases (((Arg in 0.0 .. 99.0) => Sqrt'Result < 10.0,
+                             Arg >= 100.0         => Sqrt'Result >= 10.0,
+                             others               => Sqrt'Result = 0.0));
      ...
   end Math_Functions;
 
@@ -1380,6 +1380,21 @@ This pragma is standard in Ada 2012, but is available in all earlier
 versions of Ada as an implementation-defined pragma.
 See Ada 2012 Reference Manual for details.
 
+Pragma Deadline_Floor
+=====================
+
+Syntax:
+
+
+.. code-block:: ada
+
+  pragma Deadline_Floor (time_span_EXPRESSION);
+
+
+This pragma applies only to protected types and specifies the floor
+deadline inherited by a task when the task enters a protected object.
+It is effective only when the EDF scheduling policy is used.
+
 .. _Pragma-Default_Initial_Condition:
 
 Pragma Default_Initial_Condition
@@ -2248,14 +2263,13 @@ Syntax:
   pragma Favor_Top_Level (type_NAME);
 
 
-The named type must be an access-to-subprogram type. This pragma is an
-efficiency hint to the compiler, regarding the use of 'Access or
-'Unrestricted_Access on nested (non-library-level) subprograms. The
-pragma means that nested subprograms are not used with this type, or
-are rare, so that the generated code should be efficient in the
-top-level case. When this pragma is used, dynamically generated
-trampolines may be used on some targets for nested subprograms.
-See also the No_Implicit_Dynamic_Code restriction.
+The argument of pragma `Favor_Top_Level` must be a named access-to-subprogram
+type. This pragma is an efficiency hint to the compiler, regarding the use of
+`'Access` or `'Unrestricted_Access` on nested (non-library-level) subprograms.
+The pragma means that nested subprograms are not used with this type, or are
+rare, so that the generated code should be efficient in the top-level case.
+When this pragma is used, dynamically generated trampolines may be used on some
+targets for nested subprograms. See restriction `No_Implicit_Dynamic_Code`.
 
 Pragma Finalize_Storage_Only
 ============================
@@ -2268,11 +2282,14 @@ Syntax:
   pragma Finalize_Storage_Only (first_subtype_LOCAL_NAME);
 
 
-This pragma allows the compiler not to emit a Finalize call for objects
-defined at the library level.  This is mostly useful for types where
-finalization is only used to deal with storage reclamation since in most
-environments it is not necessary to reclaim memory just before terminating
-execution, hence the name.
+The argument of pragma `Finalize_Storage_Only` must denote a local type which
+is derived from `Ada.Finalization.Controlled` or `Limited_Controlled`. The
+pragma suppresses the call to `Finalize` for declared library-level objects
+of the argument type. This is mostly useful for types where finalization is
+only used to deal with storage reclamation since in most environments it is
+not necessary to reclaim memory just before terminating execution, hence the
+name. Note that this pragma does not suppress Finalize calls for library-level
+heap-allocated objects (see pragma `No_Heap_Finalization`).
 
 Pragma Float_Representation
 ===========================
@@ -2849,9 +2866,13 @@ Syntax:
   pragma Inline_Always (NAME [, NAME]);
 
 
-Similar to pragma `Inline` except that inlining is not subject to
-the use of option *-gnatn* or *-gnatN* and the inlining
-happens regardless of whether these options are used.
+Similar to pragma `Inline` except that inlining is unconditional.
+Inline_Always instructs the compiler to inline every direct call to the
+subprogram or else to emit a compilation error, independently of any
+option, in particular *-gnatn* or *-gnatN* or the optimization level.
+It is an error to take the address or access of `NAME`. It is also an error to
+apply this pragma to a primitive operation of a tagged type. Thanks to such
+restrictions, the compiler is allowed to remove the out-of-line body of `NAME`.
 
 Pragma Inline_Generic
 =====================
@@ -2974,7 +2995,9 @@ Interrupts can be in one of three states:
 
   The interrupt is reserved (no Ada handler can be installed), and the
   Ada run-time may not install a handler. As a result you are guaranteed
-  standard system default action if this interrupt is raised.
+  standard system default action if this interrupt is raised. This also allows
+  installing a low level handler via C APIs such as sigaction(), outside
+  of Ada control.
 
 * Runtime
 
@@ -2984,7 +3007,8 @@ Interrupts can be in one of three states:
 
 * User
 
-  The interrupt is unreserved.  The user may install a handler to provide
+  The interrupt is unreserved.  The user may install an Ada handler via
+  Ada.Interrupts and pragma Interrupt_Handler or Attach_Handler to provide
   some other action.
 
 These states are the allowed values of the `State` parameter of the
@@ -3614,12 +3638,44 @@ Syntax:
 
 This is a program unit pragma (there is also an equivalent aspect of the
 same name) that establishes the restriction `No_Elaboration_Code` for
-the current unit and any extended main source units (body and subunits.
-It also has has the effect of enforcing a transitive application of this
-aspect, so that if any unit is implicitly or explicitly WITH'ed by the
+the current unit and any extended main source units (body and subunits).
+It also has the effect of enforcing a transitive application of this
+aspect, so that if any unit is implicitly or explicitly with'ed by the
 current unit, it must also have the No_Elaboration_Code_All aspect set.
 It may be applied to package or subprogram specs or their generic versions.
 
+Pragma No_Heap_Finalization
+===========================
+
+Syntax:
+
+
+::
+
+  pragma No_Heap_Finalization [ (first_subtype_LOCAL_NAME) ];
+
+
+Pragma `No_Heap_Finalization` may be used as a configuration pragma or as a
+type-specific pragma.
+
+In its configuration form, the pragma must appear within a configuration file
+such as gnat.adc, without an argument. The pragma suppresses the call to
+`Finalize` for heap-allocated objects created through library-level named
+access-to-object types in cases where the designated type requires finalization
+actions.
+
+In its type-specific form, the argument of the pragma must denote a
+library-level named access-to-object type. The pragma suppresses the call to
+`Finalize` for heap-allocated objects created through the specific access type
+in cases where the designated type requires finalization actions.
+
+It is still possible to finalize such heap-allocated objects by explicitly
+deallocating them.
+
+A library-level named access-to-object type declared within a generic unit will
+lose its `No_Heap_Finalization` pragma when the corresponding instance does not
+appear at the library level.
+
 Pragma No_Inline
 ================
 
@@ -4855,14 +4911,16 @@ Syntax:
 
 .. code-block:: ada
 
-  pragma Profile (Ravenscar | Restricted | Rational | GNAT_Extended_Ravenscar);
+  pragma Profile (Ravenscar | Restricted | Rational |
+                  GNAT_Extended_Ravenscar | GNAT_Ravenscar_EDF );
 
 
 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 possibilities (`Restricted`, `Rational`, `GNAT_Extended_Ravenscar`)
+The other possibilities (`Restricted`, `Rational`,
+`GNAT_Extended_Ravenscar`, `GNAT_Ravenscar_EDF`)
 are implementation-defined. The set of configuration pragmas
 is defined in the following sections.
 
@@ -4992,6 +5050,11 @@ is defined in the following sections.
   The ``Max_Protected_Entries``, ``Max_Entry_Queue_Length``, and
   ``No_Relative_Delay`` restrictions have been removed.
 
+* Pragma Profile (GNAT_Ravenscar_EDF)
+
+  This profile corresponds to the Ravenscar profile but using
+  EDF_Across_Priority as the Task_Scheduling_Policy.
+
 * Pragma Profile (Restricted)
 
   This profile corresponds to the GNAT restricted run time. It
@@ -7384,6 +7447,10 @@ also be used at any point that a pragma is allowed, and it is permissible
 to have more than one such pragma in a file, allowing multiple encodings
 to appear within the same file.
 
+However, note that the pragma cannot immediately precede the relevant
+wide character, because then the previous encoding will still be in
+effect, causing "illegal character" errors.
+
 The argument can be an identifier or a character literal. In the identifier
 case, it is one of `HEX`, `UPPER`, `SHIFT_JIS`,
 `EUC`, `UTF8`, or `BRACKETS`. In the character literal

gcc/ada/doc/gnat_rm/implementation_of_specific_ada_features.rst

@@ -285,6 +285,31 @@ Note that this simple scheme preserves the relative order of the tasks
 that were ready to execute in the priority queue where R has been
 placed at the end.
 
+.. Support_for_Locking_Policies
+
+Support for Locking Policies
+----------------------------
+
+This section specifies which policies specified by pragma Locking_Policy
+are supported on which platforms.
+
+GNAT supports the standard `Ceiling_Locking` policy, and the
+implementation defined `Inheritance_Locking` and
+`Concurrent_Readers_Locking` policies.
+
+`Ceiling_Locking` is supported on all platforms if the operating system
+supports it. In particular, `Ceiling_Locking` is not supported on
+VxWorks.
+`Inheritance_Locking` is supported on
+Linux,
+Darwin (Mac OS X),
+LynxOS 178,
+and VxWorks.
+`Concurrent_Readers_Locking` is supported on Linux.
+
+Note that on Linux, `Ceiling_Locking` requires the program to be running
+with root privileges. Otherwise, the policy is ignored.
+
 .. _GNAT_Implementation_of_Shared_Passive_Packages:
 
 GNAT Implementation of Shared Passive Packages

gcc/ada/doc/gnat_rm/representation_clauses_and_pragmas.rst

@@ -1576,10 +1576,9 @@ check Alignment_Check is suppressed, or if
 `pragma Restrictions (No_Elaboration_Code)` is in effect. It is also
 suppressed by default on non-strict alignment machines (such as the x86).
 
-Finally, GNAT does not permit overlaying of objects of controlled types or
-composite types containing a controlled component. In most cases, the compiler
-can detect an attempt at such overlays and will generate a warning at compile
-time and a Program_Error exception at run time.
+Finally, GNAT does not permit overlaying of objects of class-wide types. In
+most cases, the compiler can detect an attempt at such overlays and will
+generate a warning at compile time and a Program_Error exception at run time.
 
 .. index:: Export
 

gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst

@@ -2713,6 +2713,8 @@ of the pragma in the :title:`GNAT_Reference_manual`).
 
   * :samp:`-gnatw.h` (holes in record layouts)
 
+  * :samp:`-gnatw.j` (late primitives of tagged types)
+
   * :samp:`-gnatw.k` (redefinition of names in standard)
 
   * :samp:`-gnatwl` (elaboration warnings)
@@ -3186,6 +3188,24 @@ of the pragma in the :title:`GNAT_Reference_manual`).
   This switch disables warnings on use of obsolescent features.
 
 
+.. index:: -gnatw.j  (gcc)
+
+:samp:`-gnatw.j`
+  *Activate warnings on late declarations of tagged type primitives.*
+
+  This switch activates warnings on visible primitives added to a
+  tagged type after deriving a private extension from it.
+
+
+.. index:: -gnatw.J  (gcc)
+
+:samp:`-gnatw.J`
+  *Suppress warnings on late declarations of tagged type primitives.*
+
+  This switch suppresses warnings on visible primitives added to a
+  tagged type after deriving a private extension from it.
+
+
 .. index:: -gnatwk  (gcc)
 
 :samp:`-gnatwk`
@@ -6114,7 +6134,7 @@ be presented in subsequent sections.
   sized result, for example a function returning an unconstrained
   String. There are two ways in which this secondary stack is allocated.
 
-  For most targets, the secondary stack is growing on demand and is allocated
+  For most targets, the secondary stack grows on demand and is allocated
   as a chain of blocks in the heap. The -D option is not very
   relevant. It only give some control over the size of the allocated
   blocks (whose size is the minimum of the default secondary stack size value,

gcc/ada/doc/gnat_ugn/gnat_and_program_execution.rst

@@ -3354,7 +3354,7 @@ and similarly for `Mass`, `Time`, `Electric_Current`,
 The package also defines conventional names for values of each unit, for
 example:
 
-  .. code-block":: ada
+  .. code-block:: ada
 
      m   : constant Length           := 1.0;
      kg  : constant Mass             := 1.0;

gcc/ada/doc/gnat_ugn/platform_specific_information.rst

@@ -237,6 +237,20 @@ value greater than 0.0, or else use the corresponding *-T*
 binder option.
 
 
+To make sure a program is running as root, you can put something like
+this in a library package body in your application:
+
+  .. code-block:: ada
+
+     function geteuid return Integer;
+     pragma Import (C, geteuid, "geteuid");
+     Ignore : constant Boolean :=
+       (if geteuid = 0 then True else raise Program_Error with "must be root");
+
+It gets the effective user id, and if it's not 0 (i.e. root), it raises
+Program_Error.
+
+
 .. index:: Solaris Sparc threads libraries
 
 .. _Solaris-Specific_Considerations:
@@ -2215,7 +2229,7 @@ This setting can be done with *gnatlink* using either of the following:
 
   This sets the stack reserve size to 0x1000000 bytes. Note that with
   *-Wl* option it is not possible to set the stack commit size
-  because the coma is a separator for this option.
+  because the comma is a separator for this option.
 
 
 .. _Setting_Heap_Size_from_gnatlink:
@@ -2244,7 +2258,7 @@ Under Windows systems, it is possible to specify the program heap size from
 
   This sets the heap reserve size to 0x1000000 bytes. Note that with
   *-Wl* option it is not possible to set the heap commit size
-  because the coma is a separator for this option.
+  because the comma is a separator for this option.
 
 
 .. _Win32_Specific_Addons: