mirror of
https://github.com/autc04/Retro68.git
synced 2024-09-30 01:57:08 +00:00
1580 lines
71 KiB
Ada
1580 lines
71 KiB
Ada
------------------------------------------------------------------------------
|
|
-- --
|
|
-- 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;
|