From f9215c73f2fc4cb0ed468190554662da2d795360 Mon Sep 17 00:00:00 2001 From: Ben Reynwar Date: Mon, 11 May 2020 23:08:04 -0700 Subject: Adding some comments to the RTI processing. (#1304) --- src/grt/grt-rtis.ads | 75 ++++++++++++++++++++++++++++++++++++++-------- src/grt/grt-rtis_addr.ads | 6 ++++ src/grt/grt-rtis_utils.adb | 7 +++-- 3 files changed, 73 insertions(+), 15 deletions(-) (limited to 'src/grt') 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 => -- cgit v1.2.3