CSIM GUI

(Graphical User Interface for Block Diagram Models)
5-29-2014

CSIM's GUI provides a graphical interface for creating, editing, and viewing block diagrams. Block diagrams may be used to represent, integrate, or construct models - for example, hardware architectures and/or software data flow diagrams.


Contents

  1. Invocation
  2. Diagram Entry / Editing
  3. Data Flow Graph Entry
  4. Macro Definition - Graph Parameters
  5. Hierarchy: Modules and Bundles
  6. View Modes
  7. Bounding Box
  8. Renaming Diagrams
  9. Dimensional Drawing Units
  10. Automatic Backup
  11. Automatic Journaling
  12. Status Information
  13. Making External Ports Unique
  14. Changing Box Display Styles
  15. Changing Background Colors
  16. Opening Text-Editor
  17. Sticky vs. Non-Sticky Draw Mode
  18. Printing to Files
  19. Accessing Model Documentation and Object Properties
  20. Cutting & Pasting Between GUI's
  21. Automatic Placement
  22. Highlighting Connections & Connected Boxes
  23. GUI Set-Ups
  24. Special Functions / Alternate Text Editors, etc.


1. Invocation:

The GUI can accept a source file to be edited or viewed as a command-line argument. If no arguments are specified, it will assume you are going to create a new diagram which you would save to a file name of your choice by the save_as function.
     Example:
                gui   radar.dfg
Alternatively, you can open an existing file after you start the GUI, by selecting the File / Open menu within the GUI.


2. Diagram Entry and Editing

To create a new diagram file, bring up the GUI by typing gui. Then enter your diagram, such as a hardware architecture, and save it to a file name. Future edits to your diagram can be made by starting the GUI with your diagram file name as the command-line argument to the GUI. The GUI will recognize the file format and automatically set the appropriate mode, such as HW-Graph.
     Example:
               gui  arch_1.sim
On entering the GUI you will notice a Draw Mode Palette on the left control panel. It contains buttons for adding boxes, modules, links, and annotations. To add a box, select the Add Box button on the Draw Mode Palette and then move your mouse pointer to a place in the drawing canvas where you would like to place the box and click the mouse once there. You will see that a new box has been added there.

Boxes (also called nodes) are the building-block models. For example, they can represent the devices of architectures, such as processor elements, cross-bar switches, and memories. Modules are super-boxes that reference sub-diagrams. They represent hierarchical groupings of underlying sub-boxes. Links are the connections between boxes and also modules. Bundles are hierarchical collections of links, just as modules are hierarchical collections of boxes.

Notice that after adding an object, the GUI is still in the Add-object mode. This enables you to quickly add several more objects by simply placing the pointer and clicking. Try adding some more nodes. (This is called sticky-draw-mode. If you prefer to change this behavior, see non-sticky-draw-mode.)

After adding a new box, it has a default name. You can set the box's name by opening its properties. To select an object, the GUI must first be placed in the Select/Move mode by clicking on the Select/Move button of the Draw Mode Palette. Then select a box with a click of the mouse. When you select an object, you will see the object highlighted by tick-marks. The node's properties are then opened by clicking on the Open Properties button on the left side under the Draw Mode Palette. You will see a properties dialog appear. It contains fields for the relevant attributes of a box, such as the box's name or instance-name, and the box's type or type-name. Filling in the fields and clicking OK will set the box's attributes.


Example Screen Shot: Basic diagram entry/editing

You can add links to connect the boxes by selecting the Add Link button on the Draw Mode Palette. To add a link, click and release the mouse at the spot where you want the link to attach from the source box.

Then move the mouse to the destination box of the link and double-click. You will see the arc formed between the boxes. Again, notice that the GUI remains in the Add Link mode. You can continue adding new links quickly without returning to the menu, by simply clicking where you want the links to be.

A link does not need to be a straight line. To make a link turn corners, you can add vertices to the link either while you are entering a new link, or to an existing link. Vertices appear as tick-marks on a selected link. You can manipulate a link by dragging a vertex. To add a vertex while you are entering a link, click the mouse button once, where you want each vertex to be placed as you enter the link. You will see that segment of the link spider-web change from a dashed to a solid line segment. To add vertices to an existing link, select the Add-Vertices button on the left Draw Mode Palette, then select the link you wish to add vertices to. You will see an additional vertex added to the selected link for each time you click on the link.

Summary: To add a new link, select Add Link, then point to where you want the link to begin. To start the link, click once and release. Move the mouse the where you want the next vertex to be, and click once and release, for each intermediate vertex (I.E. corner). To end the link, click twice at the same spot (I.E. double-click).

After adding a new link, you will want to set its parameters, such as the link's transfer rate, latency, associated buffer queue-length, and port names. You can set a link's attributes by selecting the link and opening it properties. To select a link, be sure to go into the Select/Move mode by clicking the Select/Move button on the Draw Mode Palette at left. Then click on the link. You will see that it is selected by the tick-marks that appear on its vertices. Next click the Open Properties button under the Draw Mode Palette. You will see a dialog box appear for setting the link parameters.

The port names are significant for connecting the links to the respective ports of a device or module.


Figure 2 - Link properties edit-popup.


The direction may be one of: simplex, half-duplex, or full-duplex. Simplex means the link is uni-directional. Data may flow in only one direction ever. The first port is an output while the second is an input-only.

Half-duplex means the link is bi-directional, but data can only flow in one direction at a time.

Full-duplex means that data can flow in both directions simultaneously. A full-duplex link is composed of two simplex links running in opposite directions. It is convenient to show such links as one line in diagrams.

In other words, the basic choices for link direction are: uni-directional and bi-directional. The bi-directional case is further sub-divided into half-duplex and full-duplex. The former consists of a single link capable of data flow in either direction at a time, and the latter consists of two links in opposite directions that can be used simultaneously. For consistency, the uni-directional case is called, simplex. Figure 3 illustrates the distinction between link directions visually.


Figure 3 - The meaning of link directions.

Editing Object Properties

The properties of any object (box or wire) can be edited by selecting the object and clicking on the Open Properties button on the Draw Mode Palette of the left control panel. The properties of wires and leaf-boxes can also be opened by double-clicking on the box or link itself.

The properties of one object can be quickly copied to another object by opening the properties of the first object, and then selecting the second object before closing the properties dialog. The properties will be saved to whichever object is selected when the property dialog is accepted by the Ok button.

The properties of multiple objects can be set in a single operation by selecting a group of similar objects prior to opening the properties. (Either drag a stretch-line around the objects, or select them individually while holding-down the shift-key to add or remove objects from the selected group.) You can set some attribute fields while leaving others unchanged, by leaving the fields you do not wish to modify blank.



3. Data Flow Graph Entry:

Editing flow-graphs is very similar to editing other diagrams. To create a new data flow graph (DFG) file, bring up the GUI by typing GUI, and select Edit SW Graph under the Tools menu. Then enter your graph and save it to a file name. Future edits to your DFG file can be made by starting the GUI with the DFG file name as the command-line argument to the GUI. The GUI will recognize the file format and automatically set the mode to SW-Graph.

Example:
	GUI  app_1.dfg

On entering the GUI you will notice a Draw Mode Palette on the left control panel. It contains buttons for adding flow-graph nodes, super-nodes, arcs, and annotations. To add a node, select the Add Node button on the Draw Mode Palette and then move your mouse pointer to a place in the drawing window where you would like to place the node and click the mouse once there. You will see that a new node has been added there.

Notice that after adding an object, the GUI is still in the add-object mode, so you can add several more nodes by simply placing the pointer and clicking. Try adding some more nodes.

After adding a new node, it has a default name. You can set the node-name by opening its properties. To select an object, the GUI must first be placed in the Select/Move mode by clicking on the Select/Move button of the Draw Mode Palette. Then select a node with a click of the mouse. When you select an object, you will see the object highlighted by tick-marks. The node's properties are then opened by clicking on the Open Properties button on the left side under the Draw Mode Palette. You will see a properties dialog box appear. It contains fields for the relevant attributes of a DFG node, such as the node name or instance-name, the compute-time, iterations, and optional mappings. Filling in the fields and clicking OK will set the node's attributes.

You can add arcs to connect the nodes by selecting the Add Arc button on the left Draw Mode Palette. To add an arc, click and release at the spot where you want the arc to attach from the source node, Then move the mouse to the destination node of the arc and double-click. You will see the arc formed between the nodes. Again, notice that the GUI remains in the Add Arc mode, so you can continue adding new arcs quickly with returning to the menu, by simply clicking where you want the arcs to be.

Note that because DFG's are directed graphs, the direction of the arcs is very significant. It indicates the direction of data flow and the direction of data-dependency. To indicate direction, an arc must be drawn from its source node as the first vertex of the arc toward the destination node as the last vertex in the arc.

After adding a new arc, you will want to set its parameters, such as the produce amount, threshold amount, and consume amounts associated with the flow-graph arc. You can set an arc's attributes by selecting the arc and opening it properties. To select an arc, be sure to go into the Select/Move mode by clicking the Select/Move button on the Draw Mode Palette at left. Then click on an arc. You will see that it is selected by the tick-marks that appear on its vertices. Next click the Open Properties button under the Draw Mode Palette. You will see a dialog box appear for setting the arc parameters.

The port name is not significant for performance modeling on a flat graph. However the port names *are* significant for functional flow-graph modeling and for connection of internal-to- external arcs to the arcs within super-nodes.

To support manual mapping of DFG Nodes to PE's, you may optionally specify the map_PE that you want a Node to execute on by specifying the PE (name or number) as an optional parameter (after the iteration parameter).

You can specify a DFG node to execute on a series of PEs by listing the PE sequence instead of specifying a single PE. This can be used to specify round-robin type mappings, and etc..


3.1 Pre-Defining Leaf-Nodes:

Leaf-Nodes do not need to be pre-defined. However, if a leaf-type is not defined, then the GUI will be unable to suggest port-names when making connections to nodes of that type. Module-types are defined by the module's drawing, so the external ports become known from outside a module.   Pre-defining the node-types also enables convenient menu selection of the node types from the properties dialog.

You can define the ports on a leaf-node-type by the following method:


        DEFINE_NODE_TYPE:   FFT_1024
          PORT_LIST( input, coef, mode, out );
        END_DEFINE_NODE_TYPE.
You can place the definitions in your .dfg file(s). It can either be your main diagram file, or a common library file that you reference via import.



4. Macro Definition - Graph Parameters

The macro feature allows you to define frequently referenced constants or parameters in your diagrams. It provides an easy way to modify parameters. To define a macro, open the EDIT menu under the top tool bar and select macro. This will cause a macro window to open. You can either enter new macro definitions here, or you can view and edit the existing definitions.

A macro definition is constructed by placing the macro name you wish to define first, followed by an equals sign, and then the value you wish to define it as.

For example:


                        FFT_Delay = 0.68
                        FFT_Size = 4096
                        MATMUL = FFT_DELAY * 40.7 + 2.3
                        PE2  = Board1Mcm0Pe0
Related to macros are graph-variables, which are the accessed from the Edit menu, just below the macros item. Graph macros and variables belong to the more general class called Attributes. Arbitrary arithmetic expressions will be evaluated for attributes, graph macros and variables. For further information and Macros and Variables, see Graph Variables. Attributes can be set at any level, such as on individual objects, on specific modules, or globally. The Edit/Macro or Edit/Variable menu items control global attributes, visible to all underlying objects unless overridden by the attribute properties of a specific object or module. See Object Attributes. To designate attributes to be visible on diagrams, see Designating Visible Attributes.





5. Hierarchy: Modules and Bundles

The special constructs of Modules and Bundles introduce the concept of hierarchy into diagrams. See Hierarchy.
  • A Module is a special box that references a sub-diagram. The sub-diagrams contain other boxes, modules, links and bundles. The GUI distinguishes a module from a regular box by rendering it with a thicker outline.
  • A Bundle is a special link that references a group of sub-links and/or sub-bundles. The GUI distinguishes a bundle from a regular link by rendering it with a thicker line.
Bundles are to Links, as Modules are to Boxes. Like Modules, Bundles are diagrams, or sub-diagrams, depending on your view-point. However, Bundles may contain only Links and other Bundles, while Modules may contain Boxes, Modules, Links, and Bundles.

In the GUI, you can open a module or bundle by double-clicking on it (I.E. drop-DOWN into). -- Or by selecting it and clicking Open Module. You return to the upper diagram by clicking Close Module (I.E. go-UP).

The first time you attempt to open a new module or bundle, it will ask for a Type-Name. You can give an existing module (or bundle) name, in which case it will reference that diagram. Or you can give a new name, which enables you to create a new module (or bundle) diagram.

A given sub-diagram (or bundle) may be referenced by multiple instances on upper diagrams. Modifying a sub-diagram will change all instances of it.

When you edit a bundle-diagram, the links will be listed top-to-bottom. Each will appear horizontally. The From or source port is on the left. And the To or destination port is on the right. As you add new links or sub-bundles, you should draw them left to right in this way. Don't worry about getting them perfectly straight, as the GUI will straighten them for you when you close the diagram.

Bundles

There are a few things to know about properly using bundles:
  1. The bundle is merely a conceptual idea and a convenience for drawing diagrams. Bundles exist only in the GUI.
  2. Bundles are expanded into regular links prior to simulation. Each bundle is replaced by it's constituent links during the build process. The constituent links are called strands.
  3. The order of the links within a bundle is irrelevant. Only the port-names at the end of the link-segments matter.
  4. The left side port-names correspond to the From side of the bundle, and the right side port-names correspond to the To side of the bundle, as drawn in the GUI.
  5. IMPORTANT - The port-names of the links within bundles get concatenated with the port-names on the outer bundle layers, if any. The concatenation follows a hierarchical (slash-delimited) format similar to module name hierarchies.
  6. Hierarchical port-name concatenation can be used to attach multiple bundle connections to unique ports, even when the same bundle type is connected multiple times to a given box. See examples below.
  7. Some layers of bundles may not need port-names. The port-names of the links will be taken from the other layers.
  8. The links within bundles, (for bundles containing more than one link), must have port-names to uniquely identify their connections. All port-names on a given side (right or left) must be unique relative to the other port-names on that side. (ex. you can have a port called B on the right and left sides of a bundle diagram. But you cannot have two ports called B on the right side, or on the left side.)
  9. When connecting bundles to modules or boxes, the expanded (concatenated) port-names of the strands must match the expected port-names of the box or module.
  10. When connecting bundles to other bundles through levels of hierarchy within a module, care must be taken to connect to compatible bundles. This is often accomplished by connecting to bundles of the same type, or to combinations of bundles/links which produce the same sets of expanded port-names.

Examples
Several helpful working examples of using bundles are included in the $CSIM_ROOT/demo_examples/example_bundles directory of CSIM installations.

Figure 5 shows an example of using two bundle types, with four bundle instances. Note the resulting port names in the expanded view. Note also how the port names match within and outside the module.


Figure 5 - A bundle example.





6. View Modes:

You set the viewing modes individually to display specific information on your diagram. These are useful because your diagram may grow too crowded to display all information. Sometimes unnecessary details can be distracting. Other times, such as at close-zoom, more information may be useful. You can toggle the types of information displayed under the View menu of the main menu bar.
  • Show Node Names
  • Show Node Types
  • Show Port Names
  • Show Link Attributes
  • Show Grid
  • Toggle AspectRatio Lock
The first three options toggle the display of node names-and-types and port names. The fourth option, Show Link Attributes, allows you to toggle the display information on each link, specifically:
  • Direction (Simplex, Half-Duplex, Full-Duplex)
  • Transfer Rate (Bandwidth MB/S)
  • Fixed Transfer Latency (Overhead uS)
  • Routing Cost

The Show Grid option toggles a background grid which is helpful while drawing.

The Toggle AspectRatio Lock option allows you to turn-off the aspect-ratio lock. The aspect-ratio lock forces the same scale in the horizontal and vertical dimensions after zooming. For example, this lock prevents you from setting a tall-narrow view of your architecture. Turning the lock off lets you zoom to such a view.

The default mode is to have the aspect-ratio lock on. Although it is often useful to turn the lock off for viewing very tall-and-narrow, or short-and-wide cross-sections of your drawings, we recommend that you keep the aspect-ratio lock on while drawing. The reason is because otherwise you may tend to create very tall-and-narrow or else very-squat drawings, without realizing it.

However, even if you should do this accidentally, remember that you can always re-establish or change the aspect-ratio of your drawing (or any section) by selecting all the objects, grabbing the tick mark on one of the four corners of the selected region, and then dragging. This will stretch all the selected objects together, while keeping all connections.




7. Bounding Box:

A bounding-box, like an annotation, is merely a diagrammatic aid. It does not enter into the models, nor alter the generated model-code in any way. It merely places a light line around groups of objects on the drawing. A bounding-box is often useful on drawings for showing a conceptual border between groups of objects.



8. Renaming Diagrams:

You can re-name a diagram that you are viewing by selecting Edit / Rename Diagram, (under the Edit menu). A dialog-box will pop-up for you to enter a new name.

Note 1: When you rename a module-diagram that other modules pointed at (ie. Other diagrams contained module-boxes whose type-name matched the name of the diagram being changed.), there will no longer be a diagram definition for the old name, so those boxes will point to an empty diagram or be considered a leaf-nodes. To make them point to the same diagram whose name has changed, change each instance to the new name. Alternately, this can be used as a convenient method for switching the definition of all of instances of a given module-type by a single operation.

Note 2: If you rename the top_level diagram, then when you later re-open the file, the GUI may not know which module to show first, so it may open to an arbitrary module. However, you can move directly to any module at any time by selecting File / Open / Open a currently loaded diagram.




9. Dimensional Drawing Units:

Locations on the drawing area, or canvas, are recorded as floating-point values. Because the GUI is a graphical tool supported by a mouse, the user does not normally need to be concerned with the actual location values. However, some users may be interested in understanding more about the units that are used. You will occasionally see geometry information when zooming -in or -out, panning, changing the grid size, or perhaps perusing the data files. So the following discussion may help interpret the units.

The geometry information is in floating-point units. Because all views are scaled to fit the viewing area or sheet of printing paper, either by the GUI or by the user, the units are strictly relative and arbitrary. As a convention and point of reference, the first drawing canvas (when starting a new diagram) is sized as 8.5 by 11.0 in landscape orientation. The drawing canvas will then expand indefinitely in any direction as needed, by zooming-out and placing objects that make the occupied area larger. When printing hardcopy, the viewable area of the screen is scaled, as needed, to fit on one sheet of paper just as it appears in the viewing window of the GUI.




10. Automatic Backup:

The GUI automatically saves a backup copy of your previous diagram file each time you save a diagram. The backup copy is placed in a file of the same root-name, but with a .bak suffix. If you should need to revert to the previous version, rename the .bak file to the .sim or .dfg file name.



11. Automatic Journaling:

The GUI automatically saves intermediate versions of your drawings as you edit. The intermediate drawings are saved to .jrn journal files with the same root-names as your diagram files. In the event of a crash or system failure during a long editing session, you can recover your recent edits, up to within five minutes of the crash, from the journal files. The journal files are automatically cleaned-up after normal exits from GUI.

The journaling feature is automatic on all Unix versions of the GUI. It is not available in the Microsoft environment (MS-Windows).

The default journaling-period is set to five (5) minutes. You can change the journaling-period by making an entry in your GUI_SETUP_FILE.
For example:

journal_period = 15
This sets the period save interval to 15 minutes. See GUI_SETUP_FILE.



12. Status Information:

The GUI continuously displays status information in two forms:
  1. In the status display of the upper right corner of the GUI window,
  2. In the text-window from which GUI was launched.
The status display shows the current mode, such as: add box, or select/point. It also shows the file being edited and the tool version.

The text-window shows important messages about drawing activities as they occur. It is often instructive to look at the text-window if anything unexpected occurs. For example, attempting to close the top-level diagram will do nothing, but you may not know why. The text window explains:


    Attempt to close graph that has NO parent.  Ignored.
We recommend keeping the lower portion of the text-window visible under the GUI while editing, especially for beginners.

You will find that the text window is a record of important events, such as what file-names diagram or exports were saved to, -even after you have exited GUI.




13. Making External Ports Unique

External-ports on a diagram connect links, through levels of the module hierarchy, to the links on other diagrams. The external-ports are shown as small orange symbols. The individual ports are distinguished from each other by their port-names. Therefore, it is important that each external-port have a unique port-name, on given diagram. (The port-name is set by editing the link-properties of the link attached to a given orange port symbol.)

Often it is convenient to create large numbers of external ports through copy/paste operations in the GUI. However, this results in many external ports having identical port-names. A convenient method for making the port-names unambiguous is to select the Options / Make Ext. Ports Unique feature. When you do, the GUI will examine all the external ports on the current diagram. If any are identical, it will add a unique number to the end of such port-names.

For example, if you have three external-ports called out. Then after selecting Make Ext. Ports Unique under the options menu, you will have three ports named: out_0, out_1, and out_2.




14. Changing Box Display Styles

Various users prefer different styles for the display of the blocks in diagrams. Some prefer boxes with shadows, or three-dimensional borders. Others prefer simple skeleton boxes, or the default solid-boxes.

The CSIM GUI allows you to select or customize-to your favorite box-style. Select Options / Box Display Styles, under the Options menu. It will drop-down to show you the five box-styles to choose from. When you select, the display of all boxes will change style. This affects only how boxes are displayed in your session of the GUI. It does not affect how your diagrams will print, nor the saved files.

You can configure the GUI to always start-up with your favorite box-style by editing the GUI-set-up file. See GUI Set-Ups.

Additionally, all objects, including text-notes, boxes, modules, links, and bundles have a pre-defined color attribute. You change each object's color to differentiate your design objects into distinct functional classes. Change an object's color under the Properties / Attributes dialog after selecting the object.


14.1 Replacing Boxes with Icons -

Instead of plain boxes, you may also use arbitrary icons. The icons can be drawn from arbitrary images.

To replace a given box by an icon:

  • select the box,
  • open it's properties, and click Attributes,
    (you will see a dialog window with a button called Icon),
  • click the Icon button, (you will see a dialog window prompting for an image-icon-file),
  • enter your image-icon-file.
  • click ok.
A set of network-related icon images is provided with every CSIM distribution under csim/model_libs/icons.

Most popular image formats, such as, JPG, GIF, PNG, and PPM will be accepted directly by CSIM's GUI. (On systems lacking the required image-support libraries, PPM format will always work, because it does not depend on any external functions. If needed, all image formats, such as, JPG, GIF, TIFF, BPM, PNG, etc., can be converted to PPM via free utilities such as XV, GIMP, etc..)

Because the icon images may obscure the box names and type labels, there is an option under the View Menu to turn-off icon display. This may be useful for printing documentation. The icon-display mode may be toggled-off for printing, and then toggled back on for editing.

Alternatively, carefully selecting a contrasting background area in your icons where the node name and type displays, will enable easier identification with icons images.

Default Icons
A second way of attaching an icon-image to boxes is to specify a default-icon for a type class. This way, all objects of the given type will automatically appear with the default-icon, unless overridden on an instance basis with the method above.

Within device definitions, use:
            DEFAULT_ICON( iconfile.ppm );
Within module definitions, use:
            <DEFAULT_ICON> iconfile.ppm </DEFAULT_ICON>

See also General Description about Object Icons.




15. Changing Background Colors

Various users prefer different background colors. Some prefer white backgrounds, others like gray, while others prefer the default black background. Often your preference may depend on other tools you have used.

To personalize the GUI to a style that you are most comfortable with, the CSIM GUI allows you to select from five background colors. Select Options / Background Color, under the Options menu. It will drop-down to show you the five colors to select from. When you select, the background will change. Try changing the background in combination with various box-styles. You will find that the look of your diagrams will change quite dramatically.

You can configure the GUI to always start-up with your favorite background by editing the GUI-set-up file. See GUI Set-Ups.




16. Opening Text-Editor:

The CSIM GUI can open a text editor to your model-code when you open the properties of a leaf box, such as by double-clicking on it. A leaf box is a box containing no sub-boxes at the bottom of the structural hierarchy. Leaf boxes are described in textual behavioral files.

By default, the GUI invokes the vi editor in an xterm window. You can invoke your favorite editor by setting the GUI-Setup variable TEXT_EDITOR. See GUI Set-Ups.
For example:

    TEXT_EDITOR = xterm -e vi
or
    TEXT_EDITOR = xterm -e emacs
or
    TEXT_EDITOR = textedit
See Alternative Text Editors.

Alternatively, you don't need to make your own copy of the gui_setup_file, or modify it. Instead, simply set the CSIM_TEXT_EDITOR environment variable. This environment variable overrides whatever the gui_setups file says for the text editor. You can place this setting in your .cshrc or .bash file.
For csh for example:

setenv CSIM_TEXT_EDITOR "xterm -e edt_1.2"
For bash for example:
export CSIM_TEXT_EDITOR="xterm -e edt_1.2"

The text editor opens to the respective model definition, which can be viewed and modified. This feature is very intuitive. If the respective model is as-yet undefined, then the text editor will open to a convenient model template. All you need to do is to fill out the respective fields and model sections. The keyword encapsulation is already provided for you.

Notes:

  • GUI operation freezes until the text editor is closed. This avoids any potential of file collisions from concurrent edits.

  • Opening the text-editor on an undefined model-type brings the editor up with a standard model-shell or template. It is convenient for starting new model definitions.



17. Sticky vs. Non-Sticky Draw Mode

By default, the CSIM GUI operates in Sticky Draw-Mode. That is, the Draw-Mode stays in whatever setting the you last selected (I.E. Add Boxes, etc..), until you explicitly select another mode.

In Non-Sticky mode, the Draw-Mode automatically pops back to "Pointing/Selecting" after any operation. (This is similar to the default mode of simple drawing tools, such as MS-PowerPoint and Adobe-FrameMaker. So if you are used to their operation, you may want to switch to Non-Sticky mode.)

You can set the Sticky vs. Non-Sticky mode by either:

  • Put the keyword "nonsticky" in your gui_setups file. Or,

  • Toggle Options / Non-sticky Draw Mode under the Options menu.
The former sets the default mode for all sessions. The latter toggles the mode within a session.



18. Printing to Files

You can save your diagrams to printer files in several formats, including PostScript (PS), Encapsulated Postscript (EPS), PDF, MIF, and most image formats such as .xpm, .jpg, .gif, .png, etc.. PS is useful for later printing. EPS and GIF are useful for inclusion in PPT or Word reports. MIF is useful for inclusion in Frame Maker or Interleaf reports. PDF, JPG, and GIF are useful for including diagrams on HTML web-pages.

The default format for image files is, .xpm. If you wish to save to another image format, then specify the format by changing the file suffix accordingly. For example, to save as a JPG image, change the file name from image.xpm to image.jpg. The GUI automatically causes the file to be converted to the appropriate type. (If you have a problem on your platform, see other image formats.)




19. Accessing Model Documentation and Object Properties

While editing diagrams, you can access documentation about the models in your diagram, by double-clicking on a model to bring up it's properties dialog, and then selecting Documents. You will then see any documentation the author of that model provided.

Documentation can be added to models within a DOCUMENTATION: ... END_DOCUMENTATION. block in the header area of the model definition. Example:

	DEFINE_DEVICE_TYPE:  sensor
	 PORT_LIST( in, out );
         DOCUMENTATION:
	   This is the documentation. ...
	 END_DOCUMENTATION.

Besides documentation, there are many other types of information you can view from the properties dialog. When opening the properties menu on an object, you will see the properties dialog as shown in figure 6.


Figure 6 - Node Properties Dialog

If you select Attributes, you will see the attributes dialog as shown in figure 7.


Figure 7 - Object Attributes Dialog

From this dialog, you can set the object's color or icon-image, or view or set any of the objects instance parameters. These settings will affect only the object instance you selected.

Alternatively, from the properties dialog, you can select information about the object's life-cycle, by clicking the Life-Cycle button. The life-cycle information dialog will pop-up, as shown in figure 8.


Figure 8 - Object Life-Cycle Dialog

From this dialog, you can find or enter information about an object's, purpose, requirements, critical issues, status, schedule, size, weight, power, cost, availability, reliability, availability, interfaces, dependencies and relationship to other components, history, contact info, etc..




20. Cutting & Pasting Between GUI's

You may copy/cut and paste diagrams, or sections of diagrams, from one GUI to another. This is done by exporting the paste-buffer of one GUI, and importing the paste-buffer into a second GUI. Imports can be repeated without leaving either GUI, or can be done in later sessions. GUI provides two simple ways to export and import paste-buffers.
Method 1:
 In first GUI:
    1. Get some objects into your paste buffer as usual (*).
    2. Click File/Special/Export-Paste-Buffer.
 In the second GUI, or at a later time:
    3. Click File/Special/Import-Paste-Buffer.

    * Items go into paste-buffer whenever you copy or cut objects.
      Ex. - Select a set of objects by dragging your mouse around them, or
       holding shift and clicking on a series of individual objects.
      You will see the selected objects have tick-marks.
      Clicking  Edit/Copy  or  Edit/Cut  (under the Edit menu),
          or typing control-C or control-X, gets items into paste buffer.

Method 2:  (quicker)
 In first GUI:
    1. Select items with mouse.
    2. Type control-E.  (Selects items into paste-buffer and exports in one step!)
 In the second GUI, or at later time:
    3. Type control-I.  Or do (3) above.

Remember:
  Ctrl-E = Export selected items.
  Ctrl-I = Import items.



21. Automatic Placement

For diagrams missing geometry or box-placement information, such as when network topologies are imported from network discovery tools, UML tools, or external data sources. Adding -autoplace on the GUI command-line causes GUI to calculate reasonable positions for all boxes, based on connectivity. It minimizes long connections, overlaps, or cross-connections. The diagram(s) can then be further edited as desired. See also: Auto-Placement Animations.



22. Highlighting Connections & Connected Boxes

By default, the GUI will automatically highlight all links connected to a selected box in a deep violet color. It will also highlight all directly connected boxes in a light green color. This helps rapidly find all boxes connected to a given box, especially in complex diagrams. The selected box is highlighted brighter green with gray tick-marks, to distinguish it from the other boxes.

Connection highlighting occurs only when exactly one box is selected. When lighter background colors are used, the connection-highlighting colors may be different than mentioned above, to optimize contrast.

Connection-highlighting may be toggled On/Off during a session under the View menu. It can be set for all sessions in the GUI Set-up File.




22. GUI Set-Ups:

You may provide settings that override the defaults when starting the GUI. For example, you may wish to use a specific window size and grid size. Rather than setting these from within the GUI every time you invoke GUI, you can set these parameters in your gui-setup file. Your setup file can be placed anywhere. Set the GUI_SETUP_FILE environment variable to point to your setup file. The GUI will reference whatever the environment variable points to. All settings can be changed as needed within the GUI. This discussion regards the initial settings only. Your initial default gui_setups file is located in the csim/tools/machine_type directory that you are running the csim exacutables from. You can edit it directly if you have permissions, or you may create a modified copy and point your gui-setup environment variable to your copy.

An example setup file is shown below:


	window_size_x   = 1125
	window_size_y   = 900
	print_command   = lpr -h -Plw3
	grid_size       0.2
	snap_to_grid    yes
	show_grid       yes
	show_node_names  on
	show_node_types  on
	show_node_attr   off
	show_port_names  on
	show_link_attr   off
	background_color = black
	box_display_style = solid-box
	connection_highlighting = on
	csim_tool 	= $CSIM_ROOT/tools/csim
	scheduler_tool 	= $CSIM_ROOT/tools/scheduler
	router_tool	= $CSIM_ROOT/tools/router
	timeline_tool	= $CSIM_ROOT/tools/timeline
	xgraph_tool	= $CSIM_ROOT/tools/xgraph
	text_editor	= xterm -e vi
	journal_period  = 15
	nonsticky

To make the GUI reference your setup file, set the gui-setup environment variable as follows:
 In BASH:
	export GUI_SETUP_FILE="your_setup_file"
 In Microsoft:
	set GUI_SETUP_FILE="your_setup_file"
   Or,
	1. From the Desktop, right-click My Computer and click Properties.
	2. Click Advanced System Settings link in the left column.
	3. In the System Properties window click the Environment Variables button.
The syntax of the setup file is:
	parameter   =   setting
There must be no more than one parameter setting to a line. Blank lines are allowed. All keywords are case-insensitive. (Any combination of caps and smalls is allowed.) The equals sign (=) is optional. The parameters can be any of the following:
  • window_size_x - Sets the horizontal width of the GUI window on startup. Units are integer pixels.
  • window_size_y - Sets the vertical height of the GUI window on startup. Units are integer pixels.
  • print_command - Sets default printer for hardcopy, and any print options. Arbitrary character string.
  • snap_to_grid - Sets the snap mode. Values are boolean on-off.
  • grid_size - Sets the grid size for snapping. Units are floating-point page inches.
  • show_grid - Sets the view mode to display the grid in the background, or not. Boolean on-off.
  • show_node_names - Sets the view mode to display node instance names in boxes. Boolean on-off.
  • show_node_types - Sets the initial view mode to display node type names in boxes. Boolean on-off.
  • show_node_attr - Sets the initial view mode to display node attributes in boxes. Boolean on-off.
  • show_port_names - Sets the initial view mode to display port names on links. Boolean on-off.
  • show_link_attr - Sets the initial view mode to display link/arc attributes. Boolean on-off.
  • connection_highlighting - Sets highlighting of a selected box's links and connected boxes. Boolean on-off.
  • highlight_color_primary_box - Sets the highlight color of the box that is selected. Accepts a numeric color value.
  • highlight_color_connected_box - Sets the highlight color of the boxes that are connected to the selected box. Accepts a numeric color value.
  • highlight_color_input_connections - Sets the highlight color of the input-links (simplex-only) to the selected box. Accepts a numeric color value.
  • highlight_color_output_connections - Sets the highlight color of the output-links (simplex-only) to the selected box. Accepts a numeric color value.
  • highlight_color_bidir_connections - Sets the highlight color of the bi-directional (half and full -duplex) links connected to the selected box. Accepts a numeric color value.
  • background_color - Sets the default background color. Valid values are: black, dark-gray, medium gray, light-gray, white.
  • box_display_style - Sets the default box display style. Valid values are: plain-skeleton, solid-box, 3D- border, 3D-solid, 3D-shadow.
  • double_click_interval - Sets the maximum time between mouse-clicks to be considered as a double-click. Specified in milli-Seconds (mSec). By default, it is set to 300-mSec (~1/3-Second). If you are having trouble double-clicking, set this value larger. Ex. 500 = one-half second. If you work so rapidly that your individual single-clicks sometimes are mistaken as double-clicks, then set this value smaller. The optimal value may depend slightly on your computer and, if you are running remotely, the speed of your network.
  • csim_tool - Sets the location of the CSIM Preprocessor tool invoked by Build HW Sim under the Mode menu.
  • scheduler_tool - Sets the location of the Scheduler tool invoked by Build SW under the Mode menu.
  • router_tool - Sets the location of the Router tool invoked by Build Routing Table under the Mode menu.
  • timeline_tool - Sets the location of the TimeLine Analysis tool invoked by Post Analyze EventHistory under the Mode menu.
  • xgraph_tool - Sets the location of the XGRAPH tool invoked by any of the plotting functions under the Mode menu.
  • text_editor - Sets the text-editor to invoke when opening a leaf-box.
                               For example:
                                            text_editor = xterm -e   emacs
  • journal_period - Sets the period journal save period, in minutes. Accepts integer value of minutes.
  • lock_files - Controls file-locking. Default is on. Prevents multiple simultaneous edits on the same file. Good for group projects. Turn off by setting to off, false, no, or 0.
  • nonsticky - Sets GUI into non-sticky draw-mode. This feature is optional. Without it, the GUI assumes the normal default behavior or sticky. See Sticky vs. Non-Sticky Draw-Mode for more information.
The boolean settings can be either of the following:
  • On, Yes, True, 1 (- are equivalent and any can be used to activate an option.)
Or:
  • Off, No, False, 0 (- are equivalent and any can be used to deactivate an option.)
Your setup file does not need to contain all the parameters. You can change a subset of the parameters. The other parameters will take their normal defaults.

The standard default values are as follows:


	window_size_x   = 1025
	window_size_y   = 800
	print_command   = lpr
	grid_size       = 0.1
	snap_to_grid      yes
	show_grid         no
	show_node_names   on
	show_node_types   on
	show_node_attr    off
	show_port_names   on
	show_link_attr    off
	connection_highlighting = on
	background_color = black
	box_display_style = solid-box
	double_click_interval = 250
	csim_tool 	= $CSIM_ROOT/tools/csim
	scheduler_tool 	= $CSIM_ROOT/tools/scheduler
	router_tool	= $CSIM_ROOT/tools/router
	simulation_tool = sim.exe
	timeline_tool	= $CSIM_ROOT/tools/timeline
	xgraph_tool	= $CSIM_ROOT/tools/xgraph
	text_editor	= xterm -e vi
	journal_period  = 5

You can also make settings on a file specific basis by setting options within individual .sim or .dfg diagram files. See: Setting options in diagram files, for further information.

You can also add your own commands to the GUI's Tools menu.   See: Extending Tool Menu Options for further information.


23. Special Functions

Under the Edit Menu is a submenu of Special Functions. These are rarely used, but sometimes helpful functions especially for expert or knowledgeable users.
  • Convert Leaf to Module - This function converts the selected leaf box to a Module type. Use this function when you wish place a sub-diagram beneath a previously created box. This converts a simple thin-lined box to a thick-lined super-module type box. You can then give the module a new type-name and enter inside it. (Note that this function is not necessary for changing a box to an existing module/diagram type. Simply edit the box's properties to set it's type to that of the existing diagram. The leaf-box instantly becomes a module of that type.)
  • Rotate 90 degrees - Rotates the selected objects 90-degrees on your diagram. Most useful for rotating groups of objects.
  • Flip Left-Right - Flips the selected objects left-to-right. Most useful for flipping the positions of groups of objects.
  • Flip Up-Down - Flips the selected objects top-to-bottom. Most useful for flipping the positions of groups of objects.
  • Align Objects - Aligns the Top, Bottom, Left, or Right sides of a group of objects.
  • Show Graph Parameters - Places the current graph's attributes (macros/variables) onto the diagram as text-notes. Useful for self-documentation.
  • Edit Include Files - Opens the Include File Editor. Enables you to change the order of included Imported-By-Reference files, by elevating/raising or lowering their order in the include stack. Also allows you to add or remove included files.
  • Make This The Top Graph - By default, there is exactly ONE Top-Level or Root graph during an editing session or for a simulation. Sometimes it is useful to reassign which is the top-level diagram. This occurs sometimes when several graphs are edited separately and later combined. Also, when presented with no graphs designated top-level, the GUI may arbitrarily designate one. You can force any graph to be the top-diagram by navigating to it (perhaps under the Open/Switch-To-Graph menu), and setting it as Top-Graph with this option. This option changes the status of the currently displayed graph. Any previous Top-Graph is automatically demoted to a Child graph.
  • Make This A Child Graph - When editing graph files separately for later inclusion with other graphs, it is sometimes useful to change a graph's designation from Top-Diagram to Child-Diagram. Use this option by going to the present Top-Level diagram and selecting this option. This option changes the status of the currently displayed graph.
The following future features are not presently active.
  • Group -
  • Un-Group -
  • Send-To-Back -

24. Additional Information

  • Alternative Text Editors:
    • GEdit. Simple, modern, easier than Vi or Emacs.
    • Edt. Simple, modern, easier to learn than Vi or Emacs. More features than GEdit, such as jump-by-word/page, kill-line/word, mouse copying without loosing insertion point, automatic screen centering, multiple buffers, include files, etc..

	


(Questions, Comments, & Suggestions: admin@csim.com)