path: root/doc/internals/RTI.rst

Run Time Information (RTI)
##########################

.. WARNING::
   This section was written while trying to understand how the RTI is
   organized. It almost certainly contains errors, and it likely
   won't be updated with the codebase, so don't belive any of the
   information here. Nevertheless, it may be helpful for a developer new
   to GHDL trying to understand the organization of the RTI.

Useful Definitions
==================

RTI

 Run Time Information. The information that is used when simulating the design.

RTIN

 Run Time Information Node. The design is organized into a directed
 graph where the architectures, signals and statements are represented
 as nodes on the graph. This graph can be cyclic since an architecture
 may be instantiated many times, and could be recursively
 instantiated.

Context

 The context of a node is the position in the elaborated design. For
 example a architecture might be instantiated 4 times in a design, but
 will have a single RTI node. The data related to that node but
 specfic to particular instantiation has an address in memory. A
 context object (`Rti_Context`) bundles an RTI node with an address for
 it's instantiation data.  If this RTI node references another RTI node we
 can find the relevant instantiation data for that node by considering the
 context.

RTII

 Run Time Instance Information. This is a record that groups an RTI
 node with any other data necessary to specify a particular
 instantiation. The RTII objects create a tree that represents the
 elaborated design. Currently they are only implemented for RTIN nodes
 of signals, ports, generics, constants and their subcomponents.


RTI Nodes / RTII Nodes
======================

All RTI node records have a `Ghdl_Rtin_Common` record as their first
element. This record contains the following elements:

Kind \: Ghdl_Rtik

 This specified what kind of node it is. For example a `process` and
 an `entity` node are both represented by `Ghdl_Rtin_Block` records
 but they are distinguished by having a different Kind.

Depth \: Ghdl_Rti_Depth

 The depth indicates the relationship between the RTI Node and the RTI
 Context. Child nodes often just use the same Context as their parent,
 and the depth indicates how far up in the hierarchy you go to find
 where the Context is based.

Mode \: Ghdl_Rti_U8

 ??

Max_Depth \: Ghdl_Rti_Depth

 ??

It's also useful to look at some of the other elements that commonly
appear in the different RTI Node records.

Loc \: Ghdl_Rti_Loc

 This is an address offset. It tells us where the instantiation data
 for this node is located relative to the data of it's parent.

Linecol \: Ghdl_Index_Type

 Refers back to a location in the source code.

Parent \: Ghdl_Rti_Access

 Points to the parent. This isn't necessarily the parent in the RTI
 tree though. For example the `Parent` of an architecture RTI node
 points at the entity node, however the parent in the tree is the
 instance RTI.

This document will now review that main classes of RTI Nodes.

Architecture RTI (Ghdl_Rtin_Block)
-----------------------------------

The architecture acts as a simple container for it's children. Create
the child tree nodes by looping through `Ghdl_Rti_Block.Children` and
keeping the context unchanged.

The information about the generics and ports access the entity RTI
nodes through `Ghdl_Rti_Block.Parent` using the same context.

The instantiation data of an architecture contains a single item, a
pointer to the RTI node. This is necessary because it is necessary to
store which of the possible architectures of this entity was
instantiated.

Entity RTI (Ghdl_Rtin_Block)
----------------------------

The RTI of an entity is a `Ghdl_Rti_Block` record (the same as the
architecture) and uses the same context as the architecture. It is
accessed via the architecture's `Parent` element. The generics and
ports can be accessed as the children of the entity.

Other Blocks (Package/Process) (Ghdl_Rtin_Block)
------------------------------------------------

The block just loops over it's children.

if_generate / case_generate (Ghdl_Rtin_Block)
---------------------------------------------

If-Generate and Case-Generate statements are represented with
`Ghdl_Rtin_Block` records with Kind `Ghdl_Rtik_If_Generate` and
`Ghdl_Rtik_Case_Generate`.

Their children are all of Kind `Ghdl_Rtik_Body`, and represent the
different possible blocks that could be selected.

The instantiation data of a if_generate or case_generate RTI contains two items:
1) A pointer to the context of the selected generate body (instance_pointer).
2) The index of the selected child (block_id)

The child node is then created from the RTI node
`Ghdl_Rtik_Body.Children(block_id)` combined with the instantiation data given by
`instance_pointer`.

for_generate (Ghdl_Rtin_Generate)
---------------------------------

For-Generate statements are represented with `Ghdl_Rtin_Generate`
records with Kind `Ghdl_Rtik_For_Generate`.

Their RTI-node structure is different from the `Ghdl_Rtin_Block`
record in that rather than having `Nbr_Child` and `Children` elements,
it has:

Child \: Ghdl_Rti_Access

 A pointer to the generate body node that is their only child.

Size \: Ghdl_Index_Type

 The amount of memory requrired for the context of their child.

The Child element is a generate body. There is only a single RTI-node
structure which Child points to, however a different context is used
each time we go around the for-generate loop.

The context of a for_generate RTI contains a single item: An address
which points at the contexts for it's children.

Each time we go around the for generate loop we increment the address
of the context by `Size` so we looking at the correct context for that
instantiation of the contexts of the loop.

One complexity of the for-generate is finding the number of times that
we go around the loop. The first element in the child generate body is
an iterator. That iterator has a type and we can get the bounds of
that type by passing it the local context. The type of the iterator
for the for-generate loop is implicitly created and placed directly
before the for_generate block, so using the local context will work.
There might be a bug if the for-generate loop uses a type that wasn't
defined implicitly.

instance (Ghdl_Rtin_Instance)
-----------------------------

An instantiation of an entity is represented by a `Ghdl_Rtin_Instance`
node with Kind `Ghdl_Rtik_Instance`.

The context contains a single item, which is a pointer to the context
of the architecture. The architecture context also contains a single
item, which is a pointer to the architecture RTI Node.

Port (Ghdl_Rtin_Object)
-----------------------

Array Kinds
-----------

Ghdl_Rtik_Type_Array
 A VHDL array where the range is not specified.

Ghdl_Rtik_Subtype_Array
 A VHDL array where the range is specified.
 A Type_Array together with the bounds.

Object_To_Base_Bound
--------------------

This function takes an object type and an object's static context
location and returns the complex context location and the bounds.

When the object is static the bounds is null (because the bounds
are held in the type definition) and the complex context is the
same as the static context.

When the object is complex the bounds is null, and the static
context location contains a pointer to the complex context
location.

When the object is unbound the static context contains a `Ghdl_Uc_Array`
record. The contains `Bounds` which points to the bounds, and `Base`
which points to the complex context location.

Array_Type (Ghdl_Rtin_Type_Array)
---------------------------------
Contains Common and Name fields followed by:

Element \: Ghdl_Rti_Access
 The type of the elements in the array.

Nbr_Dim \: Ghdl_Index_Type
 The number of dimensions in the array.
 Multidimensional arrays are not stored as arrays of arrays,
 but rather directly as multidimensional arrays.

Indexes \: Ghdl_Rti_Arr_Acc
 ??? This is an array of the indices for each dimension, but I don't
 know what kind of object they are represented by yet.

Functions acting on types don't seem to use context in the same way.
The functions are often pass the RTI object, a context (of a object
higher in the hierarcy, and a pointer to a local context (often called
layout)).

The context of an Array Type has a defined structure which is `Ghdl_Uc_Array`.
This contains a `Base` and a `Bounds` field.

Base \: Address
 Points to the complex context of the object.
Bounds \: Address
 Points to the bounds of the array.


Array Subtype (Ghdl_Rtin_Subtype_Array)
---------------------------------------
Array subtypes are represented by the `Ghdl_Rtin_Subtype_Composite`
RTI node.
The node contains the `Common` and `Name` fields, followed by

Basetype \: Ghdl_Rti_Access
 A pointer to the RTI array type which it is a subtype of.

Layout \: Ghdl_Rti_Loc
 A pointer to the context of the subtype relative to the parent context.
 The layout contains:
 a value size, a signal sizes, and the bounds.

Port / Signal / Generic / Constant / Variable (Ghdl_Rtin_Object)
----------------------------------------------------------------

The context of an object is found by taking offsetting the Context by
the `Loc` field on the object. The implementation often uses the same
Context for a group of hierarhical signals, so that the determination
of the location of the context of objects in the hierarchy must be
found using a function such as `Loc_To_Addr`.

The `Obj_Type` field of an object points at the type of the object.

A signal definition can also include placing bounds on a unbounded
type.

The tree of an object can be created by pairing the hierarchy of types
with the hierarchy of contexts.

If the type is a scalar type then the value of the object is found at:
  If the object is a port or signal then the only item in the context
   is a pointer to the signal object.  The first item in the signal object
   is a pointer to the value.
  If the object is a constant, generic or variable then the context
   contains a pointer to the value itself.

If the type is an unbound array:
  We must be at the top level of a hierarchical object.
  The context contains a pointer to the first element context,
  and a pointer to the bounds.

If the type is a static array:
  The context is the same as the context of the first element.
  The bounds are given in the layout of the type (composite).

If the type is a complex array:
  The context contains a pointer to the context of the first element.
  Because the size of the context cannot be determined at compile time
  this layer of indirection is necessary.


Record Kinds
------------
Ghdl_Rtik_Type_Record

 A standard VHDL record.

Ghdl_Rtik_Type_Unbounded_Record

 A vhdl record containing an unbounded array (directory or indirectly).

Ghdl_Rtik_Subtype_Record

 A subtype of an unbounded record where all arrays are not bounded.

Ghdl_Rtik_Subtype_Unbounded_Record

 A subtype of an unbounded record where some but not all of the previously
 unbound arrays have been bound.

Record Type (Ghdl_Rtin_Type_Record)
-----------------------------------
Can have Kind of `Ghdl_Rtik_Type_Record` or `Ghdl_Rtik_Type_Unbounded_Record`.
The record elements after `Common` and `Name` are:

Nbrel \: Ghdl_Index_Type

 Number elements in the record.

Elements \: Ghdl_Rti_Arr_Acc;

 The RTI nodes of the element defintions.

Layout \: Ghdl_Rti_Loc

 The layout is the relative address that the layout/bounds information
 of the elements will be relative to.

Record Type (Ghdl_Rtin_Type_Record)
---------------------------------------------
For an unbounded record the Layout is not used, but rather a `Bounds` must be
given.

Element Type (Ghdl_Rtin_Element)
--------------------------------
The record elements after `Common` and `Name` are:

Eltype \: Ghdl_Rti_Access
 The RTI node representing the type of the element.

Val_Off \: Ghdl_Index_Type
 For static element the offset is in the record.
 For complex element the offset is in the type layout or object layout.
 This is the offset for the value for generics or constants.

Sig_Off \: Ghdl_Index_Type
 This is the offset for the value wrapper in signals or ports.

Layout_Off \: Ghdl_Index_Type;
 For unbounded records: element layout offset in the layout.
 The layout is stores all the bounds for the various elements
 when the unbounded record is given bounds.

Examples
--------

.. code-block:: vhdl

   library ieee ;
   use ieee.std_logic_1164.all;

   package mypkg is

     type mytype is record
       a: std_logic;
       b: std_logic;
     end record;

   end package;

   library ieee ;
   use ieee.std_logic_1164.all;
   use work.mypkg.all;

   entity myentity is
     port(
       x: in mytype
       );
   end myentity;

   architecture arch of myentity is
   begin
   end arch;


What will be the structure of the RTI for the port `myentity.x`?

The architecture has a context.
Address of the architecture is A

The entity has the same context.
Address of the entity is A.

The child on the entity is the port.
Address of the port is A + 16.

A port is a record 'x'
Address of the record value is A + 16.

The record contains 'a' a std_logic vector.
Address is A + 16.

The record contains 'b' a std_logic_vector.
Address is A + 24

.. code-block:: vhdl

   library ieee ;
   use ieee.std_logic_1164.all;

   package mypkg is

     type mytype is record
       a: std_logic_vector(1 downto 0);
       b: std_logic_vector(1 downto 0);
     end record;

   end package;

   library ieee ;
   use ieee.std_logic_1164.all;
   use work.mypkg.all;

   entity myentity is
     port(
       x: in mytype
       );
   end myentity;

   architecture arch of myentity is
   begin
   end arch;

.. code-block::

   - Architecture (A)
     - Entity (A)
       - port x (A+16)
         - x.a (A+16)
         - x.a(?) (A+16)
         - x.a(?) (A+24)
         - x.b (A+32)
         - x.b(?) (A+40)
         - x.b(?) (A+48)

.. code-block:: vhdl

   library ieee ;
   use ieee.std_logic_1164.all;

   entity myentity is
     generic (
       WIDTH: natural := 2
       );
     port(
       x: in std_logic_vector(WIDTH-1 downto 0)
       );
   end myentity;

   architecture arch of myentity is
   begin
   end arch;

.. code-block::

   - Architecture (A)
     - Entity (A)
       - generic WIDTH (A+16)
       - port x (A+48) content of address (A+48) is B
         - type information
           analyze a type with context (address=A, rti=entity)
           layout is located at A+20
           so bounds is located at A+28
         - x subtype array (B)
           - x(?) (B)
           - x(?) (B+8)