How-to use ARRAY and RARRAY ?

Synopsis

ARRAY ( typename, no_of_elements, type_of_elements )

The ARRAY construct provides a mechanism for defining lists of objects of the same type, similar to the array construct in C & C++. Anytime such a declaration is encountered, a new C++ class will be created. This class will have the name typename.

typename: str - The name of the array type, used when creating instances. Instances can either be created in C++ (as using any existing class) or using RARRAY. Using RARRAY will allow the display of arrays from the Hase graphical interface. It is strongly recommend to do so.
no_of_elements: str or int (-1 or >0) - The number of elements in the array. Several mechanisms are provided but in every case the size of the array has to be known before the simulation begins.
int (>0): The integer value which is specified is the default size. That is to say: for each RARRAY created from this type, an array of the size specified in that field will be allocated at the beginning of the simulation. The HASE user interface allows user to modify the size of RARRAY parameters. Each instance of a defined ARRAY is independent regarding its number of elements.
-1: -1 is to be set (before building the project: in EDL or with the gui) whenever the user wants the size of the array to be computed from values of other parameters.
- If -1 is set before building the project, a more complex C++ code is generated.
- If -1 was set before building and is unset before running the simulation, the complex code is simply not used. And the new integer value (>0) is used to set the size of the array.
- If -1 was not set before building and is set just before running the simulation an error will occur since the complex code would have not been generated (Just re-build the project in that case).
- If -1 was set before building and is still set before running the simulation, a pre-declared method is called to compute the size of the array. The user MUST define this method in the .hase file of each entity which declares an RARRAY with the -1 size. This method is called typename_f(), has no parameter and must return an int.
str: The user may also type the name of an RINT (See the reference section) parameter to represent the number of elements. This value of this parameter just before running the simulation, will be used to set the size of the array. This value MUST be positive. The RINT parameter can either be declared in the GLOBALS section of the EDL file or as a parameter of the entity which defines the RARRAY.
type_of_elements: str - The name of the type of the elements in the list. This should be a HASE built-in type or a type previously defined into the parameter library section.

Examples:

ARRAY ( Memory, 4096, Memory_Contents_Structure )
ARRAY ( Cache, -1, int)
...
ENTITY Sender(
...
PARAMS (
RINT(no_lines,256)
RINT(no_blocks,4)
RARRAY(Cache, data)
...

in Sender.hase:
$class_defs
int Sender::data_f() { return no_lines*no_blocks; }

Initialisation

The arrays, which most of the time are used to represent the content of a memory, can be initialised by providing a .mem file. The C++ code which is generated does not depend of the content of the .mem file. This right .mem file is read to fill the array just before the simulation is run. Thus, the same executable file can be used with different memory contents.
The initialisation process depends on the context of the array (entity type name, entity instance name, parent type and parent instance name) and of the name of the RARRAY instance.
When the array belongs to an entity, which itself belongs to a compound entity the first readable file which name match the following criterions is used:

<compound_instance_name>.<entity_instance_name>.<array_instance_name>.mem

<compound_instance_name>.<entity_type_name>.<array_instance_name>.mem

<compound_type_name>.<entity_instance_name>.<array_instance_name>.mem

<compound_type_name>.<entity_type_name>.<array_instance_name>.mem

When the array's entity does not belong to a compound entity or when one of the preceding .mem file was not found the two following files are checked:

<entity_instance_name>.<array_instance_name>.mem

<entity_type_name>.<array_instance_name>.mem

Examples:

Let us consider the instance SEND of type Sender. The entity Sender declares an RARRAY called data.
Then, the file SEND.data.mem is used if existing, otherwise the file Sender.data.mem is used. In the latter case, the same file may be used to initialise several instances (e.g. SEND2 of type Sender if the file SEND2.data.mem does not exist).
Let us consider now the instance NODE1 of type Node,. The entity Node is defined as a COMPENTITY and has a child SEND1 of type Sender.
In that case each of the following file will be checked (in order) until finding one readable: NODE1.SEND1.data.mem, NODE1.Sender.data.mem, Node.SEND1.data.mem, Node.Sender.data.mem, SEND1.data.mem, Sender.data.mem.

Warning: Sharing the same file for the initialisation does not mean that the arrays are physically shared. This mechanism is mainly useful when defining meshes with lots of nodes to avoid creating a different file for each node (The number of nodes may be important and may change).
Notes:

The format of the data contained in the .mem file is checked during the initialisation process. It has to match the format declared in the EDL. Otherwise, an error message occurs at the beginning of the simulation and the initialisation process is cancelled.
Empty lines are ignored.
Lines starting with '//' are also ignored.
if the size of the array is >0, size elements are read at most.

Initialisation and sections

A .mem file may contain some sections. The section separator is a line equals to: //$next section.
When a file contains some sections (no_section), the i^th array which has to be initialised from that file will be initialised with the content of the (i modulo no_section)^th section.
The order of the arrays is determined by the declaration order of instances (AENTITY) in the STRUCTURE part of the EDL file.

Frederic Mallet

Last modified: Tue Apr 2 15:06:35 BST 2002