Documentation

The ip.yaml manifest is the foundation of every package in the ipkg registry. It describes your IP in a portable, target-agnostic format that tools and engineers can understand.

What is ip.yaml?

The ip.yaml file is a machine-readable manifest that describes your hardware IP. It captures metadata, interfaces, parameters, and build targets in a single file. This enables automated discovery, dependency resolution, and build verification across the ecosystem.

Required Fields

Field	Type	Description
name	string	Unique package identifier using dot notation (e.g., acme.stream.sha256)
version	string	Semantic version (e.g., 1.4.2, 2.0.0-beta)
license	string	SPDX license identifier (e.g., MIT, Apache-2.0)
description	string	Brief description of the IP functionality
interfaces	object	Map of interface definitions with type, role, and width
targets	array	List of supported build targets (e.g., vivado, yosys, sky130)

Optional Fields

Field	Type	Description
author	string	Author or organization name
repository	string	URL to source repository
parameters	object	Configurable parameters with types, defaults, and constraints
dependencies	object	Map of required packages with version constraints
clock_domains	array	List of clock domain descriptions
reset	string	Reset semantics (e.g., sync_high, async_low)
verification	object	Test suites, simulators, and coverage information

Examples

Minimal Example

yaml

name: myorg.util.fifo
version: 1.0.0
license: MIT
description: Simple synchronous FIFO

interfaces:
  write:
    type: valid-ready
    role: slave
    width: 32
  read:
    type: valid-ready
    role: master
    width: 32

targets:
  - vivado
  - yosys

Full Example

yaml

name: acme.stream.aes256
version: 2.1.0
license: Apache-2.0
author: ACME Silicon Labs
repository: https://github.com/acme/aes256

description: >
  AES-256 encryption engine with AXI4-Stream
  interface. Supports ECB, CBC, and CTR modes.

interfaces:
  s_axis_data:
    type: axi4-stream
    role: slave
    width: 128
  m_axis_data:
    type: axi4-stream
    role: master
    width: 128
  s_axis_key:
    type: axi4-stream
    role: slave
    width: 256
  ctrl:
    type: axi-lite
    role: slave
    width: 32

parameters:
  MODE:
    type: string
    default: CBC
    values: [ECB, CBC, CTR]
  PIPELINE_STAGES:
    type: integer
    default: 4
    range: [1, 10]
  KEY_EXPANSION:
    type: string
    default: ON_FLY
    values: [ON_FLY, PRECOMPUTED]

dependencies:
  acme.util.sbox: ^1.2.0
  acme.stream.common: ^2.0.0

clock_domains:
  - Single clock domain (data and control)

reset: sync_high

verification:
  tests:
    - NIST Known Answer Tests
    - Random vector tests
    - Mode switching
  simulators:
    - verilator
    - iverilog
  coverage: 96% line coverage

targets:
  - vivado
  - quartus
  - yosys

Supported Interface Types

axi4

Full AXI4 bus interface

axi4-stream

AXI4-Stream for data flow

axi-lite

Lightweight control interface

apb

AMBA APB peripheral bus

wishbone

Open-source SoC interconnect

valid-ready

Simple handshaking protocol

uart

Serial UART interface

spi

SPI master/slave

i2c

I2C controller interface