Sigasi logo

Table Of Contents

Previous topic

Setting up a project

Next topic

User Interface

Support

VHDL Libraries

Introduction

VHDL libraries are a very powerful albeit slightly complex feature of the VHDL language. Sigasi HDT tries to make it easy and straightforward 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 HDT.

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 or a configuration file.

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

VHDL library concepts in Sigasi HDT

Sigasi HDT makes a distinction between 3 types of VHDL libraries.

Project libraries
These are the libraries in which you store your designs. You have full read-write access to these libraries.
External libraries
These are libraries that you need in your design, but that can be treated as read-only.
Built-in libraries
The standard VHDL libraries, std and IEEE, are built-in in Sigasi HDT. This means that they are always available without any additional configuration. This is done for convenience, as any VHDL project will need parts of them.

External libraries usage

When you define a library as external, you indicate that it is read-only. This has a number of advantages. First, you cannot accidentally change files that are not in the current project. Moreover, Sigasi HDT will preprocess the files and cache their contents for quick access. This is especially important for certain third party libraries that contain huge amounts of information.

When an external library is modified by some action outside of the project, the cache becomes out of date. The next time the project is fully compiled, the external library will be recompiled by Sigasi HDT.

Warning

Sigasi HDT currently does not inform you when an external library cache is out of date. To trigger a full recompile of the project, press F6.

Also, a software update may render the cache out of date. To reset the cache, select Window ‣ Preferences ‣ Libraries and press reset cache.

The library configuration GUI

Examining the library configuration

You can examine the library configuation in the Project Explorer view.

First, each physical file or folder is annotated with the VHDL library it belongs to, between square brackets:

../_images/ProjectExplorerLibraryDecorator.png

Second, the Project Explorer contains logical library folders that show the file contents of each library:

../_images/libraries_0.png

The External libraries folder contains both the built-in libraries and the external libraries that you have configured. The Project libraries folder contains the libraries defined in your project, and their contents. This makes it easy to examine the library setup of your project.

Modifying the library configuration

The library mapping for project files can be modified using the Project Explorer GUI.

By right-clicking on a file or folder, you can select the library it belongs to:

../_images/LibraryMappingUI_small.png

You have a number of options:

  • Select None to exclude the file or folder from any library
  • Select an existing library to map the file or folder to it
  • Select New Library to define a new VHDL library and map the file or folder to it

The library configuration file

Examining the library configuration file

To examine the VHDL library configuration, select Project ‣ Properties ‣ Libraries. Per VHDL library, three attributes are listed:

Attribute Meaning
name The name of the library.
location Library location in the form type:/path. type is project for a project library, file for an external library, and resource for a built-in library. path specifies the path of the library’s folder on the file system.
excludes Files and folders that are excluded from the library.

The library location folder is used by Sigasi HDT as the top of a search tree for VHDL files. This means that all subfolders are considered recursively.

Default library configuration

By default, the standard VHDL libraries std and IEEE are configured as built-in resource libraries. Moreover, library work is defined as a project library with the top-level project directory as its location.

Editing the library configuration

The library configuration described in the previous section is fully editable. You can use the add button to add a new library and the remove button to remove an existing library. Furthermore, with the edit button a library’s attributes can be modified as follows:

Attribute Edit interface
name The project or external library name can be defined or changed in text field.
location Press Select external folder for an external library, or Select project folder for a project library. In both cases, a file browser pops up that lets you select the folder path. For a project library, this will be relative to the top project folder.
excludes A file browser pops ups that lets you select files and folders that should be excluded from consideration as VHDL project files.

Library configuration using a quickfix

A convenient way to configure a new library is by using a quickfix. Start by typing the library declaration of the new library in your code. Sigasi HDT will flag an error and propose the quickfix Define undefined library. If you choose the quickfix, the library configuration window will open with the new library ready to be defined further.

Using a subfolder as the location for another library

Recall that a library’s location folder is used as the top of a search tree for VHDL files.

Sometimes you may want to use a subfolder of a library location as the location of another library. Sigasi HDT lets you do this without a problem. Just specify the subfolder as the location for the new library. All files found in the subfolder tree will become part of that library instead of the original one.

Note that the order of the library configurations does not matter. When assigning files to libraries, Sigasi HDT will use the most specific location definition.

Defining multiple locations for a library

Sometimes it may be convenient to have multiple locations to search for library files. In Sigasi HDT, you can add multiple entries for the same library, each with a different location. All locations will be considered when looking for VHDL files.

You can even use mix project and external locations for the same library. However, this is not recommended practice, with the possible exception of the special library work.

Library configuration use cases

Introduction

Libraries are a powerful but somewhat underutilized feature of VHDL. Sigasi HDT makes it easy to set them up and take advantage of them. In this section, we describe a number of use cases for working with libraries in Sigasi HDT.

Using the default configuration

Some projects may only need standard libraries and library work. In that case, no additional library configuration is needed. You can just go ahead with the default configuration.

Using third party libraries

Many projects use third party libraries. These should be defined as external libraries.

A number of popular third party libraries are the following:

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

As an example, we will show how to configure the Xilinx library XilinxCoreLib as an external library. Add the following line to your vhdl file:

Library XilinxCoreLib;

When you save, a quick fix icon errorBulb occurs next to the new line. Select the quickfix Define undefined library. The library configuration window pops up, with the XilinxCoreLib library marked as undefined.

Select the library location and press edit. A library definition window pops up. Select Select external folder to define the library as external. Then browse to \vhdl\src\XilinxCoreLib in the Xilinx installation to define the path of the library’s folder, and click OK. A pathname similar to C:/Xilinx/10.1/ISE/vhdl/src/XilinxCoreLib will appear. Click OK. As the library is external, the specified folder is scanned for all vhdl files. All these files are preprocessed and cached for quick access.

Using libraries to organize internal projects

In many organizations, new projects reuse older ones. Moreover, some projects may be set up as IP projects for which reusability is the primary design goal.

It is good practice to use libraries to organize reusable projects. Libraries improve design clarity and avoid name clashes between design units from different projects.

Only the current project should be defined as a project library. The reusable projects that it refers to should be defined as external libraries. As external libraries are read-only, such a set-up makes the project’s purpose clear and avoids mistakes.

Using libraries to organize design variants

Sometimes it is required to maintain multiple variants of a design unit. For example, an entity definition may need to be slightly different depending on the target technology. Although they are different, you may want to refer to the “same” entity by the same name. Conceptually, such a problem can be solved by defining the same identifier in different namespaces.

VHDL libraries can emulate namespaces. For example, you could define a library MY_PROJ for the common design units of a project. In addition, you could define libraries for technology-dependent design units, for example MY_PROJ_XILINX and MY_PROJ_ALTERA. The set-up gives you the required flexibility and clarifies the purpose of all design units.

Copyright © 2008-2011 Sigasi nv - "Sigasi" is a registered trademark of Sigasi nv