aly-tool 0.1.2

ALY (Advanced Logic Yieldflow) is a Python-based RTL meta-tool that automates build, simulation, synthesis, and verification workflows across multiple EDA tools, providing a unified and efficient design flow for hardware projects.

ALY - Advanced Logic Yieldflow

Professional Python build and verification tool for RTL/SoC development

Features

RTL Workflow

• Multi-Tool Simulation - XSIM, Questa/ModelSim, Verilator, Icarus Verilog
• Synthesis - Vivado (FPGA), Yosys (open-source/ASIC)
• Linting - Verilator lint, Vivado DRC
• Waveform Management - Automated capture and viewing with GTKWave

Firmware & Memory

• RISC-V Toolchain - Integrated firmware builds (RV32/RV64)
• Memory Generation - ELF to hex/mem/bin/COE/Verilog conversion

Developer Experience

• Project Templates - Bootstrap complete SoC projects with aly init
• Manifest System - YAML-based RTL, testbench, and firmware manifests
• Pluggable Backends - Clean simulator/synthesis tool abstraction
• Hierarchical Configuration - Project-wide settings with per-component overrides

Quick Start

Installation

pip install aly-tool

Or install from source:

git clone https://github.com/RWU-SOC/aly-tool.git
cd aly-tool
pip install -e .

Create a New Project

# Create new RV64I SoC project (default template)
aly init my-soc
cd my-soc

# Create project with specific template
aly init my-project --template soc

# List available templates
aly init --list-templates

# Pass template variables
aly init my-cpu --var language=verilog --var toolchain=riscv32

RTL Simulation

# Run simulation with XSIM (Vivado)
aly sim --top soc_tb --tool xsim --waves

# Run with Questa/ModelSim
aly sim --top soc_tb --tool questa --gui

# Run with Verilator (fast)
aly sim --top core_tb --tool verilator

Synthesis

# Vivado synthesis for FPGA
aly synth --module alu --part xc7a100tcsg324-1

# Yosys synthesis (generic/ASIC)
aly synth --module alu --part xc7a100tcsg324-1 --tool yosys

Linting

# Lint specific module
aly lint --module cpu_core

# Lint with specific tool
aly lint --module cpu_core --tool slang

# Lint specific files
aly lint rtl/cpu.sv rtl/alu.sv

Build Firmware

# Build all firmware
aly firmware

# Build specific firmware
aly firmware instr_test

# List available builds
aly firmware --list

Other Commands

# Show project information
aly info

# Clean build artifacts
aly clean

# Manage constraints
aly constraints list

# Show version
aly version

Project Structure

ALY generates well-organized SoC projects:

my-soc/
├── .aly/                  # ALY configuration
│   ├── config.yaml        # Project settings
│   ├── sim.yaml           # Simulation config
│   ├── synth.yaml         # Synthesis config
│   ├── lint.yaml          # Linting config
│   ├── toolchains.yaml    # Toolchain paths
│   └── constraints.yaml   # Constraint sets
├── rtl/                   # HDL sources
│   ├── pkg/               # SystemVerilog packages
│   ├── core/              # Processor core
│   │   ├── alu/
│   │   ├── decoder/
│   │   └── regfile/
│   ├── bus/               # Bus interfaces
│   ├── mem/               # Memory modules
│   └── soc_top/           # Top-level integration
├── tb/                    # Testbenches
│   ├── unit/              # Module tests
│   └── integration/       # System tests
├── fw/                    # Firmware
│   └── instr_test/        # Test programs
├── ip/                    # External IP
├── synth/                 # Synthesis files
│   └── constraints/       # XDC/SDC constraints
├── docs/                  # Documentation
└── build/                 # Build outputs (gitignored)

Manifest System

ALY uses YAML manifests to describe RTL modules, testbenches, and firmware:

RTL Manifest (rtl/core/manifest.yaml)

name: cpu_core
version: 1.0.0
type: rtl
language: systemverilog

modules:
  - name: cpu_core
    top: cpu_core
    files:
      - CPU.sv
      - PC.sv
    dependencies:
      - name: cpu_pkg
        type: package
      - name: cpu_alu
        type: rtl

Testbench Manifest (tb/unit/manifest.yaml)

name: unit_tests
type: testbench
version: 1.0.0

testbenches:
  - name: tb_alu
    top: tb_alu
    files:
      - tb_alu.sv
    dependencies:
      - name: cpu_alu
        type: rtl

testsuites:
  - name: unit_tests
    testbenches: [tb_alu, tb_regfile]
    parallel: 4

Firmware Manifest (fw/instr_test/manifest.yaml)

name: instr_test
type: firmware
toolchain: riscv64

builds:
  - name: test_program
    languages: [asm]
    sources: [test.asm]
    linker_script: linkers/memory.ld
    outputs:
      - format: elf
      - format: mem
        plusarg: MEM_FILE

Template System

Create custom project templates:

# template.yaml
name: my_template
version: "1.0"
description: "Custom SoC template"
extends: base

variables:
  project_name:
    description: "Project name"
    default: "my_project"
  language:
    description: "HDL language"
    choices: [systemverilog, verilog]

structure:
  directories:
    - rtl
    - tb
    - fw

files:
  - src: "rtl/**/*"
    dest: "rtl/"
  - src: "config.yaml.j2"
    dest: ".aly/config.yaml"
    template: true

Use Jinja2 templating in .j2 files:

{% if language == 'systemverilog' %}
import {{ project_name }}_pkg::*;
{% endif %}

module {{ project_name }}_top (
    input logic clk_i,
    input logic rst_i
);
endmodule

Documentation

Full documentation available at RWU-SOC.github.io/aly-tool

• Getting Started
• Configuration
• Template System
• Command Reference
• API Documentation

Development

Setup Development Environment

git clone https://github.com/RWU-SOC/aly-tool.git
cd aly-tool
pip install -e ".[dev]"

Run Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=aly

# Run specific test
pytest tests/test_init.py -v

Build Documentation

cd docs
pip install -r requirements.txt
make html
# View at docs/build/html/index.html

Requirements

• Python 3.8+
• Optional: RISC-V toolchain (riscv64-unknown-elf-gcc) for firmware builds
• Optional: Vivado for XSIM simulation and FPGA synthesis
• Optional: Verilator for fast simulation
• Optional: Yosys for open-source synthesis

License

Apache License 2.0 - See LICENSE for details.

Contributing

Contributions welcome! Please see CONTRIBUTING.md for guidelines.

Acknowledgments

• Built with Python and Jinja2
• Inspired by modern build systems like Bazel and Buck