Introduction
HDL libraries are a very powerful feature of the HDL languages. Sigasi Studio makes it easy to configure and use them. In this chapter, we assume that the basic concepts of HDL libraries are understood. We will explain how they are implemented in Sigasi Studio.
Like with any HDL tool, Sigasi Studio 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 libraries with Sigasi Studio to organize your projects.
Examining the Library Configuration
You can examine the library configuration in the Sigasi Projects view. The Sigasi Projects view shows how VHDL or SystemVerilog files are mapped.
In the Sigasi Projects view each physical file or folder is annotated with the library it belongs to, between square brackets.
In the image above, we 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, we 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
The library mapping for project files can be modified in the Sigasi Projects view.
Select a file or a folder in the Sigasi Projects view and right-click.
Once you select Set Library
in the menu, you will get the library configuration options as in the image below.
- Select Exclude from Build to exclude the file or folder from any library
- Select New Library… to define a new library and map the file or folder to it
- If one or more folders are selected, the folder name is automatically suggested as a library - in this case, the
includes
folder - Select the name of an existing library to map the file or folder to that library
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 previous library mapping configurations applied to files or folders in this folder are 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, 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.
To exclude a file from all libraries, you can select Exclude from build
option.
You can exclude any file or folder in the project. Sigasi Studio 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
HDL files or folders lying around that you simply want to be ignored.
(System)Verilog Include Files
(System)Verilog 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 the .library_mapping.xml
should be checked into your version control system.
Sigasi Studio only writes changes to this configuration file when you make changes to the library configuration. When you do make changes, Sigasi Studio 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: either 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 and apply a different library mapping.
In most cases, however, the default configuration is just what you need.
How to add files to Common Libraries?
In any newly created VHDL project, the Common Libraries
folder
contains the VHDL files of the IEEE
and STD
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
.
How is Common Libraries different from another folder?
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. Sigasi Studio will not mark errors or warnings in these files. - Next to 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
, andmodelsim_lib
. - While you work on your project, you don’t want to edit the files in the
Common Libraries
, but you need them to compile your project.
Using Common Libraries
is recommended for files that are supposed to be error free.
This increases Sigasi Studio’s performance by preventing it from analyzing files that don’t need to be analyzed.
Using Third-party Libraries
Many projects use third-party libraries. These can be added to the project as any other set of files.
A number of popular third-party libraries are the following:
Vendor | Library | Install dir example |
---|---|---|
AMD/Xilinx | unisim | C:\Xilinx\Vivado\2020.1\data\vhdl\src\unisims |
AMD/Xilinx | unimacro | C:\Xilinx\Vivado\2020.1\data\vhdl\src\unimacro |
AMD/Xilinx | XilinxCoreLib | C:\Xilinx\14.4\ISE_DS\ISE\vhdl\src\XilinxCoreLib |
AMD/Xilinx | xpm | C:\Xilinx\Vivado\2020.1\data\ip\xpm |
Intel | altera_mf | C:\Intel\17.0\quartus\libraries\vhdl |
Mentor | modelsim_lib | ${ModelSimPath}\vhdl_src\modelsim_lib |
Aldec | aldec | C:\Aldec\Riviera-PRO-2015.02\vlib\aldec\ |
On Linux the default installation location for AMD/Xilinx software is /opt/Xilinx
.