Gates

Minimal C subset → VHDL translator

Quick Start

git clone https://github.com/byteshiftlabs/gates.git
cd gates
cmake -S . -B build -DENABLE_TESTING=ON
cmake --build build --target gates -j"$(nproc)"
./build/gates input.c output.vhdl
./build/gates --version

For the full local proof bar used by this repository, run:

./run_validation.sh

Beginner Ramp-Up

If you are new to Gates, use this path:

1. Build the gates binary and run ./build/gates --version.
2. Translate one curated example from examples/ before trying your own input files.
3. Run ./run_tests.sh once you understand the basic translation path.
4. Use ./run_validation.sh as the full public proof bar before you treat a change as release-ready.
5. Read ROADMAP.md after that so you do not confuse supported behavior with planned future work.

Example

Given this C input:

int add(int a, int b) {
    int sum = a + b;
    return sum;
}

Gates generates:

-- VHDL generated by gates

library IEEE;
use IEEE.STD_LOGIC_1164.ALL;
use IEEE.NUMERIC_STD.ALL;

-- Function: add
entity add is
  port (
    clk   : in  std_logic;
    reset : in  std_logic;
    a : in std_logic_vector(31 downto 0);
    b : in std_logic_vector(31 downto 0);
    result : out std_logic_vector(31 downto 0)
  );
end entity;

architecture behavioral of add is
  signal sum : std_logic_vector(31 downto 0);
begin
  process(clk, reset)
  begin
    if reset = '1' then
      sum <= (others => '0');
    elsif rising_edge(clk) then
      sum <= std_logic_vector(unsigned(a) + unsigned(b));
      result <= sum;
    end if;
  end process;
end architecture;

Each C function becomes a VHDL entity with clock/reset ports, input parameters as std_logic_vector ports, and a result output port. Local variables become signals, and control flow maps to synchronous process logic.

Features

• Recursive-descent parser with full operator precedence
• Control flow: if/else, while, for, break, continue
• Self-contained functions with return value propagation, plus structs and arrays
• VHDL entity/architecture generation with clock/reset, signals, and synchronous processes
• Multi-level error diagnostics (error/warning/note across 5 categories)
• GoogleTest-based unit, integration, structural validation, and edge case coverage

Requirements

• Platform: Ubuntu 24.04 x86_64
• CMake 3.14+
• C11-compatible compiler (tested on GCC 13.3.0)
• C++17 for GoogleTest

Optional Tools

• cppcheck 2.13+ — static analysis (cmake --build build --target cppcheck)
• Sphinx + sphinx_rtd_theme — documentation (./build_docs.sh)

Setup Contract

Gates has two public setup paths:

1. Native Ubuntu 24.04 x86_64 development This is the fast local iteration path documented in this README.
2. Docker-based validation This is the authoritative release gate. GitHub Actions builds the repository Docker image and runs ./run_validation.sh inside it.

If native and Docker results disagree, the Docker path is the source of truth for release decisions.

Testing

./run_tests.sh    # Build and run all tests
./run_validation.sh
./build_docs.sh   # Build documentation

./run_validation.sh configures the project, runs GoogleTest via CTest, smoke-generates VHDL from the curated positive examples in examples/, builds the Sphinx docs, and runs cppcheck.

Building Documentation

Use the convenience wrapper below when you want just the Sphinx HTML output:

./build_docs.sh

The script configures build/ automatically if it does not exist yet, then builds the docs CMake target. The authoritative release path is still ./run_validation.sh, which exercises the docs build together with tests, smoke translation, and static analysis.

Docker

Build an interactive development image:

docker build -t gates-dev .
docker run --rm -it -v "$PWD":/workspace gates-dev

Run full validation during image build:

docker build --build-arg RUN_VALIDATION=1 -t gates-validated .

Inside the container, use the existing project scripts:

./run_validation.sh

Validation Scope

Current public validation proves:

• unit and integration tests via GoogleTest/CTest
• structural VHDL validation checks in the test suite
• smoke translation of the curated positive examples shipped in examples/
• Sphinx documentation build health
• cppcheck static analysis cleanliness

Current public validation does not yet include GHDL parsing, vendor synthesis, or timing/resource closure. Structural correctness is the current public contract.

Project Structure

src/
  app/         — Entry point (gates.c)
  parser/      — Tokenizer, recursive-descent parser, AST construction
  codegen/     — VHDL entity/architecture/process generation
  core/        — AST node definitions, utility functions
  symbols/     — Symbol tables for arrays and structs
tests/         — GoogleTest unit, integration, and edge case tests
docs/          — Sphinx documentation
examples/      — Sample C input files

Known Limitations

• No global variables
• No nested structs or arrays of structs
• No pointer support
• No switch/case or do-while
• Function calls are parsed, but cross-function hardware wiring is not yet synthesized. Multi-function files emit independent entities, so keep hardware-generating examples self-contained.
• Generated VHDL targets the currently supported C subset. Structural well-formedness is verified by self-contained validation tests (balanced constructs, declared signals, proper type wrapping). Current output does not perform resource sharing, pipelining, or constant folding (see ROADMAP.md for planned future work)

Release Surface

Public releases are source-first. The supported release evidence is the tagged source tree, the CI-built docs artifact, and the Docker validation path above. This repository does not currently promise prebuilt binaries or synthesized hardware artifacts.

Documentation

See ROADMAP.md for planned features and docs/ for full documentation.

License

GPL v3 — see LICENSE.

Disclosure: This software was developed with AI assistance under human supervision.