[RFC][FIRRTL] Add firrtl.declare op for cross-circuit linking placeholders
- Dominant language
- C++
- Stars
- 2.2k
- Forks
- 524
- Avg merge
- 3d 2h
- Merged PRs (30d)
- 46
Description
## Motivation
firld currently uses `firrtl.extmodule` as a forward declaration placeholder for cross-circuit linking. But `firrtl.extmodule` represents a reference to an external Verilog module. Its identity is determined by `defname`, and it carries attributes like `parameters` and `convention` that are properties of the Verilog module, not the FIRRTL design.
Circuit linking resolves references between FIRRTL modules, not Verilog modules. A placeholder only needs to say "a FIRRTL module with this name and port signature will be provided by another circuit." Using `firrtl.extmodule` for this purpose conflates two unrelated concepts and forces the linker to work around the mismatch (e.g., exempting extmodules from symbol mangling, special-casing empty parameters).
## Proposal
Add `firrtl.declare` to represent a forward declaration for cross-circuit linking:
```mlir
firrtl.declare @Queue(
in %clock: !firrtl.clock,
in %reset: !firrtl.reset,
in %enq: !firrtl.bundle, ready flip: uint<1>, bits: uint<8>>,
out %deq: !firrtl.bundle, ready flip: uint<1>, bits: uint<8>>
) {layers = [@Verification]}
```
## Design
- Attributes: `sym_name`, `portDirections`, `portNames`, `portTypes`, `portLocations`, `layers`.
- Interfaces: `FModuleLike`, `Symbol`.
- Always public: the symbol name is the reference to the target module, so it must not be mangled.
- Must be resolved and removed by firld. Other passes should reject it.
## Resolution
The linker resolves `firrtl.declare @Foo` by symbol name collision with `firrtl.module @Foo` or `firrtl.extmodule @Foo` from another circuit. With `firrtl.declare` handling forward declarations, `firrtl.extmodule` no longer participates in linking. It remains purely an external Verilog module reference.
The existing extmodule-specific logic in the linker (mangling exemption, empty parameters workaround) can be removed.
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.