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:

• (×) Intended replacement (the API is decided on)
• (−) Implemented replacement (the API and compatibility shim are provided)
• (+) Verified replacement and/or compatibility shim (the compatibility shim is manually reviewed and has 100% coverage)
• (∼) No direct replacement or compatibility shim is provided

Compatibility summary

• (×) fhdl
  • (×) bitcontainer ⇒ .tools
    • (×) log2_int id
    • (×) bits_for id
    • (×) value_bits_sign → Value.shape
  • (×) conv_output ?
  • (×) decorators ⇒ .fhdl.xfrm Note: transform_* methods not considered part of public API.
    • (∼) ModuleTransformer brk
    • (∼) ControlInserter brk
    • (×) CEInserter id, clock_domains=→controls=
    • (×) ResetInserter id, clock_domains=→controls=
    • (×) ClockDomainsRenamer → DomainRenamer, cd_remapping=→domain_map=
  • (∼) edif brk
  • (×) module obs → .fhdl.dsl
    • (×) FinalizeError obs
    • (×) Module obs → .fhdl.dsl.Module
  • (∼) namer brk
  • (×) simplify ?
    • (×) FullMemoryWE ?
    • (×) MemoryToArray ?
    • (×) SplitMemory ?
  • (×) specials obs
    • (×) Special ?
    • (×) Tristate ?
    • (×) TSTriple → .genlib.io.TSTriple, bits_sign=→shape=
    • (×) Instance ?
    • (×) READ_FIRST/WRITE_FIRST/NO_CHANGE ?
    • (×) _MemoryPort ?
    • (×) Memory ?
  • (×) structure → .fhdl.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 → Mux
    • (×) _Slice → Slice, stop=→end=, .stop→.end
    • (×) _Part → Part
    • (×) Cat id, .l→.operands
    • (×) 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 → .fhdl.dsl.Module.If
    • (×) Case obs → .fhdl.dsl.Module.Switch
    • (×) _ArrayProxy ?
    • (×) Array ?
    • (×) ClockDomain → .fhdl.cd.ClockDomain
    • (×) _ClockDomainList ?
    • (×) SPECIAL_INPUT/SPECIAL_OUTPUT/SPECIAL_INOUT ?
    • (∼) _Fragment brk → .fhdl.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 → .fhdl.xfrm.ResetInserter
    • (∼) lower_basics brk
    • (∼) lower_complex_slices brk
    • (∼) lower_complex_parts brk
    • (∼) rename_clock_domain_expr brk
    • (∼) rename_clock_domain brk → .fhdl.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 → .fhdl.xfrm
    • (∼) NodeVisitor brk
    • (∼) NodeTransformer brk → .fhdl.xfrm.ValueTransformer/.fhdl.xfrm.StatementTransformer
• (×) genlib
  • (×) 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
  • (∼) core brk
  • (∼) vcd brk → vcd Note: only items directly under nmigen.compat.sim, not submodules, are provided.
  • (×) Simulator brk
  • (×) run_simulation obs → .back.pysim.Simulator
  • (×) passive obs → .fhdl.ast.Passive
• (×) build ?
• (×) util obs
  • (×) misc ⇒ .tools
    • (×) flat_iteration → .flatten
    • (∼) xdir brk
    • (∼) gcd_multiple brk
  • (∼) treeviz brk