Working with VHDL Libraries in OSVVM
Abstract
Small projects may use a single library for all aspects of the project. As projects increase in size separating different chips into separate VHDL libraries can help avoid naming conflicts. Libraries can also be used to separate different aspects of a project, such as separating the design from the testbench.
As a language VHDL makes the usage of libraries easy. Unfortunately, many simulators make the usage of libraries more tedious than necessary. OSVVM on the other hand makes the usage of libraries easy.
This blog takes a look at the purpose of VHDL libraries and goes on to discuss how to use multiple VHDL libraries within OSVVM scripting.
Purpose of VHDL Libraries
VHDL libraries provide a means to logically organize a design and prevent conflicts between the names of primary design units – Entities, Packages, Configurations, and Context Units. To reduce the potential for naming conflicts between design units, it is recommended to use separate libraries for separate chips, projects, or sources of intellectual property.
To reference a library unit (a design unit analyzed into a library), VHDL design units reference the logical library name into which the library unit was analyzed. The name “work” in VHDL is a special logical library name that is a shorthand name for the current working library (the library into which this design unit is being analyzed).
The name “work” is a subtle and powerful capability.
It is recommended that a design unit reference a library unit as being in the logical library name “work” when both the design unit and library unit are analyzed into the same library. As an example, consider a UART core composed of several entities and a package that provides shared constant and subtype declarations. From a modularity perspective, it reasonable to always put the design units associated with a UART core into the same library. Given that the UART design units are in the same library, when a UART design unit references a UART library unit, it is appropriate to use the logical library name “work”. This gives the UART core library independence – meaning that on one project, the UART core can be analyzed into Proj1Lib and on another project the UART core can be analyzed into UartCoreLib – in both of these cases the logical library reference “work” is appropriate.
A design unit should reference a named library (other than “work”) when referencing library units that are in separate libraries. On some designs, this may only happen in the testbench that connects the test sequencer, the verification components, and the DUT.
Some simulator GUI’s suggest creating a physical library named work – this should be rejected as a bad practice as a library named work cannot be referenced from design units that are analyzed into other libraries.
Creating and Activating Libraries
OSVVM simplifies creating and using libraries. A library is created and activated using the library API command:
library osvvm_TbUart
If the library does not exist, library creates it. If the library exists, but is not mapped (within OSVVM), library creates a mapping to the library (between the logical library name and the physical library). Finally, library sets the name as the working library. Any following analyze, simulate, and RunTest commands use this library as the working library.
In the following script, the library name is by the library command as osvvm_TbUart and all the following OSVVM API commands use the library osvvm_TbUart as the working library.
TestSuite Uart library osvvm_TbUart analyze TestCtrl_e.vhd analyze TbUart.vhd TestName TbUart_SendGet1 analyze TestCtrl_SendGet1.vhd simulate TbUart RunTest TbUart_SendGet2.vhd
Creating libraries is essential to OSVVM as each of our testbenches has an entity named TestCtrl. Keeping each testbench in a separate library keeps each of these entities separate, and hence, there are no naming conflicts.
Default Library Directory
By default, the library directory is created in the current simulation directory (location from which build was started). If the build was started in the directory “C:/MyProject/sim” and library osvvm_TbUart was created in RivieraPRO release 2022.10, the following library directory is created: C:/MyProject/sim/VHDL_LIBS/RivieraPRO-2022.10.117.8716/osvvm_tbuart.
Setting the Library Directory with LocalScriptDefaults.tcl
The library directory can be specified by setting the variables in OsvvmLibraries/Scripts/LocalScriptDefaults.tcl. Here are the default settings that resulted in the above directory:
variable VhdlLibraryParentDirectory ""
variable VhdlLibraryDirectory "VHDL_LIBS"
variable VhdlLibrarySubdirectory "${ToolNameVersion}
If you do not have a LocalScriptDefaults.tcl, copy the template from Example_LocalScriptDefaults.tcl.
The directory path is formed by the TCL expression:
[file join $CurrentSimulationDirectory $VhdlLibraryParentDirectory $VhdlLibraryDirectory $VhdlLibrarySubdirectory]
The VhdlLibrarySubdirectory puts the tool name and revision in the library directory path.
If VhdlLibraryParentDirectory is an absolute pathname, then $CurrentSimulationDirectory is ignored. As a result, the following setting moves the base library directory from the current simulation directory to C:/temp
variable VhdlLibraryParentDirectory "C:/temp"
Now the library directory for osvvm_TbUart will be created the directory C:/temp/VHDL_LIBS/RivieraPRO-2022.10.117.8716/osvvm_tbuart.
Setting the Library Directory with SetLibraryDirectory
Settings from LocalScriptDefaults.tcl are set by the StartUp.tcl script. To change VhdlLibraryParentDirectory after StartUp, use the SetLibraryDirectory script API command. The following sets the library directory to C:/sim_temp:
SetLibraryDirectory C:/sim_temp
Note that library path names are relative to the current simulation directory ($::osvvm::CurrentSimulationDirectory).
Using SetLibraryDirectory to set the directory to the current simulation directory:
SetLibraryDirectory .
Sharing a Release Directory with Team Members
An OSVVM release only needs to be analyzed once when it is installed. If it is analyzed into a shared directory, then multiple team members can use the pre-analyzed library.
Unzip the zip release or git clone the release into a release directory such as C:/Shared/Libs/OsvvmLibraries_2023_09. To build the release, run the OSVVM startup scripts (ie: StartUp.tcl per the directions in Scripts_user_guide.pdf), set the library directory, and analyze OsvvmLibraries by doing:
SetLibraryDirectory $::OsvvmLibraries build $::OsvvmLibraries/OsvvmLibraries.pro
Note that above we took advantage of the OsvvmLibraries TCL variable. This is just a shorthand for:
SetLibraryDirectory C:/Libs/OsvvmLibraries_2023_09 build C:/Libs/OsvvmLibraries_2023_09/OsvvmLibraries.pro
The above commands create the library directory
C:/Libs/OsvvmLibraries_2023_09/VHDL_LIBS/RivieraPRO-2022.10.117.8716
Since the simulator name and release is included in the library path by default, if you are using more than one simulator or more than one version of the same simulator, simply repeat the steps for the other simulators or simulator versions. Hence, the naming used by OSVVM keeps libraries from different tools or different versions of the same tool from colliding with each other.
Linking to other Libraries and Library Directories
LinkLibrary and LinkLibraryDirectory are used to associate libraries analyzed separately (by OSVVM or other means) with the current project. To include the OSVVM release compiled in the previous steps with a project that includes your current DUT, you can do the following:
LinkLibraryDirectory $::OsvvmLibraries
OSVVM scripting remembers libraries for the current session. When you start another session, you will need to use LinkLibraryDirectory to make libraries visible to the new session.
Working with Multiple Projects – Putting it all together
OSVVM calls a collection of libraries that have a common purpose a project. Hence, the libraries that are associated with OSVVM are a project.
This example uses three projects:
- One project for OsvvmLibraries,
- One project for the DUT, and
- One project for the testbenches for the DUT.
Create the DUT Project
Many industries require a separation of the design and verification aspects of a project. One aspect of that is to put the DUT into a separate library. On this project, the libraries associated with the DUT are kept in a separate directory, C:/Libs/Project1/DUT. Create the project directory and build the DUT.
SetLibraryDirectory C:/Libs/Project1/DUT build C:/Libs/Project1/DUT/DUT.pro
Create testbench Project
Continuing with the separation of design and verificaiton, the libraries associated with the testbench are kept in the directory C:/Libs/Project1/TbDut. Assuming a fresh start of the simulator, the steps for this project are, link in the projects for OSVVM and DUT, set the testbench library, and build the testbench. These steps are shown below:
LinkLibraryDirectory $::OsvvmLibraries LinkLibraryDirectory C:/Libs/Project1/DUT SetLibraryDirectory C:/Libs/Project1/TbDut build C:/Libs/Project1/TbDut/TbDut.pro
Other Considerations
Add write protection to OsvvmLibraries and DUT to prevent others from overwriting or deleting the libraries.
Removing Libraries
A good thing to do before running regression tests is to delete all libraries and recreate them. This ensures that old design information is not used in the regression simulations. A single library can be deleted with RemoveLibrary, such as shown below.
RemoveLibrary DutLib
An entire library directory can be deleted with RemoveLibraryDirectory. This is most effective when libraries are organized by concern like was done with the previous example.
RemoveLibraryDirectory C:/Libs/Project1/DUT
All libraries that are known to the current simulation session can be deleted using RemoveAllLibraries.
RemoveAllLibraries
If you are using libraries that are shared with others, be sure to set file protections on projects so that a user calling RemoveAllLibraries does not accidentally delete items that are shared with other users – or better, use separate library directories for different aspects of the project and just use RemoveLibraryDirectory.
Wrapping Up
Usage of VHDL libraries is essential to support verification methodologies. OSVVM makes library creation and activation simple. The notion of activation is remembering the VHDL working library so that it does not need to be specified (repetitively) in the analysis (aka compile) and simulation steps.
OSVVM allows you to either use a single working library or use a separate library for different aspects of a project and organize the libraries into separate directories – one directory for each separate concern (such as OSVVM vs DUT vs Testbench).