Introduction

HDL libraries are a very powerful feature of the HDL languages. Sigasi Visual HDL (SVH) makes it easy to configure and use them. We’re assuming that you understand the basic concepts of HDL libraries, and so this section focuses on how they are implemented in SVH.

As with any HDL tool, SVH needs to know where the libraries are located on your file system. Below, we describe how the library configuration can be examined and modified using the GUI.

We’ve also presented a use case about how to set up libraries with SVH to organize your projects.

Examining the Library Configuration

You can examine the library configuration in the Sigasi Projects view, which shows how VHDL or SystemVerilog files are mapped.

Each physical file or folder is annotated with the library it belongs to between square brackets.

In the image above, you can see a mixed-language project called Sigasi-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.

Lower down, you can see other folders, most of which are mapped to the library work. One of the folders (verilog) is mapped to the library verilog.

Modifying the Library Configuration

You can modify library mapping for project files right in the Sigasi Projects view.

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

Once you select Set Library in the menu, you will get the library configuration options, as you can see in the image below.

• Select Exclude from Build to exclude a file or folder from any library
• Select New Library… to define a new library and map a file or folder to it
• If you select one or more folders, SVH automatically suggests the folder name as a library - in this case, the includes folder
• Select the name of an existing library to map a file or folder to that library

When you map a file into a library, only that file is affected. However, if you map a folder into a library, then everything in that folder will be mapped into that library. Any previous library mapping configurations applied to files or folders in the given folder will be overridden. When you are defining the library mapping for a new project, you should map from top to bottom.

So, in the case of our Sigasi-Demo project, if work is not a good default, you would change the top folder’s mapping first and then override the mapping in the sub-folders.

To exclude any file from all libraries, you can select the Exclude from build option. SVH will then assume that the corresponding resource is not part of the project and will not include that resource in a project build. This is typically useful when you have stale copies of HDL files or folders lying around that you simply want to ignore.

SystemVerilog Include Files

SystemVerilog include files are always excluded from the build. Any file that is included in another design file gets excluded from the build, even if it has an extension that would normally identify it as a design file, e.g. .v or .sv. It often doesn’t make sense to compile include files by themselves. Instead, include files are compiled in the context of the file in which they are included.

Configuration File

All library configuration information is stored in the .library_mapping.xml file in the root of your project. If you edit this file, the affected HDL files in your project will be rebuilt automatically. Note that .library_mapping.xml should be checked into your version control system.

SVH only writes changes to this configuration file when you make changes to the library configuration. When you do make changes, SVH first checks that all paths in the library configuration still exist. If a path no longer exists, it will be removed from the configuration file. Note that the library configuration file is case-sensitive, even on Windows.

Common Libraries

Each project has a folder called Common Libraries. This is where reusable libraries go: whether vendor libraries, third-party IP libraries, or your own reusable libraries. By default, the VHDL STD and IEEE libraries are added to this folder. The Common Libraries folder behaves like any other folder. You can delete it, rename it, or apply a different library mapping. In most cases, however, the default configuration is just what you need.

In any newly created Sigasi project, the Common Libraries folder contains the VHDL files of the IEEE and STD libraries.

Manually Adding Files to Common Libraries

To add files, right-click the Common Libraries folder and select the New Linked Folder to create a Linked Folder pointing to the actual folder location that contains the files you wish to add to the Common Libraries.

Need to add third-party libraries? Learn how here.

How Is “Common Libraries” Different From Other Folders?

• Common Libraries by default is a virtual folder. This means that it is not a real folder in the project directory and it can only contain references to folders on your file system.
• Files in Common Libraries are supposed to be error free. SVH will not mark errors or warnings in these files.
• Aside from these, a few other libraries’ errors and warnings are never marked, regardless of their location. These libraries are: std, ieee, altera_mf, altera, XilinxCoreLib, unisim, mentor, lpm, simprim, std_developerskit, unimacro, and modelsim_lib.
• While you work on your project, you don’t want to edit the files in the Common Libraries, but you do need them to compile your project.

Using Common Libraries is recommended for files that are supposed to be error free. This increases SVH’s performance by preventing it from analyzing files that don’t need to be analyzed.

Adding Third-Party Libraries to a Project

Sigasi Visual HDL provides an easy way to add libraries from Quartus or Vivado or standalone libraries (e.g. UVVM or UVM) to your projects. Different versions of these tools and libraries can be configured, allowing you to easily switch between them.

Library Database, Tools and Libraries

The Library Database stores all third-party libraries. Once libraries are extracted into the Database, they can be used in any Sigasi project.

To manage a Library Database, you can open the Tools and Libraries settings page by running the Open Tools and Libraries Settings command or clicking on the corresponding link in the SVH extension settings. On this page, you can see the location of the current Library Database, which libraries are available in this Database, as well as all configured tools and libraries that can be extracted into the Database.

Initially, the Database is empty. Adding a tool will populate the Database with libraries provided by this tool. When a standalone library is added, it will also be copied to the Database. If needed, the tool or library configuration can be changed in the right panel. If you don’t need it anymore, you can remove it from the Library Database as well.

When adding a new tool, you can find a list of detected tool paths in the drop-down menu. Use BROWSE if your tool isn’t there.

It’s good practice to use a tool or library version as its alias; however any identifying string can be used, e.g. latest, stable, etc. The Library Database is self-sufficient, so it’s possible to distribute it between SVH users to ensure everyone uses the same library versions. You can also share it between multiple Sigasi projects.

Note that extracting tool libraries may take a while. During this process, a message is shown in a notification area. If you click on it, a pop-up notification appears, where you can see extraction progress. Pressing the Cancel button will abort the extraction process.

By default, the Library Database will be located inside a workspace storage directory from VS Code. If you are planning to reuse the Library Database, you can choose a different location. When selecting an empty directory, you’ll be given the option to copy an existing Database to this new location. Otherwise, you’ll be able to manually extract added tool libraries or standalone libraries to the new location.

If you have a previously created Library Database, you can select it instead of creating a new one. In this case, if there’s no configuration added for tools and libraries available in the database, a <database> marker will be shown instead of their paths. You can see which libraries are present for a tool by selecting it. You can add more tools or libraries or remove those that are already present in the database as well.

Note: A Library Database can also be created through CLI.

Troubleshooting

The SVH extension should be running in order to to open Tools and Libraries settings page. You can open or create a project to start the extension.

VS Code provides different scopes for settings: User, Workspace, and Folder. Settings in more specific scopes can override settings in more generic scopes. Be careful if you want to specify tools or libraries manually in settings.json—they can override changes made on the Tools and Libraries settings page.

Common Libraries

Once all libraries you need are in the Library Database, right-click your project in Sigasi Projects and click Open Preference View. In the Common Libraries tab, you can select what libraries you want to use in your project (if you don’t need them later on, you can deselect them here as well). After pressing the APPLY button, selected libraries will be linked to your project in the Common Libraries folder (while deselected libraries will be removed). In a “Source” column, you can see which library or tool version is used.

Note: If project configuration for a library is out-of-sync with an intended library layout (e.g., library files mapping was manually changed), this library will be marked as (out-of-sync) and the SYNCHRONIZE button will appear. Pressing this button will fix the configuration of all libraries that are out-of-sync.

Active Tools and Libraries

On the Active Tools and Libraries project preference page you can see which versions of libraries and tools are currently being used by your project. If there are multiple versions of tools or libraries available in the Library Database, you can change the version that should be used by a project.

Migration from Sigasi Visual HDL 2024.1

This functionality to add third-party tools and libraries was first introduced in SVH 2024.1, but underwent a major overhaul in SVH 2024.2, resulting in changes to the format of the Library Database. If you’ve already added tools or libraries in SVH 2024.1 and used them in your projects, after updating to SVH 2024.2 or newer, you’ll see that corresponding library files in Common Libraries folder can not be resolved anymore. In order to update your project setup, you have to:

1. Re-extract libraries on the Tools and Libraries settings page by pressing EXTRACT button for added tools and libraries. If you used automatically detected tools in SVH 2024.1 you’ll have to add them explicitly first. Learn more
2. Ensure project configuration for libraries is up-to-date. Go to the project preferences Common Libraries page, and if there are out-of-sync libraries, press the SYNCHRONIZE button to update the project configuration. Learn more