GateFlow

# GateFlow <p align="center"> <a href="https://github.com/Firo718/GateFlow/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT License"></a> <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10%2B-blue" alt="Python 3.10+"></a> <a href="https://github.com/Firo718/GateFlow/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/Firo718/GateFlow/ci.yml?branch=main" alt="CI"></a> </p> <p align="center"> <strong>AI-assisted MCP server and Python SDK for AMD Vivado FPGA workflows.</strong> </p> <p align="center"> AI-assisted Vivado FPGA automation interface for Claude, Cursor, and other AI tools, covering project creation, constraints, synthesis, implementation, simulation, hardware debugging, and Block Design. </p> > Status: `0.1.0` alpha. Current primary platform is Windows. Vivado-dependent workflows require a local Vivado installation. <p align="center"> <a href="#Tool-List">Tool List</a> - <a href="#Quick-Start">Quick Start</a> - <a href="#User-Guide">User Guide</a> - <a href="#MCP-Tool-List">MCP Tool List</a> - <a href="#Contribution-Guide">Contribution Guide</a> </p> --- ## Introduction GateFlow is an open-source MCP (Model Context Protocol) server that enables AI programming tools to control AMD (Xilinx) Vivado FPGA development software. Through natural language interaction, it completes the entire FPGA development process from project creation to bitstream generation. ### Why Choose GateFlow? - **Natural Language Driven**: No need to remember complex Tcl commands; describe requirements in natural language. - **AI-native Design**: Optimized for AI programming assistants, supporting mainstream AI tools like Claude, Cursor, and Trae. - **Complete Workflow**: Covers the entire FPGA development process, from project creation to hardware programming. - **Open-source and Free**: MIT license, fully open-source, and community-driven. ## Features - **Project Management** - Create, open, and configure Vivado projects. - **Source File Management** - Add Verilog/VHDL source files and constraint files. - **Synthesis and Implementation** - Run synthesis, implementation, and generate bitstreams. - **Timing Constraints** - Create clock constraints, IO delays, and timing exceptions. - **Hardware Programming** - Connect to hardware servers and program FPGAs. - **IP Configuration** - Configure Clocking Wizard, FIFO, BRAM, and other IPs. - **Block Design** - Create and manage Block Designs. - **Simulation Support** - Behavioral simulation and Testbench management. - **Report Analysis** - Resource utilization, timing, and power reports. ## System Requirements - Python 3.10+ - Vivado 2018.1+ (needs to be added to PATH or set XILINX_VIVADO environment variable) - Windows 10/11 (Linux support planned) ## Quick Start ### Installation ```bash # Install using pip pip install gateflow # Or using uv uv tool install gateflow ``` ### Post-installation Configuration After installation, if the `gateflow` command is not found, it is usually because the `Scripts` directory of the current Python environment is not in the `PATH`. ### AI Tool Configuration CLI PATH note: ```bash python -m gateflow.cli --version python -m gateflow.cli doctor python -c "import sysconfig; print(sysconfig.get_path('scripts'))" ``` The `Scripts` directory is different for each user and Python environment. Do not copy the example path above from another machine. Query the active interpreter and add the reported directory to your user `PATH`. If you do not want to modify `PATH`, keep using `python -m gateflow.cli <subcommand>`. #### Claude Desktop Edit the configuration file `~/AppData/Roaming/Claude/claude_desktop_config.json`: ```json { "mcpServers": { "gateflow": { "command": "gateflow" } } } ``` #### Cursor Add MCP server configuration in settings: ```json { "mcp.servers": { "gateflow": { "command": "gateflow" } } } ``` ### Verification ```bash # Check if GateFlow is correctly installed gateflow --version # Diagnose environment and connection configuration gateflow doctor # Check current connection status gateflow status # Generate capability list (docs/CAPABILITIES.md + docs/CAPABILITIES.json) gateflow capabilities --write ``` ## User Guide GateFlow provides two usage methods: 1. **MCP Tool** - Use natural language control through AI assistants (Claude, Cursor, etc.). 2. **Python SDK** - Directly use APIs in Python code. ### Python SDK See [Python SDK Documentation](docs/PYTHON_SDK.md) to learn how to use GateFlow API in Python code. ```python import asyncio from gateflow import GateFlow async def main(): gf = GateFlow() await gf.create_project("my_proj", "./projects", "xc7a35tcpg236-1") await gf.run_synthesis() result = await gf.generate_bitstream() print(f"Bitstream: {result['bitstream_path']}") asyncio.run(main()) ``` ### FPGA Model Format GateFlow uses the standard Vivado device model format: `<family><model><package><speed grade>` **Correct Format Examples**: - `xc7z020clg484-2` (Zynq-7000) - `xc7a35tcpg236-1` (Artix-7) - `xc7k325tffg900-2` (Kintex-7) **Incorrect Format Examples**: - `xc7z020-2clg484i` (speed grade position incorrect) - `xc7z020-2clg484` (missing speed grade) ### Basic Workflow #### 1. Create Project ``` Create a project named "led_blink", target device xc7a35tcpg236-1, saved in D:/projects/led_blink ``` #### 2. Add Source Files ``` Add Verilog source file top.v and constraint file top.xdc Set top module as top-level module ``` #### 3. Add Constraints ``` Create a 100MHz clock constraint, target port clk Set LED output pin constraint ``` #### 4. Synthesis and Implementation ``` Run synthesis View resource utilization report Run implementation Generate bitstream ``` #### 5. Hardware Programming ``` Connect to local hardware server Get device list Program FPGA ``` ### Advanced Usage #### Using IP Cores ``` Create a Clocking Wizard IP, input 100MHz, output 50MHz and 200MHz Create a 32-bit wide, 2048-depth FIFO Create a dual-port BRAM, depth 4096 ``` #### Block Design ``` Create a Block Design named system Add Zynq Processing System IP Add AXI GPIO IP Automatically connect all interfaces Verify design and generate HDL Wrapper ``` #### Simulation ``` Create simulation set sim_1, add testbench.v Set simulation top module as tb_top Launch behavioral simulation, run 1ms Add waveform signals clk and data ``` ## MCP Tool List GateFlow's actual tool surface is based on runtime registration results and is no longer manually maintained in the README. Single source of truth: - [docs/CAPABILITIES.md](docs/CAPABILITIES.md) - [docs/CAPABILITIES.json](docs/CAPABILITIES.json) - `gateflow capabilities --write` High-frequency capability examples: - Project and build: `create_project`, `add_source_files`, `run_synthesis_async`, `run_full_flow` - Report and check: `get_utilization_report`, `get_timing_report`, `check_drc`, `check_methodology` - Simulation and debug: `compile_simulation`, `elaborate_simulation`, `launch_simulation`, `probe_signal`, `add_force_signal` - Hardware debug runtime: `list_hardware_targets`, `set_probe_file`, `hw_ila_run`, `hw_vio_get_input`, `hw_axi_read` - Block Design high-frequency templates: `bd_create_zynq_gpio_uart_bram_system`, `bd_create_zynq_gpio_uart_timer_dma_system` Minimal runnable examples: - [examples/README.md](examples/README.md) - [examples/simple_project.py](examples/simple_project.py) - [examples/build_zed_led_tcp.py](examples/build_zed_led_tcp.py) - [examples/report_checks_example.py](examples/report_checks_example.py) - [examples/simulation_debug_example.py](examples/simulation_debug_example.py) - [examples/zynq_template_example.py](examples/zynq_template_example.py) - [examples/hardware_debug_runtime_example.py](examples/hardware_debug_runtime_example.py) ## Project Structure ```bash gateflow/ ├── src/gateflow/ │ ├── server.py # MCP server entry │ ├── vivado/ # Vivado interaction module │ │ ├── tcl_engine.py # Tcl execution engine │ │ ├── project.py # Project management │ │ ├── synthesis.py # Synthesis │ │ ├── implementation.py # Implementation │ │ ├── constraints.py # Constraint management │ │ ├── hardware.py # Hardware programming │ │ ├── ip_config.py # IP configuration │ │ ├── block_design.py # Block Design │ │ └── simulation.py # Simulation support │ ├── tools/ # MCP tools │ │ ├── project_tools.py │ │ ├── build_tools.py │ │ ├── constraint_tools.py │ │ ├── hardware_tools.py │ │ ├── ip_tools.py │ │ ├── block_design_tools.py │ │ └── simulation_tools.py │ └── utils/ # Utility functions │ └── parser.py ├── tests/ # Test files ├── examples/ # Example projects │ ├── simple_project.py # Simple project example │ └── blink_led/ # LED blink example └── docs/ # Documentation ``` ## Example Projects ### Simple Project Creation See [examples/simple_project.py](examples/simple_project.py) to learn how to create a basic project using GateFlow. ### LED Blink Example See the [examples/blink_led/](examples/blink_led/) directory, which contains a complete LED blink project example: - `blink_led.v` - Verilog source code - `blink_led.xdc` - Constraint file - `build.py` - Build script ## Troubleshooting ### Tcl Server Startup Failure If an error occurs when running `start_server.bat`, check: 1. Is Vivado correctly installed? 2. Is the Vivado version 2018.1 or higher? 3. Do you have permission to access the Vivado installation directory? 4. `start_server.bat` / `tcl_server.tcl` belongs to the manual startup link, which keeps the Tcl session alive, different from the automatic injection behavior of `Vivado_init.tcl`. 5. Do not manually copy `tcl_server.tcl` to `%APPDATA%/Xilinx/Vivado/Vivado_init.tcl`, as the auto-injected version must be non-blocking, otherwise, Vivado GUI may launch and get stuck. ### Command Not Found If the `gateflow` command is not found, refer to the "Post-installation Configuration" section. ### Vivado Detection Failure If `gateflow status` shows that Vivado is not detected, manually specify the path: ```bash gateflow install F:\Xilinx\Vivado\2023.1 ``` ## Frequently Asked Questions ### Q: Which Vivado versions are supported by GateFlow? A: GateFlow supports Vivado 2018.1 and above. It is recommended to use Vivado 2020.1 or higher for the best experience. ### Q: How to set up Vivado environment variables? A: There are two ways: 1. Add Vivado to the system PATH: ```bash # Windows (PowerShell) $env:Path += ";C:\Xilinx\Vivado\2023.1\bin" ``` 2. Set the XILINX_VIVADO environment variable: ```bash # Windows (PowerShell) $env:XILINX_VIVADO = "C:\Xilinx\Vivado\2023.1" ``` ### Q: Does GateFlow support Linux? A: Currently, GateFlow mainly supports the Windows platform. Linux support is under development and is expected to be available in the next version. ### Q: How to debug GateFlow? A: Debugging can be done by setting the log level: ```bash # Set debug mode set GATEFLOW_DEBUG=1 gateflow ``` ### Q: What is the difference between GateFlow and traditional Tcl scripts? A: GateFlow provides a higher level of abstraction, allowing AI tools to understand the FPGA development process. Additionally, the Tcl commands generated by GateFlow can be exported, making it easy to integrate with traditional workflows. ## Contribution Guide Welcome to contribute! Please check [CONTRIBUTING.md](CONTRIBUTING.md) for details. ### Setting Up the Development Environment ```bash # Clone the repository git clone https://github.com/Firo718/GateFlow.git cd gateflow # Install development dependencies pip install -e ".[dev]" # Run tests pytest tests/ # Code formatting ruff format src/ ``` ### Contribution Process 1. Fork this repository 2. Create a feature branch (`git checkout -b feature/amazing-feature`) 3. Commit changes (`git commit -m 'Add some amazing feature'`) 4. Push to the branch (`git push origin feature/amazing-feature`) 5. Create a Pull Request ## License This project is licensed under the MIT License - see [LICENSE](LICENSE) file. ## Acknowledgements - Thanks to Xilinx/AMD for providing the Vivado toolchain - Thanks to the MCP protocol team for providing an excellent framework ## Contact Information - Email: levelup718@126.com - Project homepage: https://github.com/Firo718/GateFlow --- ## CLI PATH Note If `gateflow` is installed but the command is not found, see [docs/PATH_SETUP.md](docs/PATH_SETUP.md). Use `python -m gateflow.cli ...` as the fallback form when the active Python `Scripts` directory is not yet in `PATH`. <p align="center"> Made with love by the GateFlow Team </p>