VHDL Packages, numeric_std, and Project Structure

Small examples fit in one file. Real FPGA projects need shared constants, reusable types, clean folders, and repeatable build order. VHDL packages help with that.

Learning Objectives

By the end of this lesson, you should be able to:

• use numeric_std for arithmetic;
• place constants and types in a package;
• understand compile order;
• organize RTL and testbench files clearly.

Why numeric_std

Use:

use ieee.numeric_std.all;

Then represent arithmetic values as unsigned or signed, not plain std_logic_vector.

signal addr : unsigned(7 downto 0);
addr <= addr + 1;

This is clearer than relying on nonstandard packages.

Simple Package

library ieee;
use ieee.std_logic_1164.all;
use ieee.numeric_std.all;

package uart_pkg is
    constant DATA_BITS : natural := 8;

    type uart_state_t is (
        IDLE,
        START_BIT,
        DATA_BITS_STATE,
        STOP_BIT
    );
end package;

Use it in RTL:

library ieee;
use ieee.std_logic_1164.all;
use ieee.numeric_std.all;
use work.uart_pkg.all;

Suggested Project Layout

fpga-project/
  rtl/
    uart_pkg.vhd
    uart_tx.vhd
    uart_rx.vhd
    top.vhd
  tb/
    uart_tx_tb.vhd
  constraints/
    board.pcf
  sim/
    waves.gtkw

Keep testbench files out of synthesis file lists.

Compile Order

VHDL tools need packages analyzed before files that use them.

ghdl -a rtl/uart_pkg.vhd
ghdl -a rtl/uart_tx.vhd
ghdl -a tb/uart_tx_tb.vhd
ghdl -e uart_tx_tb
ghdl -r uart_tx_tb

For larger projects, use a build script or file list so the order is repeatable.

Exercise

Create a package counter_pkg with:

• constant COUNT_WIDTH : natural := 8;
• subtype count_t as unsigned(COUNT_WIDTH - 1 downto 0).

Then modify an 8-bit counter to use count_t.

Common Mistakes

• Using nonstandard arithmetic packages.
• Putting board-specific constants inside reusable RTL.
• Letting compile order depend on manual memory.
• Mixing RTL, testbench, constraints, and generated files in one folder.
• Creating huge packages that become dumping grounds.

Summary

Packages make VHDL projects more maintainable. Use numeric_std, keep shared types/constants explicit, and build projects in a repeatable order.

Next: Simulation and Testbenches.

Further Reading

• GHDL invoking guide
• VHDL package references
• Vendor VHDL project templates

Mind Map