amaranth/doc/COMPAT_SUMMARY.md

Migen and nMigen compatibility summary

nMigen intends to provide as close to 100% compatibility to Migen as possible without compromising its other goals. However, Migen widely uses * imports, tends to expose implementation details, and in general does not have a well-defined interface. This document attempts to elucidate a well-defined Migen API surface (including, when necessary, private items that have been used downstream), and describes the intended nMigen replacements and their implementation status.

API change legend:

• id: identical
• obs: removed or irreversibly changed with compatibility stub provided
• obs →n: removed or irreversibly changed with compatibility stub provided, use n instead
• brk: removed or irreversibly changed with no replacement provided
• brk →n: removed or irreversibly changed with no replacement provided, use n instead
• →n: renamed to n
• ⇒m: merged into m
• a=→b=: parameter a renamed to b
• a=∼: parameter a removed
• .a=→.b: attribute a renamed to b
• ?: no decision made yet

When describing renames or replacements, mod refers to a 3rd-party package mod (no nMigen implementation provided), .mod.item refers to nmigen.mod.item, and "(import .item)" means that, while item is provided under nmigen.mod.item, it is aliased to, and should be imported from a shorter path for readability.

Status legend:

• (−) No decision yet, or no replacement implemented
• (+) Implemented replacement (the API and/or compatibility shim are provided)
• (⊕) Verified replacement and/or compatibility shim (the compatibility shim is manually reviewed and/or has 100% test coverage)
• (⊙) No direct replacement or compatibility shim is provided

Compatibility summary

• (−) fhdl → .hdl
  • (+) bitcontainer ⇒ .tools
    • (+) log2_int id
    • (+) bits_for id
    • (+) value_bits_sign → Value.shape
  • (−) conv_output ?
  • (+) decorators ⇒ .hdl.xfrm
    Note: transform_* methods not considered part of public API.
    • (⊙) ModuleTransformer brk
    • (⊙) ControlInserter brk
    • (-) CEInserter obs
    • (-) ResetInserter obs
    • (+) ClockDomainsRenamer → DomainRenamer, cd_remapping=→domain_map=
  • (⊙) edif brk
  • (+) module obs → .hdl.dsl
    • (+) FinalizeError obs
    • (+) Module obs → .hdl.dsl.Module
  • (⊙) namer brk
  • (−) simplify ?
    • (−) FullMemoryWE ?
    • (−) MemoryToArray ?
    • (−) SplitMemory ?
  • (−) specials obs
    • (−) Special ?
    • (−) Tristate ?
    • (+) TSTriple → .lib.io.TSTriple, bits_sign=→shape=
    • (−) Instance ?
    • (+) Memory id
      • (+) .get_port obs → .read_port() + .write_port()
    • (+) _MemoryPort obs
      Note: nMigen separates read and write ports.
    • (+) READ_FIRST/WRITE_FIRST obs
      Note: READ_FIRST corresponds to mem.read_port(transparent=False), and WRITE_FIRST to mem.read_port(transparent=True).
    • (-) NO_CHANGE brk
      Note: in designs using NO_CHANGE, repalce it with an asynchronous read port and logic implementing required semantics explicitly.
  • (−) structure → .hdl.ast
    • (+) DUID id
    • (+) _Value → Value
      Note: values no longer valid as keys in dict and set; use ValueDict and ValueSet instead.
    • (+) wrap → Value.wrap
    • (+) _Operator → Operator
    • (+) Mux id
    • (+) _Slice → Slice, stop=→end=, .stop→.end
    • (+) _Part → Part
    • (+) Cat id, .l→.parts
    • (+) Replicate → Repl, v=→value=, n=→count=, .v→.value, .n→.count
    • (+) Constant → Const, bits_sign=→shape=
    • (+) Signal id, bits_sign=→shape=, attr=→attrs=, name_override=∼, related=, variable=∼
    • (+) ClockSignal id, cd=→domain=
    • (+) ResetSignal id, cd=→domain=
    • (+) _Statement → Statement
    • (+) _Assign → Assign, l=→lhs=, r=→rhs=
    • (-) _check_statement obs → Statement.wrap
    • (+) If obs → .hdl.dsl.Module.If
    • (+) Case obs → .hdl.dsl.Module.Switch
    • (+) _ArrayProxy → .hdl.ast.ArrayProxy, choices=→elems=, key=→index=
    • (+) Array id
    • (+) ClockDomain → .hdl.cd.ClockDomain
    • (−) _ClockDomainList ?
    • (−) SPECIAL_INPUT/SPECIAL_OUTPUT/SPECIAL_INOUT ?
    • (⊙) _Fragment brk → .hdl.ir.Fragment
  • (−) tools brk
    • (−) list_signals ?
    • (−) list_targets ?
    • (−) list_inputs ?
    • (−) group_by_targets ?
    • (⊙) list_special_ios brk
    • (⊙) list_clock_domains_expr brk
    • (−) list_clock_domains ?
    • (−) is_variable ?
    • (⊙) generate_reset brk
    • (⊙) insert_reset brk
    • (⊙) insert_resets brk → .hdl.xfrm.ResetInserter
    • (⊙) lower_basics brk
    • (⊙) lower_complex_slices brk
    • (⊙) lower_complex_parts brk
    • (⊙) rename_clock_domain_expr brk
    • (⊙) rename_clock_domain brk → .hdl.xfrm.DomainRenamer
    • (⊙) call_special_classmethod brk
    • (⊙) lower_specials brk
  • (−) tracer brk
    • (−) get_var_name ?
    • (−) remove_underscore ?
    • (−) get_obj_var_name ?
    • (−) index_id ?
    • (−) trace_back ?
  • (−) verilog
    • (−) DummyAttrTranslate ?
    • (−) convert obs → .back.verilog.convert
  • (⊙) visit brk → .hdl.xfrm
    • (⊙) NodeVisitor brk
    • (⊙) NodeTransformer brk → .hdl.xfrm.ValueTransformer/.hdl.xfrm.StatementTransformer
• (−) genlib → .lib
  • (−) cdc ?
    • (−) MultiRegImpl ?
    • (+) MultiReg id
    • (−) PulseSynchronizer ?
    • (−) BusSynchronizer ?
    • (−) GrayCounter ?
    • (−) GrayDecoder ?
    • (−) ElasticBuffer ?
    • (−) lcm ?
    • (−) Gearbox ?
  • (−) coding ?
    • (−) Encoder ?
    • (−) PriorityEncoder ?
    • (−) Decoder ?
    • (−) PriorityDecoder ?
  • (−) divider ?
    • (−) Divider ?
  • (−) fifo ?
    • (−) SyncFIFO ?
    • (−) SyncFIFOBuffered ?
    • (−) AsyncFIFO ?
    • (−) AsyncFIFOBuffered ?
    • (−) _FIFOInterface ?
  • (+) fsm obs
    • (+) AnonymousState obs
    • (+) NextState obs
    • (+) NextValue obs
    • (+) _LowerNext obs
    • (+) FSM obs
  • (−) io ?
    • (−) DifferentialInput ?
    • (−) DifferentialOutput ?
    • (−) CRG ?
    • (−) DDRInput ?
    • (−) DDROutput ?
  • (−) misc ?
    • (−) split ?
    • (−) displacer ?
    • (−) chooser ?
    • (−) timeline ?
    • (−) WaitTimer ?
    • (−) BitSlip ?
  • (−) record ?
    • (−) DIR_NONE/DIR_S_TO_M/DIR_M_TO_S ?
    • (−) set_layout_parameters ?
    • (−) layout_len ?
    • (−) layout_get ?
    • (−) layout_partial ?
    • (−) Record ?
  • (−) resetsync ?
    • (−) AsyncResetSynchronizer ?
  • (−) roundrobin ?
    • (−) SP_WITHDRAW/SP_CE ?
    • (−) RoundRobin ?
  • (−) sort ?
    • (−) BitonicSort ?
• (-) sim obs → .back.pysim
  Note: only items directly under nmigen.compat.sim, not submodules, are provided.
  • (⊙) core brk
  • (⊙) vcd brk → vcd
  • (⊙) Simulator brk
  • (+) run_simulation obs → .back.pysim.Simulator
  • (−) passive obs → .hdl.ast.Passive
• (−) build ?
• (+) util obs
  • (+) misc ⇒ .tools
    • (+) flat_iteration → .flatten
    • (⊙) xdir brk
    • (⊙) gcd_multiple brk
  • (⊙) treeviz brk