amaranth icon indicating copy to clipboard operation
amaranth copied to clipboard

Published 20 hours ago • verified publisher icon amaranth-lang

Roadmap to Amaranth 0.5

Open whitequark opened this issue 1 year ago • 0 comments

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. https://github.com/amaranth-lang/rfcs/pull/61
  2. https://github.com/amaranth-lang/rfcs/pull/59
  3. https://github.com/amaranth-lang/rfcs/pull/58
  4. https://github.com/amaranth-lang/rfcs/pull/62
  5. https://github.com/amaranth-lang/rfcs/pull/65
  6. https://github.com/amaranth-lang/rfcs/pull/63
  7. https://github.com/amaranth-lang/rfcs/pull/64

Features:

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

Improvements:

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

Regressions and problems:

  1. Quartus DSP inference (https://github.com/amaranth-lang/amaranth/issues/1148)
    • Remaining work:
      • [x] Testing
  2. True dual-port BRAM inference with Yosys (https://github.com/amaranth-lang/amaranth/issues/1011)
    • Remaining work:
      • [x] Investigation
      • [x] Addressing
  3. Empty submodule name (https://github.com/amaranth-lang/amaranth/issues/1209)
    • Remaining work:
      • [ ] Implementation
  4. Continuous assignment to Verilog reg (https://github.com/amaranth-lang/amaranth/issues/717)
    • Remaining work:
      • [x] Implementation
      • [x] Yosys dependency bump
  5. Signal.like for shape-castables (https://github.com/amaranth-lang/amaranth/issues/1285)
    • Remaining work:
      • [x] Implementation
  6. Detection of combinational loops (https://github.com/amaranth-lang/amaranth/issues/704)
    • Remaining work:
      • [x] Implementation
  7. Domain handling in lib.io (https://github.com/amaranth-lang/amaranth/pull/1347)
    • Remaining work:
      • [x] Design
      • [x] 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:

  • https://github.com/amaranth-lang/rfcs/pull/52
  • https://github.com/amaranth-lang/rfcs/pull/41

Features:

  1. Structured source locations (https://github.com/amaranth-lang/amaranth/issues/1131)
    • Enables improved integration with CXXRTL protocol debuggers.
    • Remaining work:
      • [ ] Design
      • [ ] Implementation
      • [ ] Testing
  2. Lattice Nexus platform (https://github.com/amaranth-lang/amaranth/pull/759)
    • Enables support for a new FPGA family.
    • Remaining work:
      • [x] Validation on a Nexus developer board by @whitequark
  3. Expanded .gtkw generation for the simulator (https://github.com/amaranth-lang/amaranth/issues/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 (https://github.com/amaranth-lang/amaranth/issues/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:
      • [x] Value.__getitem__
      • [x] Value.matches
      • [ ] Const
      • [ ] C
      • [ ] Mux
      • [ ] Cat
      • [ ] Signal
      • [ ] ClockSignal
      • [ ] ResetSignal
      • [ ] Array
      • [ ] Format
      • [ ] Statement (?)
      • [ ] Assign (?)
      • [ ] Print
      • [ ] Assert
      • [ ] IOValue
      • [ ] IOPort
  2. Clarify purpose of .bool() vs .any() (https://github.com/amaranth-lang/amaranth/issues/1219)
    • Confusing to newcomers.
    • Remaining work:
      • [x] Update guide level documentation
      • [x] Update reference documentation
  3. Clarify semantics of .implies() (https://github.com/amaranth-lang/amaranth/issues/1239)
    • Potentially very confusing semantics
    • Remaining work:
      • [x] Decide on new semantics
      • [x] Implement new semantics
      • [x] If operator is kept, update guide level documentation
      • [x] If operator is kept, update reference level documentation
  4. Fix TestPyPI upload (https://github.com/amaranth-lang/amaranth/issues/1229)
    • Necessary to have HEAD on playground.
    • Remaining work:
      • [x] Implement PDM backend version hook
      • [x] Test that uploads work

whitequark avatar Mar 22 '24 03:03 whitequark