# swapcells

> Swap library cells or module instances in a Verilog netlist for another cell or module, remapping ports by name -- for library migration and ECO.

- Catalog id: `Swapcells`; bundle: `swapcells`; latest version 20261018
- Documentation page: https://edautils.com/Baya.html
- Keywords: swap cells, cell replacement, netlist ECO, library migration, Verilog instance swap
- Terms: as stated on edautils.com, EDAUtils tools are free for commercial and academic use, with no license server. The bundle's own metadata says: "Free to evaluate with the bundled licence; commercial licences from help@edautils.com". Licence prerequisites per tool are under "How an agent runs it".
- This file: https://edautils.com/capabilities/swapcells.md

## Downloads

- EDAUtils download site: https://edautils.ai/download/Swapcells (latest file `swapcells-20261018.tar.gz`)
- SourceForge: https://sourceforge.net/projects/edautils-free-utilities/files/swapcells/
- GitHub Releases: https://github.com/edautils/releases/releases/download/RELEASE_20261018/swapcells-20261018.tar.gz (release `RELEASE_20261018`; all releases: https://github.com/edautils/releases/releases)

## How an agent runs it

The following is the AGENTS.md shipped at the root of the bundle.

Surgically replaces cell (module) instances in Verilog/SystemVerilog source with other cells,
remapping their pins, from cell-map CSV files. Each swapped instance is, by default, wrapped as
`` `ifndef EDAUTILS_CELLSWAP `` <original> `` `else `` <new> `` `endif ``, so the new cell is
selected by defining the macro; `-disable_define` swaps in place instead. Only files that change
are written, into an output directory (default `outputdir/`), with the rest of the text kept as
written. Main class: `com.eu.miscedautils.surgicalchange.SwapCells`
(jar `lib/surgicalchange.jar`).
Before release 10.0 (October 2026) the package was `com.eu.miscedautils.verilogsurgicalchange` and the
jar `lib/verilogsurgicalchange.jar`; a script that names either directly must use the new names.

### Where it ships

Its own bundle, `swapcells.tar.gz` (flow `swapcells`; release tree
`release_scripts/swapcells/1.0`), and as a point tool in the **designplayer-shell** bundle
(`bin/swapcells` running the shell's jar; this guide as `tools/swapcells/AGENTS.md`, examples
under `tools/swapcells/examples/`).

### Prerequisites

- Java on `PATH` (the launcher runs plain `java`). Use Java 11 or newer (Java 21 recommended: the
  release is built and regression-tested with OpenJDK 21); the bundled JAXB and Eclipse libraries
  are class-file version 55, so a Java 8 runtime fails with `UnsupportedClassVersionError`.
- `EDAUTILS_ROOT` = the unpacked bundle directory (must contain `bin/` and `lib/`). The
  launcher exits 1 with "Environment variable EDAUTILS_ROOT is not set" otherwise.
  `source setup_env.sh` (or `setup_env.csh`) from the bundle root sets `EDAUTILS_ROOT`,
  `EDAUTILS_LICENSE_FILE=$EDAUTILS_ROOT/edautils.lic`, `CLASSPATH` and prepends `bin/` to `PATH`.
- Licence: a valid licence file is required at start-up (else exit status 10, no message).
  The licence file is searched in this order: `$EDAUTILS_LICENSE_FILE`, `./edautils.lic`
  (run directory), `$HOME/edautils.lic`, `$EDAUTILS_ROOT/edautils.lic`. Feature `SWAPCELLS` is
  checked when the swap starts; a missing feature is error 56404
  `Failed to checkout LICENSE for the feature : SWAPCELLS`; the run continues and exits 1.
- Optional environment: `JAVA_FLAGS` (passed to the JVM, e.g. `-Xmx8g`; with no heap option in it the launcher adds `-Xmx` sized to the machine (`bin/eu_heap.sh`: the largest of 64/32/16/12/8/4 GB within 3/4 of physical or cgroup memory, else 2 GB; `EDAUTILS_MAX_HEAP_GB` caps it)),
  `EDAUTILS_LOG_FILE` / `EDAUTILS_APPEND_LOG_FILE` (log file name; the second appends),
  `EDAUTILS_DISABLE_USAGE_TRACKING=true`, `EDAUTILS_PRINT_STACK_TRACE` (stack traces on
  internal exceptions), `EDAUTILS_ENABLE_DEBUG_ENVIRONMENT=1` (debug messages).
- On Unix the edit restores preprocessor text with `diff` and `patch` run from a generated
  `./patchscript.sh` (`/bin/sh`), so both must be on `PATH` and the current directory must be
  writable and allow executing that script.

### Invocation

```
swapcells -in <file.v> | -f <filelist>  -csvfiles <a.csv:b.csv> | -csvdir <dir>
          [-outdir <dir>] [-disable_define | -ifndef_macro_name <macro>] [options]
```

Tool-specific options:

| Option | Meaning |
|---|---|
| `-csvfiles <a.csv:b.csv>` | Colon-separated cell-map CSV files |
| `-csvdir <dir>` | Read every `*.csv` (any case) in `<dir>`; may be combined with `-csvfiles` |
| `-outdir <dir>` | Directory for rewritten files (default `outputdir`) |
| `-disable_define` | Replace the instance in place, no `` `ifndef``/`` `else``/`` `endif`` wrapper |
| `-ifndef_macro_name <macro>` | Macro used in the wrapper (default `EDAUTILS_CELLSWAP`) |
| `-replace_path_sep` | Name each output after the input's full path with separators replaced, not its basename |
| `-no_pp` | Skip Verilog preprocessing (only if the input has no compiler directives) |
| `-print_parse_errors` | Enable printing of parse errors (per the usage text; use it if the result is unexpected) |
| `-help`, `-h` | Print usage and return |

No CSV given means no mapping: every file logs "Nothing changed" and nothing is written. An
unknown option is error 50651 "Unknown option" followed by the usage, exit 255. `-top` and
`-out` are accepted by the shared parser but are not part of this tool's usage; neither is
used (`FVPSwapCells` ignores the top name it is given).

Common Verilog-reader options (shared parser, `FVPProcessCmdLineArgs`): `-in <file>`,
`-f <filelist>` (repeatable; one file per line, `#`/`// ` comments, `+incdir+`/`+define+` and
option lines allowed, `$VAR` resolved), `-excludefilelist <file>`, `+incdir+<p1>+<p2>`,
`+define+A+B=1`, `-v95`, `-nowildcard`, `-nokeywords a:b`, `-l <log>` / `-la <log>`, `-quiet`,
`-nobanner`, `-dbg` (also keeps `patchscript.sh` and temp files), `-suppress <id1:id2>`,
`-user <email>`.

### Cell-map CSV format

Excel-style CSV. Headers are found by case-insensitive substring match, so `# Old Cell Name`
works; extra columns (comments) are ignored.

```
Old Cell Name,New Cell Name
AND2X1,AND2X4
Old Pin Name,New Pin Name
A,A1
B,A2
Z,ZN
```

Pin rows (from the source and the shipped example's comments):

- `old,new` renames the pin in named connections. For positional connections the pin rows are
  paired with the connections in CSV order, one per connection, skipping the `@n` rows, so list
  them in port order.
- `old,` (empty new pin) or `old,-` deletes that connection.
- `old,new/<expr>` renames and replaces the connected expression with `<expr>`;
  `new/+<tie>` is meant to give `{<actual>,<tie>}` (tie on the LSBs) and `new/<tie>+` to give
  `{<tie>,<actual>}` (tie on the MSBs). **Not verified by a run**: from source the `+` form trims
  the wrong end of `<tie>` (`+3'h0` becomes `+3'h`, `2'h0+` becomes `'h0+`); inspect the output
  before relying on tie values.
- `@1,<text>`, `@2,<text>` ... append `<text>` verbatim as extra connections (e.g. `.c(1'b0)`);
  keep these rows last.

A cell with an `Old Cell Name,New Cell Name` row and no pin-map block is swapped with its
connections unchanged (the instance keeps its `;`). Only module instances are swapped: named
gate primitives (`and g1(...)`) are left alone.

Only the first cell block of each CSV file is read (a second `Old Cell Name` header in the same
file is taken as pin data): use one CSV per cell, e.g. `-csvfiles MEM.csv:NAND2x1.csv`.

### Inputs / Outputs

- Reads: the Verilog files from `-in` / `-f` and their `` `include`` files, and the CSV files.
- Writes: `<outdir>/<basename>` for every input file in which a mapped cell was instantiated
  (Note 57826 "Saved modified contents file"); files without one are not written (Note 55384
  "Nothing changed in the file").
- Log: `swapcells.log` in the current directory. Also created there: `myEdaUtilsWork/`,
  `edautils_temp/`, temporary `edautils_temp_file*` files and `patchscript.sh` (removed at the
  end unless `-dbg`).

### Exit status and messages

- 0 when the run finished with no error. 1 = the run reported any error (parse errors,
  licence feature missing ...) or caught an internal exception, `EDAUTILS_ROOT` missing, or out
  of memory (Fatal Error 53092). 255 = unknown option or missing input (error 54024). 10 = no
  valid licence file.
- Message format: `swapcells: <Severity>: <id>: <text>`; the printed id is 50000 + the source
  number, and `-suppress` takes the printed id. The banner is always printed.
- The run ends with `swapcells: Note: 53250: Found N error(s) and M warning(s) ...` (also on the
  missing-input exit, not on "Unknown option").
- Bundles built before 2026-09-02 never write an output file (every edit was discarded as
  "Nothing changed"); if a mapped cell still yields no output, check the bundle date.

### Examples

Shipped: `examples/simple_test_with_define/` (`runme.csh`, `infile.list`, `test_1.v`,
`bottom.v`, `cellmaps.csv`, `NAND2x1.csv`) and `examples/simple_test_no_define/` (`runme.csh`,
`infile.list`, `src/`, `CSV/`):

```
cd $EDAUTILS_ROOT/examples/simple_test_with_define
swapcells -f infile.list -csvfiles cellmaps.csv:NAND2x1.csv +define+TECH_1 \
    -ifndef_macro_name TECHNODE_10NM
cd $EDAUTILS_ROOT/examples/simple_test_no_define
swapcells -f infile.list -csvdir CSV -disable_define
```

The bundle self-test (`swapcells_example`) runs both with `</dev/null` and requires
`Found 0 error(s)` in each `swapcells.log`; it does not inspect `outputdir/`.

From the regression suite (reference: `tests.edautilscommandline/tests/swapcells/simple_swap`
and `disable_define` via `../runme_common.csh`), which compares `out/<name>.v` to a golden:

```
swapcells -in simple_swap.v -csvfiles cellmap.csv -outdir out
swapcells -in disable_define.v -csvfiles cellmap.csv -outdir out -disable_define
```

### Integration notes

- Non-interactive; does not read stdin. Run with `</dev/null`.
- Writes the log, `outputdir/`, `patchscript.sh` and temp files into the current directory:
  give each parallel run its own working directory.
- Set `EDAUTILS_DISABLE_USAGE_TRACKING=true` to stop usage registration.
- Success test: exit status 0 (the log then says `Found 0 error(s)`) **and** the expected
  `<outdir>/<file>` exists (its absence means no mapped cell was found).

### See also

punchports and uniquifyverilog (same surgical-edit engine), lib2verilog, verilog2lib.
