Subversion Repositories openrisc

------------------------------------------------------------------------------

--                                                                          --

--                         GNAT COMPILER COMPONENTS                         --

--                                                                          --

--                             E X P _ D B U G                              --

--                                                                          --

--                                 S p e c                                  --

--                                                                          --

--          Copyright (C) 1996-2010, 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 --

   ----------------------------------------------------

   No_Dollar_In_Label : constant Boolean := True;

   --  True iff the target does not allow dollar signs ("$") in external names

   --  ??? We want to migrate all platforms to use the same convention. As a

   --  first step, we force this constant to always be True. This constant will

   --  eventually be deleted after we have verified that the migration does not

   --  cause any unforeseen adverse impact. We chose "__" because it is

   --  supported on all platforms, which is not the case of "$".

   procedure Get_External_Name

     (Entity     : Entity_Id;

      Has_Suffix : Boolean);

   --  Set Name_Buffer and Name_Len to the external name of entity E. The

   --  external name is the Interface_Name, if specified, unless the entity

   --  has an address clause or a suffix.

   --

   --  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.

   procedure Get_External_Name_With_Suffix

     (Entity : Entity_Id;

      Suffix : String);

   --  Set Name_Buffer and Name_Len to the external name of entity E. If

   --  Suffix is the empty string the external name is as above, otherwise

   --  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

   --

   --  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.

   --------------------------------------------

   -- 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.

      ------------------------------

      -- VAX Floating-Point Types --

      ------------------------------

      --   Vax floating-point types are represented at run time as integer

      --   types, which are treated specially by the code generator. Their

      --   type names are encoded with the following suffix:

      --     typ___XFF

      --     typ___XFD

      --     typ___XFG

      --   representing the Vax F Float, D Float, and G Float types. The

      --   debugger must treat these specially. In particular, printing these

      --   values can be achieved using the debug procedures that are provided

      --   in package System.Vax_Float_Operations:

      --     procedure Debug_Output_D (Arg : D);

      --     procedure Debug_Output_F (Arg : F);

      --     procedure Debug_Output_G (Arg : G);

      --   These three procedures take a Vax floating-point argument, and

      --   output a corresponding decimal representation to standard output

      --   with no terminating line return.

      --------------------

      -- 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