Appendix 1 to CSIM Simulator Document

Appendix A - Structural/Topology Description Text Format

Block diagrams, such as structural descriptions of modeled systems, are usually created with the CSIM-GUI drawing tool. The GUI creates a textual net-list, or topology file, that is accepted by the CSIM pre-processor and ultimately the CSIM simulator. Diagrams may have hierarchy, by including or referencing other diagrams within objects of a given diagram. This appendix describes the format of CSIM's XML topology files. Extensible Markup Language, (XML) is a standard method of encapsulating data within tagged sections, using angle-bracket (<>) tags. See W3.ORG. (The current XML format evolved from earlier pre-XML formats, that are still accepted by the CSIM tools, and which are documented in Old Format v1.8.)

A given file may contain multiple diagrams or sub-diagrams. The file may also reference other files containing diagrams. Each diagram is contained within a diagram-block, or module, which contains two parts:

Diagram-Block:

Box Instantiations - Boxes may represent nodes, devices, tasks, modules, or other modeled objects.
Link Interconnections - Links may represent wires, data-flow arcs, or other connections. This net-list describes the topology of the diagram.

The box instantiation list is a declaration of each box, or device, in your modeled system according to its designated class or type. The system topology is the connection list specifying how the devices are interconnected.

Example:

  <DEFINE_MODULE type="top_level" rank="top_diagram">

      <DEFINE_NODE_INSTANCES>
          <box name="procA" type="MC6830" > </box>
          <box name="procB" type="MC6830" > </box>
      </DEFINE_NODE_INSTANCES>

      <DEFINE_TOPOLOGY>
         <lnk from="procA" frmprt="ioprt" to="procB" toprt="ioprt" 
		a_dr="hdplx" a_ql="1" a_tr="20.0" a_lt="10.0>
         </lnk>
      </DEFINE_TOPOLOGY>
   </DEFINE_MODULE>

Note that all tags must be balanced. That is, there must be a closing tag (containing a "/") for each opening tag.

The formal definition is shown in the CSIM XML Schema document.

The remaining sections of this document describe the contents of the module-block.

A1. Diagram Blocks

A diagram may contain a collection of boxes (objects), connections (links), and text notes -- all of which may have attributes. The diagram-block must be encapsulated in the following tags to designate the beginning and ending of the block of items contained within the named diagram:


  <DEFINE_MODULE type="" rank="">
	...
  </DEFINE_MODULE>

The type attribute specifies the diagram's name. The name is arbitrary, but must be unique within a collection of diagram-types. The diagram can be referenced on other diagrams by its given type-name. This enables hierarchical diagrams.

The rank attribute specifies information about where a diagram exists within the diagram hierarchy. Presently two values are allowed: top_diagram and child. Only the top-diagram of a system should have rank="top_diagram". All others should have rank="child". This provides a mechanism to indicate which diagram is the top-diagram out of a set of diagrams.

Arbitrary attributes may be added to module-definitions and module-instances. The former are called default module attributes, while the latter are called instance-attributes. See Module Attribute Format for more information.

Documentation about a given diagram type may be enclosed in <Documentation> ...</Documentation> tags.
Example:


  <DEFINE_MODULE type="xx" rank="">
      <Documentation>
            ...
      </Documentation>

A2. Box Instantiation:

Boxes within a diagram may represent network-nodes, architectural-devices, software-tasks, sub-diagrams or modules, or basically any other kind of modeled objects. The box-instantiation section of a diagram, declares each box, or device, in your modeled system according to its designated class or type. The box-instantiation section must be encapsulated in the following tags (in bold) to designate the beginning and ending of the box items contained within the current diagram block:

   <DEFINE_MODULE type="" rank="">
      <DEFINE_NODE_INSTANCES>
          ...
      </DEFINE_NODE_INSTANCES>
     ...

Within the DEFINE_NODE_INSTANCES block, a list of two kinds of entries are permitted: box and mod. This allows for instantiating boxes or modules, respectively. (Module is another word for diagram, which in this case will instantiate a sub-diagram.)

The boxes and modules instances must have a name and a type attribute. The instance-name is arbitrary, but must be unique within a given diagram. The type-name binds a box (or device) to a model (class of devices), which must be defined under the device-type behavior description section (3). The type-name binds modules (or sub-diagrams) to another diagram, which must be defined.
Example:

    <DEFINE_NODE_INSTANCES>
       <box name="b1" type="t1"> </box>
       <mod name="subdiag" type="diagram2"> </mod>

All instantiations may also have additional attributes, depending on the application, or arbitrary ones added by the user. By convention, [most]-all attribute tags begin with the letter a, to designate them as such. For example, the nodes of DFG (data-flow-graph) diagrams contain attributes for compute-time, iterations, and mapping assignments, designated as a_ct, a_it, and a_mp, respectively.
Example:

       <box name="b1" type="t1" a_ct="3.4" a_it="1" a_mp="pe3"> </box>

Additional user-defined attributes are specified with the following tag:


      <a name="attribname"/> value </a>

... where attribname is the user-supplied attribute name, and value is what the the attribute is set to. The value may be a letter, number, character-string, integer, or floating-point value. Many attributes may be listed before the closing </box> tag.
Example:

       <box name="b1" type="t1"> 
          <a name="fruit"/> bananas </a>
          <a name="soup"/> veggie </a>
       </box>

Additionally, objects can have attributes containing information about where to place the item within the diagram. Placement information is also called geometry, and is specified in x-y coordinates or vertices. Vertex information is always specified with : <vert x="" y=""/> tag in CSIM diagram files. Often multiple vertices may be required, so the vertices may be listed.
Example:

       <box name="b1" type="t1"> 
          <a name="fruit"/> bananas </a>      
	  <vrt x="4.5" y="2.1"/>   <vrt x="4.9" y="2.6"/>
	  <vrt x="5.5" y="3.1"/>   <vrt x="5.9" y="3.6"/>
	</box>

It is often convenient to think of a diagram as viewed on a page of paper. Notionally, the geometry coordinates are locations on the page in inches, with (0,0) at the top-left, and (11,8.5) at the lower right in a landscape mode 8.5x11 printout. However, the coordinates are merely relative floating-point values on the X-Y plane, and may span from -infinity to +infinity. The GUI will automatically scale the range to fit on the screen and printed pages, so the typical user will be unaware of the actual values. Note that geometry information is used only for presentation of drawings to human users in understandable and visually appealing layouts. Most of the simulation tools ignore the geometry information, and use only the logical attributes instead. Therefore, the geometry vertex attributes are always optional. This is helpful, especially if you are generating CSIM diagram files from purely logical sources. CSIM's GUI contains an auto-placement option that can generate reasonable placement information when absent.

A3. Topology Interconnection List:

Links may represent wires, data-flow arcs, or other connections. The list of connections, sometimes called a net-list, describes the logical topology of a diagram. Generally, the system topology describes specific links through which devices communicate with each other. Communications between devices are constrained to occur through network links. 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 link-instantiation section must be encapsulated in the following tags (in bold) to designate the beginning and ending of the connecting-line contained within the current diagram block:

      <DEFINE_MODULE type="" rank="">
      <DEFINE_NODE_INSTANCES>
          ...
      </DEFINE_NODE_INSTANCES>
      <DEFINE_TOPOLOGY>
          ...
      </DEFINE_TOPOLOGY>

Within the DEFINE_TOPOLOGY block, a list of two kinds of entries are permitted: lnk and bundle. This allows for instantiating links or bundles, respectively. (Bundle is a hierarchical link. It references a diagram containing sub-links. Bundles can represents multiple links with a single graphical connection.)

Links and bundles must have attributes designating what their end-points are connected to, if anything. The links and bundles must have from and to attributes that designate the box-names to which the link is connected. This also establishes directionality, if relevant. The referenced box-names must appear in the instantiated set from the instantiation section above, or else be set to the module's name, or "EXTERNAL_PORT", or "DEV_NULL". Connecting a link to the module's type-name or "EXTERNAL_PORT" creates an external port on the module, and causes the link to be connected to that external port. External ports enable connections through levels hierarchy in hierarchical diagrams. Connecting a link to "DEV_NULL" means the link is not connected to anything.

In addition to naming the boxes to which links connect, you must also specify a unique port-name on the respective boxes, by the frmprt and toprt attributes.
Example:

      <DEFINE_TOPOLOGY>
            <lnk from="dev1" frmprt="out7" to="dev4" toprt="in0"> </lnk>
            <bundle type="bud3" from="dev1" frmprt="out7" to="dev4" toprt="in0"> </lnk>
      </DEFINE_TOPOLOGY>

Note that the bundle-link as the additional bundle-type attribute which references the bundles sub-link diagram.

All links may also have additional attributes, depending on the application, or arbitrary ones added by the user. By convention, [most]-all attribute tags begin with the letter a, to designate them as such. For example, the arcs of hardware architecture diagrams or network diagrams, contain attributes for directionality, queue-length, transfer-rate, latency, and cost (routing), designated as a_dr, a_ql, a_tr, a_lt, and a_cs, respectively. Directionality values for the a_dr attribute can be" fdplx, hdplx, or smplx. 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 a_ql attribute indicates 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 a_tr attribute 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 a_lt attribute 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.

For the arcs of DFG (data-flow-graph) diagrams, attributes for produce, threshold, consume, and initial amounts are designated by a_pd, a_th, a_cn, and a_in respectively.
Example:

       <lnk from="dev1" frmprt="out7" to="dev4" toprt="in0" a_pd="1" a_th="1" a_cn="1" a_in="0"> </lnk>

As in earlier sections, additional user-defined attributes are specified with the following tag:


      <a name="attribname" > value </a>

       <lnk from="dev1" frmprt="out7" to="dev4" toprt="in0" a_dr="fdplx" a_ql="1" a_tr="40" a_lt="0" a_cs="1.0">
          <a name="priority"/> medium </a>
          <a name="protocol"/> tcp/ip </a>
       </lnk>

Additionally, links can have attributes containing information about where the link appears within the diagram. As in other sections above, vertex information is always specified with : <vert x="" y=""/> tag in CSIM diagram files. Links do not need to be draw as straight lines, but can have multiple vertices, which allows them to turn corners, etc.. Therefore the vertices may be listed.
Example:

       <lnk from="dev1" frmprt="out7" to="dev4" toprt="in0" a_dr="fdplx" a_ql="1" a_tr="40" a_lt="0" a_cs="1.0">
          <a name="priority"/> medium </a>
          <vrt x="4.5" y="2.1"/>   <vrt x="4.9" y="2.6"/>
          <vrt x="5.5" y="3.1"/>   <vrt x="5.9" y="3.6"/>
        </lnk>

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:

an infinite value, if the attribute is transfer-rate or queue-size,
0.0, if the attribute is latency, and,
fdplx, if the attribute is direction.

Each attribute is resolved independently.

A4. Text Notes:

Arbitrary text, text-notes, or annotations, can be added to diagrams via note tags following the topology sections. The note tag has the following form:

     <note x="" y=""> your text </note>

Other attributes, such as the text size, font, or color can be specified with attributes.

Example:

     <note color="9" x="3.5488" y="1.5829"> Example diagram 1. </note>

A5. Bounding Boxes:

Boundary boxes can be added to diagrams via boundbox tags following the topology sections. The boundbox tag has the following form:

     <boundbox x1="" y1="" x2="" y2="" x3="" y3="" x4="" y4="" x5="" y5="" x6="" y6=""/>

Other attributes, such as the line thickness or color can be specified with attributes.

Example:

     <boundbox x1="1.2" y1="2.2" x2="8.4" y2="5.4" x3="8.4" y3="2.2" x4="1.2" y4="2.2" x5="1.2" y5="5.4" x6="8.4" y6="5.4"/>

A6. File Encapsulations:

To be a proper XML file, as dictated by the W3C, the file should begin with the following line:

      <?xml version="1.0" standalone="yes"?>

CSIM files can contain both XML and non-XML data. For example, the C-code sections are definitely not XML, while the diagram sections are conveniently represented in XML. Therefore, to conform with XML standards, all the contents must be enclosed with <csim_hw_file> or <csim_sw_file> and </csim_hw_file> or </csim_sw_file> tags, usually placed at the very beginning (just after the <?xml version="1.0" ... > tag) and ending, respectively. The <csim_hw_file> tag is intended for hardware (hw) or system architecture diagrams. It is presently used for all types of diagrams except software-DFG's, and is the default. Using the <csim_sw_file> causes the nodes and links to be interpreted with software-DFG attributes.

To accommodate different tool-versions and file formats, the early contents after the <csim_hw_file> or <csim_sw_file> opening tag can contain the CGUIformatVersion Example:

      CGUIformatVersion 3.0

Recapping, 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">
<csim_hw_file>
CGUIformatVersion 3.0

Comments may be placed in the file by encapsulating them within <HEADER_COMMENT> </HEADER_COMMENT> tags. For example:

<HEADER_COMMENT>
This is a comment.
Another comment.
.... etc..
</HEADER_COMMENT>

A7. Library Organization

Models may be organized into hierarchical library structures by the following constructs. Organizing your models in a hierarchical library 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.
Example:


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

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.

A8. Complete Examples

A complete example of an xml file containing a simple module with topology is shown below:


<?xml version="1.0" standalone="yes"?>
<csim_hw_file>
CGUIformatVersion 3.0


<DEFINE_MODULE type="top_level" rank="top_diagram">

  <DEFINE_NODE_INSTANCES>
        <box name="B1" type="uProcA" >
		 <a name="CPU"/> i386 </a>
		 <a name="ClockSpeed"/> 300 Mhz </a>
                <vrt x="1.8" y="2.4"/> <vrt x="3.6" y="4"/>
        </box>
        <box name="B2" type="uProcA" >
                <vrt x="6.2" y="2.4"/> <vrt x="8" y="4"/>
        </box>
  </DEFINE_NODE_INSTANCES>

  <DEFINE_TOPOLOGY>
    <lnk from="B1" frmprt="out1" to="B2" toprt="in2" a_dr="fdplx" a_ql="100" a_tr="10" a_lt="0.1" a_cs="1 1" >
                <vrt x="6.2" y="3"/>    <vrt x="3.6" y="3"/>
    </lnk>
    <lnk from="B1" frmprt="in7" to="B2" toprt="out5" a_dr="smplx" a_ql="100" a_tr="10" a_lt="0.1" a_cs="* *" >
                <vrt x="6.2" y="3.6"/>  <vrt x="3.6" y="3.6"/>
    </lnk>
    <lnk from="B1" frmprt="cntrl" to="B2" toprt="cntrl" a_dr="*" a_ql="*" a_tr="*" a_lt="*" a_cs="* *" >
                <vrt x="7" y="4"/>      <vrt x="7" y="4.8"/>    <vrt x="2.8" y="4.8"/>
                <vrt x="2.8" y="4"/>
    </lnk>
  </DEFINE_TOPOLOGY>

  <note x="3.5488" y="1.5829">Example diagram 1.</note>
  <boundbox x1="1.2" y1="2.2" x2="8.4" y2="5.4" x3="8.4" y3="2.2" x4="1.2" y4="2.2" 
	x5="1.2" y5="5.4" x6="8.4" y6="5.4"/>

</DEFINE_MODULE>


</csim_hw_file>

Note: This topological specification style makes it convenient to build automatic topology generators for regular topologies such as meshes, grids, etc., that can always 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 its own "DEFINE_DEVICE_INSTANCES" section and a "DEFINE_TOPOLOGY" section, just like in the top-level description. In the upper level, the module names are used just like device names. Hierarchical diagrams may an any number of levels. Be careful however to understand the aspect of exponential growth that is possible. For example, six (6) levels of diagrams, where each diagram instantiates ten (10) sub-diagrams, effectively instantiates a million (1,000,000) objects!

Connections to external ports from within a module are defined as being connected to EXTERNAL_PORT or the name of the module definition itself. Links connected to external ports pass through layers of hierarchy, and are depicted as small orange boxes in the GUI.

Example module definition:

<?xml version="1.0" standalone="yes"?> <csim_hw_file> CGUIformatVersion 3.0 <DEFINE_MODULE type="top_level" rank="top_diagram"> <DEFINE_NODE_INSTANCES> <mod name="Dual1" type="Double_node" > <a name="CPU"/> i386 </a> <vrt x="1.8" y="2.2"/> <vrt x="4.8" y="6"/> </mod> <mod name="Dual2" type="Double_node" > <vrt x="6.8" y="2.2"/> <vrt x="9.8" y="6"/> </mod> </DEFINE_NODE_INSTANCES> <DEFINE_TOPOLOGY> <lnk from="Dual1" frmprt="Ext_IO" to="Dual2" toprt="Ext_IO" a_dr="fdplx" a_ql="100" a_tr="20" a_lt="1.0" a_cs="1.0 1.0" > <vrt x="6.8" y="3.8"/> <vrt x="4.8" y="3.8"/> </lnk> </DEFINE_TOPOLOGY> </DEFINE_MODULE> <DEFINE_MODULE type="Double_node" rank="child"> <PORT_LIST> Ext_IO </PORT_LIST> <DEFINE_NODE_INSTANCES> <box name="proc1" type="Pentium" > <vrt x="3.4" y="1.6"/> <vrt x="6.8" y="2.6"/> </box> <box name="xbar" type="Crossbar" > <vrt x="3.4" y="3.8"/> <vrt x="5.6" y="5"/> </box> <box name="proc2" type="Pentium" > <vrt x="3.4" y="6.4"/> <vrt x="6.8" y="7.4"/> </box> </DEFINE_NODE_INSTANCES> <DEFINE_TOPOLOGY> <lnk from="proc1" frmprt="io_port" to="xbar" toprt="p1" a_dr="hdplx" a_ql="*" a_tr="20" a_lt="0.1" a_cs="* *" > <vrt x="4.2" y="3.8"/> <vrt x="4.2" y="2.6"/> </lnk> <lnk from="proc2" frmprt="io_port" to="xbar" toprt="p2" a_dr="hdplx" a_ql="*" a_tr="20" a_lt="0.1" a_cs="* *" > <vrt x="4.2" y="5"/> <vrt x="4.2" y="6.4"/> </lnk> <lnk from="xbar" frmprt="p3" to="Double_node" toprt="Ext_IO" a_dr="*" a_ql="*" a_tr="*" a_lt="*" a_cs="* *" > <vrt x="8.8" y="4.2"/> <vrt x="5.6" y="4.2"/> </lnk> </DEFINE_TOPOLOGY> </DEFINE_MODULE> </csim_hw_file>

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: admin@csim.com)