Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 37 ยท Entities and Architectures

Libraries, Packages and Use Clauses

Learn how VHDL organizes code: the work and ieee libraries, use clauses, std_logic_1164 and numeric_std, and how to write your own package with types, constants and functions.

VHDL code is stored in libraries. A library is a named collection of compiled design units (entities, architectures, packages). Packages group related declarations so they can be shared across files. Understanding both is essential, because nearly every VHDL file starts with library and use lines.

Libraries you always have

  • std contains the language's basics: types such as bit, boolean, integer, time, string, and the textio package for file and console I/O. It is always visible.
  • work is the name of the library where your own design units are compiled. It is the default and also always visible.
  • ieee holds the standard industry packages. You must name it yourself:
VHDL
library ieee;
use ieee.std_logic_1164.all;
use ieee.numeric_std.all;

library ieee; makes the library name available. use ieee.std_logic_1164.all; imports every name from that package so you can write std_logic instead of ieee.std_logic_1164.std_logic. Without the use clause, you would need the long names.

The important IEEE packages

Package Provides
std_logic_1164 std_logic, std_logic_vector, rising_edge, logic operators
numeric_std signed, unsigned, arithmetic and to_integer, to_unsigned, resize
math_real real functions such as sqrt, ceil, log2 (simulation and constants)
numeric_std_unsigned VHDL-2008: arithmetic directly on std_logic_vector
fixed_pkg, float_pkg VHDL-2008: fixed and floating point

Do not use std_logic_arith, std_logic_unsigned or std_logic_signed. They are not IEEE standards (they come from a vendor), they conflict with numeric_std, and old tutorials still mention them. Use numeric_std.

Use clause scope

A use clause applies to the design unit that follows it. In a file with an entity and two architectures, the context clause at the top of the file covers the entity and the architecture that comes immediately after it; to be safe, repeat the context clause before units that need it or put the use inside the architecture's declarative part.

You can import everything (.all) or just one item:

VHDL
use ieee.numeric_std.unsigned;      -- only the unsigned type

In VHDL-2008 you can bundle clauses into a context declaration, so a project can say context work.common_ctx; instead of repeating several lines.

Writing your own package

Packages hold constants, types, subtypes, components and subprograms that several designs share. A package has a declaration (the interface) and an optional body (the implementation of functions).

VHDL
library ieee;
use ieee.std_logic_1164.all;

package bus_pkg is
  constant data_width : positive := 16;
  subtype  word_t     is std_logic_vector(data_width - 1 downto 0);

  type opcode_t is (op_add, op_sub, op_and, op_or);

  function parity (v : std_logic_vector) return std_logic;
end package bus_pkg;

package body bus_pkg is
  function parity (v : std_logic_vector) return std_logic is
    variable p : std_logic := '0';
  begin
    for i in v'range loop
      p := p xor v(i);
    end loop;
    return p;
  end function parity;
end package body bus_pkg;

Another file uses it with library work; use work.bus_pkg.all;. Analyze the package before any file that uses it. If you change a package, every file depending on it must be re-analyzed, which is why build scripts matter.

Packages are the right place for: shared widths and constants, state-machine types used across modules, record types for buses, and small helper functions such as clog2 from Generics and Constants.

The package function in C

Here is the parity function from the package modeled in C, along with the word_t width constant. It computes an even-parity bit by XOR-ing every bit, just like the VHDL loop.

C Stand-in (C): the parity function

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.

Enumeration types from a package

Types such as opcode_t are enumerations: the compiler assigns codes. This stand-in uses a C enum and a table of names to show how an enumerated opcode is selected and how many bits its binary encoding needs (the synthesizer picks the encoding).

C Stand-in (C): opcode enumeration

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.

Visibility rules in short

  • A name declared in a package is visible after a matching use.
  • Two use ... .all clauses that import the same name make it ambiguous: the name becomes hidden and using it is an error. Qualify it with the package name to fix this.
  • Local declarations hide imported ones.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which library is always available without a library clause?

    Both std and work are implicit. The ieee library must be named with a library clause.
  2. 2. Which package should you use for unsigned and signed arithmetic?

    numeric_std is the IEEE standard; the others are non-standard or unrelated.
  3. 3. What does use ieee.std_logic_1164.all; do?

    The use clause imports names so you can write std_logic without prefixes.
  4. 4. What goes in a package body?

    The declaration lists constants, types and subprogram headers; the body supplies the code of those subprograms.

Summary

  • Libraries store compiled units: std and work are implicit, ieee must be declared.
  • use clauses import names; use numeric_std for arithmetic, not the vendor packages.
  • Packages share constants, types and functions; the body implements the functions.
  • Analyze packages before the files that use them.
  • Conflicting imports make a name ambiguous; qualify it to resolve the clash.

Next: std_logic and Other Basic Types