Sigasi VHDL Documentation

Sigasi is distributed online. It is available in two versions: as a stand-alone application or as a plugin inside a standard Eclipse installation. Your license gives you the right to use either version,at any time, at your discretion. Therefore, your first task is to decide which version suits your requirements, based on the description below. Depending on the chosen version, you should then follow the corresponding installation instructions.

To download and install Sigasi HDT as a stand-alone application, follow the online Installation Instructions.

After downloading, choose or create a folder where you want to install the software, and unpack the archive there. The archive contains a single top-level folder called sigasi. Inside the folder there is an application startup file, also called sigasi. Start the application by executing this startup file.

To download and install Sigasi HDT as an Eclipse Plugin, first check which Eclipse version you are using. Then follow either the Installation Instructions for Eclipse 3.6 (Helios) or 3.7 (Indigo) or the Installation Instructions for Eclipse 3.5 (Galileo).

For small projects, all features of Sigasi can be used without a license. You can monitor the relative size of your VHDL projects in the right corner of the status bar:

The relative size is shown as a percentage. For projects larger than 100%, the size indication area turns red and Sigasi 2.0 falls back to a base-line modus (which is still more powerful than any other editor). To enable full Sigasi support for such projects, you need a valid license. The license key can be filled in under Window > Preferences > VHDL > License Key.

Sigasi HDT stores its projects on the file system in one or more workspaces.

When you start the tool for the first time, it will propose to create a workspace for you:

Although you can work with multiple workspaces, we recommend to use a single workspace for all your projects.

Sigasi HDT has an automated update system. When updates are available, you are notified by a pop-up window called Updates Available in the bottom right corner:

If you want to install the updates, click anywhere in the pop-up window. After a few seconds, a new window will appear with further instructions.

The updates can be postponed by closing the pop-up. You can perform the updates at any time by clicking the -icon in the status bar at the bottom of the screen.

Consult the troubleshooting section if the update does not start automatically.

Your work with Sigasi typically is organized as a project. A project is a collection of VHDL files that belong together. Sigasi understands the VHDL units defined in the files, and the relationships between them.

Your first step is to set up a project. There are a number of ways to do this:

Each of these methods is discussed in detail in the following sections.

To create a new project, select File > New > Empty VHDL Project. Then give your project a name.

By default, the Use default location checkbox is checked, which means that new projects will be located in the workspace folder. Alternatively, you can uncheck the checkbox and choose an arbitrary location for your project.

After creating a new project, you can add existing files by dragging them from your filesystem into the project explorer. New files can be added by clicking File > New > VHDL file.

You can import an existing project from the file system by clicking File > Import > General > Existing projects into Workspace, and selecting Select root directory. Browse to the root directory of the project, and press Finish.

By default, you will work on the project files in their original location. If you want to copy the project files in the workspace instead, uncheck Copy projects into workspace before importing.

Sigasi projects can be shared using file archives. All project-related settings are stored in two hidden files in the project folder. Therefore, you can create an archive of the entire top level folder ( File > Export > General > Archive file) and send it to someone else.

You can import a project from an archive by clicking File > Import > General > Existing projects into Workspace, and selecting Select archive file. Browse to your project archive, and press Finish.

Sigasi is built upon the Eclipse platform, which permits to use multiple languages within a single environment. The user interface can be customized for a particular language. In Eclipse terminology, this customized user interface is called a perspective. The logo of the current perspective is higlighted in the upper right corner. The recommended perspective to use with Sigasi is the VHDL perspective, with the following logo:

If you use the standalone version, this is the default perspective. If you use the Eclipse plugin, another perspective may be open instead. You can select the VHDL perspective by clicking the button next the perspective logo. A window pops up in which you can select the perspective:

When you open a project in Sigasi HDT, a number of views are presented in the user interface. Here is a typical screenshot, with the views highlighted:

The functionality of the views is as follows:

Project Explorer view

This view is a hierarchical representation of all files in all projects. You can use it to navigate to a particular file in a particular project and select it.

Editor view

In this view, the contents of the currently selected file are shown. The file contents can be directly edited here.

Problems view

In this view, all problems that were detected in the current project are listed.

Outline view

This view shows the contents of the selected file in terms of VHDL objects. You can use it to review the content, and to navigate to a specific VHDL object.

Hierarchy view (coming soon)

This view shows the VHDL design hierarchy below the selected top level object.

The views provide alternative ways to access the information in a project. They permit efficient navigation, inspection and editing.

The Project Explorer view shows the file contents of the project. When you click on a file, it is opened in the Editor view.

In the Editor view, you can edit the contents of a file. It is a tabbed view so that multiple files can be open for editing simultaneously. The currently selected file is the active file.

The outline view is always synchronized with the active file. It displays the contents of the active file in terms of the VHDL objects that it contains.

The hierarchy view displays the VHDL design hierarchy below the selected top level object. You can select a top level from the available candidates in a pop-up window after clicking Select toplevel.... Alternatively, you can right-click on an architecture in the outline or hierarchy view and click Set as top level.

When you double-click an object in the hierarchy, the Editor view is updated accordingly, possibly by displaying the contents of a different file.

You can further customize the behavior of the Project Explorer view in ways that can be particularly handy for large projects. For example, the Project Explorer view can be linked with the Editor view by clicking the link icon .

Furthermore, you can use filters to define which files are shown. Select the icon View Menu and then Customize view. You can then select a filter whose matching files will be hidden in the view.

Sigasi HDT offers powerful techniques to explore a project and navigate through it.

Hovering To find the declaration of a given identifier, hold your mouse pointer over it. After about a second, a popup shows you the name and datatype of the signal. This technique is called hovering.

Highlighting If you click on an identifier, it is highlighted. In addition, all other occurrences of the identifier that refer to the same object are highlighted. Note that this highlighting is intelligent: it is not based on the identifier’s string value, but on the object that the identifier refers to.

Navigate to a declaration You can easily navigate to the declaration of any port, signal, entity, etc. Place the cursor on the identifier, right-click and select Open Declaration. The editor immediately switches to the line that declares the object. Since this operation is so commonly used, it is assigned to the shortcut key F3.

Finding object occurrences To look for occurrences of a given identifier in different files, place your cursor on the identifier and right-click. Now select Search References. A search window will appear on the bottom of your workbench, displaying all occurrences of the selected identifier. You can easily navigate through all occurrences by clicking the Show Next Match arrow and the Show Previous Match arrow in the search result view. Note that all occurrences are highlighted and marked with a small arrow at the left border of the editor for easy recognition.

VHDL libraries are a very powerful feature of the VHDL language. Sigasi makes it easy to configure and use them. In this chapter, we assume that the basic concepts of VHDL libraries are understood. We will explain how they are implemented in Sigasi.

Like with any VHDL tool, Sigasi HDT needs to know where the libraries are located on the file system. We will describe how the library configuration can be examined and modified using the GUI.

We will also present some use case about how to set up VHDL libraries with Sigasi HDT to organize your projects.

You can examine the library configuration in the Project Explorer view. Each physical file or folder is annotated with the VHDL library it belongs to, between square brackets:

What you see here is the initial library mapping of a demo project (you can create such a project by selecting File > New > Other > Demo Vhdl project). We see a project called Demo, with a folder named Common Libraries. In that folder, you see the typical standard libraries ( std and ieee) upon which all VHDL projects depend. The demo project itself consists of a few VHDL files.

Next to the project’s name, Demo, is the annotation work. This means that, barring any overrides, everything in the project will be stored inside the work library.

Lower down, we see overrides. For example, the STD folder has an annotation std. This means that, again barring any further overrides, the entire contents of the STD folder will be mapped into the library std. There are no limits to the number of overrides that can be performed. If this needed, any individual file can be mapped to a separate library.

The library mapping for project files can be modified in the Project Explorer view.

Select a file or a folder in the Project Explorer and right-click.

You get a Library Mapping context menu, with a a number of options:

When you map a file into a library, only that file is affected. However, when you map a folder into a library, then everything in that folder will be mapped into that library. Any overrides in the folder and its sub-folders will be removed. When you are defining the library mapping for a new project you should map from top to bottom.

So in the case of our Demo project, you would change (if work is not a good default) the top folder’s mapping first and then override the mapping in the sub-folders. Note that when you would change the library mapping of the Demo project, then as consequence, the ieee and std mappings of the IEEE, IEEE Synopsys and the STD folders would also change. Most likely, you want to re-apply the standard mappings to those folders so as to conform with the VHDL standard.

When you are changing the library mapping of a project, the project will be rebuilt completely. In order to avoid several consecutive rebuilds while you are setting up your libraries, you can temporarily disable the automatic rebuilds, until you are finished setting up your library mappings. You can do this by disabling the Project > Build Automatically option.

To exclude a file from all libraries, the library mapping context menu provides an Unmap option. You can apply that to any file or folder in the project. Sigasi will then assume that the corresponding resource is not a part of the project and will not include that resource in a project build. This is typically useful when you have stale copies of VHDL files or folders lying around that you want simply to be ignored.

In any newly created VHDL project, the Common Libraries folder contains the VHDL files of the IEEE and STD libraries. This folder is special in the sense that its contents is not stored in regular files on your hard drive. Instead, the files' contents is shipped as part of the Sigasi installation. Other than that, the Common Libraries folder behaves like any other folder. You can delete it, rename it, and apply a different library mapping. In most cases, however, the default configuration is just what you need.

If you have modified the Common Libraries folder, you can always revert it back to the original state. Right-click on your project in the explorer view and apply menu-entry Restore Common Libraries.

Sigasi allows you to share libraries between multiple projects. The easiest way to do this, is to develop each library in a separate project and configure the Project Dependencies accordingly. To configure the project dependencies, right click the project (the one that uses the shared library) and select Properties. Next click Project References and mark the library project as referenced project.

Video demonstration

Many projects use third party libraries. These can be added to the project as any other set of VHDL files.

A number of popular third party libraries are the following:

Vendor	Library	Install dir example
Xilinx	unisim	C:\Xilinx\13.3\ISE\vhdl\src\unisims 1
Xilinx	XilinxCoreLib	C:\Xilinx\13.3\ISE\vhdl\src\XilinxCoreLib 1
Xilinx	simprim	C:\Xilinx\13.3\ISE\vhdl\src\simprims 1
Altera	altera_mf	C:\altera\11.1\quartus\libraries\vhdl 1

¹ On Linux the default installation location for Xilinx is /opt/Xilinx and /opt/altera for Altera.

As an example, we will show how to configure the XilinxCoreLib, unisim and altera_mf

Block selection is an alternative for standard (paragraph) selection. Block selection mode differs from standard selection mode in that it allows to select rectangular regions, or to set the cursor over multiple lines. Block selection is ideal for selecting vertical regions, for example a column of a table or all port names in a port map.

Block Selection Mode

To toggle between normal and block selection modes use Alt+Shift+A or press the Toggle Block Selection icon in the tool bar.

You can easily move lines up and down by pressing: Alt+Up and Alt+Down.

You can duplicate your current line, or the lines of the current selection by pressing: Ctrl+Alt+Down.

The action to remove trailing whitespace is hidden by default. You can access it by pressing Ctrl+3, type RTW and then select the correct action. Alternatively, you can bind this action to a keyboard shortcut of your preference.

You can format your code by pressing Ctrl+Shift+F, or selecting Format in the context menu of your VHDL editor view. Code formatting performs the following actions:

Stuttering is an editing technique popularized by Emacs, that lets you type certain things really fast. Stuttering means that you tap a certain key twice and it expands to something more complex. For example, press the period key . twice, and the editor will expand it to a right arrow =>. Stuttering works like double clicking: if you type keys slowly, the stuttering mechanism will not be triggered.

The following stuttering keys are available:

Keys	Effect
,,	<=
..	=>
::	:=

Stuttering can be disabled or enabled in Window > Preferences > VHDL > Enable Stuttering.

Sometimes you have to deal with very large VHDL files such as large concatenated library files and generated files. Unfortunately the Sigasi VHDL editor can not cope with huge VHDL files yet. Large files stress the interactive compiler too much to give timely feedback.

To allow you to edit large VHDL files the Sigasi IDE contains a lightweight VHDL editor that can handle all files without problems. This editor does not analyze your files a type time. It only offers syntax highlighting and the default Eclipse editing features. The lightweight VHDL editor will check for errors when you save your file.

The current threshold VHDL file size that is used to switch to the lightweight editor is 1 MB.

If you ever suspect that the state of your project is inconsistent in Sigasi, you can always force a complete clean compilation by selecting Project> Rebuild Project.

If the user interface of Sigasi HDT is unresponsive, you can always interrupt the internal compilation process by pressing the stop button in the progress view. To activate the progress view, select Window > Show View > Other... > General > Progress, or click the tiny conveyor belt icon , on the right side of the status bar.

If you edit a file outside of HDT with an external editor, HDT will normally notice the changes and ask you what to do. If it doesn’t, you can refresh the editor’s content by pressing F5 or by right-clicking a file or a project in the project explorer and selecting :menuselection:`Refresh`.

You can check if you have the latest update by clicking on Help > About Sigasi > Installation details. The version number contains the date of the release. (For example, version 2.0.1.20110809... was released on August 9, 2011.)

Sigasi HDT stores the history of your file so that you can compare your current version with the version you saved an hour ago.

You can define how much disk space is used for storing local history in Windows > Preferences, select General > Workspace > Local History.

For more information on local history, check out this page.

By default, HDT assumes that all VHDL files are part of the project. However, some projects may contain multiple files with older or alternative definitions of a VHDL object. In such a case you will want HDT to ignore certain files.

To exclude files (or directories) from analysis, consult the VHDL library setup section.

Ignored resource are decorated with a icon in the project explorer view.

Sometimes you want extra small fonts, so that you can fit more content on your screen. Another time you may want extra large fonts, so that you can use a beamer and your audience can see what you are doing.

Most fonts, including the font that is used by the editors, can be controlled in the preferences: Window > Preferences. Fonts are controlled in General > Appearance >Colors and Fonts. The font of the editors are in Basic > Text font.

Some fonts cannot be controlled in this preference page. These fonts are defined by general system settings, and are used for writing the menu names, the Project Explorer view and the Outline and Hierarchy views. On Windows, you can change these fonts by changing your font settings in the Windows Control Panel. On Linux, these fonts are controlled by a settings file: ${HOME}/.gtkrc-2.0 . You can change the font by adding a line like:

gtk-font-name = "Sans 10"`

You have to restart Sigasi HDT before these changes take effect.

If the updates are not automatically fetched from the Sigasi update server you are probably behind a firewall or proxy server. You can configure HDT’s proxy settings in Window > Preferences > General > Network connections. If you can not add a firewall exception for our update site, the fall back solution is to download the complete application from our website. You can completely replace your old installation; all settings are stored in your workspace (the default is workspaceSigasi in your home directory).

In this section, we list the most important shortcuts.

Annotations are colors added on top of your text editor, and to the right of your text editor, in the scroll bar. The image below shows annotations for each occurrence of a certain data type. The color has been changed to bright green.

You can change the color of annotations in Window > Preferences > General > Editors > Text Editors > Annotations. For the particular case of occurrence annotations, you want to modify the color for annotation type Occurrences. If more than one Occurrences type is displayed, you need the org.eclipse.xtext.ui.editor.defaultOccurrenceAnnotation. The others may refer to occurrences for Java or other plug-ins.

The Gutter is the small area to the left of the editor view. It is used for displaying extra information about your code.

There is not much to configure about markers, but the other categories can be turned on or off.

To enable line numbers, right-click in the gutter and select Show Line Numbers.