# punchports

> Punch new ports through a Verilog hierarchy: add a port on a sub-module and route it up to the top or across to another instance, with optional feed-through, editing the RTL in place.

- Catalog id: `Punchports`; bundle: `punchports`; latest version 20261018
- Documentation page: https://edautils.com/Baya.html
- Keywords: punch ports, add port through hierarchy, feedthrough, Verilog port routing, RTL editing
- 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/punchports.md

## Downloads

- EDAUtils download site: https://edautils.ai/download/Punchports (latest file `punchports-20261018.tar.gz`)
- SourceForge: https://sourceforge.net/projects/edautils-free-utilities/files/punchports/
- GitHub Releases: https://github.com/edautils/releases/releases/download/RELEASE_20261018/punchports-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 edits Verilog/SystemVerilog, VHDL and mixed Verilog/VHDL source to punch new ports through the hierarchy, either
pulling sub-module ports up to the top module (`-submodule`) or routing a pin from one instance
to another, optionally through intermediate instances (feedthrough sets). The design is parsed
once; the change is planned as an ECO JSON description (`eco.json`) and then applied as token
edits on the original text, so comments, macros and formatting outside the edits are kept. Only
the files that change are written, into an output directory (default `output_dir/`). Main class:
`com.eu.miscedautils.surgicalchange.PunchPorts` (engine `PunchEngine`, 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, `punchports.tar.gz` (flow `punchports`; release tree
`release_scripts/punchports/1.0`), and as a point tool in the **designplayer-shell** bundle
(`bin/punchports` running the shell's jar; this guide as `tools/punchports/AGENTS.md`, examples
under `tools/punchports/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 `PUNCHPORTS`
  is checked at start-up.
- 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).

### Invocation

```
punchports -in <file.v> | -f <filelist>  -top <module>
           ( -submodule <mod>/<port>[,<port>...] ...
           | -route from=<src> to=<dst>[,<dst>...] [via=<inst>,...] [name=<base>] [width=<msb>:<lsb>] ...
           | -route_file <file>
           | +feedthrough -from <hier pin> -to <hier inst> [-through <inst>,<inst>] -feedthrough ...
           | -json_in <eco.json> )
           [-outdir <dir>] [-json_out <file>] [-json_only] [-all_instances] [options]
```

Tool-specific options:

| Option | Meaning |
|---|---|
| `-top <module>` | Top module (mandatory; missing = error 54030, exit 1) |
| `-submodule <mod>/<p1>,<p2>` | Put these ports on every instance of module `mod` and carry them up to `-top` through every instance path (repeatable). An input is shared: one port per parent for every instance that needs it; an output gets one port per instance, named `<inst>_<port>`. Not exactly one `/` is error 54907 |
| `-route from=<src> to=<dst>[,<dst>...] [via=...] [name=...] [width=...]` | Route one signal (repeatable). The `key=value` words follow `-route` directly or quoted as one argument; see "Routes" below |
| `-route_file <file>` | One route per line in the same `key=value` form; `#` and `//` start a comment. Errors name the file and line |
| `+feedthrough` ... `-feedthrough` | The older form of one route: start / end of a set (repeatable) |
| `-from <top/inst/.../pin>[,<pin>...]` | Source instance and pin(s) of the set; the pins after the last `/` are comma separated. A pin that already exists and is connected is used as it is: the route starts from the net it drives |
| `-to <top/inst/...>` | Destination instance; it gets a new input port. `-to <top>` ends the route on a new top-level output port |
| `-through <inst>,<inst>` | Optional instances the pin passes through, in order. Each gets an input, an output `<module>_<pin>_output` and an `assign` between them |
| `-all_instances` | Feedthrough: do not uniquify. By default every module on a route that is instantiated more than once in the design is cloned as `<module>_<instance>` (written right after the original module, in the same file), so only the named path changes. With `-all_instances` shared modules are edited in place: every instance carries the new ports, and the other instances' new ports are left unconnected |
| `-ignore_modules <m1>,<m2>` | `-submodule`: do not carry ports above these modules |
| `-json_in <file>` | Apply an existing ECO JSON instead of computing one |
| `-json_out <file>` | Name of the ECO JSON written (default `eco.json`); the RTL is still written |
| `-json_only` | Write the ECO JSON and stop; no RTL |
| `-outdir <dir>` | Directory for rewritten files (default `output_dir`) |
| `-ignore_other_insts`, `-no_pp`, `-print_parse_errors` | Accepted for old scripts; no effect (path-only routing is the default) |
| `-help`, `-h` | Print usage and return |

Routes (`-route`, `-route_file`; paths start below the top, a leading top name is accepted):
- `from=` an instance pin, `u_a/u_b/pin` (created as an output when missing; an existing
  output that is already connected is tapped where it is), or a top-level input port name
  (created when missing).
- `to=` one or more destinations, comma separated. `u_x/u_y` gets a new input port;
  `u_x/u_y/port` names the port -- an existing input that is still unconnected is connected,
  any other name is created as a new input; `top` (or `top/<name>`) ends on a new top output.
  The destinations share the route out of the source: each level carries the signal once, and
  an instance that already receives it is not given a second port (fan-out).
- `via=` instances passed through in order; each gets an input, an output and an `assign`.
- `name=` base name of every port and wire the route adds (default: `<inst>_<pin>` going up,
  `<pin>` coming down); a clash gets `_1`, `_2` ...
- `width=<msb>:<lsb>` the signal's width (overrides the declared width).

```
punchports -f files.f -top soc_top -route from=u_cpu/u_core/irq_ack to=u_periph/u_uart,u_periph/u_spi/ack_in,top/irq_ack_o name=irq_ack_ft
punchports -f files.f -top soc_top -route_file eco_routes.txt
```

Port spec: `name[@in|@out|@inout[@msb:lsb]]`, e.g. `xo@out@2:0`, `zio@out`, `new_po`. A port that
does not exist yet is created (no direction: `inout` for `-submodule`, `output` for `-from`). An
explicit `@msb:lsb` also overrides the width of an existing port. One of `-submodule`, a
feedthrough set or `-json_in` is required (else error 54035, exit 1). `-from`/`-to`/`-through`
outside a `+feedthrough ... -feedthrough` set is error 56111.

How the edit lands:
- New ports are appended at the END of a module header, laid out like the last existing port
  (ANSI: `output wire [3:0] p`; non-ANSI: the name in the list plus a declaration after the
  header line). `module m;` and `module m();` get a port list.
- An instance that is edited and connects by position is rewritten to named connections, so
  the appended ports can never shift the existing ones. New connections are `.port(net)`.
- Parents never see a child's parameters: a carried port is declared `[w-1:0]` with the
  evaluated width. A port whose width depends on a parameter that some instance overrides is
  refused (error 146004) unless the width is given as `@msb:lsb`.
- New names never collide with an existing port, net, variable or instance: a clash gets a
  `_1`, `_2` ... suffix.

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`, `-blackbox`, `-l <log>` /
`-la <log>`, `-quiet`, `-nobanner`, `-dbg`, `-suppress <id1:id2>`, `-user <email>`.

### VHDL and mixed Verilog/VHDL designs

`.vhd`/`.vhdl` files in `-in`/`-f` are read as VHDL (analysed, in the order given, into the
`work` library under `myEdaUtilsWork`); everything else as Verilog. The top may be a module or
an entity, and a path may cross the language boundary at any level (a Verilog instance of a VHDL
entity, a VHDL component bound to a Verilog module). Every request works the same way:
- VHDL edits: ports are appended to the entity's port clause, and to every component
  declaration of that unit (VHDL or Verilog unit); signals go before the architecture's
  `begin`, assignments (`a <= b;`) before its `end`; a named port map gains `f => a`, a formal
  mapped to `open` is taken over in place, a positional map is rewritten as named.
- New VHDL ports are `std_logic` / `std_logic_vector(w-1 downto 0)`. A signal of any other
  type (a record, an enumeration ...) keeps its type mark; the package declaring it gets a
  `use work.<pkg>.all;` in every unit that now names it. Such a type cannot cross into Verilog
  (error 146030); a type declared inside an entity or architecture cannot leave it (146031).
- A cloned VHDL unit is its context clause, entity and architecture copied and renamed, written
  after the original architecture; a parent reaching it through a component gets a component
  declaration for the clone beside the original's (architecture or package).

```
punchports -f files.f -top htop -route from=tm to=u_v1/u_h/spare -route from=u_v0/u_h/q to=u_v1/u_h name=peer
```

### Inputs / Outputs

- Reads: the Verilog files from `-in` / `-f` and their `` `include`` files; with `-json_in` the
  given JSON (an object, or an array whose first element is the object).
- Writes: `eco.json` (or the `-json_out` name) in the current directory unless `-json_in` is
  given, then `<outdir>/<basename>` for every input file that changed (unchanged files are not
  copied). With `-f`, also `<outdir>/<filelist basename>`, the file list with every changed
  entry pointing at its rewritten copy. Nothing is written when any error is reported.
- ECO JSON layout: one object per module keyed by module name, with `module_name`,
  `source_module` (a clone: the module whose text it copies), `ports` (`port_name`, `dir`,
  optional `range`), `wires` (`"[7:0] name"` or `"name"`), `assignments` (`"lhs = rhs"`),
  `instances` (`instance_name`, optional `master` when the instance is re-pointed at a clone,
  `portmaps` as `formal:actual`), plus `is_feedthrough_mode`.
- Log: `punchports.log` in the current directory, and `myEdaUtilsWork/`.

### Exit status and messages

- 0: the edit was planned and written with no error.
- 1: any error -- option errors, top module not found (55902), an instance path segment not
  found (146001), a port already connected (146002/146015), unpacked or parameter-dependent
  width (146003/146004), a uniquify that needs an instance split out of a multi-instance
  statement (146014), parse errors in the input (146021, nothing is edited), or an internal
  exception. Nothing is written then (146018 "No RTL written").
- 10 = no valid licence file.
- Message format: `punchports: <Severity>: <id>: <text>`; the printed id is 50000 + the source
  number, and `-suppress` takes the printed id. Note 146007 reports each module cloned.
- The run ends with `punchports: Note: 53250: Found N error(s) and M warning(s) ...`.

### Examples

Shipped: `examples/from_A_n_B_to_top/`, `examples/from_A_to_C/` and
`examples/from_A_to_C_through_B/`, each with `runme.csh`, `vlog.f`, `src/` and `golden/`
(the expected `output_dir/` files and `eco.json`).

```
cd $EDAUTILS_ROOT/examples/from_A_to_C
punchports -f vlog.f +incdir+src -top top \
    +feedthrough -from top/u_mid1/u_A/new_po,xo@out@2:0,zio@out -to top/u_mid1/u_C -feedthrough
```

`from_A_to_C_through_B` routes through module `B`, which is instantiated under both `u_mid1`
and `u_mid2`: the `B` on the path under `u_mid1` is cloned as `B_u_B`. The bundle self-test
(`punchports_example`) requires `Found 0 error(s)` in `punchports.log` for all three.

From the regression suite (`tests.edautilscommandline/tests/punchports/`), a two-step JSON flow:

```
punchports -f infile.list -top top -json_only -json_out plan.json +feedthrough -from top/u_c0/u_core/u_alu/ovf -to top/u_c1/u_io -through top/u_c1/u_core -feedthrough
punchports -f infile.list -top top -json_in plan.json
```

### Integration notes

- Non-interactive; does not read stdin. Run with `</dev/null`.
- Writes `eco.json`, the log and `output_dir/` into the current directory: give each parallel run
  its own working directory.
- Keep each `+feedthrough -from ... -to ... [-through ...] -feedthrough` set contiguous on the
  command line; the `-from/-to/-through` values attach to the most recent `+feedthrough`.
- An empty positional connection (`u( , a, b)`) is not accepted by the parser; use named
  connections there.
- Success test: exit status 0. The regression suite also compiles and elaborates every edited
  design with iverilog and verilator (`tools/regress/hdl_compile.py` in the source tree).


### In Baya

The same planner runs inside baya-shell/designplayer-shell as `baya::punch_ports`,
`baya::feedthrough` and `baya::uniquify`, on the in-memory design, with `-update_upf` / `-update_sdc`
keeping the power intent and constraints in step (see the shell's AGENTS.md).

### See also

swapcells and uniquifyverilog (same surgical-edit engine), createhierarchy, mergemodules.
