Skip to content

Conversation

@seldridge
Copy link
Member

@seldridge seldridge commented Nov 28, 2025

Deprecate BlackBox and tell users to switch to ExtModule. BlackBox has a
ton of baggage associated with it, due to it mandating, at runtime, a
single val io call and no additional calls to IO while also magically
removing the io_ prefix in the generated FIRRTL. ExtModule is far
cleaner and works as a user would expect. You can call IO as much as
you want. No magic prefixing happens.

This is slightly unfortunate as one could argue that BlackBox is a good
name. However, you can also argue (more strongly I would add) that this
is an "external module" and it would be better to call it as such. If
this is controversial, we can consider a migration back from ExtModule
to BlackBox.

Migrate some tests that were only testing blackboxes to be duplicated in
the external module tests. This will allow us to just delete this test
later.

This has three motivations:

  1. BlackBox has always been janky for the reasons above and ExtModule
    is the saner generator API.

  2. It's bad to have two similar, though subtly different ways of doing
    things.

  3. The singular IO that BlackBox forces users to go through means that
    BlackBox cannot have domain information attached to it. This
    essentially means that BlackBox will be essentially unusable until
    domains gain support for being in subfields. It's easier to just
    deprecate BlackBox than to require that domains gain this complicated
    feature addition just now.

This is stacked on #5102.

Release Notes

Deprecate BlackBox in favor of ExtModule.

@seldridge seldridge added the Deprecation Deprecates an API, will be included in release notes label Nov 28, 2025
@seldridge seldridge requested a review from jackkoenig November 28, 2025 05:35
@seldridge seldridge marked this pull request as draft November 28, 2025 05:36
@seldridge seldridge force-pushed the dev/seldridge/deprecate-extmodule-traits-2 branch from e783564 to 969a052 Compare November 28, 2025 22:00
@seldridge seldridge force-pushed the dev/seldridge/deprecate-blackbox branch 4 times, most recently from 646af55 to ee05439 Compare November 28, 2025 23:18
Deprecate BlackBox and tell users to switch to ExtModule.  BlackBox has a
ton of baggage associated with it, due to it mandating, at runtime, a
single `val io` call and no additional calls to `IO` while also magically
removing the `io_` prefix in the generated FIRRTL.  `ExtModule` is far
cleaner and works as a user would expect.  You can call `IO` as much as
you want.  No magic prefixing happens.

This is slightly unfortunate as one could argue that `BlackBox` is a good
name.  However, you can also argue (more strongly I would add) that this
is an "external module" and it would be better to call it as such.  If
this is controversial, we can consider a migration back from `ExtModule`
to `BlackBox`.

Migrate some tests that were only testing blackboxes to be duplicated in
the external module tests.  This will allow us to just delete this test
later.

This has three motivations:

1. `BlackBox` has always been janky for the reasons above and `ExtModule`
is the saner generator API.

2. It's bad to have two similar, though subtly different ways of doing
things.

3. The singular IO that `BlackBox` forces users to go through means that
`BlackBox` cannot have domain information attached to it.  This
essentially means that `BlackBox` will be essentially unusable until
domains gain support for being in subfields.  It's easier to just
deprecate `BlackBox` than to require that domains gain this complicated
feature addition just now.

Signed-off-by: Schuyler Eldridge <[email protected]>
@seldridge seldridge force-pushed the dev/seldridge/deprecate-blackbox branch from ee05439 to c24d0f1 Compare November 29, 2025 00:31
@seldridge seldridge mentioned this pull request Nov 29, 2025
8 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Deprecation Deprecates an API, will be included in release notes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants