Layout Knowledge Base

Hierarchy · Files

Naming the top cell you ship

A top cell is a cell that no other cell places; a mask shop or shuttle builds from exactly one, under the name it asks for, and a GDSII file has no record that marks it.

Last edited: November 5, 2026

LayoutEditor window with metal 1 and metal 2 routing of a SKY130 encoder block and the Cell Hierarchy dock on the right, which lists via cells, encoder_top, and standard cells, each marked (*) as a top cell

A top cell is a cell that no other cell in the file places. Everything a top cell places, directly or through its children, belongs to its hierarchy; everything else in the file does not. A mask shop or a shuttle service builds the masks from exactly one top cell, and it needs that cell's name, because a GDSII file contains no record that marks one cell as the design. A file with one top cell under the agreed name is unambiguous. A file with several top cells, or with one top cell under another name, leaves the choice to the receiving program or stops the submission.

The picture at the top is a LayoutEditor window with a routed SkyWater SKY130 encoder block, saved after the standard-cell LEF file, the standard-cell GDS file, and the routed DEF file were imported in one session. Blue is metal 1, orange is metal 2, the dark squares are vias, and the thin lines are outline shapes that the LEF import writes for each standard cell. The panel on the right is the Cell Hierarchy dock, which marks every top cell with (*). The design cell encoder_top is selected. Above it are via cells that the design does not use; below it are standard cells. This file contains 910 cells, and 845 of them are top cells.

No record marks the top cell

A GDSII file is a library: a header, the units, and a list of structures (cells). Each structure has a name in its STRNAME record and contains shapes and references. A reference (SREF) or an array reference (AREF) names another structure in its SNAME record. The record list of the Calma format has no entry for "top structure". A program that needs the top cell builds the reference graph and takes the structures that no SNAME names.

Several top cells are normal in some files. The SKY130 high-density standard-cell library GDS contains 446 cells, and 442 of them are top cells: each standard cell stands alone, and only the spare-cell macro places four other cells. A design file for a mask or a shuttle slot is different. It has one cell that represents the chip or the block, and every other cell is used below it.

LayoutEditor reports top cells in two places. The Cell Hierarchy dock marks them with (*) and shows the number of placements of each child in parentheses; a right-click on an empty part of the toolbar area opens the list in which the dock is switched on. The LayoutScript function findTopCell() returns one cell that no other cell refers to. In a file with several top cells it returns one of them and gives no indication that others exist.

What the receiver asks for

The receiver states which cell it builds from, and the name rules differ:

Receiver Requirement (from the published instructions)
Mask writing, HKUST Nanosystem Fabrication Facility "provide the information about the top cellname for each layer of mask"
Photomask order form quoted by the UCSB Nanofab "Topcell Structure Name: The Name of the Cell in the GDS file that contains the data to be printed on the mask"
Mask definition form, Bonda Technology field "Top cell name" next to file name, layer number, and tone
Caravel user project (cf-precheck) file gds/<name>.gds with top cell user_project_wrapper, or user_analog_project_wrapper and others by project type
Tiny Tapeout top module name starts with tt_um_, equals the GDS file name without extension and the top_module entry in info.yaml
CORNERSTONE silicon nitride MPW top cell name Cell0_[Name of Institution]
SOIPIX MPW top cell top_<chip ID>_<chip name>, with top in lower case
IHP Open-Silicon MPW top cell name and seal-ring size in doc/info.json; all main views of the final cell carry the same name, for example OTA1336.gds and OTA1336.sch

A mask shop that receives a file with several top cells and no name in the order must choose one. What a photomask is describes the result when it chooses an empty frame cell.

What shuttle prechecks report

Shuttle prechecks test the top cell before any design-rule check. The messages below are quoted from the source code of the two open prechecks, cf-precheck (commit 6c401ed) and the Tiny Tapeout precheck (commit 01d5d28):

Precheck Condition Message
cf-precheck topcell_check no top cell No top cell found in the GDS layout
cf-precheck topcell_check more than one top cell Multiple top cells found in the GDS layout: [...]
cf-precheck XOR step required cell missing Top cell name user_project_wrapper not found
cf-precheck illegal_cellname_check # or / in a cell below the top Found '#' in subcell: ...
Tiny Tapeout more than one top cell GDS top level not unique
Tiny Tapeout one top cell with another name Top macro name mismatch: expected tt_um_..., got ...
Tiny Tapeout # or / in any cell name Cell name ... contains invalid character '#'

The cf-precheck documentation describes topcell_check as a validation of the top cell name; the code counts top cells only, and the name is tested in the XOR step. An empty unreferenced cell counts as a top cell in both prechecks.

Legal cell names

The Calma format allows structure names of up to 32 characters from the set A–Z, a–z, 0–9, underscore, question mark, and dollar sign. Both prechecks reject # and / and test no other character and no length. Current libraries exceed the length limit: 34 cell names in the SKY130 high-density library GDS are longer than 32 characters, the longest has 49, and neither precheck tests the length.

LayoutEditor keeps a # in a cell name when it opens and saves a file. A name with # must therefore be changed in the layout before submission. The new name must also be used in every other view of the block: the netlist used for LVS, the Verilog module, and the LEF macro. Tiny Tapeout compares the GDS top cell with the module name from info.yaml, and IHP asks for the same name across all views.

Where extra top cells come from

An extra top cell is created by any operation that leaves a cell without a reference:

  • a test or scratch cell drawn next to the design and never placed;
  • an empty cell, for example one created by a command and then left unused;
  • child cells after flattening: flattening shows that the children remain in the library without references;
  • an import that brings in a cell whose name already exists in the layout.

The last case produced the file in the lead picture. When LayoutEditor imports a GDS file into a layout that already has a cell of the same name, the existing cell keeps the name and its placements, and the imported cell is renamed with a 1 appended. In a minimal test, a layout with cell nand2 imported a second file with its own nand2; the result contained nand2, still placed by the top cell, and an unplaced nand21. In the encoder file, the cell LEF had already created all 437 standard cells as abstracts, so the 437 cells from the standard-cell GDS arrived as renamed copies such as sky130_fd_sc_hd__nand2_11. 433 of them are top cells; the other four are placed inside the renamed spare-cell macro.

LayoutEditor window zoomed into rows of standard cells of the encoder: teal local-interconnect shapes, blue metal 1 rails and wires, orange metal 2, black vias, no diffusion or polysilicon; on the right the Cell Hierarchy dock expanded under encoder_top with placement counts

The second picture shows the same file zoomed into the standard-cell rows, with the dock expanded under encoder_top. The numbers in parentheses are placements: 2149 of the via cell M1M2_PR, 74 of the flip-flop sky130_fd_sc_hd__dfrtp_1, and 48 of sky130_fd_sc_hd__nand2_1. The cells inside the rows contain only abstract shapes from the cell LEF: local interconnect (teal) and metal 1 pins and obstructions. Diffusion, polysilicon, and contacts are absent; they exist only in the renamed copies, which encoder_top does not place. LEF and DEF in plain language compares an abstract with the full cell.

Which cell a DRC run checks

A design-rule check needs a start cell as well. In a LayoutEditor .ledrc deck, source names it:

units 1e-6
source user_project_wrapper    # the cell you ship; a misspelled name stops the run
mode flat

layer m1 = input(68, 20)       # met1 drawing

check "m1.1" "met1 width < 0.140 um" : width(m1) < 0.14 um

The deck was run on a test file with two top cells: user_project_wrapper, which passes, and an unplaced cell scratch with a metal 1 bar 0.100 µm wide, which violates SKY130 rule m1.1. The results:

Deck Result
source user_project_wrapper 0 markers, exit code 0
source scratch 1 m1.1 marker, exit code 1
source user_project_wraper (misspelled) cell not found: user_project_wraper, exit code 2, no report
no source, hierarchical file user_project_wrapper checked in both file orders; scratch skipped without a message
no source, two flat top cells the structure written last in the file is checked; a cell named TOP is checked regardless of its position

The last row has a consequence for files that are edited. LayoutEditor writes child cells before their parents and changes the order of the structures when it saves. After one open-and-save of the two-flat-cell file, the run without source checked the other cell and reported 0 markers instead of 1. A deck with source checks the same cell in every file order. What a DRC rule deck is covers the rest of the deck.

Listing the top cells

The LayoutScript program below lists every top cell, the renamed copies left by an import, names with characters outside the GDSII set, and the number of names longer than 32 characters. It reads the references itself instead of relying on findTopCell():

import re, sys
from LayoutScript import project

d = project.newLayout().drawing
d.openFile(sys.argv[1])
names, placed = [], set()
cl = d.firstCell
while cl is not None:
    c = cl.thisCell
    names.append(c.cellName)
    el = c.firstElement
    while el is not None:
        e = el.thisElement
        if e.isCellref() or e.isCellrefArray():
            placed.add(e.depend().cellName)
        el = el.nextElement
    cl = cl.nextCell
tops = sorted(n for n in names if n not in placed)
copies = [t for t in tops if t.endswith("1") and t[:-1] in names]  # nand2_11 next to nand2_1
badchar = sorted(n for n in names if not re.fullmatch(r"[A-Za-z0-9_?$]+", n))
long = sorted(n for n in names if len(n) > 32)
print("cells", len(names))
print("top cells", len(tops), tops[:5])
print("renamed copies", len(copies), copies[:3])
print("bad characters", badchar)
print("longer than 32", len(long))
print("findTopCell()", d.findTopCell().cellName)

Run it with PYTHONPATH=/opt/layout/python python3 list_top_cells.py design.gds. On the test file with the stray scratch cell it prints:

cells 3
top cells 2 ['scratch', 'user_project_wrapper']
renamed copies 0 []
bad characters []
longer than 32 0
findTopCell() user_project_wrapper

On the encoder file it reports 910 cells, 845 top cells, 433 renamed copies, and 77 names longer than 32 characters.

Fixing the file

The second program keeps one top cell under the required name, deletes every cell that this top cell does not use, and replaces characters outside the GDSII set with an underscore. It writes a new file:

import re, sys
from LayoutScript import project

src, dst, top = sys.argv[1:4]
d = project.newLayout().drawing
d.openFile(src)
if not d.existCellname(top):
    old = d.findTopCell()
    print("rename top", old.cellName, "->", top)
    old.cellName = top
d.setCell(top)
d.stripUnneeded()              # removes every cell the current cell does not use
cl = d.firstCell
while cl is not None:
    c = cl.thisCell
    new = re.sub(r"[^A-Za-z0-9_?$]", "_", c.cellName)
    if new != c.cellName:
        if d.existCellname(new):
            sys.exit("name clash: " + new)
        print("rename", c.cellName, "->", new)
        c.cellName = new
    cl = cl.nextCell
d.saveFile(dst)

Called as fix_top_cell.py in.gds out.gds user_project_wrapper, it turned six test files into files with the single top cell user_project_wrapper and the child inv_1: a file with a stray cell, the same cells in reverse order, a file with an empty extra cell, a file whose only top cell was named my_chip, a file with the child name inv#1, and a clean file, which stayed unchanged. References follow a rename, so inv#1 became inv_1 in the cell and in its placement. The program stops when a new name already exists instead of merging two cells.

Three limits apply:

  1. The rename step uses findTopCell() and is correct only when the lister reported one top cell.
  2. stripUnneeded() deletes cells. On the encoder file it reduced 910 cells to 62 and the file from 6,483,326 to 637,226 bytes, and the result passed the top-cell test. The standard cells in it were still the LEF abstracts, because the full cells were the unplaced copies that the program deleted. Inspect the renamed copies before deleting anything, and decide which version of each cell is the mask data.
  3. The program changes only the GDS. The netlist, the Verilog module, and the LEF macro must be renamed to the same name.

Checks before handoff

  1. Run the lister on the exact file you submit. It must report one top cell, under the name the receiver requires, no renamed copies, and no characters outside the GDSII set.
  2. Write the top cell name into the mask order or the submission metadata, and use the same name for the GDS file where the receiver requires it.
  3. Put source <top cell> in every DRC deck. A misspelled name stops the run with exit code 2.
  4. After any import, look for cell names that end in 1 next to a cell with the shorter name, and confirm which of the two the design places.
  5. Open the cells in the shipped hierarchy and confirm that they contain the drawing layers, not only pin and obstruction shapes.

Continue exploring