Adding some comments to the RTI processing. (#1304)

3 files changed, 73 insertions, 15 deletions

diff --git a/src/grt/grt-rtis.ads b/src/grt/grt-rtis.ads
index eebe5c200..182cbad73 100644
--- a/src/grt/grt-rtis.ads
+++ b/src/grt/grt-rtis.ads
@@ -1,5 +1,5 @@
 --  GHDL Run Time (GRT) -  Run Time Informations.
---  Copyright (C) 2002 - 2014 Tristan Gingold
+--  Copyright (C) 2002 - 2020 Tristan Gingold
 --
 --  GHDL is free software; you can redistribute it and/or modify it under
 --  the terms of the GNU General Public License as published by the Free
@@ -152,7 +152,10 @@ package Grt.Rtis is
    type Ghdl_Rtin_Block is record
       Common : Ghdl_Rti_Common;
       Name : Ghdl_C_String;
+      --  Address of the instantiation data relative to the parent's
+      --  instantation data address.
       Loc : Ghdl_Rti_Loc;
+      --  Line and column of the declaration.
       Linecol : Ghdl_Index_Type;
       Parent : Ghdl_Rti_Access;
       Nbr_Child : Ghdl_Index_Type;
@@ -168,10 +171,16 @@ package Grt.Rtis is
    type Ghdl_Rtin_Generate is record
       Common : Ghdl_Rti_Common;
       Name : Ghdl_C_String;
+      --  Address of the instantiation data relative to the parent's
+      --  instantation data address.
       Loc : Ghdl_Rti_Loc;
+      --  Line and column of the declaration.
       Linecol : Ghdl_Index_Type;
       Parent : Ghdl_Rti_Access;
-      --  Only for for_generate_statement.
+      --  The total size of the instantiation data for the contents of
+      --  the generate statement. Useful to find the instantation data
+      --  for a particular index of the loop. Only used for
+      --  for_generate_statement.
       Size : Ghdl_Index_Type;
       Child : Ghdl_Rti_Access;
    end record;
@@ -194,14 +203,13 @@ package Grt.Rtis is
    type Ghdl_Rtin_Object is record
       Common : Ghdl_Rti_Common;
       Name : Ghdl_C_String;
-
-      --  Address of the object.  For a signal, this is the address of the
-      --  signal, the value is just after the signal.
+      --  Address of the instantiation data relative to the parent's
+      --  instantation data address. For a signal/port, this location
+      --  contains the address of the signal. For a constant/generic
+      --  this is the location of the value.
       Loc : Ghdl_Rti_Loc;
-
       --  Type of the object.
       Obj_Type : Ghdl_Rti_Access;
-
       --  Line and column of the declaration.
       Linecol : Ghdl_Index_Type;
    end record;
@@ -279,6 +287,9 @@ package Grt.Rtis is
       Common : Ghdl_Rti_Common;
       Name : Ghdl_C_String;
       Basetype : Ghdl_Rti_Access;
+      --  Address of the instantiation data relative to the parent's
+      --  instantation data address.  The instantiation data in this
+      --  case is the range of the scalar.
       Range_Loc : Ghdl_Rti_Loc;
    end record;
    pragma Convention (C, Ghdl_Rtin_Subtype_Scalar);
@@ -300,8 +311,15 @@ package Grt.Rtis is
       Common : Ghdl_Rti_Common;
       Name : Ghdl_C_String;
       Element : Ghdl_Rti_Access;
+      --  The number of dimension of the array.
+      --  (e.g. array(1 downto 0, 2 downto 0, 3 downto 0) has 3 dimensions)
       Nbr_Dim : Ghdl_Index_Type;
+      --  An array of types, one for each range of the dimensions.
       Indexes : Ghdl_Rti_Arr_Acc;
+      --  Note: An array has no `Loc` field so it has no instantiation
+      --  data.  A consequence of this is that `Element` must be
+      --  fully constrained, since there is nowhere to store the
+      --  constraints applied by this type.
    end record;
    pragma Convention (C, Ghdl_Rtin_Type_Array);
    type Ghdl_Rtin_Type_Array_Acc is access Ghdl_Rtin_Type_Array;
@@ -314,6 +332,11 @@ package Grt.Rtis is
       Common : Ghdl_Rti_Common;
       Name : Ghdl_C_String;
       Basetype : Ghdl_Rti_Access;
+      --  Address of the instantiation data relative to the parent's
+      --  instantation data address. For an array the instantiation
+      --  data would constain the element sizes, and the bounds. For a
+      --  record the instantiation data consists of the element
+      --  instantiation data.
       Layout : Ghdl_Rti_Loc;
    end record;
    pragma Convention (C, Ghdl_Rtin_Subtype_Composite);
@@ -333,21 +356,44 @@ package Grt.Rtis is
    function To_Ghdl_Rtin_Type_Fileacc_Acc is new Ada.Unchecked_Conversion
      (Source => Ghdl_Rti_Access, Target => Ghdl_Rtin_Type_Fileacc_Acc);
 
-   --  Set in the mode field to know what Val_Off and Sig_Off are relative to.
-   --  This could also be extrated from the element type.
+   --  A static element is one in which the data structure does not depend
+   --  on the context.
    Ghdl_Rti_Element_Static : constant Ghdl_Rti_U8 := 0;
+   --  A complex element is one in which the data structure can depend
+   --  on the context. For example:
+   --  * An array with a size given by a generic parameter.
+   --  * A record containing an array with a size given by a for-generate
+   --    loop variable.
    Ghdl_Rti_Element_Complex : constant Ghdl_Rti_U8 := 1;
+   --  The element is unbounded. (i.e. The bounds must be specified by
+   --  a subtype of the record).
    Ghdl_Rti_Element_Unbounded : constant Ghdl_Rti_U8 := 2;
 
+   --  Whether an element is static, complex or unbounded is set in the
+   --  `Common.Mode` field.
+   --  This could also be extracted from the element type.
+
    type Ghdl_Rtin_Element is record
       Common : Ghdl_Rti_Common;
       Name : Ghdl_C_String;
       Eltype : Ghdl_Rti_Access;
-      --  For static element: offset in the record.
-      --  For complex element: offset in the type layout or object layout.
+      --  `Val_Off` and `Sig_Off` are used to find the object data
+      --  corresponding to this element. If the object is a
+      --  constant/generic use the `Val_Off` offset. If the object is
+      --  a signal/port use the `Sig_Off` offset.
+      --  For a static element the offset is the position of
+      --  the element instantiation data within the record's instantiation
+      --  data.
+      --  For a complex element the size of the instantiation data was
+      --  unknown at compile time, so the location given my the offset
+      --  instead contains the address of the element's instantiation
+      --  data.
       Val_Off : Ghdl_Index_Type;
       Sig_Off : Ghdl_Index_Type;
-      --  For unbounded records: element layout offset in the layout.
+      --  If the element has an unbounded type, then we need to store
+      --  information about the bounds/layout of that type somewhere.
+      --  `Layout_Off` gives the location of these bounds/layout within
+      --  the instantiation data.
       Layout_Off : Ghdl_Index_Type;
    end record;
    pragma Convention (C, Ghdl_Rtin_Element);
@@ -360,7 +406,10 @@ package Grt.Rtis is
       Name : Ghdl_C_String;
       Nbrel : Ghdl_Index_Type;
       Elements : Ghdl_Rti_Arr_Acc;
-      --  Layout variable for the record, if it is complex.
+      --  Address of the instantiation data relative to the parent's
+      --  instantation data address. A record only needs instantiation
+      --  data if it is complex.  Otherwise all the layout information
+      --  is stored directly in the element RTI structures.
       Layout : Ghdl_Rti_Loc;
    end record;
    pragma Convention (C, Ghdl_Rtin_Type_Record);
diff --git a/src/grt/grt-rtis_addr.ads b/src/grt/grt-rtis_addr.ads
index db8e15264..eddd5274a 100644
--- a/src/grt/grt-rtis_addr.ads
+++ b/src/grt/grt-rtis_addr.ads
@@ -66,6 +66,12 @@ package Grt.Rtis_Addr is
      (Ctxt : Rti_Context; Gen : Ghdl_Rti_Access) return Rti_Context;
 
    --  Convert a location to an address.
+   --  `Depth` is the position in the design hierarchy of the object
+   --  we are finding the address of.
+   --  `Loc` is the location of that object, relative to the address
+   --  of it's parent.
+   --  `Context` is the RTI node and address of an object deeper in
+   --  the hierarchy that is referencing this object.
    function Loc_To_Addr (Depth : Ghdl_Rti_Depth;
                          Loc : Ghdl_Rti_Loc;
                          Ctxt : Rti_Context)
diff --git a/src/grt/grt-rtis_utils.adb b/src/grt/grt-rtis_utils.adb
index be7696580..09b9d434c 100644
--- a/src/grt/grt-rtis_utils.adb
+++ b/src/grt/grt-rtis_utils.adb
@@ -165,14 +165,17 @@ package body Grt.Rtis_Utils is
          when  Ghdl_Rtik_Subtype_Array
            | Ghdl_Rtik_Type_Record
            | Ghdl_Rtik_Subtype_Record =>
-            --  Object is a pointer.
+            --  If the type is complex then the location
+            --  contains a pointer to the instantiation data.
             if Rti_Complex_Type (Obj_Type) then
                Addr := To_Addr_Acc (Obj_Loc).all;
             end if;
          when Ghdl_Rtik_Type_Array
            | Ghdl_Rtik_Type_Unbounded_Record
            | Ghdl_Rtik_Subtype_Unbounded_Record =>
-            --  Object is a fat pointer.
+            --  If the type is unbounded then the location
+            --  for the object containts a pointer to the bounds
+            --  and a pointer to the data.
             Bounds := To_Ghdl_Uc_Array_Acc (Obj_Loc).Bounds;
             Addr := To_Ghdl_Uc_Array_Acc (Obj_Loc).Base;
          when others =>