Appendix 1 to CSIM Simulator Document

Appendix A - Structural/Topology Description Text Format   (v1.8   1999)

The structural description of a modeled system is usually entered by a user using the CSIM-GUI drawing tool. The GUI creates an XML textual netlist that is accepted by the CSIM pre-processor and ultimately the CSIM simulator. This appendix describes the XML format of the topology file. Keywords are in bold.

The header section of the XML file contains several designators indicating the file's format and type. These appear for example as:

<xml version="1.0" standalone="yes">
Comments may be placed in the file by encapsulating them within HEADER_COMMENT: END_HEADER_COMMENT. keywords. For example:
      This is a comment.
      Another comment.
      .... etc..
The topology of any module is encapsulated between the XML tags:
<DEFINE_MODULE>   module_name   <rank>
        . . .
        . . .
Immediately following the <DEFINE_MODULE> tag is the name of the module. (Remember that a module is synonymous for a diagram.) Following the module name is an indicator of the module's rank. The rank can be either top_diagram or child.

The body of the module description contains two major parts:

  1. Node Instantiations List,
  2. Topology Interconnection List.
The node instantiation list is a declaration of each node in the diagram associating it to its designated class or type. The topology is a connection list specifying how the nodes are interconnected by links.

1. Node Instantiations List:

The node instantiation list is encapsulated between the <DEFINE_NODE_INSTANCES> and the </DEFINE_NODE_INSTANCES> tags. Each node instantiation take the following form:
<ins 1> node_name = type <attributes> <vrt> geometry </vrt>
<ins 2> node_name = type <attributes> <vrt>; geometry </vrt>
The first tag is the instance designator. There are currently two kinds of instances: 1 and 2. These indicate whether the node is a leaf-node (1) or a sub-module (2). The node_name is the instance-name of the node, and it must be unique within a module. The type is the designator of the node's type. It may be the name of a behavioral model in the case of a leaf-node, or another module diagram in the case of a super-node (sub-module). A super-node or sub-module are words for a hierarchical element.

After the type designator, any number of arbitrary attributes may follow. By convention, attribute tag names being with the letter a, example: <a_ct> (compute-time attribute), <a_mp> (map attribute).

Finally, the geometry information is placed between the <vrt> and </vrt> tags. The geometry numbers are the x-y coordinates where the node is to be displayed in the GUI. The position of a rectangular node box is specified by four vertices. The coordinate of each vertex is a pair of floating point numbers. (Other shapes may be supported by specifying any number of the polygon vertices.)

2. Topology Interconnection List:

The topology section is the list links. It is encapsulated between the <DEFINE_TOPOLOGY> and the </DEFINE_TOPOLOGY> tags. Each link entry takes the following form:
<lnk> node_name_1 port_name <to> node_name_2 port_name <attributes> <vrt> geometry </vrt>
The first tag is the link designator. It is followed by the instance-name of a node within the module, and the port-name on that node to which the link connects. Following the <to> tag is the second node and its port to which the other end of the link connects.

If the link attaches to an external port of the module, then the module-name itself is used for the node-name, and the port-name is name of the external port.

After the second node and port, any number of arbitrary attributes may follow. By convention, attribute tag names being with the letter a, example: <_lt> (latency attribute), <a_tr> (transfer-rate attribute).

Finally, the geometry information is placed between the <vrt> and </vrt> tags. The geometry numbers are the x-y coordinates where the link is to be displayed in the GUI. Note that links may have any number of vertices (>= 2, of course). Each vertex is a pair of floating point numbers.

Remember that the link section must be closed by the </DEFINE_TOPOLOGY> tag.

Graph textual annotations are recorded with the tag <ANNO>, the coordinates of the beginning of the text string, followed by the text string (message). Example:

<ANNO> 2.190854 -1.447288 Message</ANNO>

Remember that the module-block must be closed by the </DEFINE_MODULE> tag.

The file must be closed by the </csim_hw_file> tag.

3. Library Organization

Models may be organized into hierarchical library structures by the following contructs. Organizing your models hierarchically makes them easier to find when adding them to a diagram. It allows you to group related models under a single heading, that when clicked on, expands to the actual models or further sub-libraries.

	<DEFINE_LIBRARY> libname1
	   <MODEL> model_name1 </MODEL>
	   <MODEL> model_name2 </MODEL>
	   <MODEL> model_name3 </MODEL>
	<DEFINE_LIBRARY> libname2
	   <MODEL> model_name4 </MODEL>
	   <MODEL> model_name5 </MODEL>
	   <MODEL> model_name6 </MODEL>

Note that this library construct affects only the GUI tool; not any of the other tools. It is a convenience feature only.

Presently, these library membership references must be encountered after the models have been defined. The typical use is to place these at the bottom of a reference library file, after the %includes of the models constituting the libraries. Then, users need only import the single library file (by reference) to have access to all the models in convenient form.

Older Formats:

Previously, older formats were used as follows:


          processor_A   =       MC6830
          processor_B   =       MC6830

       /* src-proc  /  port   to   dest-proc  /  port      dir     q-lngth   rate   ovrhd */
         processor_A   ioprt       processor_B   ioprt     hdplx     1       20.0   10.0

A1. Device Instantiation:
The device instantiation list began with the keyword "DEFINE_DEVICE_INSTANCES:". It consisted of two columns binding an arbitrary device name to a class of processor or device. The device classes must be defined under the device-type behavior description section (3). The list must be ended by the keyword "END_DEFINE_DEVICE_INSTANCES.". An example follows:
                proc1           =       iWARP
                proc2           =       iWARP
                controller      =       MC6830

A2. System Topology:
The system topology list begins with the keyword "DEFINE_TOPOLOGY:". The system topology describes specific links through which devices communicate with each other. Communications between devices are constrained to occur through network links.

The connection list consists of 8 columns. The first four columns on each line contain a processor and port connection pair (ie. processor_1 port_x to processor_2 port_y). The processor names given must match those instantiated in the instantiation section (2).

The port names may be arbitrarily chosen, but become defined here for later reference by the behavior code in section (3).

All connections are point-to-point and must be unique. A common bus structure may be defined as a special device with multiple ports in which any incoming message is distributed to all ports.

The fifth column must contain either the keyword "smplx", "hdplx", or "fdplx", depending on whether the links are simplex, half-duplex, or full-duplex. In simplex mode, messages may travel in only one direction, namely only from the first to second device. In half-duplex mode, messages may travel in either direction, but only in one direction at a time. In full-duplex mode, messages may flow in both directions simultaneously, and the ports are treated as two separate simplex ports that run in opposite directions. In other words, simplex links are "uni"-directional, while half- duplex and full-duplex links are two types of bi-directional links.

The sixth column indicates the maximum queue length of the communications link. The queue length must be an integer greater than or equal to 1. It signifies the maximum number messages which may be queued up on a port before further send operations are blocked. A queue depth of "1" indicates that a sending device will be blocked if tries to write a new message to a port on which the previous message has not yet been read by the receiving device. If blocked, operation will resume whenever the message is read. A queue length of "2" allows two messages to be enqueued before blocking, etc. If you never want blocking in your model, then use a very huge number. The queue length is critical in issues of processor synchronization and memory buffer space.

The seventh column specifies the link data rate in terms of message length units per time unit. Each message has a length which is specified in each SEND operation. For instance, if the time units are defined to be uSec, the message length units are bytes, and the data rate of the link being modeled is 10-MB/s, the rate entry in the topology table would be 10e6 B/s * 1e-6 s/us = 10.0 B/us.

The eighth column is the fixed communication overhead time delay that a message should experience in transiting the link. This time delay is added to all message transfers regardless of message size.

The topological section is closed by the keyword "END_DEFINE_TOPOLOGY.".

Wild Card / Infinity "*" Attribute Values:
Often it is convenient to defer specifying some or all of the link attributes. For example, one case is when defining a general purpose module that may be instantiated in various systems with differing parameters. A second case is when the default link-delay mechanism is not wanted because the model will account for transfer delay in another way. For either case, use the "*" (asterisk) symbol instead of a literal value.

The "*" serves as a wild-card or infinite speed attribute. In the first case above, consider a module with a link having a "*" attribute that connects to a link on another hierarchical module which has a finite literal value. The link attribute will then resolve to the finite value. It will not be considered a mismatch. In the second case above, any link attribute that does not resolve to a non-"*" value, will take on:

Each attribute is resolved independently.

An example of a simple topology is shown below:

        /* src-proc/port  to  dest-proc/port  dir  q-lngth  rate  fixd-ovrhd  */
          proc1   port_x    proc3  port_z    smplx    1    20.0   10.0
          shmem   d5         p10   y_data    fdplx    3    10.0    5.0
          sensor  i1        shmem  d0        hdplx   10    10.0    5.0
Note: This topological specification style makes it easy to build an automatic topology generator for regular topologies such as meshes, grids, etc., that can later be manually modified as needed.

Hierarchical topologies may be specified by defining the interconnection of modules. Modules may consist of devices and other modules. Each module definition contains a miniature "DEFINE_DEVICE_INSTANCES" section and a "DEFINE_TOPOLOGY" section, just like in the overall description. However, these sections are both enclosed by a common "DEFINE_MODULE" / "END_DEFINE_MODULE" keyword block. In the outer levels, the module names are used just like device names.

Example module definition:

     DEFINE_MODULE:   Double_node
              proc1  =   Pentium
              proc2  =   RS6000
              xbar   =   Crossbar
              proc1  io_port     xbar p1                 hdplx  1 20.0  1.0
              proc2  io_port     xbar p2                 hdplx  1 20.0  1.0
              xbar   p3          Double_node Ext_IO_prt    *    *   *    *

     DEFINE_MODULE:   top_level
            Dual1  =   Double_node
            Dual2  =   Double_node
            Dual1  Ext_IO_prt    Dual2   Ext_IO_prt      fdplx 1 20 1.0

Figure A1 below, shows the diagram of the example topology corresponding to the text above.

Figure A1 -Diagram of topology corresponding to example.

The device naming during simulation takes on a hierarchical "module/module/ device" syntax so that all devices in the system are uniquely identified. For example: /Dual1/proc1.

All ports that are not interconnected to other devices within the module being defined are considered to be external ports, and are thus connected to the module boundary itself. The direction, queue-length, rate, and overhead attributes of inter-module links are ignored. However, these attributes must match accordingly when resolved down to their ultimate device-device connections.

Modules must be instantiated at the outer level in order to be instantiated in the simulation. Otherwise, everything within them does not exist. Modules must be defined before they are referenced. A module cannot reference (contain) itself. These rules avoid infinite recursion.

Ports which are not connected to anything can be explicitly connected to "DEV_NULL" to avoid warning messages about unconnected ports during preprocessing. The default device "DEV_NULL" has two port types: "NC" and "null". "NC" stands for not connected, and will give a runtime error if a device tries to write or read from such a port. "null" is essentially a "bit bucket", and it will absorb anything written to it during the simulation. Reads will simply never return.

(Questions, Comments, & Suggestions: