Brainsmith

Brainsmith transforms ONNX neural networks into optimized dataflow accelerators for FPGAs through automated design space exploration.

Key Features

• Design Space Exploration - Automated search across hardware configurations
• Blueprint System - YAML-based design space definition with inheritance
• Schema-Driven Kernels - Declarative hardware semantics with automatic validation
• Component Registry - Plugin architecture for custom kernels and pipeline steps

Documentation • Discussions • Roadmap

Quick Start

Prerequisites

• Ubuntu 22.04+ (primary development platform)
• Python 3.11+ and Poetry
• Vivado 2024.2 (optional - required for RTL synthesis)
• direnv (optional - for auto environment activation)

Installation

# Clone and setup
git clone https://github.com/microsoft/brainsmith.git
cd brainsmith

# Automated setup (creates venv, initializes project)
./setup-venv.sh

# Configure Xilinx tools path
vim brainsmith.yaml  # Edit xilinx_path and xilinx_version

# Activate environment
source .venv/bin/activate && source .brainsmith/env.sh
# Or with direnv: cd .

# Verify installation
brainsmith project info

Detailed installation options and alternative Docker setup →

Run Your First Build

# Navigate to BERT example
cd examples/bert

# Run quicktest (30-60 minutes)
./quicktest.sh

This generates a single-layer BERT accelerator with RTL simulation. See example walkthrough →

Create Custom Accelerators

# Basic usage
smith model.onnx blueprint.yaml

# With custom output directory
smith model.onnx blueprint.yaml --output-dir ./my-design

# Run specific pipeline steps
smith model.onnx blueprint.yaml \
  --start-step streamline \
  --stop-step specialize_layers

Blueprint Example:

name: "My Accelerator"
clock_ns: 5.0  # 200MHz

design_space:
  kernels:
    - MVAU
    - LayerNorm
    - Softmax

  steps:
    - "streamline"
    - "infer_kernels"
    - "specialize_layers"
    - "dataflow_partition"

Blueprint schema reference →

CLI Overview

Two commands for different workflows:

• smith - Create accelerators (shown in Quick Start above)
• brainsmith - Manage projects and development environment

Common brainsmith commands:

brainsmith project init ~/my-project    # Initialize new project
brainsmith registry -v                  # List available components
brainsmith setup cppsim                 # Setup C++ simulation
brainsmith project info                 # Show configuration

Complete CLI reference →

Contributing

We welcome contributions from the community! Please read CONTRIBUTING.md for details on our development process and how to submit pull requests.

Note on CI/CD: Our continuous integration uses self-hosted runners with Xilinx Vivado tooling and license servers. For security, external pull requests require manual approval from a maintainer before CI tests run. A maintainer will review your PR and add the safe-to-test label to trigger the test suite.

This ensures our infrastructure remains secure while still providing thorough automated testing for all contributions.

Acknowledgments

Brainsmith is developed through collaboration between Microsoft and AMD.

Built on open-source foundations:

• FINN - Dataflow compiler for quantized neural networks
• QONNX - Quantized ONNX representation
• Brevitas - PyTorch quantization library