Project Structure

Understanding the organization and architecture of the VHDL Digital Design Samples project.

Overview 

The project follows a hierarchical structure designed for educational purposes, separating source code, tests, documentation, and build scripts into logical directories.

Directory Layout 

vhdl-samples/
├── 📁 src/                    # Source code (VHDL designs)
│   ├── 📁 gates/              # Basic logic gates
│   ├── 📁 combinational/      # Combinational circuits
│   │   ├── 📁 adders/         # Addition circuits
│   │   ├── 📁 decoders/       # Decoder circuits
│   │   ├── 📁 multiplexers/   # MUX/DEMUX circuits
│   │   ├── 📁 comparators/    # Comparison circuits
│   │   └── 📁 shifters/       # Bit shifting circuits
│   ├── 📁 sequential/         # Sequential circuits
│   │   ├── 📁 flip_flops/     # Flip-flop implementations
│   │   ├── 📁 latches/        # Latch implementations
│   │   ├── 📁 registers/      # Register implementations
│   │   ├── 📁 counters/       # Counter implementations
│   │   └── 📁 state_machines/ # FSM implementations
│   └── 📁 modules/            # Complex/mixed modules
├── 📁 test/                   # Test files (mirroring src/)
│   ├── 📁 gates/
│   ├── 📁 combinational/
│   └── 📁 sequential/
├── 📁 docs/                   # Documentation (Sphinx)
│   ├── 📁 _static/            # Static assets (CSS, images)
│   ├── 📁 components/         # Component documentation
│   ├── 📁 testing/            # Testing documentation
│   └── 📁 development/        # Development guides
├── 📁 scripts/                # Build and utility scripts
├── 📁 .github/workflows/      # CI/CD workflows
├── 📄 Makefile                # Build system
├── 📄 README.md               # Project overview
└── 📄 LICENSE                 # MIT License

Source Code Organization 

The src/ directory is organized by complexity and circuit type:

Basic Gates (`src/gates/`)

File	Description	Modeling Style
`or_gate.vhd`	4-input OR gate	Behavioral
`xor_3.vhd`	3-input XOR gate	Dataflow
`my_xor.vhd`	2-input XOR (structural)	Structural

Combinational Logic (`src/combinational/`)

Adders (``adders/``):

Component	Description	Key Features
Half Adders	1-bit addition (no carry-in)	Basic building block
Full Adders	1-bit addition (with carry)	Multiple implementations
4-bit Adders	Multi-bit arithmetic	Ripple carry design

Decoders (``decoders/``):

Component	Description	Outputs
`decoder_2x4.vhd`	2-to-4 line decoder	4 outputs
`decoder_3x8_str.vhd`	3-to-8 decoder (structural)	8 outputs

Multiplexers (``multiplexers/``):

Component	Description	Select Lines
`mux_2x1_df.vhd`	2-to-1 MUX (dataflow)	1 bit
`mux_4x1_str.vhd`	4-to-1 MUX (structural)	2 bits
`mux_8x1_str.vhd`	8-to-1 MUX (structural)	3 bits

Sequential Logic (`src/sequential/`)

Flip-Flops (``flip_flops/``):

Component	Description	Features
`d_flip_flop.vhd`	D flip-flop	Edge-triggered
`t_flip_flop.vhd`	T flip-flop	Toggle functionality

Registers (``registers/``):

Component	Description	Width
`register_8_bit.vhd`	8-bit register	8 bits
`pipo_4bit_behave.vhd`	4-bit PIPO register	4 bits

Test Structure 

The test/ directory mirrors the src/ structure:

test/
├── 📁 gates/
│   ├── or_gate_tb.vhd         # Tests all 16 input combinations
│   └── xor_testbench.vhd      # Tests XOR functionality
├── 📁 combinational/
│   ├── 📁 adders/
│   │   ├── fa_testbench.vhd   # Full adder tests
│   │   ├── ha_behave_tb.vhd   # Half adder tests
│   │   └── rc_adder_testbench.vhd  # 4-bit adder tests
│   ├── 📁 decoders/
│   │   └── decoder_2x4_testbench.vhd
│   └── 📁 multiplexers/
│       └── mux_2x1_tb.vhd
└── 📁 sequential/
    └── 📁 flip_flops/
        └── d_flip_flop_tb.vhd

Naming Conventions 

File Naming 

Source files: <component_name>.vhd
Testbenches: <component_name>_tb.vhd or <component_name>_testbench.vhd
Entity names: Match filename (e.g., or_gate entity in or_gate.vhd)

VHDL Naming 

Entities: lowercase with underscores (d_flip_flop)
Architectures: PascalCase (Behavioral, Dataflow, Structural)
Signals: lowercase with underscores (clk_signal)
Ports: uppercase (CLK, DATA_IN, OUTPUT)

Build System Architecture 

The project uses a multi-layered build system:

graph TD A[Developer] --> B[Makefile] B --> C[Test Scripts] B --> D[Build Scripts] B --> E[Documentation] C --> F[GHDL Compiler] D --> F E --> G[Sphinx] F --> H[Simulation Results] G --> I[HTML Documentation] J[GitHub Actions] --> B J --> K[Deploy to Pages]

Makefile Targets 

Target	Description	Usage
`test`	Run all tests	`make test`
`test-gates`	Test basic gates only	`make test-gates`
`test-<component>`	Test specific component	`make test-or-gate`
`build`	Syntax check all files	`make build`
`stats`	Show project statistics	`make stats`
`clean`	Remove build artifacts	`make clean`

Documentation Architecture 

Sphinx-based documentation system:

docs/
├── 📄 conf.py                 # Sphinx configuration
├── 📄 index.rst               # Main documentation page
├── 📄 installation.rst        # Installation guide
├── 📄 quickstart.rst          # Quick start guide
├── 📁 components/             # Component documentation
│   ├── gates.rst
│   ├── combinational.rst
│   └── sequential.rst
├── 📁 testing/                # Testing documentation
└── 📁 development/            # Development guides

Dependencies and Tools 

Core Dependencies 

Tool	Purpose	Version	Required
GHDL	VHDL compiler/simulator	5.0.1+	Yes
Make	Build automation	3.81+	Yes
Git	Version control	2.0+	Yes

Documentation Dependencies 

Package	Purpose	Version	Required
Sphinx	Documentation generator	7.0.0+	Yes
Read the Docs Theme	Documentation theme	2.0.0+	Yes
MyST Parser	Markdown support	2.0.0+	Optional

CI/CD Pipeline 

The project uses GitHub Actions for continuous integration:

graph LR A[Git Push] --> B[GitHub Actions] B --> C[Install GHDL] B --> D[Install Python] C --> E[Run Tests] D --> F[Build Docs] E --> G[Test Results] F --> H[Deploy to Pages]

Workflow Files 

File	Purpose	Triggers
`.github/workflows/test.yml`	Run VHDL tests	Push/PR
`.github/workflows/docs.yml`	Build/deploy docs	Push to main

Scalability Considerations 

Design for Growth 

The structure is designed to accommodate:

New component categories: Add directories under src/
More complex designs: Use src/modules/ for mixed designs
Extended testing: Parallel test structure in test/
Documentation expansion: Modular Sphinx documentation

Best Practices 

Separation of Concerns: Clear boundaries between source, tests, and docs
Consistent Naming: Follow established conventions
Modular Design: Each component is self-contained
Comprehensive Testing: Every component should have tests
Living Documentation: Keep docs synchronized with code

Navigation Tips 

Finding Components:

# Find all adders
find src/ -name "*adder*"

# Find all testbenches
find test/ -name "*tb.vhd"

# Count files by category
find src/gates/ -name "*.vhd" | wc -l

Understanding Dependencies:

# Search for component usage
grep -r "component.*mux_2x1" src/

# Find entity definitions
grep -r "entity.*is" src/

Project Statistics:

# Quick overview
make stats

# Detailed analysis
find . -name "*.vhd" -exec wc -l {} + | sort -n

This structure provides a solid foundation for learning VHDL while maintaining professional organization and scalability.