--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/gcc/ada/doc/gnat_rm/implementation_advice.rst	Fri Oct 27 22:46:09 2017 +0900
@@ -0,0 +1,1395 @@
+.. _Implementation_Advice:
+
+*********************
+Implementation Advice
+*********************
+
+The main text of the Ada Reference Manual describes the required
+behavior of all Ada compilers, and the GNAT compiler conforms to
+these requirements.
+
+In addition, there are sections throughout the Ada Reference Manual headed
+by the phrase 'Implementation advice'.  These sections are not normative,
+i.e., they do not specify requirements that all compilers must
+follow.  Rather they provide advice on generally desirable behavior.
+They are not requirements, because they describe behavior that cannot
+be provided on all systems, or may be undesirable on some systems.
+
+As far as practical, GNAT follows the implementation advice in
+the Ada Reference Manual.  Each such RM section corresponds to a section
+in this chapter whose title specifies the
+RM section number and paragraph number and the subject of
+the advice.  The contents of each section consists of the RM text within
+quotation marks,
+followed by the GNAT interpretation of the advice.  Most often, this simply says
+'followed', which means that GNAT follows the advice.  However, in a
+number of cases, GNAT deliberately deviates from this advice, in which
+case the text describes what GNAT does and why.
+
+.. index:: Error detection
+
+RM 1.1.3(20): Error Detection
+=============================
+
+  "If an implementation detects the use of an unsupported Specialized Needs
+  Annex feature at run time, it should raise ``Program_Error`` if
+  feasible."
+
+Not relevant.  All specialized needs annex features are either supported,
+or diagnosed at compile time.
+
+.. index:: Child Units
+
+RM 1.1.3(31): Child Units
+=========================
+
+
+  "If an implementation wishes to provide implementation-defined
+  extensions to the functionality of a language-defined library unit, it
+  should normally do so by adding children to the library unit."
+
+Followed.
+
+.. index:: Bounded errors
+
+RM 1.1.5(12): Bounded Errors
+============================
+
+  "If an implementation detects a bounded error or erroneous
+  execution, it should raise ``Program_Error``."
+
+Followed in all cases in which the implementation detects a bounded
+error or erroneous execution.  Not all such situations are detected at
+runtime.
+
+.. index:: Pragmas
+
+.. _RM_2_8_16_Pragmas:
+
+RM 2.8(16): Pragmas
+===================
+
+  "Normally, implementation-defined pragmas should have no semantic effect
+  for error-free programs; that is, if the implementation-defined pragmas
+  are removed from a working program, the program should still be legal,
+  and should still have the same semantics."
+
+The following implementation defined pragmas are exceptions to this
+rule:
+
++--------------------+-------------------+
+| Pragma             | Explanation       |
++====================+===================+
+| *Abort_Defer*      | Affects semantics |
++--------------------+-------------------+
+|*Ada_83*            | Affects legality  |
++--------------------+-------------------+
+|*Assert*            | Affects semantics |
++--------------------+-------------------+
+|*CPP_Class*         | Affects semantics |
++--------------------+-------------------+
+|*CPP_Constructor*   | Affects semantics |
++--------------------+-------------------+
+|*Debug*             | Affects semantics |
++--------------------+-------------------+
+|*Interface_Name*    | Affects semantics |
++--------------------+-------------------+
+|*Machine_Attribute* | Affects semantics |
++--------------------+-------------------+
+|*Unimplemented_Unit*| Affects legality  |
++--------------------+-------------------+
+|*Unchecked_Union*   | Affects semantics |
++--------------------+-------------------+
+
+In each of the above cases, it is essential to the purpose of the pragma
+that this advice not be followed.  For details see
+:ref:`Implementation_Defined_Pragmas`.
+
+RM 2.8(17-19): Pragmas
+======================
+
+  "Normally, an implementation should not define pragmas that can
+  make an illegal program legal, except as follows:
+
+  * A pragma used to complete a declaration, such as a pragma ``Import``;
+
+  * A pragma used to configure the environment by adding, removing, or
+    replacing ``library_items``."
+
+See :ref:`RM_2_8_16_Pragmas`.
+
+.. index:: Character Sets
+
+.. index:: Alternative Character Sets
+
+RM 3.5.2(5): Alternative Character Sets
+=======================================
+
+  "If an implementation supports a mode with alternative interpretations
+  for ``Character`` and ``Wide_Character``, the set of graphic
+  characters of ``Character`` should nevertheless remain a proper
+  subset of the set of graphic characters of ``Wide_Character``.  Any
+  character set 'localizations' should be reflected in the results of
+  the subprograms defined in the language-defined package
+  ``Characters.Handling`` (see A.3) available in such a mode.  In a mode with
+  an alternative interpretation of ``Character``, the implementation should
+  also support a corresponding change in what is a legal
+  ``identifier_letter``."
+
+Not all wide character modes follow this advice, in particular the JIS
+and IEC modes reflect standard usage in Japan, and in these encoding,
+the upper half of the Latin-1 set is not part of the wide-character
+subset, since the most significant bit is used for wide character
+encoding.  However, this only applies to the external forms.  Internally
+there is no such restriction.
+
+.. index:: Integer types
+
+RM 3.5.4(28): Integer Types
+===========================
+
+  "An implementation should support ``Long_Integer`` in addition to
+  ``Integer`` if the target machine supports 32-bit (or longer)
+  arithmetic.  No other named integer subtypes are recommended for package
+  ``Standard``.  Instead, appropriate named integer subtypes should be
+  provided in the library package ``Interfaces`` (see B.2)."
+
+``Long_Integer`` is supported.  Other standard integer types are supported
+so this advice is not fully followed.  These types
+are supported for convenient interface to C, and so that all hardware
+types of the machine are easily available.
+
+RM 3.5.4(29): Integer Types
+===========================
+
+  "An implementation for a two's complement machine should support
+  modular types with a binary modulus up to ``System.Max_Int*2+2``.  An
+  implementation should support a non-binary modules up to ``Integer'Last``."
+
+Followed.
+
+.. index:: Enumeration values
+
+RM 3.5.5(8): Enumeration Values
+===============================
+
+  "For the evaluation of a call on ``S'Pos`` for an enumeration
+  subtype, if the value of the operand does not correspond to the internal
+  code for any enumeration literal of its type (perhaps due to an
+  un-initialized variable), then the implementation should raise
+  ``Program_Error``.  This is particularly important for enumeration
+  types with noncontiguous internal codes specified by an
+  enumeration_representation_clause."
+
+Followed.
+
+.. index:: Float types
+
+RM 3.5.7(17): Float Types
+=========================
+
+  "An implementation should support ``Long_Float`` in addition to
+  ``Float`` if the target machine supports 11 or more digits of
+  precision.  No other named floating point subtypes are recommended for
+  package ``Standard``.  Instead, appropriate named floating point subtypes
+  should be provided in the library package ``Interfaces`` (see B.2)."
+
+``Short_Float`` and ``Long_Long_Float`` are also provided.  The
+former provides improved compatibility with other implementations
+supporting this type.  The latter corresponds to the highest precision
+floating-point type supported by the hardware.  On most machines, this
+will be the same as ``Long_Float``, but on some machines, it will
+correspond to the IEEE extended form.  The notable case is all ia32
+(x86) implementations, where ``Long_Long_Float`` corresponds to
+the 80-bit extended precision format supported in hardware on this
+processor.  Note that the 128-bit format on SPARC is not supported,
+since this is a software rather than a hardware format.
+
+.. index:: Multidimensional arrays
+
+.. index:: Arrays, multidimensional
+
+RM 3.6.2(11): Multidimensional Arrays
+=====================================
+
+  "An implementation should normally represent multidimensional arrays in
+  row-major order, consistent with the notation used for multidimensional
+  array aggregates (see 4.3.3).  However, if a pragma ``Convention``
+  (``Fortran``, ...) applies to a multidimensional array type, then
+  column-major order should be used instead (see B.5, *Interfacing with Fortran*)."
+
+Followed.
+
+.. index:: Duration'Small
+
+RM 9.6(30-31): Duration'Small
+=============================
+
+  "Whenever possible in an implementation, the value of ``Duration'Small``
+  should be no greater than 100 microseconds."
+
+Followed.  (``Duration'Small`` = 10**(-9)).
+
+  "The time base for ``delay_relative_statements`` should be monotonic;
+  it need not be the same time base as used for ``Calendar.Clock``."
+
+Followed.
+
+RM 10.2.1(12): Consistent Representation
+========================================
+
+  "In an implementation, a type declared in a pre-elaborated package should
+  have the same representation in every elaboration of a given version of
+  the package, whether the elaborations occur in distinct executions of
+  the same program, or in executions of distinct programs or partitions
+  that include the given version."
+
+Followed, except in the case of tagged types.  Tagged types involve
+implicit pointers to a local copy of a dispatch table, and these pointers
+have representations which thus depend on a particular elaboration of the
+package.  It is not easy to see how it would be possible to follow this
+advice without severely impacting efficiency of execution.
+
+.. index:: Exception information
+
+RM 11.4.1(19): Exception Information
+====================================
+
+  "``Exception_Message`` by default and ``Exception_Information``
+  should produce information useful for
+  debugging.  ``Exception_Message`` should be short, about one
+  line.  ``Exception_Information`` can be long.  ``Exception_Message``
+  should not include the
+  ``Exception_Name``.  ``Exception_Information`` should include both
+  the ``Exception_Name`` and the ``Exception_Message``."
+
+Followed.  For each exception that doesn't have a specified
+``Exception_Message``, the compiler generates one containing the location
+of the raise statement.  This location has the form 'file_name:line', where
+file_name is the short file name (without path information) and line is the line
+number in the file.  Note that in the case of the Zero Cost Exception
+mechanism, these messages become redundant with the Exception_Information that
+contains a full backtrace of the calling sequence, so they are disabled.
+To disable explicitly the generation of the source location message, use the
+Pragma ``Discard_Names``.
+
+.. index:: Suppression of checks
+
+.. index:: Checks, suppression of
+
+RM 11.5(28): Suppression of Checks
+==================================
+
+  "The implementation should minimize the code executed for checks that
+  have been suppressed."
+
+Followed.
+
+.. index:: Representation clauses
+
+RM 13.1 (21-24): Representation Clauses
+=======================================
+
+  "The recommended level of support for all representation items is
+  qualified as follows:
+
+  An implementation need not support representation items containing
+  nonstatic expressions, except that an implementation should support a
+  representation item for a given entity if each nonstatic expression in
+  the representation item is a name that statically denotes a constant
+  declared before the entity."
+
+Followed.  In fact, GNAT goes beyond the recommended level of support
+by allowing nonstatic expressions in some representation clauses even
+without the need to declare constants initialized with the values of
+such expressions.
+For example:
+
+.. code-block:: ada
+
+    X : Integer;
+    Y : Float;
+    for Y'Address use X'Address;>>
+
+
+  "An implementation need not support a specification for the ``Size``
+  for a given composite subtype, nor the size or storage place for an
+  object (including a component) of a given composite subtype, unless the
+  constraints on the subtype and its composite subcomponents (if any) are
+  all static constraints."
+
+Followed.  Size Clauses are not permitted on nonstatic components, as
+described above.
+
+
+  "An aliased component, or a component whose type is by-reference, should
+  always be allocated at an addressable location."
+
+Followed.
+
+.. index:: Packed types
+
+RM 13.2(6-8): Packed Types
+==========================
+
+  "If a type is packed, then the implementation should try to minimize
+  storage allocated to objects of the type, possibly at the expense of
+  speed of accessing components, subject to reasonable complexity in
+  addressing calculations.
+
+  The recommended level of support pragma ``Pack`` is:
+
+  For a packed record type, the components should be packed as tightly as
+  possible subject to the Sizes of the component subtypes, and subject to
+  any *record_representation_clause* that applies to the type; the
+  implementation may, but need not, reorder components or cross aligned
+  word boundaries to improve the packing.  A component whose ``Size`` is
+  greater than the word size may be allocated an integral number of words."
+
+Followed.  Tight packing of arrays is supported for all component sizes
+up to 64-bits. If the array component size is 1 (that is to say, if
+the component is a boolean type or an enumeration type with two values)
+then values of the type are implicitly initialized to zero. This
+happens both for objects of the packed type, and for objects that have a
+subcomponent of the packed type.
+
+
+  "An implementation should support Address clauses for imported
+  subprograms."
+
+Followed.
+
+.. index:: Address clauses
+
+RM 13.3(14-19): Address Clauses
+===============================
+
+  "For an array ``X``, ``X'Address`` should point at the first
+  component of the array, and not at the array bounds."
+
+Followed.
+
+  "The recommended level of support for the ``Address`` attribute is:
+
+  ``X'Address`` should produce a useful result if ``X`` is an
+  object that is aliased or of a by-reference type, or is an entity whose
+  ``Address`` has been specified."
+
+Followed.  A valid address will be produced even if none of those
+conditions have been met.  If necessary, the object is forced into
+memory to ensure the address is valid.
+
+  "An implementation should support ``Address`` clauses for imported
+  subprograms."
+
+Followed.
+
+  "Objects (including subcomponents) that are aliased or of a by-reference
+  type should be allocated on storage element boundaries."
+
+Followed.
+
+  "If the ``Address`` of an object is specified, or it is imported or exported,
+  then the implementation should not perform optimizations based on
+  assumptions of no aliases."
+
+Followed.
+
+.. index:: Alignment clauses
+
+RM 13.3(29-35): Alignment Clauses
+=================================
+
+  "The recommended level of support for the ``Alignment`` attribute for
+  subtypes is:
+
+  An implementation should support specified Alignments that are factors
+  and multiples of the number of storage elements per word, subject to the
+  following:"
+
+Followed.
+
+  "An implementation need not support specified Alignments for
+  combinations of Sizes and Alignments that cannot be easily
+  loaded and stored by available machine instructions."
+
+Followed.
+
+  "An implementation need not support specified Alignments that are
+  greater than the maximum ``Alignment`` the implementation ever returns by
+  default."
+
+Followed.
+
+  "The recommended level of support for the ``Alignment`` attribute for
+  objects is:
+
+  Same as above, for subtypes, but in addition:"
+
+Followed.
+
+  "For stand-alone library-level objects of statically constrained
+  subtypes, the implementation should support all alignments
+  supported by the target linker.  For example, page alignment is likely to
+  be supported for such objects, but not for subtypes."
+
+Followed.
+
+.. index:: Size clauses
+
+RM 13.3(42-43): Size Clauses
+============================
+
+  "The recommended level of support for the ``Size`` attribute of
+  objects is:
+
+  A ``Size`` clause should be supported for an object if the specified
+  ``Size`` is at least as large as its subtype's ``Size``, and
+  corresponds to a size in storage elements that is a multiple of the
+  object's ``Alignment`` (if the ``Alignment`` is nonzero)."
+
+Followed.
+
+RM 13.3(50-56): Size Clauses
+============================
+
+  "If the ``Size`` of a subtype is specified, and allows for efficient
+  independent addressability (see 9.10) on the target architecture, then
+  the ``Size`` of the following objects of the subtype should equal the
+  ``Size`` of the subtype:
+
+  Aliased objects (including components)."
+
+Followed.
+
+  "`Size` clause on a composite subtype should not affect the
+  internal layout of components."
+
+Followed. But note that this can be overridden by use of the implementation
+pragma Implicit_Packing in the case of packed arrays.
+
+  "The recommended level of support for the ``Size`` attribute of subtypes is:
+
+  The ``Size`` (if not specified) of a static discrete or fixed point
+  subtype should be the number of bits needed to represent each value
+  belonging to the subtype using an unbiased representation, leaving space
+  for a sign bit only if the subtype contains negative values.  If such a
+  subtype is a first subtype, then an implementation should support a
+  specified ``Size`` for it that reflects this representation."
+
+Followed.
+
+  "For a subtype implemented with levels of indirection, the ``Size``
+  should include the size of the pointers, but not the size of what they
+  point at."
+
+Followed.
+
+.. index:: Component_Size clauses
+
+RM 13.3(71-73): Component Size Clauses
+======================================
+
+  "The recommended level of support for the ``Component_Size``
+  attribute is:
+
+  An implementation need not support specified ``Component_Sizes`` that are
+  less than the ``Size`` of the component subtype."
+
+Followed.
+
+  "An implementation should support specified Component_Sizes that
+  are factors and multiples of the word size.  For such
+  Component_Sizes, the array should contain no gaps between
+  components.  For other Component_Sizes (if supported), the array
+  should contain no gaps between components when packing is also
+  specified; the implementation should forbid this combination in cases
+  where it cannot support a no-gaps representation."
+
+Followed.
+
+.. index:: Enumeration representation clauses
+
+.. index:: Representation clauses, enumeration
+
+RM 13.4(9-10): Enumeration Representation Clauses
+=================================================
+
+  "The recommended level of support for enumeration representation clauses
+  is:
+
+  An implementation need not support enumeration representation clauses
+  for boolean types, but should at minimum support the internal codes in
+  the range ``System.Min_Int .. System.Max_Int``."
+
+Followed.
+
+.. index:: Record representation clauses
+
+.. index:: Representation clauses, records
+
+RM 13.5.1(17-22): Record Representation Clauses
+===============================================
+
+  "The recommended level of support for
+  *record_representation_clause*\ s is:
+
+  An implementation should support storage places that can be extracted
+  with a load, mask, shift sequence of machine code, and set with a load,
+  shift, mask, store sequence, given the available machine instructions
+  and run-time model."
+
+Followed.
+
+  "A storage place should be supported if its size is equal to the
+  ``Size`` of the component subtype, and it starts and ends on a
+  boundary that obeys the ``Alignment`` of the component subtype."
+
+Followed.
+
+  "If the default bit ordering applies to the declaration of a given type,
+  then for a component whose subtype's ``Size`` is less than the word
+  size, any storage place that does not cross an aligned word boundary
+  should be supported."
+
+Followed.
+
+  "An implementation may reserve a storage place for the tag field of a
+  tagged type, and disallow other components from overlapping that place."
+
+Followed.  The storage place for the tag field is the beginning of the tagged
+record, and its size is Address'Size.  GNAT will reject an explicit component
+clause for the tag field.
+
+  "An implementation need not support a *component_clause* for a
+  component of an extension part if the storage place is not after the
+  storage places of all components of the parent type, whether or not
+  those storage places had been specified."
+
+Followed.  The above advice on record representation clauses is followed,
+and all mentioned features are implemented.
+
+.. index:: Storage place attributes
+
+RM 13.5.2(5): Storage Place Attributes
+======================================
+
+  "If a component is represented using some form of pointer (such as an
+  offset) to the actual data of the component, and this data is contiguous
+  with the rest of the object, then the storage place attributes should
+  reflect the place of the actual data, not the pointer.  If a component is
+  allocated discontinuously from the rest of the object, then a warning
+  should be generated upon reference to one of its storage place
+  attributes."
+
+Followed.  There are no such components in GNAT.
+
+.. index:: Bit ordering
+
+RM 13.5.3(7-8): Bit Ordering
+============================
+
+  "The recommended level of support for the non-default bit ordering is:
+
+  If ``Word_Size`` = ``Storage_Unit``, then the implementation
+  should support the non-default bit ordering in addition to the default
+  bit ordering."
+
+Followed.  Word size does not equal storage size in this implementation.
+Thus non-default bit ordering is not supported.
+
+.. index:: Address, as private type
+
+RM 13.7(37): Address as Private
+===============================
+
+  "`Address` should be of a private type."
+
+Followed.
+
+.. index:: Operations, on ``Address``
+
+.. index:: Address, operations of
+
+RM 13.7.1(16): Address Operations
+=================================
+
+  "Operations in ``System`` and its children should reflect the target
+  environment semantics as closely as is reasonable.  For example, on most
+  machines, it makes sense for address arithmetic to 'wrap around'.
+  Operations that do not make sense should raise ``Program_Error``."
+
+Followed.  Address arithmetic is modular arithmetic that wraps around.  No
+operation raises ``Program_Error``, since all operations make sense.
+
+.. index:: Unchecked conversion
+
+RM 13.9(14-17): Unchecked Conversion
+====================================
+
+  "The ``Size`` of an array object should not include its bounds; hence,
+  the bounds should not be part of the converted data."
+
+Followed.
+
+  "The implementation should not generate unnecessary run-time checks to
+  ensure that the representation of ``S`` is a representation of the
+  target type.  It should take advantage of the permission to return by
+  reference when possible.  Restrictions on unchecked conversions should be
+  avoided unless required by the target environment."
+
+Followed.  There are no restrictions on unchecked conversion.  A warning is
+generated if the source and target types do not have the same size since
+the semantics in this case may be target dependent.
+
+  "The recommended level of support for unchecked conversions is:
+
+  Unchecked conversions should be supported and should be reversible in
+  the cases where this clause defines the result.  To enable meaningful use
+  of unchecked conversion, a contiguous representation should be used for
+  elementary subtypes, for statically constrained array subtypes whose
+  component subtype is one of the subtypes described in this paragraph,
+  and for record subtypes without discriminants whose component subtypes
+  are described in this paragraph."
+
+Followed.
+
+.. index:: Heap usage, implicit
+
+RM 13.11(23-25): Implicit Heap Usage
+====================================
+
+  "An implementation should document any cases in which it dynamically
+  allocates heap storage for a purpose other than the evaluation of an
+  allocator."
+
+Followed, the only other points at which heap storage is dynamically
+allocated are as follows:
+
+*
+  At initial elaboration time, to allocate dynamically sized global
+  objects.
+
+*
+  To allocate space for a task when a task is created.
+
+*
+  To extend the secondary stack dynamically when needed.  The secondary
+  stack is used for returning variable length results.
+
+..
+
+  "A default (implementation-provided) storage pool for an
+  access-to-constant type should not have overhead to support deallocation of
+  individual objects."
+
+Followed.
+
+  "A storage pool for an anonymous access type should be created at the
+  point of an allocator for the type, and be reclaimed when the designated
+  object becomes inaccessible."
+
+Followed.
+
+.. index:: Unchecked deallocation
+
+RM 13.11.2(17): Unchecked Deallocation
+======================================
+
+  "For a standard storage pool, ``Free`` should actually reclaim the
+  storage."
+
+Followed.
+
+.. index:: Stream oriented attributes
+
+RM 13.13.2(17): Stream Oriented Attributes
+==========================================
+
+  "If a stream element is the same size as a storage element, then the
+  normal in-memory representation should be used by ``Read`` and
+  ``Write`` for scalar objects.  Otherwise, ``Read`` and ``Write``
+  should use the smallest number of stream elements needed to represent
+  all values in the base range of the scalar type."
+
+Followed.  By default, GNAT uses the interpretation suggested by AI-195,
+which specifies using the size of the first subtype.
+However, such an implementation is based on direct binary
+representations and is therefore target- and endianness-dependent.
+To address this issue, GNAT also supplies an alternate implementation
+of the stream attributes ``Read`` and ``Write``,
+which uses the target-independent XDR standard representation
+for scalar types.
+
+.. index:: XDR representation
+
+.. index:: Read attribute
+
+.. index:: Write attribute
+
+.. index:: Stream oriented attributes
+
+The XDR implementation is provided as an alternative body of the
+``System.Stream_Attributes`` package, in the file
+:file:`s-stratt-xdr.adb` in the GNAT library.
+There is no :file:`s-stratt-xdr.ads` file.
+In order to install the XDR implementation, do the following:
+
+* Replace the default implementation of the
+  ``System.Stream_Attributes`` package with the XDR implementation.
+  For example on a Unix platform issue the commands:
+
+  .. code-block:: sh
+
+    $ mv s-stratt.adb s-stratt-default.adb
+    $ mv s-stratt-xdr.adb s-stratt.adb
+
+
+*
+  Rebuild the GNAT run-time library as documented in
+  the *GNAT and Libraries* section of the :title:`GNAT User's Guide`.
+
+RM A.1(52): Names of Predefined Numeric Types
+=============================================
+
+  "If an implementation provides additional named predefined integer types,
+  then the names should end with ``Integer`` as in
+  ``Long_Integer``.  If an implementation provides additional named
+  predefined floating point types, then the names should end with
+  ``Float`` as in ``Long_Float``."
+
+Followed.
+
+.. index:: Ada.Characters.Handling
+
+RM A.3.2(49): ``Ada.Characters.Handling``
+=========================================
+
+  "If an implementation provides a localized definition of ``Character``
+  or ``Wide_Character``, then the effects of the subprograms in
+  ``Characters.Handling`` should reflect the localizations.
+  See also 3.5.2."
+
+Followed.  GNAT provides no such localized definitions.
+
+.. index:: Bounded-length strings
+
+RM A.4.4(106): Bounded-Length String Handling
+=============================================
+
+  "Bounded string objects should not be implemented by implicit pointers
+  and dynamic allocation."
+
+Followed.  No implicit pointers or dynamic allocation are used.
+
+.. index:: Random number generation
+
+RM A.5.2(46-47): Random Number Generation
+=========================================
+
+  "Any storage associated with an object of type ``Generator`` should be
+  reclaimed on exit from the scope of the object."
+
+Followed.
+
+  "If the generator period is sufficiently long in relation to the number
+  of distinct initiator values, then each possible value of
+  ``Initiator`` passed to ``Reset`` should initiate a sequence of
+  random numbers that does not, in a practical sense, overlap the sequence
+  initiated by any other value.  If this is not possible, then the mapping
+  between initiator values and generator states should be a rapidly
+  varying function of the initiator value."
+
+Followed.  The generator period is sufficiently long for the first
+condition here to hold true.
+
+.. index:: Get_Immediate
+
+RM A.10.7(23): ``Get_Immediate``
+================================
+
+  "The ``Get_Immediate`` procedures should be implemented with
+  unbuffered input.  For a device such as a keyboard, input should be
+  available if a key has already been typed, whereas for a disk
+  file, input should always be available except at end of file.  For a file
+  associated with a keyboard-like device, any line-editing features of the
+  underlying operating system should be disabled during the execution of
+  ``Get_Immediate``."
+
+Followed on all targets except VxWorks. For VxWorks, there is no way to
+provide this functionality that does not result in the input buffer being
+flushed before the ``Get_Immediate`` call. A special unit
+``Interfaces.Vxworks.IO`` is provided that contains routines to enable
+this functionality.
+
+.. index:: Export
+
+RM B.1(39-41): Pragma ``Export``
+================================
+
+  "If an implementation supports pragma ``Export`` to a given language,
+  then it should also allow the main subprogram to be written in that
+  language.  It should support some mechanism for invoking the elaboration
+  of the Ada library units included in the system, and for invoking the
+  finalization of the environment task.  On typical systems, the
+  recommended mechanism is to provide two subprograms whose link names are
+  ``adainit`` and ``adafinal``.  ``adainit`` should contain the
+  elaboration code for library units.  ``adafinal`` should contain the
+  finalization code.  These subprograms should have no effect the second
+  and subsequent time they are called."
+
+Followed.
+
+  "Automatic elaboration of pre-elaborated packages should be
+  provided when pragma ``Export`` is supported."
+
+Followed when the main program is in Ada.  If the main program is in a
+foreign language, then
+``adainit`` must be called to elaborate pre-elaborated
+packages.
+
+  "For each supported convention *L* other than ``Intrinsic``, an
+  implementation should support ``Import`` and ``Export`` pragmas
+  for objects of *L*\ -compatible types and for subprograms, and pragma
+  `Convention` for *L*\ -eligible types and for subprograms,
+  presuming the other language has corresponding features.  Pragma
+  ``Convention`` need not be supported for scalar types."
+
+Followed.
+
+.. index:: Package Interfaces
+
+.. index:: Interfaces
+
+RM B.2(12-13): Package ``Interfaces``
+=====================================
+
+  "For each implementation-defined convention identifier, there should be a
+  child package of package Interfaces with the corresponding name.  This
+  package should contain any declarations that would be useful for
+  interfacing to the language (implementation) represented by the
+  convention.  Any declarations useful for interfacing to any language on
+  the given hardware architecture should be provided directly in
+  ``Interfaces``."
+
+Followed.
+
+  "An implementation supporting an interface to C, COBOL, or Fortran should
+  provide the corresponding package or packages described in the following
+  clauses."
+
+Followed.  GNAT provides all the packages described in this section.
+
+.. index:: C, interfacing with
+
+RM B.3(63-71): Interfacing with C
+=================================
+
+  "An implementation should support the following interface correspondences
+  between Ada and C."
+
+Followed.
+
+  "An Ada procedure corresponds to a void-returning C function."
+
+Followed.
+
+  "An Ada function corresponds to a non-void C function."
+
+Followed.
+
+  "An Ada ``in`` scalar parameter is passed as a scalar argument to a C
+  function."
+
+Followed.
+
+  "An Ada ``in`` parameter of an access-to-object type with designated
+  type ``T`` is passed as a ``t*`` argument to a C function,
+  where ``t`` is the C type corresponding to the Ada type ``T``."
+
+Followed.
+
+  "An Ada access ``T`` parameter, or an Ada ``out`` or ``in out``
+  parameter of an elementary type ``T``, is passed as a ``t*``
+  argument to a C function, where ``t`` is the C type corresponding to
+  the Ada type ``T``.  In the case of an elementary ``out`` or
+  ``in out`` parameter, a pointer to a temporary copy is used to
+  preserve by-copy semantics."
+
+Followed.
+
+  "An Ada parameter of a record type ``T``, of any mode, is passed as a
+  ``t*`` argument to a C function, where ``t`` is the C
+  structure corresponding to the Ada type ``T``."
+
+Followed.  This convention may be overridden by the use of the C_Pass_By_Copy
+pragma, or Convention, or by explicitly specifying the mechanism for a given
+call using an extended import or export pragma.
+
+  "An Ada parameter of an array type with component type ``T``, of any
+  mode, is passed as a ``t*`` argument to a C function, where
+  ``t`` is the C type corresponding to the Ada type ``T``."
+
+Followed.
+
+  "An Ada parameter of an access-to-subprogram type is passed as a pointer
+  to a C function whose prototype corresponds to the designated
+  subprogram's specification."
+
+Followed.
+
+.. index:: COBOL, interfacing with
+
+RM B.4(95-98): Interfacing with COBOL
+=====================================
+
+  "An Ada implementation should support the following interface
+  correspondences between Ada and COBOL."
+
+Followed.
+
+  "An Ada access ``T`` parameter is passed as a ``BY REFERENCE`` data item of
+  the COBOL type corresponding to ``T``."
+
+Followed.
+
+  "An Ada in scalar parameter is passed as a ``BY CONTENT`` data item of
+  the corresponding COBOL type."
+
+Followed.
+
+  "Any other Ada parameter is passed as a ``BY REFERENCE`` data item of the
+  COBOL type corresponding to the Ada parameter type; for scalars, a local
+  copy is used if necessary to ensure by-copy semantics."
+
+Followed.
+
+.. index:: Fortran, interfacing with
+
+RM B.5(22-26): Interfacing with Fortran
+=======================================
+
+  "An Ada implementation should support the following interface
+  correspondences between Ada and Fortran:"
+
+Followed.
+
+  "An Ada procedure corresponds to a Fortran subroutine."
+
+Followed.
+
+  "An Ada function corresponds to a Fortran function."
+
+Followed.
+
+  "An Ada parameter of an elementary, array, or record type ``T`` is
+  passed as a ``T`` argument to a Fortran procedure, where ``T`` is
+  the Fortran type corresponding to the Ada type ``T``, and where the
+  INTENT attribute of the corresponding dummy argument matches the Ada
+  formal parameter mode; the Fortran implementation's parameter passing
+  conventions are used.  For elementary types, a local copy is used if
+  necessary to ensure by-copy semantics."
+
+Followed.
+
+  "An Ada parameter of an access-to-subprogram type is passed as a
+  reference to a Fortran procedure whose interface corresponds to the
+  designated subprogram's specification."
+
+Followed.
+
+.. index:: Machine operations
+
+RM C.1(3-5): Access to Machine Operations
+=========================================
+
+  "The machine code or intrinsic support should allow access to all
+  operations normally available to assembly language programmers for the
+  target environment, including privileged instructions, if any."
+
+Followed.
+
+  "The interfacing pragmas (see Annex B) should support interface to
+  assembler; the default assembler should be associated with the
+  convention identifier ``Assembler``."
+
+Followed.
+
+  "If an entity is exported to assembly language, then the implementation
+  should allocate it at an addressable location, and should ensure that it
+  is retained by the linking process, even if not otherwise referenced
+  from the Ada code.  The implementation should assume that any call to a
+  machine code or assembler subprogram is allowed to read or update every
+  object that is specified as exported."
+
+Followed.
+
+RM C.1(10-16): Access to Machine Operations
+===========================================
+
+  "The implementation should ensure that little or no overhead is
+  associated with calling intrinsic and machine-code subprograms."
+
+Followed for both intrinsics and machine-code subprograms.
+
+  "It is recommended that intrinsic subprograms be provided for convenient
+  access to any machine operations that provide special capabilities or
+  efficiency and that are not otherwise available through the language
+  constructs."
+
+Followed.  A full set of machine operation intrinsic subprograms is provided.
+
+  "Atomic read-modify-write operations---e.g., test and set, compare and
+  swap, decrement and test, enqueue/dequeue."
+
+Followed on any target supporting such operations.
+
+  "Standard numeric functions---e.g.:, sin, log."
+
+Followed on any target supporting such operations.
+
+  "String manipulation operations---e.g.:, translate and test."
+
+Followed on any target supporting such operations.
+
+  "Vector operations---e.g.:, compare vector against thresholds."
+
+Followed on any target supporting such operations.
+
+  "Direct operations on I/O ports."
+
+Followed on any target supporting such operations.
+
+.. index:: Interrupt support
+
+RM C.3(28): Interrupt Support
+=============================
+
+  "If the ``Ceiling_Locking`` policy is not in effect, the
+  implementation should provide means for the application to specify which
+  interrupts are to be blocked during protected actions, if the underlying
+  system allows for a finer-grain control of interrupt blocking."
+
+Followed.  The underlying system does not allow for finer-grain control
+of interrupt blocking.
+
+.. index:: Protected procedure handlers
+
+RM C.3.1(20-21): Protected Procedure Handlers
+=============================================
+
+  "Whenever possible, the implementation should allow interrupt handlers to
+  be called directly by the hardware."
+
+Followed on any target where the underlying operating system permits
+such direct calls.
+
+  "Whenever practical, violations of any
+  implementation-defined restrictions should be detected before run time."
+
+Followed.  Compile time warnings are given when possible.
+
+.. index:: Package ``Interrupts``
+
+.. index:: Interrupts
+
+RM C.3.2(25): Package ``Interrupts``
+====================================
+
+  "If implementation-defined forms of interrupt handler procedures are
+  supported, such as protected procedures with parameters, then for each
+  such form of a handler, a type analogous to ``Parameterless_Handler``
+  should be specified in a child package of ``Interrupts``, with the
+  same operations as in the predefined package Interrupts."
+
+Followed.
+
+.. index:: Pre-elaboration requirements
+
+RM C.4(14): Pre-elaboration Requirements
+========================================
+
+  "It is recommended that pre-elaborated packages be implemented in such a
+  way that there should be little or no code executed at run time for the
+  elaboration of entities not already covered by the Implementation
+  Requirements."
+
+Followed.  Executable code is generated in some cases, e.g., loops
+to initialize large arrays.
+
+RM C.5(8): Pragma ``Discard_Names``
+===================================
+
+  "If the pragma applies to an entity, then the implementation should
+  reduce the amount of storage used for storing names associated with that
+  entity."
+
+Followed.
+
+.. index:: Package Task_Attributes
+
+.. index:: Task_Attributes
+
+RM C.7.2(30): The Package Task_Attributes
+=========================================
+
+  "Some implementations are targeted to domains in which memory use at run
+  time must be completely deterministic.  For such implementations, it is
+  recommended that the storage for task attributes will be pre-allocated
+  statically and not from the heap.  This can be accomplished by either
+  placing restrictions on the number and the size of the task's
+  attributes, or by using the pre-allocated storage for the first ``N``
+  attribute objects, and the heap for the others.  In the latter case,
+  ``N`` should be documented."
+
+Not followed.  This implementation is not targeted to such a domain.
+
+.. index:: Locking Policies
+
+RM D.3(17): Locking Policies
+============================
+
+  "The implementation should use names that end with ``_Locking`` for
+  locking policies defined by the implementation."
+
+Followed.  Two implementation-defined locking policies are defined,
+whose names (``Inheritance_Locking`` and
+``Concurrent_Readers_Locking``) follow this suggestion.
+
+.. index:: Entry queuing policies
+
+RM D.4(16): Entry Queuing Policies
+==================================
+
+  "Names that end with ``_Queuing`` should be used
+  for all implementation-defined queuing policies."
+
+Followed.  No such implementation-defined queuing policies exist.
+
+.. index:: Preemptive abort
+
+RM D.6(9-10): Preemptive Abort
+==============================
+
+  "Even though the *abort_statement* is included in the list of
+  potentially blocking operations (see 9.5.1), it is recommended that this
+  statement be implemented in a way that never requires the task executing
+  the *abort_statement* to block."
+
+Followed.
+
+  "On a multi-processor, the delay associated with aborting a task on
+  another processor should be bounded; the implementation should use
+  periodic polling, if necessary, to achieve this."
+
+Followed.
+
+.. index:: Tasking restrictions
+
+RM D.7(21): Tasking Restrictions
+================================
+
+  "When feasible, the implementation should take advantage of the specified
+  restrictions to produce a more efficient implementation."
+
+GNAT currently takes advantage of these restrictions by providing an optimized
+run time when the Ravenscar profile and the GNAT restricted run time set
+of restrictions are specified.  See pragma ``Profile (Ravenscar)`` and
+pragma ``Profile (Restricted)`` for more details.
+
+.. index:: Time, monotonic
+
+RM D.8(47-49): Monotonic Time
+=============================
+
+  "When appropriate, implementations should provide configuration
+  mechanisms to change the value of ``Tick``."
+
+Such configuration mechanisms are not appropriate to this implementation
+and are thus not supported.
+
+  "It is recommended that ``Calendar.Clock`` and ``Real_Time.Clock``
+  be implemented as transformations of the same time base."
+
+Followed.
+
+
+  "It is recommended that the best time base which exists in
+  the underlying system be available to the application through
+  ``Clock``.  `Best` may mean highest accuracy or largest range."
+
+Followed.
+
+.. index:: Partition communication subsystem
+
+.. index:: PCS
+
+RM E.5(28-29): Partition Communication Subsystem
+================================================
+
+  "Whenever possible, the PCS on the called partition should allow for
+  multiple tasks to call the RPC-receiver with different messages and
+  should allow them to block until the corresponding subprogram body
+  returns."
+
+Followed by GLADE, a separately supplied PCS that can be used with
+GNAT.
+
+  "The ``Write`` operation on a stream of type ``Params_Stream_Type``
+  should raise ``Storage_Error`` if it runs out of space trying to
+  write the ``Item`` into the stream."
+
+Followed by GLADE, a separately supplied PCS that can be used with
+GNAT.
+
+.. index:: COBOL support
+
+RM F(7): COBOL Support
+======================
+
+  "If COBOL (respectively, C) is widely supported in the target
+  environment, implementations supporting the Information Systems Annex
+  should provide the child package ``Interfaces.COBOL`` (respectively,
+  ``Interfaces.C``) specified in Annex B and should support a
+  ``convention_identifier`` of COBOL (respectively, C) in the interfacing
+  pragmas (see Annex B), thus allowing Ada programs to interface with
+  programs written in that language."
+
+Followed.
+
+.. index:: Decimal radix support
+
+RM F.1(2): Decimal Radix Support
+================================
+
+  "Packed decimal should be used as the internal representation for objects
+  of subtype ``S`` when ``S``'Machine_Radix = 10."
+
+Not followed.  GNAT ignores ``S``'Machine_Radix and always uses binary
+representations.
+
+.. index:: Numerics
+
+RM G: Numerics
+==============
+
+  "If Fortran (respectively, C) is widely supported in the target
+  environment, implementations supporting the Numerics Annex
+  should provide the child package ``Interfaces.Fortran`` (respectively,
+  ``Interfaces.C``) specified in Annex B and should support a
+  ``convention_identifier`` of Fortran (respectively, C) in the interfacing
+  pragmas (see Annex B), thus allowing Ada programs to interface with
+  programs written in that language."
+
+Followed.
+
+.. index:: Complex types
+
+RM G.1.1(56-58): Complex Types
+==============================
+
+  "Because the usual mathematical meaning of multiplication of a complex
+  operand and a real operand is that of the scaling of both components of
+  the former by the latter, an implementation should not perform this
+  operation by first promoting the real operand to complex type and then
+  performing a full complex multiplication.  In systems that, in the
+  future, support an Ada binding to IEC 559:1989, the latter technique
+  will not generate the required result when one of the components of the
+  complex operand is infinite.  (Explicit multiplication of the infinite
+  component by the zero component obtained during promotion yields a NaN
+  that propagates into the final result.) Analogous advice applies in the
+  case of multiplication of a complex operand and a pure-imaginary
+  operand, and in the case of division of a complex operand by a real or
+  pure-imaginary operand."
+
+Not followed.
+
+  "Similarly, because the usual mathematical meaning of addition of a
+  complex operand and a real operand is that the imaginary operand remains
+  unchanged, an implementation should not perform this operation by first
+  promoting the real operand to complex type and then performing a full
+  complex addition.  In implementations in which the ``Signed_Zeros``
+  attribute of the component type is ``True`` (and which therefore
+  conform to IEC 559:1989 in regard to the handling of the sign of zero in
+  predefined arithmetic operations), the latter technique will not
+  generate the required result when the imaginary component of the complex
+  operand is a negatively signed zero.  (Explicit addition of the negative
+  zero to the zero obtained during promotion yields a positive zero.)
+  Analogous advice applies in the case of addition of a complex operand
+  and a pure-imaginary operand, and in the case of subtraction of a
+  complex operand and a real or pure-imaginary operand."
+
+Not followed.
+
+  "Implementations in which ``Real'Signed_Zeros`` is ``True`` should
+  attempt to provide a rational treatment of the signs of zero results and
+  result components.  As one example, the result of the ``Argument``
+  function should have the sign of the imaginary component of the
+  parameter ``X`` when the point represented by that parameter lies on
+  the positive real axis; as another, the sign of the imaginary component
+  of the ``Compose_From_Polar`` function should be the same as
+  (respectively, the opposite of) that of the ``Argument`` parameter when that
+  parameter has a value of zero and the ``Modulus`` parameter has a
+  nonnegative (respectively, negative) value."
+
+Followed.
+
+.. index:: Complex elementary functions
+
+RM G.1.2(49): Complex Elementary Functions
+==========================================
+
+  "Implementations in which ``Complex_Types.Real'Signed_Zeros`` is
+  ``True`` should attempt to provide a rational treatment of the signs
+  of zero results and result components.  For example, many of the complex
+  elementary functions have components that are odd functions of one of
+  the parameter components; in these cases, the result component should
+  have the sign of the parameter component at the origin.  Other complex
+  elementary functions have zero components whose sign is opposite that of
+  a parameter component at the origin, or is always positive or always
+  negative."
+
+Followed.
+
+.. index:: Accuracy requirements
+
+RM G.2.4(19): Accuracy Requirements
+===================================
+
+  "The versions of the forward trigonometric functions without a
+  ``Cycle`` parameter should not be implemented by calling the
+  corresponding version with a ``Cycle`` parameter of
+  ``2.0*Numerics.Pi``, since this will not provide the required
+  accuracy in some portions of the domain.  For the same reason, the
+  version of ``Log`` without a ``Base`` parameter should not be
+  implemented by calling the corresponding version with a ``Base``
+  parameter of ``Numerics.e``."
+
+Followed.
+
+.. index:: Complex arithmetic accuracy
+
+.. index:: Accuracy, complex arithmetic
+
+RM G.2.6(15): Complex Arithmetic Accuracy
+=========================================
+
+  "The version of the ``Compose_From_Polar`` function without a
+  ``Cycle`` parameter should not be implemented by calling the
+  corresponding version with a ``Cycle`` parameter of
+  ``2.0*Numerics.Pi``, since this will not provide the required
+  accuracy in some portions of the domain."
+
+Followed.
+
+.. index:: Sequential elaboration policy
+
+RM H.6(15/2): Pragma Partition_Elaboration_Policy
+=================================================
+
+  "If the partition elaboration policy is ``Sequential`` and the
+  Environment task becomes permanently blocked during elaboration then the
+  partition is deadlocked and it is recommended that the partition be
+  immediately terminated."
+
+Not followed.