VHDL Simili Documentation:

Introduction:

Basic VHDL concepts:

In this section, we are going to focus on the concepts of libraries and design units as they relate to VHDL. A typical VHDL source file contains zero or more design units. Examples of a design units are entity, architecture, package, etc. When a VHDL source file is compiled, the results of a successful compilation are placed in a library. So, in effect, the design units contained within a VHDL source file are placed in a library.

A design unit that has been compiled into one library can reference other designs units in any other library through the use of use clauses and library statements.

In VHDL, the current working library is always called "work". When using a VHDL compiler or simulator, there is always a concept of a current working library. If no particular  library is specified as the current working library, the current working library is assumed to be "work". You can associate the "work" library with any other library.

There are two kinds of design units. Primary design units and secondary design units. The design units of type entity, package and configuration are primary design units. Design units or type architecture and "package body" are secondary design units. Secondary design units are always associated with a particular primary design unit. Secondary units typically contain the implementation of their primary units. 

Simple rules to remember:

  • All primary units in a given library must have unique names. Note: VHDL language actually allows an entity to have the same name as one of its configurations but VHDL Simili requires that all primary units have unique names in a given library. 
  • All secondary units for a given primary unit must also be named uniquely.
  • A primary design unit and all of its secondary design units must both reside in the same library.

More on libraries: Library names have a logical name and a physical name. In the VHDL source file, all references to library names are logical library names. Each logical library name is associated with some physical library name (a path-name to some physical storage mechanism). This association is made through controlling the environment of the tools via the use of the Symphony.ini file described in the next section.

The STD library: There is also a library with a special name "std". This library and its contents (the packages standard and textio) are built into the tools and cannot be controlled. This also means that you cannot have a user defined library called "std".

VHDL Simili directory structure:

Before we begin introducing the tools and their usage, it may be helpful for you to get familiarized with the directory structure that the tools rely on. You can also learn how your own libraries and design units are maintained by using examples out of the pre-compiled libraries.

First, we begin by describing the VHDL Simili installation directory. The installation directory contains the following subdirectories.

  • Bin -- The Bin directory contains a default Symphony.ini file and the executables (programs).
  • Lib -- The Lib directory contains pre-compiled libraries that are shipped with VHDL Simili. This directory also contains documentation for each vendor library that is currently installed. It is highly recommended that you browse this directory for more information.
  • Doc -- The Doc directory contains HTML documentation for the tools.

The Lib directory contains a set of sub-directories. Each one of these sub-directories contains a library, any documentation related to the library (in HTML form) and in some cases the VHDL source code used to generate the library.

Controlling your environment -- Symphony.ini:

Libraries are about the only thing that cause external dependencies on how a given VHDL source file is interpreted. Different vendors use some of the same common names (such as DFF, AND2, etc.) for the design units within their libraries. If you want VendorA's components, you definitely do not want to unintentionally pick up VendorB's components. You as a user may also have multiple libraries with some design units in those libraries using the same names. Within the VHDL source file, a user typically uses library names to make things more specific.

To avoid any confusion and to allow flexibility, the mapping of libraries occurs through a file named "symphony.ini". All VHDL Simili tools use this file. They all look for this file in the current-working-directory and if they do not find one there, they use the default INI file located in the installation directory's Bin sub-directory. This file can be used to map library logical names to physical library names.

You do not need a custom Symphony.ini file if you meet the following requirements:

  • You are using the pre-compiled libraries shipped with VHDL Simili.
  • Any other libraries that you have created are in the current directory.
  • You have use the default physical-directory naming convention (the physical-directory name is the logical-name with a .sym extension).
  • None of your logical library names are extended VHDL identifiers.

The tools will automatically search for a library by looking first in the current working directory and then in the set of pre-compiled libraries shipped with the tool. Any library mappings that appear in an INI file overrides the default search mechanism. Unless you have special needs you can skip the rest of this section.

You will need the INI file if you have libraries that are not in the current directory or if the base-name of the physical-directory containing the library is not the same as the library name. You may also associate multiple logical library names to the same physical library.

Depending on the vendor you use, the very first thing you will need is your own symphony.ini file (you may use the default one if you use nothing but the IEEE library).

The following are the contents of the default symphony.ini file.

#
# Setup the libraries
# You can use environment variables of the form $var or %var%
# and slashes and back-slashes are treated the same
#
# The SYMPHONY environment variable is automatically
# created to reflect the installation directory.
#
[libraries]
ieee = $SYMPHONY/Lib/Ieee/Ieee.sym

The '#' marks the beginning of a comment and the entire line after the '#' character is treated as a comment. Empty lines are ignored. The keyword "[libraries]" begins the library mapping section. It should be followed by a zero or more lines where each line represents a library mapping. The format of a library mapping file is as follows

logical-library-name = physical-library-directory

The "logical-library-name" is the name that is used to refer to this library in your VHDL source. The physical directory name is the name of the directory where the library resides. Note that typically, the VHDL Simili library directories have a suffix of ".sym". Once such a line is added to the symphony.ini file, the directory mentioned in the mapping is automatically created when needed.

Example#1: If you wanted to add your own library called "mylib" assuming that the library exists one directory above the current directory, then you would add the following line to the symphony.ini file.

mylib = ..\mylib.sym

Since the '/' character is treated the same as the '\' character, the following line would have been the equivalent.

mylib = ../mylib.sym

Example#2: Sometimes, it may become necessary to create a mapping of a library where the name of the logical library is not the same as the name that was used when the library was created (using the default conventions). The following line

mylib = ./somelib.sym

associates the logical-library-name "mylib" with the physical library directory "./somelib.sym".

Note: In the future, additional sections may be added to the symphony.ini file format to allow for tool customization.

Meet the tools:

There are only two tools you have to deal with. The compiler (called vhdlp) and the simulator (called vhdle).

Go to next chapter