Roadmap to Amaranth 0.5

[Catherine]

With both of our banner features (async testbenches and minimal streams) having undergone enough of a design process to have an RFC, it is time to decide on the final scope of the Amaranth 0.5 release. We have a milestone; this issue however provides more context.

Release blockers

All tasks from this list must be completed before Amaranth 0.5.0 is released.

RFCs:

1. amaranth-lang/rfcs#61
2. amaranth-lang/rfcs#59
3. amaranth-lang/rfcs#58
4. amaranth-lang/rfcs#62
5. amaranth-lang/rfcs#65
6. amaranth-lang/rfcs#63
7. amaranth-lang/rfcs#64

Features:

1. Async testbenches (RFC 36, #1213)
   • Banner feature.
   • Enables simulation helper functions for FIFOs and streams.
   • Remaining work:
     • Implementation
     • Guide level documentation for amaranth.sim
     • Reference documentation for amaranth.sim
2. Streams (RFC 61, #1244)
   • Banner feature.
   • Enables standard I/O and SoC interfacing.
   • Remaining work:
     • Implementation
     • Guide level documentation
     • Reference documentation
3. New lib.io (RFC 55, #1210)
   • Enables adding peripherals to standard I/O library.
   • Remaining work:
     • Platform overrides for each platform
     • Guide level documentation
     • Reference documentation
4. Component metadata (RFC 30, #1047)
   • Enables export of SoC memory maps.
   • Remaining work:
     • Bug where .array() on members is ignored
     • Guide level documentation
     • Reference documentation
5. Removing upwards propagation of clock domains (RFC 59, #1242)
   • Necessary for clock domain rework planned for Amaranth 0.6.
   • Remaining work:
     • Implementation
6. Print statement and string formatting (RFC 50, #1186)
   • Enables improved debugging and symbolic display of complex data structures in waveform viewer.
   • Remaining work:
     • Extend Yosys with more format specifiers: YosysHQ/yosys#4301
     • Expand RTLIL backend to use extended format specifiers
     • Bump amaranth-yosys package version (after Yosys release)
     • Bump Yosys version requirement (after Yosys release)
7. Move hdl.Memory to lib.Memory (RFC 45, #1083)
   • Enables Memory to interoperate with lib.wiring, lib.data
   • Remaining work:
     • Renaming r_ports, w_ports accessors for consistency
     • Using correct (flipped) members in port signatures
     • Guide level documentation
     • Reference documentation
8. Add MemoryData to replace MemoryIdentity (RFC 62, #1241)
   • Enables an improved testing and simulation workflow.
   • Remaining work:
     • Implementation
     • Updating documentation
9. Add format hook for ValueCastable (RFC 58, #1243)
   • Enables printing of custom value-castables.
   • Remaining work:
     • Implementation
     • Reference documentation
10. Add (public) hook for describing aggregate value representation (RFC 65, #1293)
    • Technical debt from Amaranth 0.4: forbidden coupling of lib with private hdl interfaces.
    • Remaining work:
      • RFC
      • Implementation
      • Reference documentation (if amaranth.hdl.Format has reference docs for 0.5)
11. Signals with private names (#1223)
    • Technical debt from FSM rework in Amaranth 0.5: public exposure of internal fsm_ongoing_STATE signals.
    • Remaining work:
      • Implementation
      • Documentation (if amaranth.hdl.Signal has reference docs for 0.5)
12. Deprecating lib.coding (RFC 63, #1292)
    • Removes a module no longer good enough by our standards.
    • Remaining work:
      • Implementation

Improvements:

1. EnumMeta renaming (#1073)
   • Required for compatibility with Python 3.11.
   • Remaining work:
     • Implementation
2. RTLIL backend refactor (#1100)
   • Required to land #1152, which is a fix for #1148.
   • Remaining work:
     • Implementation
3. Better error for platform.add_clock_constraint(ClockSignal()) (#542)
   • Common mistake, open for 4 years.
   • Remaining work:
     • Implementation

Regressions and problems:

1. Quartus DSP inference (#1148)
   • Remaining work:
     • Testing
2. True dual-port BRAM inference with Yosys (#1011)
   • Remaining work:
     • Investigation
     • Addressing
3. Empty submodule name (#1209)
   • Remaining work:
     • Implementation
4. Continuous assignment to Verilog reg (#717)
   • Remaining work:
     • Implementation
     • Yosys dependency bump
5. Signal.like for shape-castables (#1285)
   • Remaining work:
     • Implementation
6. Detection of combinational loops (#704)
   • Remaining work:
     • Implementation
7. Domain handling in lib.io (#1347)
   • Remaining work:
     • Design
     • Implementation review

Nice-to-haves

Whichever tasks from this list are complete by the time all of the blockers are complete get included in Amaranth 0.5; the rest are included in Amaranth 0.6 or later.

RFCs:

• amaranth-lang/rfcs#52
• amaranth-lang/rfcs#41

Features:

1. Structured source locations (#1131)
   • Enables improved integration with CXXRTL protocol debuggers.
   • Remaining work:
     • Design
     • Implementation
     • Testing
2. Lattice Nexus platform (#759)
   • Enables support for a new FPGA family.
   • Remaining work:
     • Validation on a Nexus developer board by @whitequark
3. Expanded .gtkw generation for the simulator (#764)
   • Enables easier debugging of complex designs.
   • Remaining work:
     • Implementation
4. Choice (unmerged RFC 52, N/A)
   • Improves orthogonality of base language.
   • Remaining work:
     • Implemenation
     • Guide level documentation
     • Reference documentation

Improvements:

1. Reference documentation for all of amaranth.hdl (#785)
   • Required for credibility of Amaranth as a production-grade platform.
   • Guide level documentation covers enouugh ground to make this a nice-to-have rather than a blocker.
   • Remaining work:
     • Value.__getitem__
     • Value.matches
     • Const
     • C
     • Mux
     • Cat
     • Signal
     • ClockSignal
     • ResetSignal
     • Array
     • Format
     • Statement (?)
     • Assign (?)
     • Print
     • Assert
     • IOValue
     • IOPort
2. Clarify purpose of .bool() vs .any() (#1219)
   • Confusing to newcomers.
   • Remaining work:
     • Update guide level documentation
     • Update reference documentation
3. Clarify semantics of .implies() (#1239)
   • Potentially very confusing semantics
   • Remaining work:
     • Decide on new semantics
     • Implement new semantics
     • If operator is kept, update guide level documentation
     • If operator is kept, update reference level documentation
4. Fix TestPyPI upload (#1229)
   • Necessary to have HEAD on playground.
   • Remaining work:
     • Implement PDM backend version hook
     • Test that uploads work

[Catherine]

All required roadmap items are now complete. 🎉