# Entity and architecture

*The interface and the insides*

In VHDL, the entity declares a circuit's external interface (its named input and output ports), and the architecture describes the implementation inside that interface; together they fully specify one design block.

Group: HDL
URL: https://digiwleea.wleeaf.dev/learn/vhdl-entity/

An [HDL](https://digiwleea.wleeaf.dev/learn/vhdl-intro/) describes hardware in text. VHDL splits every design block into two parts you already understand from building custom components in the lab: the **interface** (what pins stick out) and the **implementation** (what is wired inside). VHDL names these the **entity** and the **architecture**.

## The entity: the black box

The **entity** declares the block's boundary: its name and its **ports**, the named connections that cross the boundary. Each port has a direction (`in` or `out`) and a type. This is exactly the pin list of a saved part on your canvas: when you place an `INPUT` labelled `A` or a `PROBE` labelled `F`, you are declaring a port. The entity is the black box; it says nothing about what happens inside.

```vhdl
entity and_gate is
  port (
    A : in std_logic;
    B : in std_logic;
    F : out std_logic
  );
end entity;
```

_The entity for an AND gate: three ports, two inputs A and B, one output F. These map exactly to two INPUT pins and one PROBE pin you would place in the lab._

## The architecture: the insides

The **architecture** fills in the black box. It is always tied to one entity (`architecture rtl of and_gate`) and everything between `begin` and `end architecture` is the actual hardware. Here a single assignment, `F <= A and B`, is the whole circuit: one AND gate driving the output port. The name `rtl` (register-transfer level) is just a conventional label; you could call it anything.

```vhdl
library ieee;
use ieee.std_logic_1164.all;

entity and_gate is
  port (
    A : in std_logic;
    B : in std_logic;
    F : out std_logic
  );
end entity;

architecture rtl of and_gate is
begin
  F <= A and B;
end architecture;
```

_The complete AND gate: entity (interface) plus architecture (the one gate inside). digiwleea generated this exact text from an AND built on the canvas._

The two lines at the very top, `library ieee;` and `use ieee.std_logic_1164.all;`, pull in the standard type used for signals (`std_logic`). Think of them as the import that makes the four-valued `0`/`1`/`Z`/`X` world available; the next lesson, [signals and std_logic](https://digiwleea.wleeaf.dev/learn/vhdl-signals/), is all about that type.

_Circuit diagram: The hardware the architecture describes: an AND gate with inputs A, B and output F. Open it in the lab to toggle the ports the entity declared._

> **WARN:** A common slip is mismatching port directions. A port declared `out` (like `F`) can be driven from inside the architecture but **not read** as an input there; a port declared `in` (like `A`) can be read but not driven. Mixing them up is the textual version of trying to use a PROBE as a source: the synthesis tool rejects it. Match each port's direction to how the hardware actually uses that pin.

> **KEY:** Why this matters: the entity/architecture split is the same hierarchy that lets a CPU be built from parts. Once `and_gate` is described, a larger entity can use it as a component without caring how it works inside, exactly how you place a saved custom part. Interface and implementation, kept separate, is what makes big designs buildable.

**Q (Try it):** You want to describe a two-input OR gate called `or_gate` with inputs `A`, `B` and output `F`. What changes from the AND example: the entity, the architecture, or both?

**A:** Only the architecture's logic changes meaningfully. The **entity** is nearly identical (just rename it `or_gate`): same two `in` ports and one `out` port, because an OR gate has the same interface as an AND gate. Inside the **architecture**, the single line becomes `F <= A or B`. Same black-box shape, different insides, which is the whole point of separating the two.

### FAQ

**Q:** What is the difference between an entity and an architecture in VHDL?

**A:** The entity declares a design block's external interface: its name and its input/output ports. The architecture describes what is inside that interface, the actual logic. One entity can have its implementation given by an architecture, the same way a custom part's pins are separate from its internal circuit.

**Q:** What is a port in VHDL?

**A:** A port is a named connection on the boundary of an entity, with a direction (`in` or `out`) and a type such as `std_logic`. Ports are the textual equivalent of the INPUT and PROBE pins you place on a part in the lab.

**Q:** Can a VHDL entity have more than one architecture?

**A:** Yes. An entity declares the interface once, and you can write several architectures that implement it differently (for example a behavioral description and a structural one). Both must honor the same ports.

**Q:** What does the rtl in 'architecture rtl of ...' mean?

**A:** It is just the architecture's name. `rtl` stands for register-transfer level and is a common convention, but the label has no special meaning; you could name the architecture anything.