Ask Adam VHDL: Libraries

For many engineers, the first lines they write in a new VHDL file are "LIBRARY ieee;" swiftly followed by the USE clauses. But what exactly is a VHDL library?

In its simplest form, a library is a directory on a server or computer that contains VHDL packages, entities, and architectures, thereby allowing these items to be used across multiple projects. These directories and library names are then mapped into the EDA tools allowing the "LIBRARY <name>" to be determined -- without this mapping, the tools would not be able to find the library and hence the files. (Click here to see a larger version of this image):

A ModelSim screen showing the various library mappings required for a project.

Commonly-used libraries -- such as "IEEE" and "STD" -- are provided with the tool itself, and no mapping is thus required. This may also be true of other libraries, depending upon an EDA tool's functionality (for example, the powerful ModelSim software simulator libraries, which require no additional mapping in ModelSim). These may be supplied pre-compiled in the case of a simulation tool, or as VHDL source code in the case of an FPGA implementation tool like the Synplify synthesis tool from Synopsys or the ISE (Integrated Software Environment) from Xilinx.

If you are designing using Xilinx FPGAs, then libraries that commonly require mapping into simulation tools are the Xilinx "unisim," "unimacro," "xilinxcorelib," and "simprim" libraries as illustrated in the images below. (Click here and here to see larger, more detailed versions of these images.) These libraries are used to simulate Xilinx functional primitives, or implementation timing simulations in the case of the "simprim" library. To successfully use these libraries in a simulation tool, they must not only be mapped in the simulation tool, but also compiled in ISE for your selected simulation tool.

Modelsim screen showing the library mapping context box.

Xilinx ISE library compilation.

Another thing you will come across is the "WORK" library, which is the currently designated working library. It is into this library that compiled results are placed. How the working library is designated varies from tool to tool. In the case of ModelSim, for example, the WORK library may be declared during the setting up of a project; alternately, it can be specified using the "vmap" command ("vmap work <library path>" for example). For this reason, it is a bad idea to create a library called "work," as this can lead to confusion and all sorts of issues later on.

Both the "STD" and "WORK" libraries within VHDL are implicitly declared; hence, you do not need to declare them within a VHDL file.

As an engineer, you will generally wish to partition your design into a number of libraries. For example, if you are designing numerous FPGAs for a project and these devices share common components, then you may decide to declare a common components library and also have a separate library for each of the devices. This allows the commonly used components to be located in a central place should updates to those components be required.

If you wish to use a package within a defined library, you must declare this using the "USE" clause. This allows you to pick and choose the packages within a library you wish to use. Within the "IEEE" library, for example, you will wish to use the "std_logic_1164" and "numeric_std" packages, but you may not wish to use the "math_real" or "math complex" packages. For example, consider the statement "USE std_logic_1164.ALL." In this case, the "ALL" keyword at the end allows visibility of all names within the package. It is possible to limit visibility be declaring specific names in place of the "ALL" keyword. When combined, the "LIBRARY" and "USE" clauses are referred to as "the context clause."

Once you have your library structure all set up, you should hopefully find it easier to reuse your code, if required. However, depending on how complex your structures are, you may need to consider using configurations to correctly manage your current design to ensure you are pulling in the correct entities and architectures. I will address these in a future "Ask Adam" column, as I think we have covered enough here for one blog.

"Ask Adam" posts:

• Ask Adam VHDL: Sensitivity Lists & Simulation
• Ask Adam VHDL: Coding Styles
• Ask Adam VHDL: Registers & Latches
• Ask Adam VHDL: Metastability, Part 1
• Ask Adam VHDL: Metastability, Part 2
• Ask Adam: UART, SPI, I2C & More
• Ask Adam VHDL: Logic Values
• Ask Adam VHDL: Handling the Don't Care Value
• Ask Adam: FPGAs & RS-232
• Ask Adam VHDL: Edge Detection on Signals

Related posts:

• Using an FPGA to Drive a VGA Display
• Using an FPGA to Drive a VGA Test Pattern
• ChipScope In-Chip FPGA Virtual Logic Analyzer
• A More Sophisticated FPGA-Based VGA Display
• Are Your FPGA Designs Secure?
• MTBF & FPGA-Based System-Level Reliability
• FPGA-Based System Reliability: Tips & Tricks
• UKube: Xilinx SRAM-Based FPGAs Are Spacebound
• Space FPGA User Workshop Day 1: European FPGAs
• Space FPGA User Workshop Day 2: Non-European FPGAs
• Adam Powers Up His Zynq ZedBoard, Part 1
• Adam Powers Up His Zynq ZedBoard, Part 2
• Adam Powers Up His Zynq ZedBoard, Part 3