Roadmap to Amaranth 0.5

[whitequark]

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. Minimal stream interface rfcs#61
2. Add an RFC for removing upwards propagation of clock domains rfcs#59
3. Add an RFC for ValueCastable formatting. rfcs#58
4. RFC 62: The MemoryData class. rfcs#62
5. Add an RFC for special formatting for structures and enums rfcs#65
6. Add an RFC for lib.coding removal. rfcs#63
7. Amend RFC #36 with a concrete concurrency model rfcs#64

Features:

1. Async testbenches (RFC 36, Tracking issue for RFC 36: Async testbench functions #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, Tracking issue for RFC 61: Minimal stream interface #1244)
   • Banner feature.
   • Enables standard I/O and SoC interfacing.
   • Remaining work:
     • Implementation
     • Guide level documentation
     • Reference documentation
3. New lib.io (RFC 55, Tracking issue for RFC 55: New lib.io components #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, Tracking issue for RFC 30: Component metadata #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, Tracking issue for RFC 59: Get rid of upwards propagation of clock domains #1242)
   • Necessary for clock domain rework planned for Amaranth 0.6.
   • Remaining work:
     • Implementation
6. Print statement and string formatting (RFC 50, Tracking issue for RFC 50: Print statement and string formatting #1186)
   • Enables improved debugging and symbolic display of complex data structures in waveform viewer.
   • Remaining work:
     • Extend Yosys with more format specifiers: Add several new formatting features used by Amaranth to translate Python format strings 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, Tracking issue for RFC 45: Move hdl.Memory to lib.Memory #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, Tracking issue for RFC 62: The MemoryData class. #1241)
   • Enables an improved testing and simulation workflow.
   • Remaining work:
     • Implementation
     • Updating documentation
9. Add format hook for ValueCastable (RFC 58, Tracking issue for RFC 58: Core support for ValueCastable formatting #1243)
   • Enables printing of custom value-castables.
   • Remaining work:
     • Implementation
     • Reference documentation
10. Add (public) hook for describing aggregate value representation (RFC 65, Tracking issue for RFC 65: Special formatting for structures and enums #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 (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, Tracking issue for RFC 63: Remove amaranth.lib.coding #1292)
    • Removes a module no longer good enough by our standards.
    • Remaining work:
      • Implementation

Improvements:

1. EnumMeta renaming (EnumMeta has been renamed to EnumType in Python 3.11 #1073)
   • Required for compatibility with Python 3.11.
   • Remaining work:
     • Implementation
2. RTLIL backend refactor (Refactor back.rtlil to convert Amaranth IR structures to Yosys IR structures #1100)
   • Required to land back.rtlil: Opportunistically trim zero and sign extension on operands. #1152, which is a fix for New IR causes DSP inference issues with Quartus #1148.
   • Remaining work:
     • Implementation
3. Better error for platform.add_clock_constraint(ClockSignal()) (Using ClockSignal in platform.add_clock_constraint #542)
   • Common mistake, open for 4 years.
   • Remaining work:
     • Implementation

Regressions and problems:

1. Quartus DSP inference (New IR causes DSP inference issues with Quartus #1148)
   • Remaining work:
     • Testing
2. True dual-port BRAM inference with Yosys (Inferring True Dual-Port BRAMs with the new IR on Series 7 and ECP5 #1011)
   • Remaining work:
     • Investigation
     • Addressing
3. Empty submodule name (Zero-length submodule name breaks things #1209)
   • Remaining work:
     • Implementation
4. Continuous assignment to Verilog reg (Conditional assignment to a slice can generate invalid Verilog #717)
   • Remaining work:
     • Implementation
     • Yosys dependency bump
5. Signal.like for shape-castables (Signal.like is not fully functional with ShapeCastable-based signals #1285)
   • Remaining work:
     • Implementation
6. Detection of combinational loops (Detect and reject netlists with combinatorial loops #704)
   • Remaining work:
     • Implementation
7. Domain handling in lib.io (vendor, io: fix missing i_domain and o_domain arguments when specializing #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:

• Add RFC for Choice. rfcs#52
• Add an RFC for fixed point types. rfcs#41

Features:

1. Structured source locations (Structured source locations #1131)
   • Enables improved integration with CXXRTL protocol debuggers.
   • Remaining work:
     • Design
     • Implementation
     • Testing
2. Lattice Nexus platform (add Lattice Nexus vendor platform (using nextpnr-nexus and prjoxide) #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 (GTKW files with signal groups #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 (Document the Python APIs in 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() (doc: Reduction operators: .any() vs .bool() #1219)
   • Confusing to newcomers.
   • Remaining work:
     • Update guide level documentation
     • Update reference documentation
3. Clarify semantics of .implies() (Do something with Value.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 (Fix failing uploads to TestPyPI from CI #1229)
   • Necessary to have HEAD on playground.
   • Remaining work:
     • Implement PDM backend version hook
     • Test that uploads work

[whitequark]

All required roadmap items are now complete. 🎉