CSIM GUI
(Graphical User Interface for Hardware and Software Models)
11-19-2008
(Graphical User Interface for Hardware and Software Models)
11-19-2008
The CSIM GUI provides a graphical interface for creating, editing, and viewing models of hardware architectures and software data flow graph structure.
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.
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.
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.
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.
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.
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..
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.
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.
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.
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.
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.
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.
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.
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 = 15This sets the period save interval to 15 minutes. See GUI_SETUP_FILE.
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.
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.
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.
To replace a given box by an icon:
Presently, the image-icon-file must be an image in PPM format. 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.
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.
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:
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:
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.)
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.
If you select Attributes, you will see the attributes dialog as shown in figure 7.
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.
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..
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.
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.
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 nonstickyTo make the GUI reference your setup file, set the gui-setup environment variable as follows:
setenv GUI_SETUP_FILE your_setup_fileThe syntax of the setup file is:
parameter = settingThere must be 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:
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.
(Questions, Comments, & Suggestions: chein@atl.lmco.com)