SystemC HLS Project

A comprehensive High-Level Synthesis (HLS) educational project demonstrating hardware design with SystemC. Features two independent modules: the Sample Adder Core (Phases 1-3) with basic arithmetic operations, and the ALU Module (Phases 4-5) with advanced multiply-accumulate and full arithmetic logic unit implementations.

📋 Project Structure

sampleAdder/
├── sample_adder_core/          ← Phases 1-3: Adder variants & Multiplier
│   ├── include/                (5 hardware module headers)
│   ├── src/                    (module implementations)
│   ├── testbench/              (5 test programs)
│   └── CMakeLists.txt
│
├── alu_module/                 ← Phases 4-5: MAC Unit & Full ALU
│   ├── include/                (3 hardware module headers)
│   ├── testbench/              (2 test programs)
│   └── CMakeLists.txt
│
├── scripts/                    ← Build and execution utilities
├── CMakeLists.txt              ← Master build configuration
├── README.md                   ← This file
│
└── Documentation/
    ├── ARCHITECTURE.md         ← Comprehensive architecture guide
    ├── ARCHITECTURE_DIAGRAM.md ← Visual system diagrams
    ├── QUICK_REFERENCE.md      ← Quick lookup commands
    ├── STRUCTURE_SUMMARY.txt   ← Project snapshot
    └── SEGREGATION_COMPLETE.md ← Segregation details

🎯 Module Overview

Sample Adder Core (Phases 1-3)

Locations: sample_adder_core/include/ and testbench/

Phase	Module	Description	Features
1	adder.h	4-bit signed adder	Basic combinational logic
2	parametrized_adder.h	Multi-width template	8/16/32-bit variants
2	saturating_adder.h	Saturation support	Overflow/underflow detection
3	multiplier.h	8-bit multiplier	8×8→16-bit multiplication

Test Programs:

• tb_adder - Basic functionality
• tb_parametrized_adder - Template variants
• tb_phase1_enhanced - Enhanced testing framework
• tb_phase2_saturating_adder - Saturation behavior
• tb_phase3_multiplier - Multiplication verification

ALU Module (Phases 4-5)

Locations: alu_module/include/ and testbench/

Phase	Module	Description	Features
4	mac_unit.h	Multiply-Accumulate	8×8+16→16 saturating
5	alu.h	Full ALU (9 operations)	ADD, SUB, MUL, MAC, AND, OR, XOR, SHL, SHR

Test Programs:

• tb_phase4_mac - MAC unit verification (56 test cases)
• tb_phase5_alu - ALU operations (79 test cases)

🔨 Build & Run

Prerequisites

• SystemC 3.0.2 (installed at C:/msys64/usr/local/systemc)
• CMake 3.10+
• C++11 compiler (GCC/Clang)
• Ninja or Make build tool

Quick Build

# Navigate to project root
cd sampleAdder

# Clean build
rm -rf build && mkdir build && cd build

# Configure and build
cmake ..
ninja -j4        # or 'make -j4' if using Make

Run Tests

# All tests
cd build/bin
./tb_adder.exe
./tb_parametrized_adder.exe
./tb_phase1_enhanced.exe
./tb_phase2_saturating_adder.exe
./tb_phase3_multiplier.exe
./tb_phase4_mac.exe
./tb_phase5_alu.exe

# Or use the convenience script
cd ../..
./scripts/run.sh all

Using the run.sh Script

# Run specific test
./scripts/run.sh phase4    # Run MAC unit tests
./scripts/run.sh phase5    # Run ALU tests

# Run all tests
./scripts/run.sh all

📖 Documentation

• ARCHITECTURE.md - Complete architecture documentation with design details
• QUICK_REFERENCE.md - Quick lookup for common commands
• STRUCTURE_SUMMARY.txt - Project snapshot and statistics
• ARCHITECTURE_DIAGRAM.md - Visual diagrams of system organization

✨ Key Features

Arithmetic Operations

• Saturating arithmetic - Automatic overflow/underflow clamping
• Multi-width support - 8, 16, 32-bit variants
• Multiply-accumulate - MAC unit for DSP operations

Bitwise Operations

• Logical gates - AND, OR, XOR
• Shift operations - Left shift (SHL) with overflow detection, arithmetic right shift (SHR)

Status Monitoring

• Overflow flag - Detects positive overflow
• Underflow flag - Detects negative overflow
• Zero flag - Indicates zero result
• Sign flag - Indicates negative result

Design Quality

• SystemC methodology - Industry-standard hardware description
• Combinational & sequential logic - SC_METHOD and SC_THREAD processes
• Comprehensive testbenches - 56+ test cases per module
• Modular architecture - Independent, reusable components

🧪 Testing

Each module includes comprehensive testbenches:

• MAC Unit: 56 test cases covering basic operations, saturation, edge cases, and random vectors
• ALU: 79 test cases for all 9 operations, status flags, and sequences

Test output includes:

• Operation details (inputs, expected output, actual output)
• Pass/fail status
• Test coverage statistics
• Performance metrics

🏗️ Build System Architecture

Master CMakeLists.txt
    ├── add_subdirectory(sample_adder_core)
    │   └── 5 executables (Phases 1-3)
    └── add_subdirectory(alu_module)
        └── 2 executables (Phases 4-5)

All outputs → build/bin/ (7 total executables)

Each module:

• Builds independently
• Has isolated test suite
• Maintains separate CMakeLists.txt
• No cross-module dependencies

📊 Project Statistics

• Total Phases: 5
• Hardware Modules: 7 (adder, parametrized_adder, saturating_adder, multiplier, mac_unit, alu, plus utilities)
• Test Programs: 7 executables
• Test Cases: 200+ (across all modules)
• Lines of Code: 3000+ (hardware definitions and testbenches)

🚀 Future Enhancements

Potential expansions to the project:

• Phase 6: Pipelined ALU variant with multi-cycle operations
• Phase 7: Control flow unit with branching and conditional execution
• Phase 8: Memory subsystem with cache integration
• Integration: Combined processor core with all phases
• Parametrization: Configurable bit widths and capabilities

📝 Development Notes

Code Organization

• Header files in include/ contain SC_MODULE definitions
• Testbenches use sc_main() entry point
• All modules use SystemC 3.0.2-Accellera API
• Saturation logic uses extended-precision intermediates

Naming Conventions

• Module files: descriptive names (e.g., mac_unit.h, saturating_adder.h)
• Test programs: tb_<phase_name>.cpp format
• Signals: lowercase with underscore separation

❓ Troubleshooting

Build Issues

• CMake not found: Install CMake 3.10 or later
• SystemC not found: Verify SYSTEMC_HOME in CMakeLists.txt
• Compiler errors: Ensure C++11 support enabled

Test Failures

• Run individual tests to isolate issues
• Check SystemC library version compatibility
• Review test output for specific error messages

📄 License

This is an educational project for learning SystemC HLS concepts.

👤 Author Notes

Project designed for demonstration and educational purposes. Clean segregation of modules allows for independent study and reuse in other projects.

---

Last Updated: June 2026
SystemC Version: 3.0.2-Accellera
Status: ✓ Production Ready

Quick Start

Build and Run All Tests

bash scripts/run.sh all

Run Parametrized Adder Only (Recommended)

bash scripts/run.sh parametrized

Run Original Adder Only

bash scripts/run.sh original

Manual Build and Execution

cd sampleAdder
cmake -S . -B build
cmake --build build
./build/tb_parametrized_adder  # Run parametrized tests
./build/tb_adder               # Run original tests

Test Results

Parametrized Adder (100% Pass Rate)

✅ 8-bit Tests:    10/10 PASS
✅ 16-bit Tests:   10/10 PASS
✅ 32-bit Tests:   10/10 PASS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Total: 30/30 PASS (100.00%)

Test Coverage:

• ✅ Basic arithmetic (positive, negative, zero)
• ✅ Overflow boundaries and saturation
• ✅ Underflow boundaries and saturation
• ✅ Extreme values (min/max ± 1)
• ✅ Mixed sign operations

Original Adder (128 Test Combinations)

✅ All 128 combinations tested
✅ Overflow/underflow saturation verified
✅ Edge cases validated

Architecture

Data Flow

Input A ──┐
          ├──→ [Adder Module] ──→ Output Sum
Input B ──┤                   ──→ Overflow Flag
          └─── [Status Flags] – Underflow Flag

Module Instantiation Example (Parametrized)

// Create 16-bit adder
parametrized_adder<16> my_adder("adder");

// Bind signals
my_adder.a(signal_a);
my_adder.b(signal_b);
my_adder.sum(result);
my_adder.overflow(ov_flag);
my_adder.underflow(uf_flag);

Dependencies

• SystemC 3.0.2 (Accellera)
  • Installation: C:/msys64/usr/local/systemc
  • Provides simulation kernel and libraries
• CMake 3.10+ - For build configuration
• C++17 or later - For template functionality
• MinGW-w64 GCC 15.2.0 - C/C++ compiler

Key Differences: Original vs Parametrized

Aspect	Original	Parametrized
Bit Width	4-bit (fixed)	8/16/32-bit (configurable)
Extensibility	Limited	Template-based
Overflow Handling	Saturation only	Saturation + flag
Underflow Handling	Saturation only	Saturation + flag
Test Cases	128 combinations	30 targeted cases
Use Case	Proof of concept	Production ready

Implementation Highlights

Overflow/Underflow Detection

The parametrized adder uses extended-width arithmetic to detect boundary conditions:

// Detect overflow: sum > max_value
// Detect underflow: sum < min_value
// Saturate to valid range automatically

Template-Based Design

template<int WIDTH>
SC_MODULE(parametrized_adder) {
    typedef sc_dt::sc_int<WIDTH> data_type;
    // Generic logic works for any WIDTH
};

Combinational Logic

• Trigger: Changes to inputs a or b
• Latency: Single cycle (combinational)
• Pipeline: Can be extended with SC_THREAD for pipelined variants

Build System

• Tool: CMake (cross-platform)
• Generator: Ninja (default) or Unix Makefiles
• Output:
  • build/tb_adder - Original testbench executable
  • build/tb_parametrized_adder - Parametrized testbench executable

Next Steps

Consider expanding the project with:

1. Multiplier Module - Integer multiplication with saturation
2. ALU (Arithmetic Logic Unit) - Combined add/subtract/logic operations
3. Fixed-Point Arithmetic - Q-format number support
4. Pipelined Adder - Multi-stage pipeline for higher frequency
5. FIR Filter - Real-world signal processing application
6. Memory Subsystem - Dual-port RAM and cache

See PARAMETRIZED_ADDER.md for detailed documentation on the parametrized module.

Troubleshooting

Build Fails

# Verify SystemC installation
ls /c/msys64/usr/local/systemc/lib/libsystemc.a

# Clean rebuild
rm -rf build
cmake -S . -B build
cmake --build build

Execution Issues

# Check executable exists
ls -lh build/tb_*.exe

# Run with verbose output
./build/tb_parametrized_adder 2>&1 | head -50

Project Status

✅ Complete and Tested

• Original 4-bit adder: Fully functional
• Parametrized multi-width adder: Fully functional
• Comprehensive testbenches: 100% pass rate
• Documentation: Complete

---

Last Updated: April 12, 2026 SystemC Version: 3.0.2-Accellera Status: Production Ready