8.6 KiB

Raw Blame History

magic-vlsi-wasm

Magic VLSI layout tool, compiled to WebAssembly as a headless library. Runs in Node.js, browsers, and Web Workers — no X11, no Tk, no native dependencies.

Use it to programmatically read and write .mag, .gds, .cif, .ext, and SPICE netlists; run DRC; extract parasitics — anywhere JavaScript runs.

The package ships two variants:

Variant	Entry point	Description
notcl (default)	`magic-vlsi-wasm`	Standalone — no Tcl interpreter. Commands are plain Magic command strings.
tcl	`magic-vlsi-wasm/tcl`	Embeds a full Tcl 9 interpreter. Commands are evaluated as Tcl; Magic commands are available as the `::magic::` ensemble.

Install

The package is published to GitHub Packages. Add the following to your project's .npmrc so npm knows where to find it:

@rtimothyedwards:registry=https://npm.pkg.github.com

Then install:

npm install @rtimothyedwards/magic-vlsi-wasm

If the package is private or you hit a 401, authenticate with a GitHub personal access token that has the read:packages scope:

//npm.pkg.github.com/:_authToken=YOUR_TOKEN
@rtimothyedwards:registry=https://npm.pkg.github.com

Requires Node.js 18 or newer.

Quick start

Default variant (no Tcl)

import createMagic from 'magic-vlsi-wasm';

const { runCommand, FS } = await createMagic();

// Drop a layout into Magic's virtual filesystem
FS.mkdirTree('/work');
FS.writeFile('/work/inv.mag', layoutBytes);

// Run Magic commands — scmos is built into the WASM binary, no tech file needed
runCommand('tech load scmos');
runCommand('load /work/inv');
runCommand('gds write /work/inv');

// Read the result back out
const gdsBytes = FS.readFile('/work/inv.gds');

TCL variant

import createMagic from 'magic-vlsi-wasm/tcl';

const { runCommand, FS } = await createMagic();

// Pure Tcl works directly
runCommand('set x 42');
runCommand('puts $tcl_version');

// Magic commands are available as the ::magic:: ensemble
runCommand('magic::tech load scmos');
runCommand('magic::load /work/inv');
runCommand('magic::gds write /work/inv');

The scmos technology family (scmos, minimum, nmos, ...) is embedded in the WASM binary and available out of the box — those names work without writing any tech file. To use a custom technology, write its .tech file into the VFS at /magic/sys/current/<name>.tech before calling tech load <name>.

API

createMagic(options?): Promise<MagicInstance>

options is forwarded to the underlying Emscripten module. Useful keys:

Key	Default	Purpose
`wasmBinary`	fetched lazily	Pre-fetched ArrayBuffer of `magic.wasm` (skips a network round-trip in browsers)
`print`	`console.log`	Callback for each stdout line
`printErr`	`console.error`	Callback for each stderr line

The returned MagicInstance exposes:

Method	Description
`runCommand(cmd: string)`	Dispatch a single Magic command. Returns 0 on success.
`sourceFile(path: string)`	Execute a script from the virtual filesystem. Returns 0 on success, -1 if the file could not be opened.
`init()`	Force initialization. Idempotent — `runCommand` and `sourceFile` call it for you.
`update()`	Drive a display-update cycle. No-op in this headless build.
`FS`	Emscripten virtual filesystem. See the Emscripten docs.

Full TypeScript types ship in index.d.ts.

Low-level access

createMagic() is a thin convenience wrapper over the underlying Emscripten module. If you need direct access — for example to call cwrap yourself or to drive magic_wasm_init manually — import the module factory directly:

import createMagicModule from 'magic-vlsi-wasm/magic.js';

const module = await createMagicModule({ wasmBinary, print, printErr });
module._magic_wasm_init();
const run = module.cwrap('magic_wasm_run_command', 'number', ['string']);
run('tech load scmos');

The bundled examples use this lower-level path together with a small helper class (examples/helpers.js) that adds a runScript(text) convenience method — it splits a multi-line Tcl block, strips comments, and dispatches each line via runCommand. Useful when you have a script as a string rather than as a file in the VFS.

Examples

The package ships runnable examples for the most common workflows. After installing, run one directly:

node node_modules/magic-vlsi-wasm/examples/extract.js
node node_modules/magic-vlsi-wasm/examples/gds.js
node node_modules/magic-vlsi-wasm/examples/drc.js
node node_modules/magic-vlsi-wasm/examples/cif.js

Or, when developing inside this repo:

npm test           # full suite (extract, gds, drc, cif)
npm run example    # extract.js — RC extraction + SPICE netlist
npm run test:gds   # GDS write only
npm run test:drc   # DRC check only
npm run test:cif   # CIF write only

Each example loads the bundled min.mag (a small NPN transistor cell from Magic's own scmos test suite) under the built-in scmos technology — no external tech file required. See examples/ for the source; example.js is the simplest entry point (GDS → CIF conversion in ~40 lines).

Build from source

If you want to rebuild the WASM module yourself, see toolchains/emscripten/README.md. The short version:

bash npm/build.sh                    # both variants, debug build
bash npm/build.sh --variant=notcl    # default variant only (faster)
bash npm/build.sh --variant=tcl      # TCL variant only
bash npm/build.sh --release          # optimized (-O2, no debug symbols)
bash npm/build.sh --test             # build + run tests
bash npm/build.sh --pack             # build + produce magic-vlsi-wasm-<version>.tgz

You will need an activated emsdk on your PATH. If you pass EMSDK_DIR=/path/to/emsdk, build.sh sources emsdk_env.sh for you.

TCL variant: cloning the TCL source tree

The TCL variant links against a static WASM build of tcltk/tcl. build.sh clones the source tree automatically into build-tcl-wasm/tcl on the first run and builds it out-of-source in the same directory — everything stays under build-tcl-wasm/ (which is gitignored), so nothing outside it is touched. Subsequent runs reuse the existing clone and build.

# Override the TCL version or source repository
TCL_REF=core-9-0-3 bash npm/build.sh --variant=tcl
TCL_REPO_URL=https://github.com/tcltk/tcl.git bash npm/build.sh --variant=tcl

CI always resolves the latest stable core-9-0-x tag automatically. To build against a specific version, set TCL_REF in the environment.

Versioning

Published versions follow the scheme {MAJOR}.{MINOR}.{PATCH}0{YYYYMMDD}+git{SHA}, for example 8.3.799020261231+git01234cde.

The date is embedded directly into the patch number (separated by a leading zero for readability). This means:

Versions are orderable numerically — a later build date is always a higher version number within the same patch series.
Security or bugfix releases for 8.3.799 can be inserted as later dates (8.3.799020270101, 8.3.799020270201, …) without bumping the patch number.
Users who want to lock to the 8.3.799 series and receive only those patches can use the range <=8.3.799900000000 or <8.3.8000000000000.
~8.3.799 matches all 8.3.* versions (broader than the 799 series alone).

The +git… suffix is build metadata — it is ignored by npm for version comparison and range matching. It exists purely for traceability.

Limitations

Headless only. There is no display driver, so commands that draw to a window (view, findbox, interactive macros) are no-ops.
Single-threaded. WASM modules are not thread-safe — create one instance per worker.

License

Bundled test layout

The example layout examples/min.mag is taken from Magic's own scmos test suite (scmos/examples/bipolar/min.mag) and is included here as a runnable smoke test for the WASM build. The scmos technology it targets is compiled into the WASM binary, so no external tech file is shipped.

8.6 KiB Raw Blame History