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

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.

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:
- The rename step uses
findTopCell()and is correct only when the lister reported one top cell. 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.- 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
- 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.
- 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.
- Put
source <top cell>in every DRC deck. A misspelled name stops the run with exit code 2. - After any import, look for cell names that end in
1next to a cell with the shorter name, and confirm which of the two the design places. - Open the cells in the shipped hierarchy and confirm that they contain the drawing layers, not only pin and obstruction shapes.
Continue exploring
-
Cells and instances
Draw the pad once and stamp it many times. Each stamp is the same drawing in a new place, not a photocopy of the ink.
-
GDSII in plain language
A 1970s suitcase that still carries almost every chip drawing on Earth.
-
Hierarchy and flattening: why chips keep cells and boards go flat
Flattening replaces cell references with transformed copies of their shapes: what GDSII SREF and AREF records store, how the transform is applied, what it costs in file size, and how to flatten and check a layout in LayoutEditor.
-
What is a layout? IC layout explained: shapes, layers, units, and cells
A layout is the file a factory builds a chip from: integer coordinates on numbered layers, grouped into cells. What GDSII stores, a complete 576-byte example built in LayoutEditor, and what to check before you send one.
-
What is a photomask? The glass plate that prints a chip
A photomask, also called a reticle, is a quartz plate with a chrome pattern. Light shines through it to copy one layer of a chip onto a wafer, and a chip needs a stack of them.
-
LEF and DEF in plain language
LEF describes the layers, vias, sites, and cell abstracts of a digital library; DEF describes one design built from it, with die area, rows, placed instances, pins, power grid, and wires.
-
What a DRC rule deck is
A DRC rule deck is the file that turns a rule manual into layer definitions, derived layers, checks, and named report categories that a design-rule-check tool runs on a layout.
-
From idea to something a shop can print
How a napkin sketch becomes a file, a cover letter, and a glass plate a shop can print from.