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**