From f504d8d6fed9d2047ce8ae9b5eea1e27e72e5abb Mon Sep 17 00:00:00 2001 From: whitequark Date: Sat, 12 Oct 2019 23:15:09 +0000 Subject: [PATCH] doc: bring COMPAT_SUMMARY up to date. Fixes #112. --- doc/COMPAT_SUMMARY.md | 195 ++++++++++++++++++------------------------ 1 file changed, 83 insertions(+), 112 deletions(-) diff --git a/doc/COMPAT_SUMMARY.md b/doc/COMPAT_SUMMARY.md index d81f78a..31d3ae2 100644 --- a/doc/COMPAT_SUMMARY.md +++ b/doc/COMPAT_SUMMARY.md @@ -5,10 +5,10 @@ nMigen intends to provide as close to 100% compatibility to Migen as possible wi 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 + - *obs*: removed or incompatibly changed with compatibility stub provided + - *obs →n*: removed or incompatibly changed with compatibility stub provided, use *n* instead + - *brk*: removed or incompatibly changed with no replacement provided + - *brk →n*: removed or incompatibly changed with no replacement provided, use *n* instead - *→n*: renamed to *n* - *⇒m*: merged into *m* - *a=→b=*: parameter *a* renamed to *b* @@ -29,101 +29,83 @@ Compatibility summary --------------------- - (−) `fhdl` → `.hdl` - - (+) `bitcontainer` ⇒ `.tools` - - (+) `log2_int` id - - (+) `bits_for` id - - (+) `value_bits_sign` → `Value.shape` - - (−) `conv_output` ? - - (+) `decorators` ⇒ `.hdl.xfrm` + - (⊕) `bitcontainer` ⇒ `.tools` + - (⊕) `log2_int` id + - (⊕) `bits_for` id + - (⊕) `value_bits_sign` → `Value.shape` + - (⊕) `conv_output` **obs** + - (⊕) `decorators` ⇒ `.hdl.xfrm`
Note: `transform_*` methods not considered part of public API. - (⊙) `ModuleTransformer` **brk** - (⊙) `ControlInserter` **brk** - - (+) `CEInserter` → `EnableInserter` - - (+) `ResetInserter` id - - (+) `ClockDomainsRenamer` → `DomainRenamer`, `cd_remapping=`→`domain_map=` + - (⊕) `CEInserter` → `EnableInserter` + - (⊕) `ResetInserter` id + - (⊕) `ClockDomainsRenamer` → `DomainRenamer`, `cd_remapping=`→`domain_map=` - (⊙) `edif` **brk** - - (+) `module` **obs** → `.hdl.dsl` - - (+) `FinalizeError` **obs** - - (+) `Module` **obs** → `.hdl.dsl.Module` + - (⊕) `module` **obs** → `.hdl.dsl` +
Note: any class inheriting from `Module` in oMigen should inherit from `Elaboratable` in nMigen and use an nMigen `Module` in its `.elaborate()` method. + - (⊕) `FinalizeError` **obs** + - (⊕) `Module` **obs** → `.hdl.dsl.Module` - (⊙) `namer` **brk** - - (−) `simplify` ? - - (−) `FullMemoryWE` ? - - (−) `MemoryToArray` ? - - (−) `SplitMemory` ? + - (⊙) `simplify` **brk** - (⊕) `specials` **obs** - (⊙) `Special` **brk** - - (⊕) `Tristate` → `.lib.io.Tristate`, `target=`→`io=` - - (⊕) `TSTriple` → `.lib.io.TSTriple`, `bits_sign=`→`shape=` + - (⊕) `Tristate` **obs** + - (⊕) `TSTriple` **obs** → `.lib.io.Pin` - (⊕) `Instance` → `.hdl.ir.Instance` - (⊕) `Memory` id +
Note: nMigen memories should not be added as submodules. - (⊕) `.get_port` **obs** → `.read_port()` + `.write_port()` - - (⊕) `_MemoryPort` **obs** -
Note: nMigen separates read and write ports. + - (⊕) `_MemoryPort` **obs** → `.hdl.mem.ReadPort` + `.hdl.mem.WritePort` - (⊕) `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: in designs using `NO_CHANGE`, replace it with logic implementing required semantics explicitly, or with a different mode. + - (⊕) `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` ? + - (⊕) `wrap` → `Value.cast` + - (⊕) `_Operator` → `Operator`, `op=`→`operator=`, `.op`→`.operator` + - (⊕) `Mux` id + - (⊕) `_Slice` → `Slice` id + - (⊕) `_Part` → `Part` id + - (⊕) `Cat` id, `.l`→`.parts` + - (⊕) `Replicate` → `Repl`, `v=`→`value=`, `n=`→`count=`, `.v`→`.value`, `.n`→`.count` + - (⊕) `Constant` → `Const`, `bits_sign=`→`shape=`, `.nbits`→`.width` + - (⊕) `Signal` id, `bits_sign=`→`shape=`, `attr=`→`attrs=`, `name_override=`∼, `related=`, `variable=`∼, `.nbits`→`.width` + - (⊕) `ClockSignal` id, `cd=`→`domain=`, `.cd`→`.domain` + - (⊕) `ResetSignal` id, `cd=`→`domain=`, `.cd`→`.domain` + - (⊕) `_Statement` → `Statement` + - (⊕) `_Assign` → `Assign`, `l=`→`lhs=`, `r=`→`rhs=` + - (⊕) `_check_statement` **obs** → `Statement.cast` + - (⊕) `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` **brk** + - (⊙) `SPECIAL_INPUT`/`SPECIAL_OUTPUT`/`SPECIAL_INOUT` **brk** - (⊙) `_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** + - (⊙) `tools` **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` + - (⊙) `tracer` **brk** + - (⊕) `get_var_name` → `.tracer.get_var_name` + - (⊙) `remove_underscore` **brk** + - (⊙) `get_obj_var_name` **brk** + - (⊙) `index_id` **brk** + - (⊙) `trace_back` **brk** + - (⊙) `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 + - (⊙) `MultiRegImpl` **brk** + - (⊕) `MultiReg` → `.lib.cdc.FFSynchronizer` - (−) `PulseSynchronizer` ? - (−) `BusSynchronizer` ? - (⊕) `GrayCounter` **obs** → `.lib.coding.GrayEncoder` @@ -139,24 +121,16 @@ Compatibility summary - (⊕) `PriorityDecoder` id - (−) `divider` ? - (−) `Divider` ? - - (−) `fifo` ? + - (⊕) `fifo` → `.lib.fifo` - (⊕) `_FIFOInterface` → `FIFOInterface` - - (⊕) `SyncFIFO` id, `.fifo=`∼ + - (⊕) `SyncFIFO` id, `.replace=`∼ - (⊕) `SyncFIFOBuffered` id, `.fifo=`∼ - - (−) `AsyncFIFO` ? - - (−) `AsyncFIFOBuffered` ? - - (+) `fsm` **obs** - - (+) `AnonymousState` **obs** - - (+) `NextState` **obs** - - (+) `NextValue` **obs** - - (+) `_LowerNext` **obs** - - (+) `FSM` **obs** - - (−) `io` ? - - (−) `DifferentialInput` ? - - (−) `DifferentialOutput` ? - - (−) `CRG` ? - - (−) `DDRInput` ? - - (−) `DDROutput` ? + - (⊕) `AsyncFIFO` ? + - (⊕) `AsyncFIFOBuffered`, `.fifo=`∼ + - (⊕) `fsm` **obs** +
Note: FSMs are a part of core nMigen DSL; however, not all functionality is provided. The compatibility shim is a complete port of Migen FSM module. + - (⊙) `io` **brk** +
Note: all functionality in this module is a part of nMigen platform system. - (−) `misc` ? - (−) `split` ? - (−) `displacer` ? @@ -164,33 +138,30 @@ Compatibility summary - (−) `timeline` ? - (−) `WaitTimer` ? - (−) `BitSlip` ? - - (−) `record` **obs** → `.hdl.rec.Record` - - (−) `DIR_NONE` id - - (−) `DIR_M_TO_S` → `DIR_FANOUT` - - (−) `DIR_S_TO_M` → `DIR_FANIN` - - (−) `set_layout_parameters` **brk** - - (−) `layout_len` **brk** - - (−) `layout_get` **brk** - - (−) `layout_partial` **brk** - - (−) `Record` id - - (+) `resetsync` ? - - (+) `AsyncResetSynchronizer` **obs** → `.lib.cdc.ResetSynchronizer` + - (⊕) `record` **obs** → `.hdl.rec.Record` +
Note: nMigen uses a `Layout` object to represent record layouts. + - (⊕) `DIR_NONE` id + - (⊕) `DIR_M_TO_S` → `DIR_FANOUT` + - (⊕) `DIR_S_TO_M` → `DIR_FANIN` + - (⊕) `Record` id + - (⊙) `set_layout_parameters` **brk** + - (⊙) `layout_len` **brk** + - (⊙) `layout_get` **brk** + - (⊙) `layout_partial` **brk** + - (⊕) `resetsync` **obs** + - (⊕) `AsyncResetSynchronizer` **obs** → `.lib.cdc.ResetSynchronizer` - (−) `roundrobin` ? - (−) `SP_WITHDRAW`/`SP_CE` ? - (−) `RoundRobin` ? - (−) `sort` ? - (−) `BitonicSort` ? - - (-) `sim` **obs** → `.back.pysim` + - (⊕) `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** + - (⊙) `build` **brk** +
Note: the build system has been completely redesigned in nMigen. + - (⊙) `util` **brk** -- 2.30.2