Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 37 ยท Entities and Architectures

Entity Declarations and Ports

Learn the VHDL entity declaration: port names, modes in, out, inout and buffer, vector ports, reading output ports, default values and port-naming habits.

The entity is the contract of a design: it says what the outside world sees. Think of the pins on a chip package. Names, directions and types of those pins are all listed in the entity, while the circuitry inside lives in an architecture. Writing clean entities makes every later step, from testbenches to integration, easier.

Syntax

VHDL
entity <name> is
  [ generic ( <generic list> ); ]
  [ port    ( <port list> ); ]
end [entity] [<name>];

Both generic and port clauses are optional. A testbench entity has neither. Port lists look like this:

VHDL
entity counter is
  port (
    clk    : in  std_logic;
    reset  : in  std_logic;
    enable : in  std_logic;
    count  : out std_logic_vector(7 downto 0)
  );
end entity counter;

Each line is name : mode type. Ports with the same mode and type can share a line (a, b : in std_logic), though one per line is easier to read and to diff in version control. The last port has no semicolon before the closing parenthesis; the semicolon comes after the ).

Port modes

Mode Meaning Can the architecture read it? Can it drive it?
in Input pin Yes No
out Output pin Yes in VHDL-2008, no before Yes
inout Bidirectional pin (tri-state buses) Yes Yes
buffer Output that is also read internally Yes Yes (one driver)

The classic stumbling block is reading an out port. In VHDL-93 and earlier, the compiler rejects q <= q + 1; if q is out, because out ports were write-only. There were two workarounds: declare it buffer (which spreads, because every connected component then needs a buffer too) or keep an internal signal and copy it to the output. VHDL-2008 simply lets you read out ports, so with --std=08 the problem disappears.

The older, portable pattern still seen everywhere:

VHDL
architecture rtl of counter is
  signal count_i : unsigned(7 downto 0) := (others => '0');
begin
  process (clk)
  begin
    if rising_edge(clk) then
      if reset = '1' then
        count_i <= (others => '0');
      elsif enable = '1' then
        count_i <= count_i + 1;
      end if;
    end if;
  end process;
  count <= std_logic_vector(count_i);
end architecture rtl;

The _i suffix ("internal") is a common naming convention for the internal copy of an output.

inout is mostly used at the top level for shared pins, for instance an I2C data line or a memory data bus, where the design sometimes drives the wire and sometimes lets go ('Z', high impedance). Inside a chip, avoid tri-state logic; FPGAs generally support it only at the pins.

Vector ports and ranges

A bus is a vector of bits. The range can be written 7 downto 0 (bit 7 is the most significant and leftmost) or 0 to 7. Hardware designers overwhelmingly use downto for numeric buses so that the index matches the weight of the bit.

VHDL
port (
  data_in  : in  std_logic_vector(15 downto 0);
  addr     : in  std_logic_vector(3 downto 0);
  data_out : out std_logic_vector(15 downto 0)
);

Unconstrained ports (std_logic_vector without a range) are legal and the width is taken from the connection, but entities at the top of an FPGA design are usually fully constrained.

Default values

An in port may have a default value that applies when the port is left unconnected in an instance:

VHDL
port (
  clk    : in std_logic;
  enable : in std_logic := '1'     -- if not connected, assume enabled
);

Unconnected in ports without defaults must be tied to something (or open is only allowed if a default exists). Output ports may be left open.

Entity declarations and statements

An entity may also contain declarations and passive statements (like assertions that check generics) between is ... begin ... end. This is rarely used, but one use is excellent:

VHDL
entity fifo is
  generic ( depth : positive := 16 );
  port ( ... );
begin
  assert depth > 1 report "depth must be at least 2" severity failure;
end entity fifo;

Modeling port directions in C

Ports are about who is allowed to drive a wire. This C stand-in models a "write once" discipline: each net remembers which module drives it, and a second driver is flagged. In VHDL, two drivers on a std_logic signal give 'X' (unknown) in simulation, a typical beginner bug.

C Stand-in (C): one driver per net

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.

Tri-state and 'Z'

A tri-state bus lets several devices share one wire, but only one may drive at a time; the others output 'Z'. This stand-in resolves a bus with three drivers like std_logic does: 'Z' loses to any real value, and two different real values give 'X'.

C Stand-in (C): resolving a shared bus

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.

Do not use inout just to avoid thinking about direction. It makes designs harder to read and verify. Use in and out unless the pin really is bidirectional.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which port mode describes an input pin?

    in ports can be read by the architecture but never driven by it.
  2. 2. In VHDL-93, why does q <= q + 1; fail when q is an out port?

    Before VHDL-2008 an out port was write-only. Use an internal signal or compile with --std=08.
  3. 3. Where does the semicolon go in a port list?

    Semicolons separate ports. The last port has none; a semicolon follows the closing parenthesis.
  4. 4. What does a std_logic net with two conflicting drivers (0 and 1) resolve to?

    The resolution function reports a conflict as 'X' (forcing unknown).

Summary

  • The entity lists ports (and generics); it contains no behavior.
  • Modes: in, out, inout, buffer. VHDL-2008 allows reading out ports.
  • Use downto ranges for numeric buses; give every bus a clear width.
  • Input ports may have defaults; the optional entity statement part can check generics.
  • Two drivers on a std_logic net resolve to 'X'.

Next: The Architecture Body