llvm / llvm/circt

[RFC][FIRRTL] Add firrtl.declare op for cross-circuit linking placeholders

Open
#9,930 3 comments 0 reactions 1 assignee Claimed by @unlsycn View on GitHub
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.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.