------------------------------------------------------------------------------
--                                                                          --
--                         GNAT COMPILER COMPONENTS                         --
--                                                                          --
--                             E X P _ D B U G                              --
--                                                                          --
--                                 S p e c                                  --
--                                                                          --
--          Copyright (C) 1996-2016, Free Software Foundation, Inc.         --
--                                                                          --
-- GNAT is free software;  you can  redistribute it  and/or modify it under --
-- terms of the  GNU General Public License as published  by the Free Soft- --
-- ware  Foundation;  either version 3,  or (at your option) any later ver- --
-- sion.  GNAT is distributed in the hope that it will be useful, but WITH- --
-- OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY --
-- or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License --
-- for  more details.  You should have  received  a copy of the GNU General --
-- Public License  distributed with GNAT; see file COPYING3.  If not, go to --
-- http://www.gnu.org/licenses for a complete copy of the license.          --
--                                                                          --
-- GNAT was originally developed  by the GNAT team at  New York University. --
-- Extensive contributions were provided by Ada Core Technologies Inc.      --
--                                                                          --
------------------------------------------------------------------------------

--  Expand routines for generation of special declarations used by the
--  debugger. In accordance with the Dwarf 2.2 specification, certain
--  type names are encoded to provide information to the debugger.

with Namet; use Namet;
with Types; use Types;
with Uintp; use Uintp;

package Exp_Dbug is

   -----------------------------------------------------
   -- Encoding and Qualification of Names of Entities --
   -----------------------------------------------------

   --  This section describes how the names of entities are encoded in the
   --  generated debugging information.

   --  An entity in Ada has a name of the form X.Y.Z ... E where X,Y,Z are the
   --  enclosing scopes (not including Standard at the start).

   --  The encoding of the name follows this basic qualified naming scheme,
   --  where the encoding of individual entity names is as described in Namet
   --  (i.e. in particular names present in the original source are folded to
   --  all lower case, with upper half and wide characters encoded as described
   --  in Namet). Upper case letters are used only for entities generated by
   --  the compiler.

   --  There are two cases, global entities, and local entities. In more formal
   --  terms, local entities are those which have a dynamic enclosing scope,
   --  and global entities are at the library level, except that we always
   --  consider procedures to be global entities, even if they are nested
   --  (that's because at the debugger level a procedure name refers to the
   --  code, and the code is indeed a global entity, including the case of
   --  nested procedures.) In addition, we also consider all types to be global
   --  entities, even if they are defined within a procedure.

   --  The reason for treating all type names as global entities is that a
   --  number of our type encodings work by having related type names, and we
   --  need the full qualification to keep this unique.

   --  For global entities, the encoded name includes all components of the
   --  fully expanded name (but omitting Standard at the start). For example,
   --  if a library level child package P.Q has an embedded package R, and
   --  there is an entity in this embedded package whose name is S, the encoded
   --  name will include the components p.q.r.s.

   --  For local entities, the encoded name only includes the components up to
   --  the enclosing dynamic scope (other than a block). At run time, such a
   --  dynamic scope is a subprogram, and the debugging formats know about
   --  local variables of procedures, so it is not necessary to have full
   --  qualification for such entities. In particular this means that direct
   --  local variables of a procedure are not qualified.

   --  As an example of the local name convention, consider a procedure V.W
   --  with a local variable X, and a nested block Y containing an entity Z.
   --  The fully qualified names of the entities X and Z are:

   --    V.W.X
   --    V.W.Y.Z

   --  but since V.W is a subprogram, the encoded names will end up
   --  encoding only

   --    x
   --    y.z

   --  The separating dots are translated into double underscores

      -----------------------------
      -- Handling of Overloading --
      -----------------------------

      --  The above scheme is incomplete for overloaded subprograms, since
      --  overloading can legitimately result in case of two entities with
      --  exactly the same fully qualified names. To distinguish between
      --  entries in a set of overloaded subprograms, the encoded names are
      --  serialized by adding the suffix:

      --    __nn  (two underscores)

      --  where nn is a serial number (2 for the second overloaded function,
      --  3 for the third, etc.). A suffix of __1 is always omitted (i.e. no
      --  suffix implies the first instance).

      --  These names are prefixed by the normal full qualification. So for
      --  example, the third instance of the subprogram qrs in package yz
      --  would have the name:

      --    yz__qrs__3

      --  A more subtle case arises with entities declared within overloaded
      --  subprograms. If we have two overloaded subprograms, and both declare
      --  an entity xyz, then the fully expanded name of the two xyz's is the
      --  same. To distinguish these, we add the same __n suffix at the end of
      --  the inner entity names.

      --  In more complex cases, we can have multiple levels of overloading,
      --  and we must make sure to distinguish which final declarative region
      --  we are talking about. For this purpose, we use a more complex suffix
      --  which has the form:

      --    __nn_nn_nn ...

      --  where the nn values are the homonym numbers as needed for any of the
      --  qualifying entities, separated by a single underscore. If all the nn
      --  values are 1, the suffix is omitted, Otherwise the suffix is present
      --  (including any values of 1). The following example shows how this
      --  suffixing works.

      --    package body Yz is
      --      procedure Qrs is               -- Name is yz__qrs
      --        procedure Tuv is ... end;    -- Name is yz__qrs__tuv
      --      begin ... end Qrs;

      --      procedure Qrs (X: Int) is      -- Name is yz__qrs__2
      --        procedure Tuv is ... end;    -- Name is yz__qrs__tuv__2_1
      --        procedure Tuv (X: Int) is    -- Name is yz__qrs__tuv__2_2
      --        begin ... end Tuv;

      --        procedure Tuv (X: Float) is  -- Name is yz__qrs__tuv__2_3
      --          type m is new float;       -- Name is yz__qrs__tuv__m__2_3
      --        begin ... end Tuv;
      --      begin ... end Qrs;
      --    end Yz;

      --------------------
      -- Operator Names --
      --------------------

      --   The above rules applied to operator names would result in names with
      --   quotation marks, which are not typically allowed by assemblers and
      --   linkers, and even if allowed would be odd and hard to deal with. To
      --   avoid this problem, operator names are encoded as follows:

      --    Oabs       abs
      --    Oand       and
      --    Omod       mod
      --    Onot       not
      --    Oor        or
      --    Orem       rem
      --    Oxor       xor
      --    Oeq        =
      --    One        /=
      --    Olt        <
      --    Ole        <=
      --    Ogt        >
      --    Oge        >=
      --    Oadd       +
      --    Osubtract  -
      --    Oconcat    &
      --    Omultiply  *
      --    Odivide    /
      --    Oexpon     **

      --  These names are prefixed by the normal full qualification, and
      --  suffixed by the overloading identification. So for example, the
      --  second operator "=" defined in package Extra.Messages would have
      --  the name:

      --    extra__messages__Oeq__2

      ----------------------------------
      -- Resolving Other Name Clashes --
      ----------------------------------

      --  It might be thought that the above scheme is complete, but in Ada 95,
      --  full qualification is insufficient to uniquely identify an entity in
      --  the program, even if it is not an overloaded subprogram. There are
      --  two possible confusions:

      --     a.b

      --       interpretation 1: entity b in body of package a
      --       interpretation 2: child procedure b of package a

      --     a.b.c

      --       interpretation 1: entity c in child package a.b
      --       interpretation 2: entity c in nested package b in body of a

      --  It is perfectly legal in both cases for both interpretations to be
      --  valid within a single program. This is a bit of a surprise since
      --  certainly in Ada 83, full qualification was sufficient, but not in
      --  Ada 95. The result is that the above scheme can result in duplicate
      --  names. This would not be so bad if the effect were just restricted
      --  to debugging information, but in fact in both the above cases, it
      --  is possible for both symbols to be external names, and so we have
      --  a real problem of name clashes.

      --  To deal with this situation, we provide two additional encoding
      --  rules for names:

      --    First: all library subprogram names are preceded by the string
      --    _ada_ (which causes no duplications, since normal Ada names can
      --    never start with an underscore. This not only solves the first
      --    case of duplication, but also solves another pragmatic problem
      --    which is that otherwise Ada procedures can generate names that
      --    clash with existing system function names. Most notably, we can
      --    have clashes in the case of procedure Main with the C main that
      --    in some systems is always present.

      --    Second, for the case where nested packages declared in package
      --    bodies can cause trouble, we add a suffix which shows which
      --    entities in the list are body-nested packages, i.e. packages
      --    whose spec is within a package body. The rules are as follows,
      --    given a list of names in a qualified name name1.name2....

      --    If none are body-nested package entities, then there is no suffix

      --    If at least one is a body-nested package entity, then the suffix
      --    is X followed by a string of b's and n's (b = body-nested package
      --    entity, n = not a body-nested package).

      --    There is one element in this string for each entity in the encoded
      --    expanded name except the first (the rules are such that the first
      --    entity of the encoded expanded name can never be a body-nested'
      --    package. Trailing n's are omitted, as is the last b (there must
      --    be at least one b, or we would not be generating a suffix at all).

      --  For example, suppose we have

      --    package x is
      --       pragma Elaborate_Body;
      --       m1 : integer;                                    -- #1
      --    end x;

      --    package body x is
      --      package y is m2 : integer; end y;                 -- #2
      --      package body y is
      --         package z is r : integer; end z;               -- #3
      --      end;
      --      m3 : integer;                                     -- #4
      --    end x;

      --    package x.y is
      --       pragma Elaborate_Body;
      --       m2 : integer;                                    -- #5
      --    end x.y;

      --    package body x.y is
      --       m3 : integer;                                    -- #6
      --       procedure j is                                   -- #7
      --         package k is
      --            z : integer;                                -- #8
      --         end k;
      --       begin
      --          null;
      --       end j;
      --    end x.y;

      --    procedure x.m3 is begin null; end;                  -- #9

      --  Then the encodings would be:

      --    #1.  x__m1             (no BNPE's in sight)
      --    #2.  x__y__m2X         (y is a BNPE)
      --    #3.  x__y__z__rXb      (y is a BNPE, so is z)
      --    #4.  x__m3             (no BNPE's in sight)
      --    #5.  x__y__m2          (no BNPE's in sight)
      --    #6.  x__y__m3          (no BNPE's in signt)
      --    #7.  x__y__j           (no BNPE's in sight)
      --    #8.  k__z              (no BNPE's, only up to procedure)
      --    #9   _ada_x__m3        (library level subprogram)

      --  Note that we have instances here of both kind of potential name
      --  clashes, and the above examples show how the encodings avoid the
      --  clash as follows:

      --    Lines #4 and #9 both refer to the entity x.m3, but #9 is a library
      --    level subprogram, so it is preceded by the string _ada_ which acts
      --    to distinguish it from the package body entity.

      --    Lines #2 and #5 both refer to the entity x.y.m2, but the first
      --    instance is inside the body-nested package y, so there is an X
      --    suffix to distinguish it from the child library entity.

      --  Note that enumeration literals never need Xb type suffixes, since
      --  they are never referenced using global external names.

      ---------------------
      -- Interface Names --
      ---------------------

      --  Note: if an interface name is present, then the external name is
      --  taken from the specified interface name. Given current limitations of
      --  the gcc backend, this means that the debugging name is also set to
      --  the interface name, but conceptually, it would be possible (and
      --  indeed desirable) to have the debugging information still use the Ada
      --  name as qualified above, so we still fully qualify the name in the
      --  front end.

      -------------------------------------
      -- Encodings Related to Task Types --
      -------------------------------------

      --  Each task object defined by a single task declaration is associated
      --  with a prefix that is used to qualify procedures defined in that
      --  task. Given
      --
      --    package body P is
      --      task body TaskObj is
      --        procedure F1 is ... end;
      --      begin
      --        B;
      --      end TaskObj;
      --    end P;
      --
      --  The name of subprogram TaskObj.F1 is encoded as p__taskobjTK__f1.
      --  The body, B, is contained in a subprogram whose name is
      --  p__taskobjTKB.

      ------------------------------------------
      -- Encodings Related to Protected Types --
      ------------------------------------------

      --  Each protected type has an associated record type, that describes
      --  the actual layout of the private data. In addition to the private
      --  components of the type, the Corresponding_Record_Type includes one
      --  component of type Protection, which is the actual lock structure.
      --  The run-time size of the protected type is the size of the corres-
      --  ponding record.

      --  For a protected type prot, the Corresponding_Record_Type is encoded
      --  as protV.

      --  The operations of a protected type are encoded as follows: each
      --  operation results in two subprograms, a locking one that is called
      --  from outside of the object, and a non-locking one that is used for
      --  calls from other operations on the same object. The locking operation
      --  simply acquires the lock, and then calls the non-locking version.
      --  The names of all of these have a prefix constructed from the name of
      --  the type, and a suffix which is P or N, depending on whether this is
      --  the protected/non-locking version of the operation.

      --  Operations generated for protected entries follow the same encoding.
      --  Each entry results in two subprograms: a procedure that holds the
      --  entry body, and a function that holds the evaluation of the barrier.
      --  The names of these subprograms include the prefix '_E' or '_B' res-
      --  pectively. The names also include a numeric suffix to render them
      --  unique in the presence of overloaded entries.

      --  Given the declaration:

      --    protected type Lock is
      --       function  Get return Integer;
      --       procedure Set (X: Integer);
      --       entry Update  (Val : Integer);
      --    private
      --       Value : Integer := 0;
      --    end Lock;

      --  the following operations are created:

      --    lock_getN
      --    lock_getP,

      --    lock_setN
      --    lock_setP

      --    lock_update_E1s
      --    lock_udpate_B2s

      --  If the protected type implements at least one interface, the
      --  following additional operations are created:

      --    lock_get

      --    lock_set

      --  These operations are used to ensure overriding of interface level
      --  subprograms and proper dispatching on interface class-wide objects.
      --  The bodies of these operations contain calls to their respective
      --  protected versions:

      --    function lock_get return Integer is
      --    begin
      --       return lock_getP;
      --    end lock_get;

      --    procedure lock_set (X : Integer) is
      --    begin
      --       lock_setP (X);
      --    end lock_set;

   ----------------------------------------------------
   -- Conversion between Entities and External Names --
   ----------------------------------------------------

   procedure Get_External_Name
     (Entity     : Entity_Id;
      Has_Suffix : Boolean := False;
      Suffix     : String  := "");
   --  Set Name_Buffer and Name_Len to the external name of the entity. The
   --  external name is the Interface_Name, if specified, unless the entity
   --  has an address clause or Has_Suffix is true.
   --
   --  If the Interface is not present, or not used, the external name is the
   --  concatenation of:
   --
   --    - the string "_ada_", if the entity is a library subprogram,
   --    - the names of any enclosing scopes, each followed by "__",
   --        or "X_" if the next entity is a subunit)
   --    - the name of the entity
   --    - the string "$" (or "__" if target does not allow "$"), followed
   --        by homonym suffix, if the entity is an overloaded subprogram
   --        or is defined within an overloaded subprogram.
   --    - the string "___" followed by Suffix if Has_Suffix is true.
   --
   --  Note that a call to this procedure has no effect if we are not
   --  generating code, since the necessary information for computing the
   --  proper external name is not available in this case.

   -------------------------------------
   -- Encoding for translation into C --
   -------------------------------------

   --  In Modify_Tree_For_C mode we must add encodings to dismabiguate cases
   --  where Ada block structure cannot be directly translated. These cases
   --  are as follows:

   --    a)  A loop variable may hide a homonym in an enclosing block
   --    b)  A block-local variable may hide a homonym in an enclosing block

   --  In C these constructs are not scopes and we must distinguish the names
   --  explicitly. In the first case we create a qualified name with the suffix
   --  'L', in the second case with a suffix 'B'.

   --------------------------------------------
   -- Subprograms for Handling Qualification --
   --------------------------------------------

   procedure Qualify_Entity_Names (N : Node_Id);
   --  Given a node N, that represents a block, subprogram body, or package
   --  body or spec, or protected or task type, sets a fully qualified name
   --  for the defining entity of given construct, and also sets fully
   --  qualified names for all enclosed entities of the construct (using
   --  First_Entity/Next_Entity). Note that the actual modifications of the
   --  names is postponed till a subsequent call to Qualify_All_Entity_Names.
   --  Note: this routine does not deal with prepending _ada_ to library
   --  subprogram names. The reason for this is that we only prepend _ada_
   --  to the library entity itself, and not to names built from this name.

   procedure Qualify_All_Entity_Names;
   --  When Qualify_Entity_Names is called, no actual name changes are made,
   --  i.e. the actual calls to Qualify_Entity_Name are deferred until a call
   --  is made to this procedure. The reason for this deferral is that when
   --  names are changed semantic processing may be affected. By deferring
   --  the changes till just before gigi is called, we avoid any concerns
   --  about such effects. Gigi itself does not use the names except for
   --  output of names for debugging purposes (which is why we are doing
   --  the name changes in the first place.

   --  Note: the routines Get_Unqualified_[Decoded]_Name_String in Namet are
   --  useful to remove qualification from a name qualified by the call to
   --  Qualify_All_Entity_Names.

   --------------------------------
   -- Handling of Numeric Values --
   --------------------------------

   --  All numeric values here are encoded as strings of decimal digits. Only
   --  integer values need to be encoded. A negative value is encoded as the
   --  corresponding positive value followed by a lower case m for minus to
   --  indicate that the value is negative (e.g. 2m for -2).

   -------------------------
   -- Type Name Encodings --
   -------------------------

   --  In the following typ is the name of the type as normally encoded by the
   --  debugger rules, i.e. a non-qualified name, all in lower case, with
   --  standard encoding of upper half and wide characters

      ------------------------
      -- Encapsulated Types --
      ------------------------

      --  In some cases, the compiler encapsulates a type by wrapping it in a
      --  structure. For example, this is used when a size or alignment
      --  specification requires a larger type. Consider:

      --    type y is mod 2 ** 64;
      --    for y'size use 256;

      --  In this case the compile generates a structure type y___PAD, which
      --  has a single field whose name is F. This single field is 64 bits
      --  long and contains the actual value. This kind of padding is used
      --  when the logical value to be stored is shorter than the object in
      --  which it is allocated. For example if a size clause is used to set
      --  a size of 256 for a signed integer value, then a typical choice is
      --  to wrap a 64-bit integer in a 256 bit PAD structure.

      --  A similar encapsulation is done for some packed array types, in which
      --  case the structure type is y___JM and the field name is OBJECT.
      --  This is used in the case of a packed array stored using modular
      --  representation (see section on representation of packed array
      --  objects). In this case the JM wrapping is used to achieve correct
      --  positioning of the packed array value (left or right justified in its
      --  field depending on endianness.

      --  When the debugger sees an object of a type whose name has a suffix of
      --  ___PAD or ___JM, the type will be a record containing a single field,
      --  and the name of that field will be all upper case. In this case, it
      --  should look inside to get the value of the inner field, and neither
      --  the outer structure name, nor the field name should appear when the
      --  value is printed.

      --  When the debugger sees a record named REP being a field inside
      --  another record, it should treat the fields inside REP as being part
      --  of the outer record (this REP field is only present for code
      --  generation purposes). The REP record should not appear in the values
      --  printed by the debugger.

      -----------------------
      -- Fixed-Point Types --
      -----------------------

      --   Fixed-point types are encoded using a suffix that indicates the
      --   delta and small values. The actual type itself is a normal integer
      --   type.

      --     typ___XF_nn_dd
      --     typ___XF_nn_dd_nn_dd

      --   The first form is used when small = delta. The value of delta (and
      --   small) is given by the rational nn/dd, where nn and dd are decimal
      --   integers.
      --
      --   The second form is used if the small value is different from the
      --   delta. In this case, the first nn/dd rational value is for delta,
      --   and the second value is for small.

      --------------------
      -- Discrete Types --
      --------------------

      --   Discrete types are coded with a suffix indicating the range in the
      --   case where one or both of the bounds are discriminants or variable.

      --   Note: at the current time, we also encode compile time known bounds
      --   if they do not match the natural machine type bounds, but this may
      --   be removed in the future, since it is redundant for most debugging
      --   formats. However, we do not ever need XD encoding for enumeration
      --   base types, since here it is always clear what the bounds are from
      --   the total number of enumeration literals.

      --     typ___XD
      --     typ___XDL_lowerbound
      --     typ___XDU_upperbound
      --     typ___XDLU_lowerbound__upperbound

      --   If a discrete type is a natural machine type (i.e. its bounds
      --   correspond in a natural manner to its size), then it is left
      --   unencoded. The above encoding forms are used when there is a
      --   constrained range that does not correspond to the size or that
      --   has discriminant references or other compile time known bounds.

      --   The first form is used if both bounds are dynamic, in which case two
      --   constant objects are present whose names are typ___L and typ___U in
      --   the same scope as typ, and the values of these constants indicate
      --   the bounds. As far as the debugger is concerned, these are simply
      --   variables that can be accessed like any other variables. In the
      --   enumeration case, these values correspond to the Enum_Rep values for
      --   the lower and upper bounds.

      --   The second form is used if the upper bound is dynamic, but the lower
      --   bound is either constant or depends on a discriminant of the record
      --   with which the type is associated. The upper bound is stored in a
      --   constant object of name typ___U as previously described, but the
      --   lower bound is encoded directly into the name as either a decimal
      --   integer, or as the discriminant name.

      --   The third form is similarly used if the lower bound is dynamic, but
      --   the upper bound is compile time known or a discriminant reference,
      --   in which case the lower bound is stored in a constant object of name
      --   typ___L, and the upper bound is encoded directly into the name as
      --   either a decimal integer, or as the discriminant name.

      --   The fourth form is used if both bounds are discriminant references
      --   or compile time known values, with the encoding first for the lower
      --   bound, then for the upper bound, as previously described.

      -------------------
      -- Modular Types --
      -------------------

      --  A type declared

      --    type x is mod N;

      --  Is encoded as a subrange of an unsigned base type with lower bound
      --  zero and upper bound N. That is, there is no name encoding. We use
      --  the standard encodings provided by the debugging format. Thus we
      --  give these types a non-standard interpretation: the standard
      --  interpretation of our encoding would not, in general, imply that
      --  arithmetic on type x was to be performed modulo N (especially not
      --  when N is not a power of 2).

      ------------------
      -- Biased Types --
      ------------------

      --   Only discrete types can be biased, and the fact that they are biased
      --   is indicated by a suffix of the form:

      --     typ___XB_lowerbound__upperbound

      --   Here lowerbound and upperbound are decimal integers, with the usual
      --   (postfix "m") encoding for negative numbers. Biased types are only
      --   possible where the bounds are compile time known, and the values are
      --   represented as unsigned offsets from the lower bound given. For
      --   example:

      --     type Q is range 10 .. 15;
      --     for Q'size use 3;

      --   The size clause will force values of type Q in memory to be stored
      --   in biased form (e.g. 11 will be represented by the bit pattern 001).

      ----------------------------------------------
      -- Record Types with Variable-Length Fields --
      ----------------------------------------------

      --  The debugging formats do not fully support these types, and indeed
      --  some formats simply generate no useful information at all for such
      --  types. In order to provide information for the debugger, gigi creates
      --  a parallel type in the same scope with one of the names

      --    type___XVE
      --    type___XVU

      --  The former name is used for a record and the latter for the union
      --  that is made for a variant record (see below) if that record or union
      --  has a field of variable size or if the record or union itself has a
      --  variable size. These encodings suffix any other encodings that that
      --  might be suffixed to the type name.

      --  The idea here is to provide all the needed information to interpret
      --  objects of the original type in the form of a "fixed up" type, which
      --  is representable using the normal debugging information.

      --  There are three cases to be dealt with. First, some fields may have
      --  variable positions because they appear after variable-length fields.
      --  To deal with this, we encode *all* the field bit positions of the
      --  special ___XV type in a non-standard manner.

      --  The idea is to encode not the position, but rather information that
      --  allows computing the position of a field from the position of the
      --  previous field. The algorithm for computing the actual positions of
      --  all fields and the length of the record is as follows. In this
      --  description, let P represent the current bit position in the record.

      --    1. Initialize P to 0

      --    2. For each field in the record:

      --       2a. If an alignment is given (see below), then round P up, if
      --       needed, to the next multiple of that alignment.

      --       2b. If a bit position is given, then increment P by that amount
      --       (that is, treat it as an offset from the end of the preceding
      --       record).

      --       2c. Assign P as the actual position of the field

      --       2d. Compute the length, L, of the represented field (see below)
      --       and compute P'=P+L. Unless the field represents a variant part
      --       (see below and also Variant Record Encoding), set P to P'.

      --  The alignment, if present, is encoded in the field name of the
      --  record, which has a suffix:

      --    fieldname___XVAnn

      --  where the nn after the XVA indicates the alignment value in storage
      --  units. This encoding is present only if an alignment is present.

      --  The size of the record described by an XVE-encoded type (in bits) is
      --  generally the maximum value attained by P' in step 2d above, rounded
      --  up according to the record's alignment.

      --  Second, the variable-length fields themselves are represented by
      --  replacing the type by a special access type. The designated type of
      --  this access type is the original variable-length type, and the fact
      --  that this field has been transformed in this way is signalled by
      --  encoding the field name as:

      --    field___XVL

      --  where field is the original field name. If a field is both
      --  variable-length and also needs an alignment encoding, then the
      --  encodings are combined using:

      --    field___XVLnn

      --  Note: the reason that we change the type is so that the resulting
      --  type has no variable-length fields. At least some of the formats used
      --  for debugging information simply cannot tolerate variable- length
      --  fields, so the encoded information would get lost.

      --  Third, in the case of a variant record, the special union that
      --  contains the variants is replaced by a normal C union. In this case,
      --  the positions are all zero.

      --  Discriminants appear before any variable-length fields that depend on
      --  them, with one exception. In some cases, a discriminant governing the
      --  choice of a variant clause may appear in the list of fields of an XVE
      --  type after the entry for the variant clause itself (this can happen
      --  in the presence of a representation clause for the record type in the
      --  source program). However, when this happens, the discriminant's
      --  position may be determined by first applying the rules described in
      --  this section, ignoring the variant clause. As a result, discriminants
      --  can always be located independently of the variable-length fields
      --  that depend on them.

      --  The size of the ___XVE or ___XVU record or union is set to the
      --  alignment (in bytes) of the original object so that the debugger
      --  can calculate the size of the original type.

      --  As an example of this encoding, consider the declarations:

      --    type Q is array (1 .. V1) of Float;       -- alignment 4
      --    type R is array (1 .. V2) of Long_Float;  -- alignment 8

      --    type X is record
      --       A : Character;
      --       B : Float;
      --       C : String (1 .. V3);
      --       D : Float;
      --       E : Q;
      --       F : R;
      --       G : Float;
      --    end record;

      --  The encoded type looks like:

      --    type anonymousQ is access Q;
      --    type anonymousR is access R;

      --    type X___XVE is record
      --       A        : Character;               -- position contains 0
      --       B        : Float;                   -- position contains 24
      --       C___XVL  : access String (1 .. V3); -- position contains 0
      --       D___XVA4 : Float;                   -- position contains 0
      --       E___XVL4 : anonymousQ;              -- position contains 0
      --       F___XVL8 : anonymousR;              -- position contains 0
      --       G        : Float;                   -- position contains 0
      --    end record;

      --  Any bit sizes recorded for fields other than dynamic fields and
      --  variants are honored as for ordinary records.

      --  Notes:

      --  1) The B field could also have been encoded by using a position of
      --  zero and an alignment of 4, but in such a case the coding by position
      --  is preferred (since it takes up less space). We have used the
      --  (illegal) notation access xxx as field types in the example above.

      --  2) The E field does not actually need the alignment indication but
      --  this may not be detected in this case by the conversion routines.

      --  3) Our conventions do not cover all XVE-encoded records in which
      --  some, but not all, fields have representation clauses. Such records
      --  may, therefore, be displayed incorrectly by debuggers. This situation
      --  is not common.

      -----------------------
      -- Base Record Types --
      -----------------------

      --  Under certain circumstances, debuggers need two descriptions of a
      --  record type, one that gives the actual details of the base type's
      --  structure (as described elsewhere in these comments) and one that may
      --  be used to obtain information about the particular subtype and the
      --  size of the objects being typed. In such cases the compiler will
      --  substitute type whose name is typically compiler-generated and
      --  irrelevant except as a key for obtaining the actual type.

      --  Specifically, if this name is x, then we produce a record type named
      --  x___XVS consisting of one field. The name of this field is that of
      --  the actual type being encoded, which we'll call y. The type of this
      --  single field can be either an arbitrary non-reference type, e.g. an
      --  integer type, or a reference type; in the latter case, the referenced
      --  type is also the actual type being encoded y. Both x and y may have
      --  corresponding ___XVE types.

      --  The size of the objects typed as x should be obtained from the
      --  structure of x (and x___XVE, if applicable) as for ordinary types
      --  unless there is a variable named x___XVZ, which, if present, will
      --  hold the size (in bytes) of x. In this latter case, the size of the
      --  x___XVS type will not be a constant but a reference to x___XVZ.

      --  The type x will either be a subtype of y (see also Subtypes of
      --  Variant Records, below) or will contain a single field of type y,
      --  or no fields at all. The layout, types, and positions of these
      --  fields will be accurate, if present. (Currently, however, the GDB
      --  debugger makes no use of x except to determine its size).

      --  Among other uses, XVS types are used to encode unconstrained types.
      --  For example, given:
      --
      --     subtype Int is INTEGER range 0..10;
      --     type T1 (N: Int := 0) is record
      --        F1: String (1 .. N);
      --     end record;
      --     type AT1 is array (INTEGER range <>) of T1;
      --
      --  the element type for AT1 might have a type defined as if it had
      --  been written:
      --
      --     type at1___PAD is record F : T1; end record;
      --     for at1___PAD'Size use 16 * 8;
      --
      --  and there would also be:
      --
      --     type at1___PAD___XVS is record t1: reft1; end record;
      --     type t1 is ...
      --     type reft1 is <reference to t1>
      --
      --  Had the subtype Int been dynamic:
      --
      --     subtype Int is INTEGER range 0 .. M;  -- M a variable
      --
      --  Then the compiler would also generate a declaration whose effect
      --  would be
      --
      --     at1___PAD___XVZ: constant Integer := 32 + M * 8 + padding term;
      --
      --  Not all unconstrained types are so encoded; the XVS convention may be
      --  unnecessary for unconstrained types of fixed size. However, this
      --  encoding is always necessary when a subcomponent type (array
      --  element's type or record field's type) is an unconstrained record
      --  type some of whose components depend on discriminant values.

      -----------------
      -- Array Types --
      -----------------

      --  Since there is no way for the debugger to obtain the index subtypes
      --  for an array type, we produce a type that has the name of the array
      --  type followed by "___XA" and is a record type whose field types are
      --  the respective types for the bounds (and whose field names are the
      --  names of these types).

      --  To conserve space, we do not produce this type unless one of the
      --  index types is either an enumeration type, has a variable lower or
      --  upper bound or is a biased type.

      --  Given the full encoding of these types (see above description for
      --  the encoding of discrete types), this means that all necessary
      --  information for addressing arrays is available. In some debugging
      --  formats, some or all of the bounds information may be available
      --  redundantly, particularly in the fixed-point case, but this
      --  information can in any case be ignored by the debugger.

      ----------------------------
      -- Note on Implicit Types --
      ----------------------------

      --  The compiler creates implicit type names in many situations where a
      --  type is present semantically, but no specific name is present. For
      --  example:

      --     S : Integer range M .. N;

      --  Here the subtype of S is not integer, but rather an anonymous subtype
      --  of Integer. Where possible, the compiler generates names for such
      --  anonymous types that are related to the type from which the subtype
      --  is obtained as follows:

      --     T name suffix

      --  where name is the name from which the subtype is obtained, using
      --  lower case letters and underscores, and suffix starts with an upper
      --  case letter. For example the name for the above declaration might be:

      --     TintegerS4b

      --  If the debugger is asked to give the type of an entity and the type
      --  has the form T name suffix, it is probably appropriate to just use
      --  "name" in the response since this is what is meaningful to the
      --  programmer.

   -------------------------------------------------
   -- Subprograms for Handling Encoded Type Names --
   -------------------------------------------------

   procedure Get_Encoded_Name (E : Entity_Id);
   --  If the entity is a typename, store the external name of the entity as in
   --  Get_External_Name, followed by three underscores plus the type encoding
   --  in Name_Buffer with the length in Name_Len, and an ASCII.NUL character
   --  stored following the name. Otherwise set Name_Buffer and Name_Len to
   --  hold the entity name. Note that a call to this procedure has no effect
   --  if we are not generating code, since the necessary information for
   --  computing the proper encoded name is not available in this case.

   --------------
   -- Renaming --
   --------------

   --  Debugging information is generated for exception, object, package, and
   --  subprogram renaming (generic renamings are not significant, since
   --  generic templates are not relevant at debugging time).

   --  Consider a renaming declaration of the form

   --    x : typ renames y;

   --  There is one case in which no special debugging information is required,
   --  namely the case of an object renaming where the back end allocates a
   --  reference for the renamed variable, and the entity x is this reference.
   --  The debugger can handle this case without any special processing or
   --  encoding (it won't know it was a renaming, but that does not matter).

   --  All other cases of renaming generate a dummy variable for an entity
   --  whose name is of the form:

   --    x___XR_...    for an object renaming
   --    x___XRE_...   for an exception renaming
   --    x___XRP_...   for a package renaming

   --  and where the "..." represents a suffix that describes the structure of
   --  the object name given in the renaming (see details below).

   --  The name is fully qualified in the usual manner, i.e. qualified in the
   --  same manner as the entity x would be. In the case of a package renaming
   --  where x is a child unit, the qualification includes the name of the
   --  parent unit, to disambiguate child units with the same simple name and
   --  (of necessity) different parents.

   --  Note: subprogram renamings are not encoded at the present time

   --  The suffix of the variable name describing the renamed object is defined
   --  to use the following encoding:

   --    For the simple entity case, where y is just an entity name, the suffix
   --    is of the form:

   --       y___XE

   --          i.e. the suffix has a single field, the first part matching the
   --          name y, followed by a "___" separator, ending with sequence XE.
   --          The entity name portion is fully qualified in the usual manner.
   --          This same naming scheme is followed for all forms of encoded
   --          renamings that rename a simple entity.

   --    For the object renaming case where y is a selected component or an
   --    indexed component, the variable name is suffixed by additional fields
   --    that give details of the components. The name starts as above with a
   --    y___XE name indicating the outer level object entity. Then a series of
   --    selections and indexing operations can be specified as follows:

   --      Indexed component

   --        A series of subscript values appear in sequence, the number
   --        corresponds to the number of dimensions of the array. The
   --        subscripts have one of the following two forms:

   --          XSnnn

   --            Here nnn is a constant value, encoded as a decimal integer
   --            (pos value for enumeration type case). Negative values have
   --            a trailing 'm' as usual.

   --          XSe

   --            Here e is the (unqualified) name of a constant entity in the
   --            same scope as the renaming which contains the subscript value.

   --      Slice

   --        For the slice case, we have two entries. The first is for the
   --        lower bound of the slice, and has the form:

   --          XLnnn
   --          XLe

   --            Specifies the lower bound, using exactly the same encoding as
   --            for an XS subscript as described above.

   --        Then the upper bound appears in the usual XSnnn/XSe form

   --      Selected component

   --        For a selected component, we have a single entry

   --          XRf

   --            Here f is the field name for the selection

   --        For an explicit dereference (.all), we have a single entry

   --          XA

   --      As an example, consider the declarations:

   --        package p is
   --           type q is record
   --              m : string (2 .. 5);
   --           end record;
   --
   --           type r is array (1 .. 10, 1 .. 20) of q;
   --
   --           g : r;
   --
   --           z : string renames g (1,5).m(2 ..3)
   --        end p;

   --     The generated variable entity would appear as

   --       p__z___XR_p__g___XEXS1XS5XRmXL2XS3 : _renaming_type;
   --                 p__g___XE--------------------outer entity is g
   --                          XS1-----------------first subscript for g
   --                             XS5--------------second subscript for g
   --                                XRm-----------select field m
   --                                   XL2--------lower bound of slice
   --                                      XS3-----upper bound of slice

   --     Note that the type of the variable is a special internal type named
   --     _renaming_type. This type is an arbitrary type of zero size created
   --     in package Standard (see cstand.adb) and is ignored by the debugger.

   function Debug_Renaming_Declaration (N : Node_Id) return Node_Id;
   --  The argument N is a renaming declaration. The result is a variable
   --  declaration as described in the above paragraphs. If N is not a special
   --  debug declaration, then Empty is returned. This function also takes care
   --  of setting Materialize_Entity on the renamed entity where required.

   ---------------------------
   -- Packed Array Encoding --
   ---------------------------

   --  For every constrained packed array, two types are created, and both
   --  appear in the debugging output:

   --    The original declared array type is a perfectly normal array type, and
   --    its index bounds indicate the original bounds of the array.

   --    The corresponding packed array type, which may be a modular type, or
   --    may be an array of bytes type (see Exp_Pakd for full details). This is
   --    the type that is actually used in the generated code and for debugging
   --    information for all objects of the packed type.

   --  The name of the corresponding packed array type is:

   --    ttt___XPnnn

   --  where

   --    ttt is the name of the original declared array
   --    nnn is the component size in bits (1-31)

   --  Note that if the packed array is not bit-packed, the name will simply
   --  be tttP.

   --  When the debugger sees that an object is of a type that is encoded in
   --  this manner, it can use the original type to determine the bounds and
   --  the component type, and the component size to determine the packing
   --  details.

   --  For an unconstrained packed array, the corresponding packed array type
   --  is neither used in the generated code nor for debugging information,
   --  only the original type is used. In order to convey the packing in the
   --  debugging information, the compiler generates the associated fat- and
   --  thin-pointer types (see the Pointers to Unconstrained Array section
   --  below) using the name of the corresponding packed array type as the
   --  base name, i.e. ttt___XPnnn___XUP and ttt___XPnnn___XUT respectively.

   --  When the debugger sees that an object is of a type that is encoded in
   --  this manner, it can use the type of the fields to determine the bounds
   --  and the component type, and the component size to determine the packing
   --  details.

   -------------------------------------------
   -- Packed Array Representation in Memory --
   -------------------------------------------

   --  Packed arrays are represented in tightly packed form, with no extra bits
   --  between components. This is true even when the component size is not a
   --  factor of the storage unit size, so that as a result it is possible for
   --  components to cross storage unit boundaries.

   --  The layout in storage is identical, regardless of whether the
   --  implementation type is a modular type or an array-of-bytes type. See
   --  Exp_Pakd for details of how these implementation types are used, but for
   --  the purpose of the debugger, only the starting address of the object in
   --  memory is significant.

   --  The following example should show clearly how the packing works in
   --  the little-endian and big-endian cases:

   --     type B is range 0 .. 7;
   --     for B'Size use 3;

   --     type BA is array (0 .. 5) of B;
   --     pragma Pack (BA);

   --     BV : constant BA := (1,2,3,4,5,6);

   --  Little endian case

   --        BV'Address + 2   BV'Address + 1    BV'Address + 0
   --     +-----------------+-----------------+-----------------+
   --     | ? ? ? ? ? ? 1 1 | 0 1 0 1 1 0 0 0 | 1 1 0 1 0 0 0 1 |
   --     +-----------------+-----------------+-----------------+
   --       <---------> <-----> <---> <---> <-----> <---> <--->
   --       unused bits  BV(5)  BV(4) BV(3)  BV(2)  BV(1) BV(0)
   --
   --  Big endian case
   --
   --        BV'Address + 0  BV'Address + 1    BV'Address + 2
   --     +-----------------+-----------------+-----------------+
   --     | 0 0 1 0 1 0 0 1 | 1 1 0 0 1 0 1 1 | 1 0 ? ? ? ? ? ? |
   --     +-----------------+-----------------+-----------------+
   --       <---> <---> <-----> <---> <---> <-----> <--------->
   --       BV(0) BV(1)  BV(2)  BV(3) BV(4)  BV(5)  unused bits

   --  Note that if a modular type is used to represent the array, the
   --  allocation in memory is not the same as a normal modular type. The
   --  difference occurs when the allocated object is larger than the size of
   --  the array. For a normal modular type, we extend the value on the left
   --  with zeroes.

   --  For example, in the normal modular case, if we have a 6-bit modular
   --  type, declared as mod 2**6, and we allocate an 8-bit object for this
   --  type, then we extend the value with two bits on the most significant
   --  end, and in either the little-endian or big-endian case, the value 63
   --  is represented as 00111111 in binary in memory.

   --  For a modular type used to represent a packed array, the rule is
   --  different. In this case, if we have to extend the value, then we do it
   --  with undefined bits (which are not initialized and whose value is
   --  irrelevant to any generated code). Furthermore these bits are on the
   --  right (least significant bits) in the big-endian case, and on the left
   --  (most significant bits) in the little-endian case.

   --  For example, if we have a packed boolean array of 6 bits, all set to
   --  True, stored in an 8-bit object, then the value in memory in binary is
   --  ??111111 in the little-endian case, and 111111?? in the big-endian case.

   --  This is done so that the representation of packed arrays does not
   --  depend on whether we use a modular representation or array of bytes
   --  as previously described. This ensures that we can pass such values by
   --  reference in the case where a subprogram has to be able to handle values
   --  stored in either form.

   --  Note that when we extract the value of such a modular packed array, we
   --  expect to retrieve only the relevant bits, so in this same example, when
   --  we extract the value we get 111111 in both cases, and the code generated
   --  by the front end assumes this although it does not assume that any high
   --  order bits are defined.

   --  There are opportunities for optimization based on the knowledge that the
   --  unused bits are irrelevant for these type of packed arrays. For example
   --  if we have two such 6-bit-in-8-bit values and we do an assignment:

   --     a := b;

   --  Then logically, we extract the 6 bits and store only 6 bits in the
   --  result, but the back end is free to simply assign the entire 8-bits in
   --  this case, since we don't actually care about the undefined bits.
   --  However, in the equality case, it is important to ensure that the
   --  undefined bits do not participate in an equality test.

   --  If a modular packed array value is assigned to a register then logically
   --  it could always be held right justified, to avoid any need to shift,
   --  e.g. when doing comparisons. But probably this is a bad choice, as it
   --  would mean that an assignment such as a := above would require shifts
   --  when one value is in a register and the other value is in memory.

   ------------------------------------------------------
   -- Subprograms for Handling Packed Array Type Names --
   ------------------------------------------------------

   function Make_Packed_Array_Impl_Type_Name
     (Typ   : Entity_Id;
      Csize : Uint) return Name_Id;
   --  This function is used in Exp_Pakd to create the name that is encoded as
   --  described above. The entity Typ provides the name ttt, and the value
   --  Csize is the component size that provides the nnn value.

   --------------------------------------
   -- Pointers to Unconstrained Arrays --
   --------------------------------------

   --  There are two kinds of pointers to arrays. The debugger can tell which
   --  format is in use by the form of the type of the pointer.

   --    Fat Pointers

   --      Fat pointers are represented as a struct with two fields. This
   --      struct has two distinguished field names:

   --        P_ARRAY is a pointer to the array type. The name of this type is
   --        the unconstrained type followed by "___XUA". This array will have
   --        bounds which are the discriminants, and hence are unparsable, but
   --        will give the number of subscripts and the component type.

   --        P_BOUNDS is a pointer to a struct, the name of  whose type is the
   --        unconstrained array name followed by "___XUB" and which has
   --        fields of the form

   --           LBn (n a decimal integer) lower bound of n'th dimension
   --           UBn (n a decimal integer) upper bound of n'th dimension

   --        The bounds may be any integral type. In the case of an enumeration
   --        type, Enum_Rep values are used.

   --      For a given unconstrained array type, the compiler will generate one
   --      fat-pointer type whose name is "arr___XUP", where "arr" is the name
   --      of the array type, and use it to represent the array type itself in
   --      the debugging information.

   --      For each pointer to this unconstrained array type, the compiler will
   --      generate a typedef that points to the above "arr___XUP" fat-pointer
   --      type. As a consequence, when it comes to fat-pointer types:

   --        1. The type name is given by the typedef

   --        2. If the debugger is asked to output the type, the appropriate
   --           form is "access arr", except if the type name is "arr___XUP"
   --           for which it is the array definition.

   --    Thin Pointers

   --      The value of a thin pointer is a pointer to the second field of a
   --      structure with two fields. The name of this structure's type is
   --      "arr___XUT", where "arr" is the name of the unconstrained array
   --      type. Even though it actually points into middle of this structure,
   --      the thin pointer's type in debugging information is
   --      pointer-to-arr___XUT.

   --      The first field of arr___XUT is named BOUNDS, and has a type named
   --      arr___XUB, with the structure described for such types in fat
   --      pointers, as described above.

   --      The second field of arr___XUT is named ARRAY, and contains the
   --      actual array. Because this array has a dynamic size, determined by
   --      the BOUNDS field that precedes it, all of the information about
   --      arr___XUT is encoded in a parallel type named arr___XUT___XVE, with
   --      fields BOUNDS and ARRAY___XVL. As for previously described ___XVE
   --      types, ARRAY___XVL has a pointer-to-array type. However, the array
   --      type in this case is named arr___XUA and only its element type is
   --      meaningful, just as described for fat pointers.

   --------------------------------------
   -- Tagged Types and Type Extensions --
   --------------------------------------

   --  A type C derived from a tagged type P has a field named "_parent" of
   --  type P that contains its inherited fields. The type of this field is
   --  usually P (encoded as usual if it has a dynamic size), but may be a more
   --  distant ancestor, if P is a null extension of that type.

   --  The type tag of a tagged type is a field named _tag, of type void*. If
   --  the type is derived from another tagged type, its _tag field is found in
   --  its _parent field.

   -----------------------------
   -- Variant Record Encoding --
   -----------------------------

   --  The variant part of a variant record is encoded as a single field in the
   --  enclosing record, whose name is:

   --     discrim___XVN

   --  where discrim is the unqualified name of the variant. This field name is
   --  built by gigi (not by code in this unit). For Unchecked_Union record,
   --  this discriminant will not appear in the record (see Unchecked Unions,
   --  below).

   --  The type corresponding to this field has a name that is obtained by
   --  concatenating the type name with the above string and is similar to a C
   --  union, in which each member of the union corresponds to one variant.
   --  However, unlike a C union, the size of the type may be variable even if
   --  each of the components are fixed size, since it includes a computation
   --  of which variant is present. In that case, it will be encoded as above
   --  and a type with the suffix "___XVN___XVU" will be present.

   --  The name of the union member is encoded to indicate the choices, and
   --  is a string given by the following grammar:

   --    member_name ::= {choice} | others_choice
   --    choice ::= simple_choice | range_choice
   --    simple_choice ::= S number
   --    range_choice  ::= R number T number
   --    number ::= {decimal_digit} [m]
   --    others_choice ::= O (upper case letter O)

   --  The m in a number indicates a negative value. As an example of this
   --  encoding scheme, the choice 1 .. 4 | 7 | -10 would be represented by

   --    R1T4S7S10m

   --  In the case of enumeration values, the values used are the actual
   --  representation values in the case where an enumeration type has an
   --  enumeration representation spec (i.e. they are values that correspond
   --  to the use of the Enum_Rep attribute).

   --  The type of the inner record is given by the name of the union type (as
   --  above) concatenated with the above string. Since that type may itself be
   --  variable-sized, it may also be encoded as above with a new type with a
   --  further suffix of "___XVU".

   --  As an example, consider:

   --    type Var (Disc : Boolean := True) is record
   --       M : Integer;

   --       case Disc is
   --         when True =>
   --           R : Integer;
   --           S : Integer;

   --         when False =>
   --           T : Integer;
   --       end case;
   --    end record;

   --    V1 : Var;

   --  In this case, the type var is represented as a struct with three fields.
   --  The first two are "disc" and "m", representing the values of these
   --  record components. The third field is a union of two types, with field
   --  names S1 and O. S1 is a struct with fields "r" and "s", and O is a
   --  struct with field "t".

   ----------------------
   -- Unchecked Unions --
   ----------------------

   --  The encoding for variant records changes somewhat under the influence
   --  of a "pragma Unchecked_Union" clause:

   --     1. The discriminant will not be present in the record, although its
   --        name is still used in the encodings.
   --     2. Variants containing a single component named "x" of type "T" may
   --        be encoded, as in ordinary C unions, as a single field of the
   --        enclosing union type named "x" of type "T", dispensing with the
   --        enclosing struct. In this case, of course, the discriminant values
   --        corresponding to the variant are unavailable. As for normal
   --        variants, the field name "x" may be suffixed with ___XVL if it
   --        has dynamic size.

   --  For example, the type Var in the preceding section, if followed by
   --  "pragma Unchecked_Union (Var);" may be encoded as a struct with two
   --  fields. The first is "m". The second field is a union of two types,
   --  with field names S1 and "t". As before, S1 is a struct with fields
   --  "r" and "s". "t" is a field of type Integer.

   ------------------------------------------------
   -- Subprograms for Handling Variant Encodings --
   ------------------------------------------------

   procedure Get_Variant_Encoding (V : Node_Id);
   --  This procedure is called by Gigi with V being the variant node. The
   --  corresponding encoding string is returned in Name_Buffer with the length
   --  of the string in Name_Len, and an ASCII.NUL character stored following
   --  the name.

   ---------------------------------
   -- Subtypes of Variant Records --
   ---------------------------------

   --  A subtype of a variant record is represented by a type in which the
   --  union field from the base type is replaced by one of the possible
   --  values. For example, if we have:

   --    type Var (Disc : Boolean := True) is record
   --       M : Integer;

   --       case Disc is
   --         when True =>
   --           R : Integer;
   --           S : Integer;

   --         when False =>
   --           T : Integer;
   --       end case;

   --    end record;
   --    V1 : Var;
   --    V2 : Var (True);
   --    V3 : Var (False);

   --  Here V2, for example, is represented with a subtype whose name is
   --  something like TvarS3b, which is a struct with three fields. The first
   --  two fields are "disc" and "m" as for the base type, and the third field
   --  is S1, which contains the fields "r" and "s".

   --  The debugger should simply ignore structs with names of the form
   --  corresponding to variants, and consider the fields inside as belonging
   --  to the containing record.

   -----------------------------------------------
   --  Extra renamings for subprogram instances --
   -----------------------------------------------

   procedure Build_Subprogram_Instance_Renamings
     (N       : Node_Id;
      Wrapper : Entity_Id);
   --  The debugger has difficulties in recovering the value of actuals of an
   --  elementary type, from within the body of a subprogram instantiation.
   --  This is because such actuals generate an object declaration that is
   --  placed within the wrapper package of the instance, and the entity in
   --  these declarations is encoded in a complex way that GDB does not handle
   --  well. These new renaming declarations appear within the body of the
   --  subprogram, and are redundant from a visibility point of view, but They
   --  should have no measurable performance impact, and require no special
   --  decoding in the debugger.

   -------------------------------------------
   -- Character literals in Character Types --
   -------------------------------------------

   --  Character types are enumeration types at least one of whose enumeration
   --  literals is a character literal. Enumeration literals are usually simply
   --  represented using their identifier names. If the enumeration literal is
   --  a character literal, the name is encoded as described in the following
   --  paragraph.

   --  A name QUhh, where each 'h' is a lower-case hexadecimal digit, stands
   --  for a character whose Unicode encoding is hh, and QWhhhh likewise stands
   --  for a wide character whose encoding is hhhh. The representation values
   --  are encoded as for ordinary enumeration literals (and have no necessary
   --  relationship to the values encoded in the names).

   --  For example, given the type declaration

   --    type x is (A, 'C', B);

   --  the second enumeration literal would be named QU43 and the value
   --  assigned to it would be 1.

   -----------------------------------------------
   -- Secondary Dispatch tables of tagged types --
   -----------------------------------------------

   procedure Get_Secondary_DT_External_Name
     (Typ          : Entity_Id;
      Ancestor_Typ : Entity_Id;
      Suffix_Index : Int);
   --  Set Name_Buffer and Name_Len to the external name of one secondary
   --  dispatch table of Typ. If the interface has been inherited from some
   --  ancestor then Ancestor_Typ is such node (in this case the secondary DT
   --  is needed to handle overridden primitives); if there is no such ancestor
   --  then Ancestor_Typ is equal to Typ.
   --
   --  Internal rule followed for the generation of the external name:
   --
   --  Case 1. If the secondary dispatch has not been inherited from some
   --          ancestor of Typ then the external name is composed as
   --          follows:
   --             External_Name (Typ) + Suffix_Number + 'P'
   --
   --  Case 2. if the secondary dispatch table has been inherited from some
   --          ancestor then the external name is composed as follows:
   --             External_Name (Typ) + '_' + External_Name (Ancestor_Typ)
   --               + Suffix_Number + 'P'
   --
   --  Note: We have to use the external names (instead of simply their names)
   --  to protect the frontend against programs that give the same name to all
   --  the interfaces and use the expanded name to reference them. The
   --  Suffix_Number is used to differentiate all the secondary dispatch
   --  tables of a given type.
   --
   --  Examples:
   --
   --        package Pkg1 is | package Pkg2 is | package Pkg3 is
   --          type Typ is   |   type Typ is   |   type Typ is
   --            interface;  |     interface;  |     interface;
   --        end Pkg1;       | end Pkg;        | end Pkg3;
   --
   --  with Pkg1, Pkg2, Pkg3;
   --  package Case_1 is
   --    type Typ is new Pkg1.Typ and Pkg2.Typ and Pkg3.Typ with ...
   --  end Case_1;
   --
   --  with Case_1;
   --  package Case_2 is
   --    type Typ is new Case_1.Typ with ...
   --  end Case_2;
   --
   --  These are the external names generated for Case_1.Typ (note that
   --  Pkg1.Typ is associated with the Primary Dispatch Table, because it
   --  is the parent of this type, and hence no external name is
   --  generated for it).
   --      case_1__typ0P   (associated with Pkg2.Typ)
   --      case_1__typ1P   (associated with Pkg3.Typ)
   --
   --  These are the external names generated for Case_2.Typ:
   --      case_2__typ_case_1__typ0P
   --      case_2__typ_case_1__typ1P

   ----------------------------
   -- Effect of Optimization --
   ----------------------------

   --  If the program is compiled with optimization on (e.g. -O1 switch
   --  specified), then there may be variations in the output from the above
   --  specification. In particular, objects may disappear from the output.
   --  This includes not only constants and variables that the program declares
   --  at the source level, but also the x___L and x___U constants created to
   --  describe the lower and upper bounds of subtypes with dynamic bounds.
   --  This means for example, that array bounds may disappear if optimization
   --  is turned on. The debugger is expected to recognize that these constants
   --  are missing and deal as best as it can with the limited information
   --  available.

   ---------------------------------
   -- GNAT Extensions to DWARF2/3 --
   ---------------------------------

   --  If the compiler switch "-gdwarf+" is specified, GNAT Vendor extensions
   --  to DWARF2/3 are generated, with the following variations from the above
   --  specification.

   --   Change in the contents of the DW_AT_name attribute

   --     The operators are represented in their natural form. (for example,
   --     the addition operator is written as "+" instead of "Oadd"). The
   --     component separator is "." instead of "__"

   --   Introduction of DW_AT_GNAT_encoding, encoded with value 0x2301

   --     Any debugging information entry representing a program entity, named
   --     or implicit, may have a DW_AT_GNAT_encoding attribute. The value of
   --     this attribute is a string representing the suffix internally added
   --     by GNAT for various purposes, mainly for representing debug
   --     information compatible with other formats. In particular this is
   --     useful for IDEs which need to filter out information internal to
   --     GNAT from their graphical interfaces.

   --     If a debugging information entry has multiple encodings, all of them
   --     will be listed in DW_AT_GNAT_encoding using the list separator ':'.

   --   Introduction of DW_AT_GNAT_descriptive_type, encoded with value 0x2302

   --     Any debugging information entry representing a type may have a
   --     DW_AT_GNAT_descriptive_type attribute whose value is a reference,
   --     pointing to a debugging information entry representing another type
   --     associated to the type.

   --   Modification of the contents of the DW_AT_producer string

   --     When emitting full GNAT Vendor extensions to DWARF2/3, "-gdwarf+"
   --     is appended to the DW_AT_producer string.
   --
   --     When emitting only DW_AT_GNAT_descriptive_type, "-gdwarf+-" is
   --     appended to the DW_AT_producer string.

end Exp_Dbug;