Quick Start Guide

Get up and running with VHDL Digital Design Samples in just a few minutes!

⚡ 5-Minute Setup

Prerequisites: Git and terminal access

1. Clone and enter the project:

   git clone https://github.com/shishir-dey/vhdl-samples.git
   cd vhdl-samples
   

2. Install GHDL:

   macOSUbuntu/DebianWindows

   brew install ghdl
   

3. Run your first test:

   make test
   

   Expected output:

   🎉 All tests passed!
   Total Tests: 8, Passed: 8, Failed: 0
   

🚀 Your First VHDL Component

Let’s examine and test a simple OR gate:

1. Look at the source code:

   cat src/gates/or_gate.vhd
   

   entity or_gate is
       Port ( A : in STD_LOGIC;
              B : in STD_LOGIC;
              C : in STD_LOGIC;
              D : in STD_LOGIC;
              O : out STD_LOGIC);
   end or_gate;
   
   architecture Behavioral of or_gate is
   begin
       O <= A or B or C or D;
   end Behavioral;
   

2. Check the testbench:

   cat test/gates/or_gate_tb.vhd
   

3. Run the specific test:

   make test-or-gate
   

   Testing: or_gate_tb
   ✓ Test passed
   

🧪 Explore Different Categories

Test components by category:

Basic Gates

make test-gates
# Tests: OR gate, XOR gates

Combinational Logic

make test-combinational
# Tests: Adders, Decoders, Multiplexers

Sequential Logic

make test-sequential
# Tests: Flip-flops, Registers

📊 Project Overview

make stats

Sample output:

VHDL Digital Design Samples - Project Statistics
================================================

Directory Structure:
📁 src/
├── 📁 gates/ (3 files)
├── 📁 combinational/ (19 files)
└── 📁 sequential/ (10 files)

📁 test/ (8 files)

Lines of Code: 1,754
Components: 32
Test Coverage: 25%

🎯 Next Steps

Now that you’re set up, here are some things to try:

Learn the Architecture

1. Explore the project structure:

   tree src/
   

2. Read component documentation:

   • Basic Logic Gates - Basic logic gates

   • Combinational Logic - Adders, decoders, multiplexers

   • Sequential Logic - Flip-flops, registers, counters

Try Different Components

Test a more complex component:

# Test a 4-bit ripple carry adder
make test-rc-adder

# Test a 2x4 decoder
make test-decoder

# Test a D flip-flop
make test-dff

Examine the VHDL code:

# Look at different modeling styles
cat src/combinational/adders/fa_behaviour.vhd    # Behavioral
cat src/combinational/adders/fa_dataflow.vhd     # Dataflow
cat src/combinational/adders/fa_structural.vhd   # Structural

Build Your Own

1. Create a new component:

   cp src/gates/or_gate.vhd src/gates/my_gate.vhd
   # Edit the file to implement your logic
   

2. Create a testbench:

   cp test/gates/or_gate_tb.vhd test/gates/my_gate_tb.vhd
   # Modify to test your component
   

3. Test your component:

   # Manual testing
   cd work/
   ghdl -a ../src/gates/my_gate.vhd
   ghdl -a ../test/gates/my_gate_tb.vhd
   ghdl -e my_gate_tb
   ghdl -r my_gate_tb
   

Understand the Testing Framework

Test script details:

cat scripts/run_tests.sh

Manual testing workflow:

# Navigate to work directory
cd work/

# Compile source
ghdl -a ../src/gates/or_gate.vhd

# Compile testbench
ghdl -a ../test/gates/or_gate_tb.vhd

# Elaborate
ghdl -e or_gate_tb

# Run simulation
ghdl -r or_gate_tb

🔧 Development Workflow

The typical development cycle:

1. Edit code in your favorite editor

2. Test changes with make test

3. Check specific components with make test-<component>

4. Build all with make build

5. Clean up with make clean

💡 Tips and Tricks

Performance

# Use parallel builds
export MAKEFLAGS=-j$(nproc)  # Linux
export MAKEFLAGS=-j$(sysctl -n hw.ncpu)  # macOS

Editor Setup

VS Code: Install “VHDL Language Support” extension

Vim: Add to .vimrc:

au BufNewFile,BufRead *.vhd set filetype=vhdl

Debugging

# Verbose GHDL output
ghdl -r testbench --wave=output.ghw

# View waveforms (if gtkwave is installed)
gtkwave output.ghw

🆘 Troubleshooting

Common Issues

“GHDL not found”

# Check installation
which ghdl
ghdl --version

“Permission denied”

# Make scripts executable
chmod +x scripts/run_tests.sh

“Test failed”

# Run individual test for details
cd work/
ghdl -a ../src/gates/or_gate.vhd
ghdl -a ../test/gates/or_gate_tb.vhd
ghdl -e or_gate_tb
ghdl -r or_gate_tb --wave=debug.ghw

Getting Help

• 📖 Documentation: Browse the full docs at VHDL Digital Design Samples Documentation

• 🐛 Issues: GitHub Issues

• 💡 Contributing: Contributing Guide

🎉 What’s Next?

Congratulations! You now have a working VHDL development environment. Here are some learning paths:

For Beginners: - Start with Basic Logic Gates - Learn about Testing Framework - Try modifying existing components

For Intermediate Users: - Explore Combinational Logic - Study different VHDL modeling styles - Implement your own components

For Advanced Users: - Dive into Sequential Logic - Set up Build System - Contribute to the project via Contributing Guide

Ready to dive deeper? Head to the Basic Logic Gates documentation!