VHDL GUI Document

VHDL GUI

(VGUI - Graphical User Interface for Hardware Models)
Version 1.06a - December 3, 1999

The VHDL GUI provides a graphical interface for creating, editing, and viewing models of hardware architectures and structures. It can be used to generate structural VHDL or Verilog code.

Contents

  1. Invocation
  2. Hardware Architecture Entry
  3. Editing Object Properties
  4. Writing VHDL or Verilog
  5. View Modes
  6. Bounding Box
  7. Renaming Diagrams
  8. Dimensional Drawing Units
  9. Generic Definition
  10. Pre-Defining Leaf-Level Devices
  11. Automatic Backup
  12. Automatic Journaling
  13. Status Information
  14. Making External Ports Unique
  15. Changing Box Display Styles
  16. Changing Background Colors
  17. VGUI Set-Ups
  18. Updating VGUI, Obtaining the Latest Version

Invocation:

The VGUI can be invoked either from the command-line of a text window, or by clicking on the VGUI icon.

When invoking VGUI from a command-line, the VGUI can accept a diagram file to be edited (or viewed) as a command-line argument. If no arguments are specified, it will assume you are going to open an existing file using the File menu or to create a new diagram which you would save to a file name of your choice by the save_as function. 

     Example:
                vgui   alu.dia
The VGUI source file must be a .dia file that was produced by the VGUI. VHDL does not contain the geometric data needed for representing diagrams, so the VGUI cannot read VHDL. By default, the VGUI saves diagrams in a structural diagram language. This is necessary to preserve the geometric information of diagrams. The VGUI produces VHDL through the File/Export-VHDL menu.

If invoking VGUI by clicking on the VGUI icon under Microsoft Windows, an intermediate dialogue box will first pop up asking for a file name to edit, or whether to start a new drawing. Upon dismissing the opening dialogue, the VHDL will come up. In any case, you can always open a file by clicking File > Open > New File.

During editing, VGUI writes useful information to its status window. Under Microsoft Windows, the status window is a separate text-window that pops-up when VGUI is started. Under Unix/Linux, the shell-window from which VGUI was started serves as the status window. In either case, we recommend placing the status window underneath the main VGUI window, so as to be only partially obscured. This way, you will see any important information displayed in the text window. It is especially helpful for new users.

Hardware Architecture Entry:

To create a new hardware architecture file, invoke VGUI as above. Then enter your hardware architecture and save it to a file name. Future edits to your architecture file can be made by starting the VGUI with the architecture file name as the command-line argument to the VGUI. On entering the VGUI you will notice a Mode Palette on the left control panel. It contains buttons for adding device nodes, modules, links, and annotations. To add a leaf-device node, select the Add Node button on the 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.

Nodes represent the building-block devices of your architecture, such as processor elements, IC-chips, and memories. A module is a super-node that represents a hierarchical grouping of sub-nodes. Links are the wires that connect nodes and modules to each other,

Notice that after adding an object, the VGUI 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, VGUI must first be placed in the Select/Move mode by clicking on the Select/Move button of the 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 Mode Palette. You will see a properties dialogue box appear. It contains fields for the relevant attributes of a node, such as the node name or instance-name, and the node type or type-name. Filling in the fields and clicking OK will set the node's attributes.


Figure 1 - Example Screen Shot: Basic hardware entry/editing

You can add links to connect the nodes by selecting the Add Link button on the left Mode Palette. To add a link, click and release at the spot where you want the link to attach from the source node. Then move the mouse to the destination node of the link and double-click. You will see the arc formed between the nodes. Again, notice that the VGUI remains in the Add Link mode, so 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 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.

After adding a new link, you will want to set its parameters, such as the link's data-type, direction, 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 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 Mode Palette. You will see a dialogue 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. The ports on either end are of type: INOUT. This is typical for bus type connections. Common-bus signals should be set to half-duplex.

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. Full-duplex links are converted into pairs of simplex links in the generated VHDL or Verilog code.

In summary, 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 dialogue. The properties will be saved to whichever object is selected when the propery dialogue 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.

Writing VHDL or Verilog:

To save a diagram as VHDL or Verilog, select Export VHDL or Export Verilog under the FILE menu. This will produce a file of the same root name as the one you are editing, but with the .vhdl or .vlg suffix respectively. The command-line window also reports the name of the saved file.

The saved VHDL or Verilog file will contain all the structural information contained in all the diagrams that are currently in the VGUI. That is, the full hierarchy of a hierarchical architecture will be saved in the VHDL or Verilog file. There is no need to traverse to a given diagram through the hierarchy prior to a save.

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. 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: Note that the VHDL signal-names are only valid after VHDL code has been generated from a diagram. A signal-name is a concept specific to VHDL. It does not exist as part of a basic diagram. The signal-names are assigned by the VHDL-export process. They are then available for display for cross-referencing purposes.

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.

Bounding Box:

A bounding-box, like an annotation, is merely a diagrammatic aid. It does not enter into the models, nor alter the generated VHDL-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.

Renaming Diagrams:

You can re-name a diagram that you are viewing by selecting Edit / Rename Diagram, (under the Edit menu). A dialogue-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-device 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: The VGUI version for Microsoft-Windows/NT is currently somewhat feature-deficient. It does not have the ability to rename diagrams as the Unix/Linux versions do. An alternate method is to edit the diagram-file (.dia) directly with a text editor (outside of VGUI), by searching for the diagram-name you wish to change.

Note 3: If you rename the top_level diagram, then when you later re-open the file, VGUI will not know which module to show first, so it will 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.

Dimensional Drawing Units:

Locations on the drawing area, or canvas, are recorded as floating-point values. Because the VGUI 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 VGUI 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 VGUI.

Generic Definition:

A generic definition allows you to specify parameters associated with your entities. A generic is a VHDL construct that acts as a parameter specific to each node instance. It provides a way to parameterize nodes.

To define a generic for a module that you are editing, select Define Generic under the Edit menu. A dialogue window will pop-up that prompts you to fill in the fields of a generic definition.

A generic definition consists of a parameter-name that you wish to define, its data-type, and an optional default value.

For example: (Defining a generic and its default.) 

                        Ram_Size : integer := 1024
                        ALU_width : integer := 8
To set the generic value of a node instance, select a node-instance in a diagram and open its properties. You can enter a new value for the generic by naming the generic and assigning its value.

For example: (Setting a generic instance.) 

			Ram_size := 512

Pre-Defining Leaf-Level Devices:

Leaf-level devices need-not be pre-defined. However, if a leaf-type is not defined, then the VGUI will be unable to suggest port-names when making connections to devices of that leaf-type. Module-types are defined by the module's drawing, so the external ports become known from outside a module.

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

	DEFINE_DEVICE_TYPE:   u74030
	  PORT_LIST( a1, b2 );
	END_DEFINE_DEVICE_TYPE.
This example defined two ports for a device-type called, u74030. You must place the definitions in a ".dia" diagram file. It can either be your main diagram file, or one that you link to via import.

Automatic Backup:

The VGUI 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 .dia file name.

Automatic Journaling:

The VGUI 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 VGUI.

The journaling feature is automatic on all Unix versions of the VGUI. 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.

Status Information:

VGUI continuously displays status information in two forms:
  1. In the status display of the upper right corner of the VGUI window,
  2. In the text-window from which VGUI 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 VGUI 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 VGUI.

Making External Ports Unique

External-ports on a diagram connect wires, through levels of the module hierarchy, to the wires 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 VGUI. However, this results in many external ports having identical port-names. A convenient method for making the port-names unambiquous is to select the Options / Make Ext. Ports Unique feature. When you do, VGUI will examine all the external ports on the current diagram. If any are identical, it will add a 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.

This feature is available on all Unix and Linux versions of VGUI.
The feature is not yet available on the Microsoft-Windows/NT version of VGUI.

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.

VGUI 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 VGUI. It does not affect how your diagrams will print, nor the saved files.

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

This feature is available on all Unix and Linux versions of VGUI.
The feature is not yet available on the Microsoft-Windows/NT version of VGUI.

Changing Background Colors

Various users prefer different background colors. Some people 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 VGUI to a style that you are most comfortable with, VGUI 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 VGUI to always start-up with your favorite background by editing the VGUI-set-up file. See VGUI Set-Ups.

This feature is available on all Unix and Linux versions of VGUI.
The feature is not yet available on the Microsoft-Windows/NT version of VGUI.

VGUI Set-Ups:

Users may provide settings that override the defaults when starting the VGUI. For example, you may wish to use a specific window size and grid size. Rather than setting these from within the VGUI every time you invoke VGUI, you can set these parameters in a gui-setup file. Your setup file can be placed anywhere. Set the GUI_SETUP_FILE environment variable to point to your setup file. The VGUI will reference whatever the environment variable points to. All settings can be changed as needed within the VGUI. This discussion regards the initial settings only.

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
	journal_period   = 15
	box_display_style = solid-box
To make the VGUI reference your setup file, set the gui-setup environment variable as follows: 

          setenv  GUI_SETUP_FILE   your_setup_file_pwd

The syntax of the setup file is: 

         parameter   =   setting
There must be onle one parameter setting to a line. Blank lines are allowed. All parameters and settings 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 boolean settings can be any of the following: Or: 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
	background_color = black
	box_display_style = solid-box
	journal_period  = 5
	sim_tool 	= /compiler

Updating VGUI, Obtaining the Latest Version:

VGUI is continually being updated, improved, enhanced, and extended. You can obtain the latest version of VGUI and documentation from:

http://www.atl.lmco.com/rassp/vgui

(Questions, Comments, & Suggestions: chein@atl.lmco.com)