gcc/ada/repinfo.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                         GNAT COMPILER COMPONENTS                         --
   4 --                                                                          --
   5 --                              R E P I N F O                               --
   6 --                                                                          --
   7 --                                 S p e c                                  --
   8 --                                                                          --
   9 --          Copyright (C) 1999-2020, Free Software Foundation, Inc.         --
  10 --                                                                          --
  11 -- GNAT is free software;  you can  redistribute it  and/or modify it under --
  12 -- terms of the  GNU General Public License as published  by the Free Soft- --
  13 -- ware  Foundation;  either version 3,  or (at your option) any later ver- --
  14 -- sion.  GNAT is distributed in the hope that it will be useful, but WITH- --
  15 -- OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY --
  16 -- or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License --
  17 -- for  more details.  You should have  received  a copy of the GNU General --
  18 -- Public License  distributed with GNAT; see file COPYING3.  If not, go to --
  19 -- http://www.gnu.org/licenses for a complete copy of the license.          --
  20 --                                                                          --
  21 -- GNAT was originally developed  by the GNAT team at  New York University. --
  22 -- Extensive contributions were provided by Ada Core Technologies Inc.      --
  23 --                                                                          --
  24 ------------------------------------------------------------------------------
  25
  26 --  This package contains the routines to handle back annotation of the
  27 --  tree to fill in representation information, and also the routines used
  28 --  by -gnatR to output this information.
  29
  30 --  WARNING: There is a C version of this package. Any changes to this
  31 --  source file must be properly reflected in the C header file repinfo.h
  32
  33 with Types; use Types;
  34 with Uintp; use Uintp;
  35
  36 package Repinfo is
  37
  38    --------------------------------
  39    -- Representation Information --
  40    --------------------------------
  41
  42    --  The representation information of interest here is size and
  43    --  component information for arrays and records. For primitive
  44    --  types, the front end computes the Esize and RM_Size fields of
  45    --  the corresponding entities as constant non-negative integers,
  46    --  and the Uint values are stored directly in these fields.
  47
  48    --  For composite types, there are three cases:
  49
  50    --    1. In some cases the front end knows the values statically,
  51    --       for example in the case where representation clauses or
  52    --       pragmas specify the values.
  53
  54    --    2. If Frontend_Layout is False, then the backend is responsible
  55    --       for layout of all types and objects not laid out by the
  56    --       front end. This includes all dynamic values, and also
  57    --       static values (e.g. record sizes) when not set by the
  58    --       front end.
  59
  60    --    3. If Frontend_Layout is True, then the front end lays out
  61    --       all data, according to target dependent size and alignment
  62    --       information, creating dynamic inlinable functions where
  63    --       needed in the case of sizes not known till runtime.
  64
  65    -----------------------------
  66    -- Back Annotation by Gigi --
  67    -----------------------------
  68
  69    --  The following interface is used by gigi if Frontend_Layout is False
  70
  71    --  As part of the processing in gigi, the types are laid out and
  72    --  appropriate values computed for the sizes and component positions
  73    --  and sizes of records and arrays.
  74
  75    --  The back-annotation circuit in gigi is responsible for updating the
  76    --  relevant fields in the tree to reflect these computations, as follows:
  77
  78    --    For E_Array_Type entities, the Component_Size field
  79
  80    --    For all record and array types and subtypes, the Esize and RM_Size
  81    --    fields, which respectively contain the Object_Size and Value_Size
  82    --    values for the type or subtype.
  83
  84    --    For E_Component and E_Discriminant entities, the Esize (size
  85    --    of component) and Component_Bit_Offset fields. Note that gigi
  86    --    does not generally back annotate Normalized_Position/First_Bit.
  87
  88    --  There are three cases to consider:
  89
  90    --    1. The value is constant. In this case, the back annotation works
  91    --       by simply storing the non-negative universal integer value in
  92    --       the appropriate field corresponding to this constant size.
  93
  94    --    2. The value depends on the discriminant values for the current
  95    --       record. In this case, gigi back annotates the field with a
  96    --       representation of the expression for computing the value in
  97    --       terms of the discriminants. A negative Uint value is used to
  98    --       represent the value of such an expression, as explained in
  99    --       the following section.
 100
 101    --    3. The value depends on variables other than discriminants of the
 102    --       current record. In this case, gigi also back annotates the field
 103    --       with a representation of the expression for computing the value
 104    --       in terms of the variables represented symbolically.
 105
 106    --  Note: the extended back annotation for the dynamic case is needed only
 107    --  for -gnatR3 output. Since it can be expensive to do this back annotation
 108    --  (for discriminated records with many variable-length arrays), we only do
 109    --  the full back annotation in -gnatR3 mode. In any other mode, the
 110    --  back-end just sets the value to Uint_Minus_1, indicating that the value
 111    --  of the attribute depends on discriminant information, but not giving
 112    --  further details.
 113
 114    --  GCC expressions are represented with a Uint value that is negative.
 115    --  See the body of this package for details on the representation used.
 116
 117    --  One other case in which gigi back annotates GCC expressions is in
 118    --  the Present_Expr field of an N_Variant node. This expression which
 119    --  will always depend on discriminants, and hence always be represented
 120    --  as a negative Uint value, provides an expression which, when evaluated
 121    --  with a given set of discriminant values, indicates whether the variant
 122    --  is present for that set of values (result is True, i.e. non-zero) or
 123    --  not present (result is False, i.e. zero). Again, the full annotation of
 124    --  this field is done only in -gnatR3 mode, and in other modes, the value
 125    --  is set to Uint_Minus_1.
 126
 127    subtype Node_Ref is Uint;
 128    --  Subtype used for negative Uint values used to represent nodes
 129
 130    subtype Node_Ref_Or_Val is Uint;
 131    --  Subtype used for values that can either be a Node_Ref (negative)
 132    --  or a value (non-negative)
 133
 134    type TCode is range 0 .. 27;
 135    --  Type used on Ada side to represent DEFTREECODE values defined in
 136    --  tree.def. Only a subset of these tree codes can actually appear.
 137    --  The names are the names from tree.def in Ada casing.
 138
 139    --  name                             code   description     operands  symbol
 140
 141    Cond_Expr        : constant TCode :=  1; -- conditional          3      ?<>
 142    Plus_Expr        : constant TCode :=  2; -- addition             2        +
 143    Minus_Expr       : constant TCode :=  3; -- subtraction          2        -
 144    Mult_Expr        : constant TCode :=  4; -- multiplication       2        *
 145    Trunc_Div_Expr   : constant TCode :=  5; -- truncating div       2       /t
 146    Ceil_Div_Expr    : constant TCode :=  6; -- div rounding up      2       /c
 147    Floor_Div_Expr   : constant TCode :=  7; -- div rounding down    2       /f
 148    Trunc_Mod_Expr   : constant TCode :=  8; -- mod for trunc_div    2     modt
 149    Ceil_Mod_Expr    : constant TCode :=  9; -- mod for ceil_div     2     modc
 150    Floor_Mod_Expr   : constant TCode := 10; -- mod for floor_div    2     modf
 151    Exact_Div_Expr   : constant TCode := 11; -- exact div            2       /e
 152    Negate_Expr      : constant TCode := 12; -- negation             1        -
 153    Min_Expr         : constant TCode := 13; -- minimum              2      min
 154    Max_Expr         : constant TCode := 14; -- maximum              2      max
 155    Abs_Expr         : constant TCode := 15; -- absolute value       1      abs
 156    Truth_And_Expr   : constant TCode := 16; -- boolean and          2      and
 157    Truth_Or_Expr    : constant TCode := 17; -- boolean or           2       or
 158    Truth_Xor_Expr   : constant TCode := 18; -- boolean xor          2      xor
 159    Truth_Not_Expr   : constant TCode := 19; -- boolean not          1      not
 160    Lt_Expr          : constant TCode := 20; -- comparison <         2        <
 161    Le_Expr          : constant TCode := 21; -- comparison <=        2       <=
 162    Gt_Expr          : constant TCode := 22; -- comparison >         2        >
 163    Ge_Expr          : constant TCode := 23; -- comparison >=        2       >=
 164    Eq_Expr          : constant TCode := 24; -- comparison =         2       ==
 165    Ne_Expr          : constant TCode := 25; -- comparison /=        2       !=
 166    Bit_And_Expr     : constant TCode := 26; -- bitwise and          2        &
 167
 168    --  The following entry is used to represent a discriminant value in
 169    --  the tree. It has a special tree code that does not correspond
 170    --  directly to a GCC node. The single operand is the index number
 171    --  of the discriminant in the record (1 = first discriminant).
 172
 173    Discrim_Val      : constant TCode :=  0;  -- discriminant value  1        #
 174
 175    --  The following entry is used to represent a value not known at
 176    --  compile time in the tree, other than a discriminant value. It
 177    --  has a special tree code that does not correspond directly to
 178    --  a GCC node. The single operand is an arbitrary index number.
 179
 180    Dynamic_Val      : constant TCode := 27;  -- dynamic value       1      var
 181
 182    ----------------------------
 183    -- The JSON output format --
 184    ----------------------------
 185
 186    --  The representation information can be output to a file in the JSON
 187    --  data interchange format specified by the ECMA-404 standard. In the
 188    --  following description, the terminology is that of the JSON syntax
 189    --  from the ECMA document and of the JSON grammar from www.json.org.
 190
 191    --  The output is an array of entities
 192
 193    --  An entity is an object whose members are pairs taken from:
 194
 195    --    "name"                 :  string
 196    --    "location"             :  string
 197    --    "record"               :  array of components
 198    --    "variant"              :  array of variants
 199    --    "formal"               :  array of formal parameters
 200    --    "mechanism"            :  string
 201    --    "Size"                 :  numerical expression
 202    --    "Object_Size"          :  numerical expression
 203    --    "Value_Size"           :  numerical expression
 204    --    "Component_Size"       :  numerical expression
 205    --    "Range"                :  array of numbers
 206    --    "Small"                :  number
 207    --    "Alignment"            :  number
 208    --    "Convention"           :  string
 209    --    "Linker_Section"       :  string
 210    --    "Bit_Order"            :  string
 211    --    "Scalar_Storage_Order" :  string
 212
 213    --    "name" and "location" are present for every entity and come from the
 214    --    declaration of the associated Ada entity. The value of "name" is the
 215    --    fully qualified Ada name. The value of "location" is the expanded
 216    --    chain of instantiation locations that contains the entity.
 217    --    "record" is present for every record type and its value is the list of
 218    --    components. "variant" is present only if the record type has a variant
 219    --    part and its value is the list of variants.
 220    --    "formal" is present for every subprogram and entry, and its value is
 221    --    the list of formal parameters. "mechanism" is present for functions
 222    --    only and its value is the return mechanim.
 223    --    The other pairs may be present when the eponymous aspect/attribute is
 224    --    defined for the Ada entity, and their value is set by the language.
 225
 226    --  A component is an object whose members are pairs taken from:
 227
 228    --    "name"                 :  string
 229    --    "discriminant"         :  number
 230    --    "Position"             :  numerical expression
 231    --    "First_Bit"            :  number
 232    --    "Size"                 :  numerical expression
 233
 234    --    "name" is present for every component and comes from the declaration
 235    --    of the type; its value is the unqualified Ada name. "discriminant" is
 236    --    present only if the component is a discriminant, and its value is the
 237    --    ranking of the discriminant in the list of discriminants of the type,
 238    --    i.e. an integer index ranging from 1 to the number of discriminants.
 239    --    The other three pairs are present for every component and come from
 240    --    the layout of the type; their value is the value of the eponymous
 241    --    attribute set by the language.
 242
 243    --  A variant is an object whose members are pairs taken from:
 244
 245    --    "present"              :  numerical expression
 246    --    "record"               :  array of components
 247    --    "variant"              :  array of variants
 248
 249    --    "present" and "record" are present for every variant. The value of
 250    --    "present" is a boolean expression that evaluates to true when the
 251    --    components of the variant are contained in the record type and to
 252    --    false when they are not. The value of "record" is the list of
 253    --    components in the variant. "variant" is present only if the variant
 254    --    itself has a variant part and its value is the list of (sub)variants.
 255
 256    --  A formal parameter is an object whose members are pairs taken from:
 257
 258    --    "name"                 :  string
 259    --    "mechanism"            :  string
 260
 261    --    The two pairs are present for every formal parameter. "name" comes
 262    --    from the declaration of the parameter in the subprogram or entry
 263    --    and its value is the unqualified Ada name. The value of "mechanism"
 264    --    is the passing mechanism for the parameter set by the language.
 265
 266    --  A numerical expression is either a number or an object whose members
 267    --  are pairs taken from:
 268
 269    --    "code"                 :  string
 270    --    "operands"             :  array of numerical expressions
 271
 272    --    The two pairs are present for every such object. The value of "code"
 273    --    is a symbol taken from the table defining the TCode type above. The
 274    --    number of elements of the value of "operands" is specified by the
 275    --    operands column in the line associated with the symbol in the table.
 276
 277    --    As documented above, the full back annotation is only done in -gnatR3.
 278    --    In the other cases, if the numerical expression is not a number, then
 279    --    it is replaced with the "??" string.
 280
 281    ------------------------
 282    -- The gigi Interface --
 283    ------------------------
 284
 285    --  The following declarations are for use by gigi for back annotation
 286
 287    function Create_Node
 288      (Expr : TCode;
 289       Op1  : Node_Ref_Or_Val;
 290       Op2  : Node_Ref_Or_Val := No_Uint;
 291       Op3  : Node_Ref_Or_Val := No_Uint) return Node_Ref;
 292    --  Creates a node using the tree code defined by Expr and from one to three
 293    --  operands as required (unused operands set as shown to No_Uint) Note that
 294    --  this call can be used to create a discriminant reference by using (Expr
 295    --  => Discrim_Val, Op1 => discriminant_number).
 296
 297    function Create_Discrim_Ref (Discr : Entity_Id) return Node_Ref;
 298    --  Creates a reference to the discriminant whose entity is Discr
 299
 300    --------------------------------------------------------
 301    -- Front-End Interface for Dynamic Size/Offset Values --
 302    --------------------------------------------------------
 303
 304    --  If Frontend_Layout is True, then the front-end deals with all
 305    --  dynamic size and offset fields. There are two cases:
 306
 307    --    1. The value can be computed at the time of type freezing, and
 308    --       is stored in a run-time constant. In this case, the field
 309    --       contains a reference to this entity. In the case of sizes
 310    --       the value stored is the size in storage units, since dynamic
 311    --       sizes are always a multiple of storage units.
 312
 313    --    2. The size/offset depends on the value of discriminants at
 314    --       run-time. In this case, the front end builds a function to
 315    --       compute the value. This function has a single parameter
 316    --       which is the discriminated record object in question. Any
 317    --       references to discriminant values are simply references to
 318    --       the appropriate discriminant in this single argument, and
 319    --       to compute the required size/offset value at run time, the
 320    --       code generator simply constructs a call to the function
 321    --       with the appropriate argument. The size/offset field in
 322    --       this case contains a reference to the function entity.
 323    --       Note that as for case 1, if such a function is used to
 324    --       return a size, then the size in storage units is returned,
 325    --       not the size in bits.
 326
 327    --  The interface here allows these created entities to be referenced
 328    --  using negative Unit values, so that they can be stored in the
 329    --  appropriate size and offset fields in the tree.
 330
 331    --  In the case of components, if the location of the component is static,
 332    --  then all four fields (Component_Bit_Offset, Normalized_Position, Esize,
 333    --  and Normalized_First_Bit) are set to appropriate values. In the case of
 334    --  a non-static component location, Component_Bit_Offset is not used and
 335    --  is left set to Unknown. Normalized_Position and Normalized_First_Bit
 336    --  are set appropriately.
 337
 338    subtype SO_Ref is Uint;
 339    --  Type used to represent a Uint value that represents a static or
 340    --  dynamic size/offset value (non-negative if static, negative if
 341    --  the size value is dynamic).
 342
 343    subtype Dynamic_SO_Ref is Uint;
 344    --  Type used to represent a negative Uint value used to store
 345    --  a dynamic size/offset value.
 346
 347    function Is_Dynamic_SO_Ref (U : SO_Ref) return Boolean;
 348    pragma Inline (Is_Dynamic_SO_Ref);
 349    --  Given a SO_Ref (Uint) value, returns True iff the SO_Ref value
 350    --  represents a dynamic Size/Offset value (i.e. it is negative).
 351
 352    function Is_Static_SO_Ref (U : SO_Ref) return Boolean;
 353    pragma Inline (Is_Static_SO_Ref);
 354    --  Given a SO_Ref (Uint) value, returns True iff the SO_Ref value
 355    --  represents a static Size/Offset value (i.e. it is non-negative).
 356
 357    function Create_Dynamic_SO_Ref (E : Entity_Id) return Dynamic_SO_Ref;
 358    --  Given the Entity_Id for a constant (case 1), the Node_Id for an
 359    --  expression (case 2), or the Entity_Id for a function (case 3),
 360    --  this function returns a (negative) Uint value that can be used
 361    --  to retrieve the entity or expression for later use.
 362
 363    function Get_Dynamic_SO_Entity (U : Dynamic_SO_Ref) return Entity_Id;
 364    --  Retrieve the Node_Id or Entity_Id stored by a previous call to
 365    --  Create_Dynamic_SO_Ref. The approach is that the front end makes
 366    --  the necessary Create_Dynamic_SO_Ref calls to associate the node
 367    --  and entity id values and the back end makes Get_Dynamic_SO_Ref
 368    --  calls to retrieve them.
 369
 370    ------------------------------
 371    -- External tools Interface --
 372    ------------------------------
 373
 374    type Discrim_List is array (Pos range <>) of Uint;
 375    --  Type used to represent list of discriminant values
 376
 377    function Rep_Value (Val : Node_Ref_Or_Val; D : Discrim_List) return Uint;
 378    --  Given the contents of a First_Bit_Position or Esize field containing
 379    --  a node reference (i.e. a negative Uint value) and D, the list of
 380    --  discriminant values, returns the interpreted value of this field.
 381    --  For convenience, Rep_Value will take a non-negative Uint value
 382    --  as an argument value, and return it unmodified. A No_Uint value is
 383    --  also returned unmodified.
 384
 385    ------------------------
 386    -- Compiler Interface --
 387    ------------------------
 388
 389    procedure List_Rep_Info (Bytes_Big_Endian : Boolean);
 390    --  Procedure to list representation information. Bytes_Big_Endian is the
 391    --  value from Ttypes (Repinfo cannot have a dependency on Ttypes).
 392
 393    --------------------------
 394    -- Debugging Procedures --
 395    --------------------------
 396
 397    procedure List_GCC_Expression (U : Node_Ref_Or_Val);
 398    --  Prints out given expression in symbolic form. Constants are listed
 399    --  in decimal numeric form, Discriminants are listed with a # followed
 400    --  by the discriminant number, and operators are output in appropriate
 401    --  symbolic form No_Uint displays as two question marks. The output is
 402    --  on a single line but has no line return after it. This procedure is
 403    --  useful only if operating in backend layout mode.
 404
 405    procedure lgx (U : Node_Ref_Or_Val);
 406    --  In backend layout mode, this is like List_GCC_Expression, but
 407    --  includes a line return at the end. If operating in front end
 408    --  layout mode, then the name of the entity for the size (either
 409    --  a function of a variable) is listed followed by a line return.
 410
 411 end Repinfo;