IP Management (Under Development for Enhanced Features)

This guide covers managing IP blocks in ALY projects.

Overview

ALY supports various IP types:

Figure 22 IP Types

IP Directory Structure

ip/
+-- uart/
|   +-- manifest.yaml
|   +-- rtl/
|   |   +-- manifest.yaml
|   |   +-- uart_tx.sv
|   |   +-- uart_rx.sv
|   +-- tb/
|   |   +-- manifest.yaml
|   |   +-- tb_uart.sv
|   +-- doc/
|       +-- uart_spec.pdf
+-- spi/
|   +-- manifest.yaml
|   +-- rtl/
|   |   +-- manifest.yaml
|   +-- tb/
|   |   +-- manifest.yaml
+-- vendor_fifo/
    +-- manifest.yaml
    +-- models/
        +-- fifo_sim.o # Precompiled simulation model (still under development)

Creating IP

Basic IP Manifest

# ip/uart/manifest.yaml
name: uart
type: ip
version: 1.0.0
vendor: internal
license: Apache-2.0

language: systemverilog

files:
  - rtl/uart_tx.sv
  - rtl/uart_rx.sv
  - rtl/uart_fifo.sv

includes:
  - rtl/include

parameters:
  BAUD_RATE: 115200
  DATA_BITS: 8
  STOP_BITS: 1
  PARITY: none

interfaces:
  - name: tx
    direction: output
    width: 1
  - name: rx
    direction: input
    width: 1
  - name: interrupt
    direction: output
    width: 1

tags:
  - uart
  - serial
  - communication

Vendor IP

# ip/xilinx_fifo/manifest.yaml
name: xilinx_fifo
type: ip
version: 2.1
vendor: xilinx
license: Proprietary

# Precompiled simulation model
binaries:
  simulation: models/fifo_sim.o

compatibility:
  tools:
    - xsim
    - questa
  languages:
    - verilog
    - systemverilog

parameters:
  DEPTH: 512
  WIDTH: 32
  ALMOST_FULL_OFFSET: 16
  ALMOST_EMPTY_OFFSET: 16

Complex IP with Nested Manifests

# ip/dma_engine/manifest.yaml
name: dma_engine
type: ip
version: 1.0.0
vendor: internal

# Reference nested manifests
rtl_manifest: rtl/manifest.yaml
tb_manifest: tb/manifest.yaml
fw_manifest: fw/manifest.yaml

parameters:
  CHANNELS: 4
  MAX_BURST: 256

CLI Commands

List IP

aly ip list

Output:

Available IP:
  uart          v1.0.0  internal    UART controller
  spi           v1.0.0  internal    SPI master
  xilinx_fifo   v2.1    xilinx      FIFO generator

Show IP Details

aly ip show uart

Output:

IP: uart
Version: 1.0.0
Vendor: internal
License: Apache-2.0

Files:
  - rtl/uart_tx.sv
  - rtl/uart_rx.sv
  - rtl/uart_fifo.sv

Parameters:
  BAUD_RATE: 115200
  DATA_BITS: 8
  STOP_BITS: 1
  PARITY: none

Interfaces:
  - tx (output, 1 bit)
  - rx (input, 1 bit)
  - interrupt (output, 1 bit)

Using IP in Projects

Reference in RTL Manifest

# rtl/manifest.yaml
modules:
  - name: soc_top
    top: soc_top
    files:
      - soc_top.sv
    dependencies:
     - name: ip_counter
       type: rtl
     - name: ip_uart
       type: rtl

Reference in Testbench

# tb/manifest.yaml
testbenches:
  - name: tb_uart
    top: tb_uart
    files:
      - tb_uart.sv
    dependencies:
     - name: ip_uart
       type: rtl

IP Discovery

ALY automatically discovers IP in the ip/ directory:

Figure 23 IP Discovery Flow

IP with Internal Structure

For complex IP, use nested manifests:

ip/dma_engine/
+-- manifest.yaml           # Main IP manifest
+-- rtl/
|   +-- manifest.yaml       # RTL manifest
|   +-- dma_core.sv
|   +-- dma_channel.sv
|   +-- axi_master.sv
+-- tb/
|   +-- manifest.yaml       # Testbench manifest
|   +-- tb_dma.sv
+-- fw/
    +-- manifest.yaml       # Firmware manifest
    +-- dma_driver.c
    +-- dma_driver.h

Main manifest references nested:

# ip/dma_engine/manifest.yaml
name: dma_engine
type: ip
version: 1.0.0

rtl_manifest: rtl/manifest.yaml
tb_manifest: tb/manifest.yaml
fw_manifest: fw/manifest.yaml

Binary IP

For IP with precompiled simulation models:

name: vendor_pcie
type: ip
vendor: vendor_name
license: Proprietary

# No RTL files - binary only
binaries:
  simulation: models/pcie_bfm.o
  synthesis: netlist/pcie_core.edif

compatibility:
  tools:
    - xsim
    - questa

Check for binary models:

from aly.config.models import IPManifest

ip = IPManifest.load("ip/vendor_pcie/manifest.yaml")

if ip.has_simulation_model():
    print("Using precompiled model")

IP Parameters

Define configurable parameters:

parameters:
  DATA_WIDTH:
    type: integer
    default: 32
    range: [8, 64]
    description: Data bus width

  DEPTH:
    type: integer
    default: 256
    values: [128, 256, 512, 1024]
    description: FIFO depth

  MODE:
    type: string
    default: "sync"
    values: ["sync", "async"]
    description: Clock mode

Override in instantiation:

uart #(
    .BAUD_RATE(9600),
    .DATA_BITS(8)
) u_uart (
    .clk(clk),
    .rst_n(rst_n),
    // ...
);

IP Interfaces

Document interfaces:

interfaces:
  - name: s_axi
    type: axi4_lite
    direction: slave
    description: Configuration interface

  - name: m_axi
    type: axi4
    direction: master
    description: Data interface

  - name: irq
    direction: output
    width: 4
    description: Interrupt outputs

Best Practices

1. Version your IP: Use semantic versioning

2. Document parameters: Include descriptions and valid ranges

3. Include testbenches: Provide self-test capability

4. Specify compatibility: List supported tools and languages

5. License clearly: Specify license for each IP

# Well-documented IP manifest
name: axi_interconnect
type: ip
version: 2.1.0
vendor: internal
license: Apache-2.0
description: |
  AXI4 crossbar interconnect with configurable
  master/slave ports and address mapping.

maintainers:
  - name: John Doe
    email: john@example.com

tags:
  - axi
  - interconnect
  - noc

discoverable: true

Next Steps

• Manifest System - Full manifest reference

• Simulation - Simulating with IP

• Synthesis (Under Development for Enhanced Features) - Synthesizing with IP