Skip to content

Building and Managing PDKs

This guide covers strategies for organizing PDK repositories and managing tapeouts over time. Choosing the right structure early prevents maintenance headaches as your team scales across multiple tapeouts.

The problem

A PDK is a living codebase: it evolves with each tapeout, but completed tapeouts must stay frozen so they remain reproducible. Balancing evolution with reproducibility is the central challenge.

Repository structures

There are three common approaches, each with different tradeoffs.

1. Mutable PDK in monorepo (worst option)

A single repository where the PDK and each tapeout live as sibling directories, with the PDK as the shared, evolving source of truth.

pdk-repo/
    pdk/                # Plan of record (evolves)
    tapeout1/
        tapeout1_files/
    tapeout2/
        tapeout2_files/

Use branches or tags (_v1, _v2, _v3) to snapshot PDK state for each tapeout.

Pros:

  • Single location for all files — easy to tell people where to look.

Cons:

  • The repo becomes a monolith that is hard to maintain.
  • Completed tapeouts can break when the PDK evolves.
  • Many open issues, pull request and branches accumulate, making the repo hard to navigate and archive.
  • Makes pdk management and reproducibility difficult. Specially if you start adding new layers or experimental components.
  • Hard to update dependencies of the tools used in the PDK (e.g., gdsfactory, SAX, etc.) without breaking existing tapeouts.

2. New PDK per tapeout in monorepo

Similar to the complex monorepo, but each tapeout directory includes its own frozen copy of the PDK.

pdk-repo/
    pdk/                    # Plan of record (evolves)
    tapeout1/
        pdk/                # Frozen after tapeout1 is done
        tapeout1_files/
    tapeout2/
        pdk/                # May diverge from tapeout1's copy
        tapeout2_files/

Pros:

  • Single location for all files.
  • Each tapeout has its own PDK snapshot.

Cons:

  • Tends to get messy over time (many open Pull requests and issues).

Each tapeout lives in its own repository with an independent copy of the PDK. A shared CI/CD repo provides common tooling.

repo1: tapeout1/
    pdk/              # Frozen after tapeout1 is done
    tapeout1_files/
repo2: tapeout2/
    pdk/              # Frozen after tapeout2 is done
    tapeout2_files/
repo3: pdk/           # Plan of record PDK (Optional) Evolves over time

Pros:

  • Completed tapeout repos can be archived and will always work. Easy to reproduce results.
  • Improvements from any tapeout can be selectively copied back on an optional plan of record PDK repo.
  • Each repo stays focused and manageable.

Cons:

  • Files are spread across multiple repos. Ideally someone keeps documenation of the order of the tapeouts.
  • Requires maintenance of the centralized CI/CD repo.
  1. Start from the PDK repo. Develop and iterate on the plan-of-record PDK.
  2. Copy plan of record PDK for each tapeout. When a tapeout begins, create a new repo (e.g., tapeout-<name>) with a copy of the current PDK.
  3. Freeze on completion. After tapeout is done, archive the repo. The frozen PDK and locked dependencies ensure reproducibility. You can still use tags and releases to add comments and metadata. (like sent to foundry, re-worked metallization, etc.)
  4. Backport improvements. Copy relevant improvements from tapeout repos back into the main PDK repo for future tapeouts.
  5. Use XOR regression tests. Each tapeout repo should include regression tests to catch unintended layout changes.

Naming conventions

Use a consistent naming scheme for tapeout repos:

tapeout-<name>          # e.g., tapeout1, tapeout2, ...

Link tapeout repos from the main PDK repo's README so the full history is easy to navigate.

Extra files to include

repo: tapeout1/
    pdk/                    # Frozen after tapeout1 is done
    tapeout1_files/
    docs/ # documentation for the tapeout, including jupyter notebooks and other design documents
    tests/ # regression tests, with XOR comparisons to catch unintended layout changes
    pyproject.toml # with pinned dependencies. gdsfactory==9.43.0, ...
    uv.lock # with pinned dependencies