How rtimothyedwards/magic works
Magic is a large C-based VLSI layout system built around a shared in-memory layout database, with multiple front ends and many specialized analysis/format-conversion tools layered on top. The repo is not a single app so much as a suite of cooperating executables and libraries.
1. Core architectural center: the layout database
• The database/, tiles/, bplane/, utils/, and select/ directories form the central model layer.
• The database stores cells, tiles, geometry, labels, connectivity, tech information, timestamps, and undo state.
• tiles provides the underlying tile/plane representation; bplane is an alternate cell-plane implementation used for efficiency on hierarchical cells.
• utils supplies shared infrastructure: geometry, hashing, lists, undo, path traversal, tech parsing, netlist helpers, and memory/util primitives.
2. Editor and interaction layer
• The interactive layout editor lives primarily in magic/, commands/, textio/, windows/, graphics/, dbwind/, cmwind/, netmenu/, plot/, and wiring/.
• commands/ implements user commands and command dispatch.
• textio/ handles terminal input, output, and command-line interaction.
• windows/, graphics/, dbwind/, and cmwind/ manage display, view updates, feedback, colors, and window-specific behavior.
• select/ manages selection semantics and undo/redo for selected geometry and nets.
• wiring/ contains interactive wire-editing support.
3. Main data flow for editing
• User input arrives through the text console, Tk/Tcl bindings, or GUI events.
• Commands mutate the central database.
• The database notifies display layers (dbwind, graphics, windows) to redraw affected regions.
• Selection, undo, and feedback subsystems track user operations separately from raw geometry so edits can be reversed and visualized cleanly.
4. Technology-file and rule system
• scmos/ and parts of database/, utils/tech.*, drc/, and extract/ reflect Magic’s technology-driven architecture.
• Process rules, layer definitions, display styles, extraction rules, and CIF/GDS-related behavior are driven by technology files rather than hardcoded.
• This makes technology data a first-class input boundary: the same editor/extractor/router code adapts to different fabrication processes through tech configuration.
5. Geometry analysis and verification tools
• drc/ performs design-rule checking.
• extract/ computes connectivity and device extraction from layout.
• resis/ performs more detailed resistance-related extraction and resistor network work.
• sim/ bridges layout extraction into simulation-oriented data.
• These tools all consume the same layout database and tech information, but produce analysis results rather than editing the geometry itself.
6. Routing and layout modification subsystems
• Automatic and interactive routing are split across router/, grouter/, garouter/, irouter/, mzrouter/, gcr/, plow/, and bplane/.
• Different routers target different use cases: detailed routing, maze routing, global routing, interactive routing, channel routing, and channel compaction/plowing.
• These modules read pins, layers, constraints, and connectivity from the database, then write routed geometry back into it.
7. Import/export and interchange formats
• File-format adapters are a major boundary in the repo: calma/ for GDS/Calma, cif/ for CIF, lef/ for LEF/DEF, ext2sim/, ext2spice/, extcheck/, net2ir/, and extflat/.
• These modules translate between Magic’s internal database and external EDA interchange formats.
• The flow is generally: external file → parser/reader → internal database or netlist/extract structures; and the reverse for writers/exporters.
• This is one of the most important architectural separations in the repo.
8. Scripting and extensibility
• tcltk/ integrates Tcl/Tk for scripting and GUI composition.
• lisp/ adds a Scheme/Lisp-style extension environment, historically used for scripted commands and layout automation.
• npm/ exposes JavaScript/Tcl wrappers and examples, including wasm-oriented integration.
• These layers are not the core engine; they are extension surfaces that call into the same command and database APIs.
9. Rendering backends and platform abstraction
• graphics/ contains multiple rendering implementations and backends: X11, Tk, OpenGL, Cairo, and null/headless variants.
• The repo is designed to run with different display technologies without changing the database or command logic.
• magic/magicWasm.c and the toolchains/emscripten/ directory show a WebAssembly build path.
• This is a clear boundary: platform graphics are abstracted behind the graphics subsystem, while the editor/database remain backend-independent.
10. Command-line utilities and batch-mode workflows
• Several top-level subdirectories build standalone programs, not just library code.
• Examples include extcheck, net2ir, plot, sim, and the magicdnull/batch-mode pathways in tcltk/.
• These tools usually reuse the same lower-level libraries for parsing, database access, geometry, and tech handling, but operate without the full interactive GUI.
11. Build, packaging, and distribution
• Makefile, rules.mak, configure, and scripts/ drive the cross-platform build.
• GitHub Actions under .github/workflows/ produce CI builds for Linux, macOS, AArch64, WASM, and AppImage variants.
• appimage/ contains containerized packaging recipes, and toolchains/emscripten/ supports browser/WASM builds.
• These are deployment concerns rather than runtime architecture, but they matter because Magic is distributed as a family of native and packaged binaries.
12. Documentation and technology examples as part of the system model
• doc/ is unusually extensive and functions as part of the product architecture: it documents commands, file formats, tech files, tutorials, and historical behavior.
• scmos/examples/, doc/tutcells/, and related assets provide canonical design inputs used to validate readers, routers, extractors, and tech-file semantics.
• For diagramming, these should be treated as fixtures and reference data flowing into the same core tools.
Overall, the cleanest architecture diagram is: front ends and format adapters feed a central layout database; analysis and routing tools read/write that database; graphics/windowing layers observe it for display; tech files configure behavior; and scripting/batch tools wrap the same core APIs through Tcl, Lisp, or headless entry points.
Main entry points: DBcell.c Layout DB · ExtMain.c Extract · CmdSubrs.c Commands · magicTop.c Magic entry
Components 31
Core model
Shared layout database and foundational geometry/data structures.
- Layout DB · Central shared in-memory model for cells, geometry, labels, connectivity, tech, and undo.
database/DBcell.c - Tiles · Underlying tile and plane representation for geometry storage.
tiles/tile.c - B-plane · Alternate cell-plane implementation tuned for hierarchical efficiency.
bplane/bpMain.c - Core utils · Common geometry, hashing, lists, paths, tech parsing, netlist, memory, and undo helpers.
utils/utils.h
Interactive editor
User-facing command, selection, and display subsystems.
- Magic entry · Primary executable and startup path for the interactive editor.
magic/magicTop.c - Text I/O · Terminal input, output, and command-line interaction.
textio/txMain.c - Commands · Command parsing and editor command implementations.
commands/CmdSubrs.c - Selection · Selection semantics plus undo/redo for selected geometry and nets.
select/selOps.c - DB window · Database-driven view updates, feedback, and highlighting.
dbwind/DBWdisplay.c - Windows · Window management, event routing, and viewport behavior.
windows/windMain.c - Wiring · Interactive wire editing support and related tech rules.
wiring/wireOps.c
Analysis and extraction
Verification and extraction tools that consume the database.
- DRC · Design-rule checking over the layout database and tech rules.
drc/DRCmain.c - Extract · Connectivity and device extraction from layout.
extract/ExtMain.c - Resistive extract · Detailed resistor-network and resistance extraction support.
resis/ResMain.c - Simulation bridge · Bridges extracted layout data into simulation-oriented structures.
sim/SimExtract.c
Routing
Automatic and interactive routing subsystems.
- Router · General routing engine for pins, vias, hazards, and route painting.
router/rtrMain.c - Global router · Global routing and routing-net planning across the layout.
grouter/grouteMain.c - Maze router · Maze-search-based routing and extension logic.
mzrouter/mzMain.c - Plow · Channel compaction and layout plowing tools.
plow/PlowMain.c
Import/export
Interchange readers and writers around the internal database.
- Calma/GDS · Calma/GDS reader and writer.
calma/CalmaRead.c - CIF · CIF reader, writer, and tech handling.
cif/CIFmain.c - LEF/DEF · LEF/DEF parsing and writing boundary.
lef/lefRead.c - Ext→Spice · Exports extracted connectivity into SPICE-oriented form.
ext2spice/ext2spice.c - Ext flat · Hierarchical flattening and flat extraction support.
extflat/EFflat.c
Extensibility
Scripting and alternate front ends.
- Tcl/Tk · Tcl/Tk integration for scripting, GUI composition, and wrappers.
tcltk/tclmagic.c - Lisp/Scheme · Embedded Scheme/Lisp extension environment for automation.
lisp/lispMain.c - Node wrappers · JavaScript and Tcl wrapper layer, including wasm-oriented examples.
npm/index.js
Platform and build
Backend rendering, WebAssembly, and build/distribution support.
- Graphics · Display abstraction with X11, Tk, OpenGL, Cairo, and null backends.
graphics/grMain.c - WASM build · WebAssembly entry path for browser-style builds.
magic/magicWasm.c - Build system · Top-level make/configuration and packaging machinery.
Makefile - Tech data · Process technology, layer, display, and example rule data.
scmos/scmos.tech.in
Connections 35
- Magic entry → Text I/O: uses · Interactive startup and console command path.
- Magic entry → Commands: dispatches · User actions are translated into editor commands.
- Magic entry → Graphics: renders via · Editor output is drawn through backend-agnostic graphics.
- Commands → Layout DB: mutates · Commands edit the central layout database.
- Commands → Selection: updates · Commands operate on selection state and undo.
- Selection → Layout DB: tracks · Selection references geometry and nets in the database.
- DB window → Graphics: draws with · Database change notifications drive redraws.
- Windows → Graphics: hosts · Windowing sits above the rendering backends.
- Wiring → Layout DB: writes · Interactive wire editing commits routed geometry.
- Layout DB → Tiles: stores · Geometry is backed by tile and plane structures.
- Layout DB → B-plane: uses · Hierarchical cells may use alternate plane storage.
- Layout DB → Core utils: depends on · Core data structures rely on shared utilities.
- DRC → Layout DB: reads · Verification consumes the shared layout model.
- Extract → Layout DB: reads · Extraction traverses layout, labels, and connectivity.
- Extract → Core utils: uses · Extraction reuses tech and geometry helpers.
- Resistive extract → Extract: extends · Resistance analysis builds on extracted connectivity.
- Simulation bridge → Extract: consumes · Simulation bridging starts from extracted nets.
- Router → Layout DB: writes · Routing adds geometry back into the database.
- Global router → Layout DB: reads · Global routing consumes pins, layers, and constraints.
- Maze router → Layout DB: reads · Maze routing searches across the shared database.
- Plow → Layout DB: modifies · Compaction/plowing rewrites layout geometry.
- Calma/GDS → Layout DB: imports/exports · GDS/Calma translation is a boundary around the database.
- CIF → Layout DB: imports/exports · CIF translation maps between files and internal layout.
- LEF/DEF → Layout DB: imports/exports · LEF/DEF adapters translate to and from internal data.
- Ext→Spice → Extract: exports · SPICE output is driven by extracted connectivity.
- Ext flat → Layout DB: flattens · Flat translation and hierarchy expansion operate on layout data.
- Tcl/Tk → Commands: wraps · Tcl/Tk surfaces invoke the same command APIs.
- Lisp/Scheme → Commands: extends · Scheme/Lisp scripts call into Magic command interfaces.
- Node wrappers → Tcl/Tk: binds · Node examples and wrappers bridge into Tcl/Tk and Magic.
- WASM build → Graphics: targets · WASM build path shares the same editor/graphics split.
- Build system → Magic entry: builds · Top-level build rules produce the main executable.
- Build system → Tcl/Tk: packages · Build scripts assemble scripting and wrapper binaries.
- Tech data → DRC: configures · Technology files provide DRC rules and layer definitions.
- Tech data → Extract: configures · Extraction rules and tech data are technology-driven.
- Tech data → Calma/GDS: drives · Tech data influences interchange and display semantics.