mosaic-flow

Shared RTL quality and implementation methodology for MOSAIC repositories. It provides one versioned interface for open-source CI checks and licensed local implementation flows.

Modular repositories consume mosaic-flow at a pinned Git revision, normally as an in-tree mosaic-flow/ submodule. Updating that pointer upgrades the methodology without copying flow scripts or changing module RTL.

What belongs here

mosaic-flow owns reusable methodology:

• Make targets and flow dependency orchestration
• Open-source and Synopsys tool adapters
• Optional PyUVM verification with open-source, VCS, and Xcelium backends
• Single-module and manifest-based multi-module project orchestration
• Named parameter-profile qualification across elaboration and implementation
• Declarative HDL and formal coverage qualification with reviewed exclusions
• Declarative negative-test and four-state qualification with explicit controls
• Declarative, license-independent SDC and UPF intent validation
• Reproducible local or pinned-container ORFS implementation with declarative physical evidence
• Flow selection, statuses, reports, and quality gates
• Schema-validated release evidence with input hashes and tool identities
• Pinned open-source tool installers and versions
• Methodology CI and its independent fixture module

The consuming module owns RTL, verification, file lists, constraints, waivers, formal properties, power intent, and design-specific flow configuration.

Documentation

The documentation index is the detailed entry point for new users and contributors. It provides a recommended reading order, a command reference, and links to:

• Repository architecture and ownership boundaries
• Consumer setup and configuration overrides
• PyUVM, SVA, and coverage reuse across verification environments
• Every open-source and commercial flow
• Results, quality gates, waivers, and release evidence
• Portable SDC and UPF intent checks and their signoff boundary
• Containerized OpenROAD execution and physical evidence policy
• Methodology development, qualification, and release procedures

Consumer quick start

From a module repository with the submodule already configured:

git submodule update --init --recursive
make flow-config-check
make open-source

The module's thin Makefile imports the shared API:

export MODULE_ROOT := $(CURDIR)
export FLOW_ROOT ?= $(abspath $(MODULE_ROOT)/mosaic-flow)

include config/design.mk
include $(FLOW_ROOT)/config/tools.mk
include $(FLOW_ROOT)/mk/module.mk

A repository containing multiple independently qualified modules instead uses the project bootstrap and a validated module manifest:

include $(FLOW_ROOT)/mk/project.mk

See Getting started for the complete module contract and Multi-module projects for registry, selection, concurrent execution, and CI matrix guidance. Parameterizable RTL can use Parameter profiles to qualify independent elaborations without duplicating flow scripts.

Methodology validation

Before releasing a change to this repository, run its static checks and the complete portable fixture flow:

ci/install_ci_tools.sh "$HOME/.local"
PATH="$HOME/.local/bin:$PATH" ci/check_flow_quality.sh
make -C tests/fixture-module FLOW_ROOT="$PWD" clean open-source
make -C tests/fixture-multi-module FLOW_ROOT="$PWD" clean all-modules MODULE_JOBS=2
make -C tests/fixture-parameter-profiles FLOW_ROOT="$PWD" clean all-profiles PROFILE_JOBS=4
tests/test_release_manifest.sh

GitHub Actions runs the same validation on pushes and pull requests. Commercial Synopsys tools are not run on GitHub-hosted runners. Release-specific commercial adapters must be configured and qualified in the licensed local environment.

See Methodology development for the full contribution and release checklist.