Core Concepts

Understanding ALY’s core concepts will help you effectively manage your HDL projects.

Project Structure 

An ALY project follows a hierarchical structure with clear separation of concerns:

Figure 2 ALY Project Structure

Manifest System 

ALY uses YAML manifests to describe project components. Each component type has its own manifest format.

@startuml
skinparam backgroundColor transparent
skinparam defaultFontName sans-serif

package "Project" {
[config.yaml] as config
}

package "RTL" {
[rtl/manifest.yaml] as rtl
[RTLModule] as rtlmod
}

package "Testbench" {
[tb/manifest.yaml] as tb
[Testbench] as tbmod
[TestSuite] as suite
}

package "Firmware" {
[fw/manifest.yaml] as fw
[FirmwareBuild] as fwbuild
}

package "IP" {
[ip/*/manifest.yaml] as ip
[IPManifest] as ipmod
}

config --> rtl : references
config --> tb : references
config --> fw : references

rtl --> rtlmod : defines
tb --> tbmod : defines
tb --> suite : groups
fw --> fwbuild : defines
ip --> ipmod : defines

tbmod --> rtlmod : depends on
tbmod --> fwbuild : may include
@enduml — Figure 3 Manifest Hierarchy

Manifest Types 

Type	Purpose	Key Fields
`rtl`	RTL source code	`modules`, `packages`, `includes`
`testbench`	Simulation testbenches	`testbenches`, `test_suites`, `rtl_deps`
`firmware`	Embedded firmware	`builds`, `toolchain`, `outputs`
`ip`	Vendor IP blocks	`files`, `binaries`, `interfaces`

RTL Modules 

RTL modules represent synthesizable hardware blocks. They can be organized hierarchically.

Module Definition 

# rtl/manifest.yaml
name: my_design
type: rtl
language: systemverilog

modules:
  - name: alu
    top: alu
    files:
      - alu.sv
      - adder.sv
      - shifter.sv
  - name: register_file
    top: register_file
    files:
      - register_file.sv
  - name: cpu_core
    top: cpu_core
    files:
      - cpu_core.sv
    dependencies:
     - name: rv64i_pkg
       type: package
     - name: alu
       type: rtl
     - name: register_file
       type: rtl

Module Hierarchy 

Figure 4 Module Dependency Graph

File Resolution 

ALY supports multiple ways to specify source files:

modules:
  - name: design
    files:
      # Direct file paths
      - core.sv
      - utils/helpers.sv

      # Glob patterns
      - "*.sv"
      - "subdir/**/*.v"

Testbenches 

Testbenches define simulation environments and test cases.

# tb/manifest.yaml
name: my_tests
type: testbench
language: systemverilog

testbenches:
  - name: tb_alu
   description: ALU unit test
   top: tb_alu
   files:
     - tb_alu.sv
   dependencies:
     - name: alu
       type: rtl
     - name: rv64i_pkg
       type: package
   default_timeout: 10000
   tags: [unit, alu]
   - name: tb_cpu
     description: CPU core integration test
     top: tb_cpu
     files:
       - tb_cpu.sv
     dependencies:
       - name: cpu_core
         type: rtl
       - name: boot
         type: firmware
       - name: core_pkg
         type: package
     default_timeout: 50000
     tags: [integration, cpu]

test_suites:
  - name: regression
    testbenches:
      - tb_alu
      - tb_cpu
    parallel: 4 # Number of parallel jobs

Dependency Types 

@startuml
skinparam backgroundColor transparent
skinparam defaultFontName sans-serif

rectangle "Testbench" as TB {
component "tb_cpu.sv" as tb
}

rectangle "RTL Dependencies" as RTL {
component "cpu_core" as cpu
component "alu" as alu
}

rectangle "Firmware" as FW {
component "boot.hex" as boot
}

rectangle "Packages" as PKG {
component "core_pkg" as uvm
}

tb --> cpu : rtl_deps
tb --> boot : fw_deps
tb --> uvm : pkg_deps
cpu --> alu : internal
@enduml — Figure 5 Testbench Dependencies

Firmware Builds 

Firmware manifests define embedded software builds for processor cores.

 # fw/manifest.yaml
  name: instr_test
  type: firmware
  author: Mohamed Aly
  version: 1.0.0

  toolchain: riscv64

  builds:
    # ASM builds
    - name: allinstructions
      languages: [asm]
      sources: [allinstructions.asm]
      includes: [include/]
      linker_script: linkers/memory.ld
      flags:
        common: [-fno-builtin, -nostdlib]
        asm: [-x]
        ld: [-nostartfiles]
      outputs:
        - format: elf

        - format: mem

          plusarg: MEM_FILE
      mem:
        - name: memory_le.mem
          format: mem
          word_width: 64
          byte_order: little
    - name: instr01loadbyte
  languages: [asm]
  sources: [instr01loadbyte.asm]
  includes: [include/]
  linker_script: linkers/memory.ld
  flags:
    common: [-fno-builtin, -nostdlib]
    asm: [-x]
    ld: [-nostartfiles]
  outputs:
    - format: elf

    - format: mem

      plusarg: MEM_FILE
  mem:
    - name: memory_le.mem
      format: mem
      word_width: 64
      byte_order: little


- name: instr02loadhalf
  languages: [asm]
  sources: [instr02loadhalf.asm]
  includes: [include/]
  linker_script: linkers/memory.ld
  flags:
    common: [-fno-builtin, -nostdlib]
    asm: [-x]
    ld: [-nostartfiles]
  outputs:
    - format: elf

    - format: mem

      plusarg: MEM_FILE
  mem:
    - name: memory_le.mem
      format: mem
      word_width: 64
      byte_order: little

Build Pipeline 

@startuml
skinparam backgroundColor transparent
skinparam defaultFontName sans-serif

start
:Source Files (.c, .S);
:Compile (GCC);
:Object Files (.o);
:Link (linker.ld);
:ELF Binary;

fork
:objcopy;
:Binary (.bin);
fork again
:objcopy;
:Intel HEX (.hex);
fork again
:Custom Script;
:Verilog MEM (.mem);
end fork

stop
@enduml — Figure 6 Firmware Build Flow

IP Management 

IP blocks represent reusable or vendor-provided components.

# ip/uart/manifest.yaml
name: uart_ip
type: ip
vendor: xilinx
description: Parameterized UART IP Core
version: 1.0.0

parameters:
  BAUD_RATE: 115200
  DATA_WIDTH: 8

IP Types 

Figure 7 IP Classification

Build System 

ALY manages build artifacts in a structured output directory.

build/
+-- sim/                    # Simulation outputs
|   +-- xsim/              # XSim-specific files
|   +-- verilator/         # Verilator-specific files
+-- synth/                  # Synthesis outputs
|   +-- vivado/            # Vivado project files
|   +-- yosys/             # Yosys outputs
+-- fw/                     # Firmware outputs
    +-- bootloader/        # Per-build outputs

Backend Architecture 

@startuml
skinparam backgroundColor transparent
skinparam defaultFontName sans-serif

interface "SimulatorBackend" as sim
interface "SynthBackend" as synth

class XSimBackend
class QuestaBackend
class VerilatorBackend

class VivadoBackend
class YosysBackend

sim <|.. XSimBackend
sim <|.. QuestaBackend
sim <|.. VerilatorBackend

synth <|.. VivadoBackend
synth <|.. YosysBackend
@enduml — Figure 8 Tool Backend System

Next Steps 

Configuration - Detailed configuration options
Manifest System - Complete manifest reference
Architecture - Internal architecture details