Vyges Metadata Specification

Overview

The Vyges Metadata Specification defines a standardized way to describe hardware IP blocks, enabling discovery, validation, and integration across the semiconductor ecosystem.

This specification serves as both a technical reference and a manifesto for how hardware IP should be documented, shared, and consumed in the modern era.

Discovery

Enable search and discovery of IP blocks across repositories and platforms

Validation

Provide automated validation of IP quality, compliance, and completeness

Integration

Enable seamless integration with EDA tools, build systems, and workflows

Manifesto

The Case for Standardized Hardware IP Metadata

Hardware development is stuck in the 1990s. While software has evolved to use package managers, dependency resolution, and automated testing, hardware IP remains fragmented, undocumented, and difficult to discover.

The Vyges Metadata Specification represents a fundamental shift in how we think about hardware IP. It's not just a technical standard—it's a declaration that hardware development deserves the same level of tooling, automation, and community support that software development has enjoyed for decades.

Our Vision

• Democratization: Make hardware IP accessible to everyone, from students to startups to established companies
• Automation: Eliminate manual processes through standardized metadata and automated tooling
• Trust: Build confidence through validation, verification, and community-driven quality metrics
• Interoperability: Enable seamless integration across tools, platforms, and workflows

This specification is the foundation of a new era in hardware development—one where innovation is limited only by imagination, not by tooling or documentation.

Schema Reference

Basic Structure

Every Vyges IP block must include a vyges-metadata.json file at the root of the repository with the following structure:

{
  "$schema": "https://vyges.com/schema/v1/vyges-metadata.schema.json",
  "name": "string",
  "x-version": "string",
  "version": "string",
  "description": "string",
  "license": "string",
  "maturity": "string",
  "target": "array",
  "design_type": "array",
  "interfaces": "array",
  "template": "string",
  "dependencies": "array",
  "parameters": "array",
  "source": "object",
  "test": "object",
  "flows": "object"
}

Required Fields

name

The name of the IP block (must be unique within the repository)

"pwm-controller"

x-version

Schema version - indicates which version of the Vyges Metadata Schema this metadata file conforms to

"1.0.0"

version

Semantic version of the IP block - used for dependency resolution and downloading specific versions

"1.0.0"

description

Human-readable description of the IP block's functionality

"Configurable PWM controller with multiple channels"

license

SPDX-compatible license identifier

"Apache-2.0" | "MIT" | "CERN-OHL-S" | "Proprietary"

maturity

Development stage and readiness level

"prototype" | "alpha" | "beta" | "production" | "deprecated"

target

Target platforms this IP supports

["asic"] | ["fpga"] | ["asic", "fpga"]

design_type

Design types this IP supports

["digital"] | ["analog"] | ["mixed-signal"] | ["hard-ip"]

License Classification

The license object provides structured information about IP licensing and compliance:

{
  "type": "Apache-2.0",
  "compliance": "permissive",
  "url": "https://opensource.org/licenses/Apache-2.0",
  "file": "LICENSE"
}

Permissive

MIT, BSD, Apache (easy to use, minimal restrictions)

Reciprocal

LGPL, MPL (moderate restrictions, source sharing)

Copyleft

GPL, AGPL (strong restrictions, full source sharing)

Build Configuration

The build object defines how the IP block should be built and integrated:

{
  "simulator": "iverilog",
  "entry": "tb/tb_top.v",
  "run": "make test",
  "targets": ["simulation", "synthesis", "formal"],
  "dependencies": ["other-ip-block@1.0.0"]
}

Examples

PWM Controller Example

{
  "$schema": "https://vyges.com/schema/v1/vyges-metadata.schema.json",
  "name": "vyges/pwm-controller",
  "x-version": "1.0.0",
  "version": "1.0.0",
  "description": "Configurable PWM controller with multiple channels and precise frequency control",
  "license": "Apache-2.0",
  "maturity": "production",
  "target": ["asic", "fpga"],
  "design_type": ["digital"],
  "template": "vyges-ip-template@1.0.0",
  "interfaces": [
    {
      "type": "bus",
      "direction": "input",
      "protocol": "APB",
      "width": 32,
      "signals": [
        {
          "name": "PCLK",
          "direction": "input",
          "type": "clock",
          "description": "APB clock signal"
        },
        {
          "name": "PRESETn",
          "direction": "input",
          "type": "reset",
          "active_level": "low",
          "description": "APB reset signal"
        }
      ]
    }
  ],
  "parameters": [
    {
      "name": "CHANNELS",
      "type": "int",
      "default": 4,
      "description": "Number of PWM channels",
      "range": { "min": 1, "max": 16 },
      "units": "channels"
    },
    {
      "name": "FREQ_WIDTH",
      "type": "int",
      "default": 16,
      "description": "Frequency control width in bits",
      "range": { "min": 8, "max": 32 },
      "units": "bits"
    }
  ],
  "source": {
    "type": "git",
    "url": "https://github.com/vyges/pwm-controller",
    "commit": "main",
    "private": false,
    "containsEncryptedPayload": false
  },
  "test": {
    "status": "passing",
    "testbenches": ["cocotb"],
    "simulators": ["verilator"]
  },
  "flows": {
    "verilator": { "status": "verified" },
    "openlane": { "status": "tested", "pdks": ["sky130B"] }
  }
}