Streaming Out GDS From Magic

In the previous article we looked at what a GDS file contains. In this article we look at how the UART’s GDS is produced. You have in fact been using it already: every check in Module 8 ran on runs/uart_full/results/final/gds/uart_top.gds. Here we look at where that file comes from, and how to make it yourself.

What goes into the stream

The router’s output, the DEF, does not contain transistors. It contains cell instances with positions, and the wires and vias between them. The detailed geometry of each standard cell lives in the PDK, in the library’s own GDS. Streaming out combines the two, as Figure 1 shows: the design’s placement and routing from the DEF, and the cell geometry from the library, written as one hierarchical GDS.

Inputs to GDS streamout — Figure 1: Magic combines the routed DEF, the standard cell GDS and the technology data into one hierarchical GDS

Streaming out by hand

This is a simplified version of what OpenLane’s Magic streamout step does. Run it in Magic’s batch mode:

magic -dnull -noconsole \
      -rcfile "$PDK_ROOT/sky130A/libs.tech/magic/sky130A.magicrc" <<'EOF'
gds readonly true
gds rescale false
gds read $PDK_ROOT/sky130A/libs.ref/sky130_fd_sc_hd/gds/sky130_fd_sc_hd.gds
lef read $PDK_ROOT/sky130A/libs.ref/sky130_fd_sc_hd/lef/sky130_fd_sc_hd.lef
def read runs/uart_full/results/routing/uart_top.def
load uart_top
select top cell
gds write uart_top.gds
quit -noprompt
EOF

gds read of the library first loads the real geometry of every standard cell. gds readonly true marks those cells as read-only, so Magic writes them back exactly as the PDK supplied them instead of regenerating them from its own view of the layers.
lef read gives Magic the cell outlines and pins, and def read builds uart_top from the routed design: cell placements plus every wire and via.
gds write walks the hierarchy under the top cell and writes one stream: the library cells once each, and uart_top with its references and routing.

If you ran the fixes in Module 8 by hand on the GDS, remember they are not in the DEF. This is the point made in the DRC fixing article: either make the change in the routing database, or reapply your manual edits after every streamout.

Streaming out as part of the flow

In normal use you never run this by hand. OpenLane’s Classic flow has a Magic streamout step after routing and fill, and the full flow run writes the GDS along with everything else:

openlane --flow Classic --run-tag uart_full designs/uart/config.json

OpenLane also writes a second GDS of the same design with KLayout and compares the two with an XOR, a geometric difference of every layer. If Magic and KLayout, two independent programs, produce the same geometry from the same inputs, you can be fairly confident neither introduced an error while writing. We come back to this idea of independent tools in Section 9.2.

Confirming it worked

GDS is binary, but structure names are stored as plain ASCII, so a blunt tool like strings can pull them out without a viewer:

ls -la runs/uart_full/results/final/gds/uart_top.gds
strings runs/uart_full/results/final/gds/uart_top.gds | grep -m 20 -E "uart_top|sky130_fd_sc_hd__"

You should see uart_top and the names of the SKY130 cells it uses, such as sky130_fd_sc_hd__dfxtp_2 and sky130_fd_sc_hd__nand2_1. That confirms the top structure has the name you expect and refers to real library cells. For our UART the file is a few megabytes, most of it the standard cell geometry.

One failure to watch for when doing this by hand: if the library GDS is not loaded before streamout, Magic can write each standard cell from its own abstract view, and you get a file with correct placements but empty or incomplete cells. It exists, it has the right names, and it is useless. OpenLane always loads the library GDS; by hand, you have to remember to.

Practice Exercise

Your streamout produces a GDS of only 40 KB for a design with 12,000 standard cell instances, although every earlier check passed. What is the most likely cause, and how would you start confirming it?

Solution

40 KB is far too small. Even with hierarchy, the file must hold the full geometry of every cell type used, and the SKY130 cells alone account for far more than that, plus 12,000 placement records and all the routing. The most likely cause is that the library GDS was not loaded at streamout, so the cells were written empty or as abstracts.

To confirm, list the structures (strings shows the cell names, which will probably still be present) and then open the file in KLayout and descend into one standard cell. If it has no diffusion, poly or li1 inside, the cell geometry is missing. The fix is in the streamout setup, loading the library GDS first, not in your design. And it is a reminder that the checks in Module 8 must run on the same GDS you submit, since that is what would have caught this.

In the next article we open uart_top.gds in a real viewer and look at the geometry the whole flow has been building.