Configuration

ALY uses a YAML-based configuration system with a clear hierarchy. This guide covers all configuration options.

Configuration Files

Project configuration lives in the .aly/ directory with separate files for each domain:

.aly/
+-- config.yaml         # Main project configuration
+-- sim.yaml            # Simulation configuration
+-- synth.yaml          # Synthesis configuration
+-- lint.yaml           # Linting configuration
+-- constraints.yaml    # Constraints configuration
+-- fpga.yaml           # FPGA programming configuration
+-- toolchains.yaml     # Firmware toolchains configuration

Each domain has its own configuration file that is loaded when needed. This modular approach keeps configurations organized and focused.

Configuration Structure

Figure 9 Configuration Class Hierarchy

Project Information

Basic project metadata:

# .aly/config.yaml
project:
  name: my_soc
  version: 1.0.0
  author: Your Name
  license: Apache-2.0
  description: My System-on-Chip design
  language: systemverilog

Field	Required	Description
name	Yes	Project identifier (alphanumeric, underscores)
version	No	Semantic version (default: “1.0.0”)
author	No	Project author or organization
license	No	License identifier (SPDX format)
description	No	Brief project description
language	No	Default HDL language (verilog, systemverilog, vhdl)

Feature Flags

Enable or disable project features:

features:
  firmware: true      # Enable firmware builds
  ip: true           # Enable IP management
  constraints: true  # Enable constraint management  (still under development)
  formal: false      # Enable formal verification    (still under development)
  coverage: false    # Enable coverage collection    (still under development)

Features affect which commands and configurations are available.

Path Configuration

Customize project directory structure:

paths:
  rtl: rtl              # RTL source directory
  testbench: tb         # Testbench directory
  firmware: fw          # Firmware directory
  ip: ip                # IP blocks directory
  constraints: constraints  # Constraints directory (still under development)
  build: build          # Build output directory

All paths are relative to the project root.

Default Tools

Set default tools for each workflow:

defaults:
  simulator: xsim      # Default simulator
  synthesizer: vivado  # Default synthesizer
  linter: verilator    # Default linter

Simulation Configuration

Configure simulation tools and options in .aly/sim.yaml:

 # .aly/sim.yaml
 default_tool: xsim
 language: systemverilog
 build_dir: build/sim
 waves: false
 verbosity: normal

 tools:
  # ---------------------------------------------------------------------------
  # Xilinx XSim
  # ---------------------------------------------------------------------------
  xsim:
    bin: xsim
    vlog: xvlog
    compile_opts:
      - "--sv"
      - "--relax"
    xelab: xelab
    elab_opts:
      - "--debug"
      - "typical"
      - "--relax"
    run_opts:
      - "--runall"

  # ---------------------------------------------------------------------------
  # Mentor Questa/ModelSim
  # ---------------------------------------------------------------------------
  questa:
    bin: vsim
    vlog: vlog
    vsim: vsim
    compile_opts:
      - "-sv"
      - "+acc"
      - "-timescale"
      - "1ns/1ps"
    run_opts:
      - "-do"
      - "run -all; quit"
    gui_opts:
      - "-do"
      - "add wave -r /*"

  modelsim:
    bin: vsim
    vlog: vlog
    vsim: vsim
    compile_opts:
      - "-sv"
      - "+acc"
      - "-timescale"
      - "1ns/1ps"
    run_opts:
      - "-do"
      - "run -all; quit"
    gui_opts:
      - "-do"
      - "add wave -r /*"

# ---------------------------------------------------------------------------
# Verilator (SystemVerilog/Verilog only)
# ---------------------------------------------------------------------------
verilator:
  bin: verilator
  args:
    - "--sv"
    - "--trace"
    - "--trace-fst"
    - "-Wall"
    - "--timing"

# ---------------------------------------------------------------------------
# Icarus Verilog (SystemVerilog/Verilog only)
# ---------------------------------------------------------------------------
iverilog:
  bin: iverilog
  vvp: vvp
  args:
    - "-g2012"
    - "-Wall"

Tool Options Reference

Option	Description
bin	Path to main tool binary (if not in path “some tools like xsim use this to find xsim path”)
vlog	Verilog/SV compiler (XSim, Questa)
xelab	Elaborator (XSim)
vsim	Simulator executable (Questa)
vvp	VVP runtime (Icarus)
compile_opts	Compilation flags
elab_opts	Elaboration flags
run_opts	Runtime flags
gui_opts	GUI mode flags
args	General arguments

Synthesis Configuration (still under development to be used for synth commands)

Configure synthesis tools and targets in .aly/synth.yaml:

# .aly/synth.yaml
default_tool: vivado
build_dir: build/synth

# Cell libraries (for ASIC flows)
libraries:
  sky130_hd:
    liberty: libs/sky130_fd_sc_hd__tt_025C_1v80.lib
    verilog: libs/sky130_fd_sc_hd.v
    lef: libs/sky130_fd_sc_hd.lef

# Tool configurations
tools:
  vivado:
    bin: vivado
    threads: 8
    batch_opts:
      - -mode
      - batch

  yosys:
    bin: yosys
    tech: generic
    script_ext: .ys

# Synthesis targets
targets:
  arty_a7:
    tool: vivado
    part: xc7a100tcsg324-1
    top: fpga_top
    constraints:
      - constraints/arty_a7.xdc
    options:
      strategy: Flow_PerfOptimized_high

  ice40:
    tool: yosys
    tech: ice40
    top: fpga_top

Synthesis Target Options

Option	Description
tool	Synthesis tool (vivado, yosys)
part	FPGA part number
tech	Technology target (Yosys: generic, ice40, ecp5, gowin)
library	Reference to cell library (ASIC)
top	Top-level module name
constraints	List of constraint files
options	Tool-specific options

Lint Configuration

Configure linting tools and rules in .aly/lint.yaml:

# .aly/lint.yaml
default_tool: verilator
severity: warning

tools:
  verilator:
    bin: verilator
    args:
      - --lint-only
      - -Wall
      - -Wno-fatal

  slang:
    bin: slang
    args:
      - --lint-only

rules:
  categories:
    style: true
    synthesis: true
    simulation: false

  enable:
    - UNUSED
    - WIDTH

  disable:
    - DECLFILENAME

waivers: # Under development: will be used later for waivers
  - "ip/**/*.v"           # Waive vendor IP
  - "**/deprecated/**"    # Waive deprecated code

Constraints Configuration (Under development)

Configure design constraints in .aly/constraints.yaml:

# .aly/constraints.yaml
default_target: arty_a7

sets:
  arty_a7:
    target: xc7a100tcsg324-1
    files:
      - constraints/arty_a7/pins.xdc
      - constraints/arty_a7/timing.xdc

  nexys_a7:
    target: xc7a100tcsg324-1
    files:
      - constraints/nexys_a7/pins.xdc

clocks:
  sys_clk:
    period: 10.0
    waveform: [0.0, 5.0]
    pin: E3

io_defaults:
  standard: LVCMOS33
  drive: 12
  slew: SLOW

FPGA Configuration (Under development to be used with the program/synth command)

Configure FPGA programming in .aly/fpga.yaml:

# .aly/fpga.yaml
default_board: arty_a7

boards:
  arty_a7:
    part: xc7a100tcsg324-1
    programmer: hw_server
    bitstream: build/synth/vivado/fpga_top.bit

  nexys_a7:
    part: xc7a100tcsg324-1
    programmer: hw_server

Toolchain Configuration

Configure firmware toolchains in .aly/toolchains.yaml:

# .aly/toolchains.yaml
default: riscv64

toolchains:
  riscv64:
    prefix: riscv64-unknown-elf-
    cc: gcc
    ld: ld
    as: as
    objcopy: objcopy
    objdump: objdump
    size: size

    # Default flags
    cflags:
      - -march=rv64imac
      - -mabi=lp64
      - -Wall
    asflags:
      - -march=rv64imac
    ldflags:
      - -nostartfiles
  riscv32:
    prefix: riscv32-unknown-elf-
    march: rv32i
    mabi: ilp32
    cflags:
      - -O2
      - -g
      - -Wall
    ldflags:
      - -nostdlib
  arm:
    prefix: arm-none-eabi-
    cc: gcc
    ld: ld
    as: as
    objcopy: objcopy
    objdump: objdump
    size: size

    cflags:
      - -mcpu=cortex-m4
      - -mthumb
      - -Wall

Complete Example

Here’s a complete main configuration file:

# .aly/config.yaml

project:
  name: my_riscv_soc
  version: 1.0.0
  author: Mohamed Aly
  license: Apache-2.0
  language: systemverilog

features:
  firmware: true
  ip: true
  constraints: true
  formal: false

paths:
  rtl: rtl
  testbench: tb
  firmware: fw
  ip: ip
  constraints: constraints
  build: build

defaults:
  simulator: xsim
  synthesizer: vivado
  linter: verilator

And a companion simulation configuration:

# .aly/sim.yaml

default_tool: xsim
waves: true
build_dir: build/sim

tools:
  xsim:
    bin: xsim
    vlog: xvlog
    xelab: xelab
    compile_opts: [-sv, -d SIMULATION]
    elab_opts: [-debug typical]
    run_opts: [-runall]

  verilator:
    bin: verilator
    args: [--binary, --trace, -Wall, --timing]

Next Steps

• Manifest System - Component manifest reference

• Command Reference - CLI command reference

• Examples - Example configurations