--- /dev/null
+on: push
+name: CI
+jobs:
+ build:
+ if: github.event_name == 'push' && github.event.ref == 'refs/heads/doc'
+ runs-on: ubuntu-latest
+ steps:
+ - name: Check out source code
+ uses: actions/checkout@v2
+ with:
+ fetch-depth: 0
+ - name: Set up Python
+ uses: actions/setup-python@v2
+ - name: Install dependencies
+ run: |
+ python -m pip install --upgrade setuptools setuptools_scm wheel
+ pip install -r docs/requirements.txt
+ pip install -e .
+ - name: Build documentation
+ run: |
+ sphinx-build docs docs/_build
+ - name: Publish documentation
+ uses: JamesIves/github-pages-deploy-action@releases/v3
+ with:
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ BRANCH: gh-pages
+ FOLDER: docs/_build
+ TARGET_FOLDER: latest/
*.gtkw
# misc user-created
-*.il
-*.v
+/*.il
+/*.v
/build
+++ /dev/null
-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 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*
- - *a=∼*: parameter *a* removed
- - *.a=→.b*: attribute *a* renamed to *b*
- - *.a=∼*: attribute *a* removed
- - *?*: 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` **obs**
- - (⊕) `decorators` ⇒ `.hdl.xfrm`
- <br>Note: `transform_*` methods not considered part of public API.
- - (⊙) `ModuleTransformer` **brk**
- - (⊙) `ControlInserter` **brk**
- - (⊕) `CEInserter` → `EnableInserter`
- - (⊕) `ResetInserter` id
- - (⊕) `ClockDomainsRenamer` → `DomainRenamer`, `cd_remapping=`→`domain_map=`
- - (⊙) `edif` **brk**
- - (⊕) `module` **obs** → `.hdl.dsl`
- <br>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` **brk**
- - (⊕) `specials` **obs**
- - (⊙) `Special` **brk**
- - (⊕) `Tristate` **obs**
- - (⊕) `TSTriple` **obs** → `.lib.io.Pin`
- - (⊕) `Instance` → `.hdl.ir.Instance`
- - (⊕) `Memory` id
- <br>Note: nMigen memories should not be added as submodules.
- - (⊕) `.get_port` **obs** → `.read_port()` + `.write_port()`
- - (⊕) `_MemoryPort` **obs** → `.hdl.mem.ReadPort` + `.hdl.mem.WritePort`
- - (⊕) `READ_FIRST`/`WRITE_FIRST` **obs**
- <br>Note: `READ_FIRST` corresponds to `mem.read_port(transparent=False)`, and `WRITE_FIRST` to `mem.read_port(transparent=True)`.
- - (⊙) `NO_CHANGE` **brk**
- <br>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`
- <br>Note: values no longer valid as keys in `dict` and `set`; use `ValueDict` and `ValueSet` instead.
- - (⊕) `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**
- - (⊙) `insert_resets` **brk** → `.hdl.xfrm.ResetInserter`
- - (⊙) `rename_clock_domain` **brk** → `.hdl.xfrm.DomainRenamer`
- - (⊙) `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` **brk**
- - (⊕) `MultiReg` → `.lib.cdc.FFSynchronizer`
- - (−) `PulseSynchronizer` ?
- - (−) `BusSynchronizer` ?
- - (⊕) `GrayCounter` **obs** → `.lib.coding.GrayEncoder`
- - (⊕) `GrayDecoder` **obs** → `.lib.coding.GrayDecoder`
- <br>Note: `.lib.coding.GrayEncoder` and `.lib.coding.GrayDecoder` are purely combinatorial.
- - (−) `ElasticBuffer` ?
- - (−) `lcm` ?
- - (−) `Gearbox` ?
- - (⊕) `coding` id
- - (⊕) `Encoder` id
- - (⊕) `PriorityEncoder` id
- - (⊕) `Decoder` id
- - (⊕) `PriorityDecoder` id
- - (−) `divider` ?
- - (−) `Divider` ?
- - (⊕) `fifo` → `.lib.fifo`
- - (⊕) `_FIFOInterface` → `FIFOInterface`
- - (⊕) `SyncFIFO` id, `.replace=`∼
- - (⊕) `SyncFIFOBuffered` id, `.fifo=`∼
- - (⊕) `AsyncFIFO` ?
- - (⊕) `AsyncFIFOBuffered`, `.fifo=`∼
- - (⊕) `fsm` **obs**
- <br>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**
- <br>Note: all functionality in this module is a part of nMigen platform system.
- - (−) `misc` ?
- - (−) `split` ?
- - (−) `displacer` ?
- - (−) `chooser` ?
- - (−) `timeline` ?
- - (−) `WaitTimer` ?
- - (−) `BitSlip` ?
- - (⊕) `record` **obs** → `.hdl.rec.Record`
- <br>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`
- <br>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` **brk**
- <br>Note: the build system has been completely redesigned in nMigen.
- - (⊙) `util` **brk**
+++ /dev/null
-*The text below is the original nMigen implementation proposal. It is provided for illustrative and historical purposes only.*
-
-This repository contains a proposal for the design of nMigen in form of an implementation. This implementation deviates from the existing design of Migen by making several observations of its drawbacks:
-
- * Migen is strongly tailored towards Verilog, yet translation of Migen to Verilog is not straightforward, leaves much semantics implicit (e.g. signedness, width extension, combinatorial assignments, sub-signal assignments...);
- * Hierarchical designs are useful for floorplanning and optimization, yet Migen does not support them at all;
- * Migen's syntax is not easily composable, and something like an FSM requires extending Migen's syntax in non-orthogonal ways;
- * Migen reimplements a lot of mature open-source tooling, such as conversion of RTL to Verilog (Yosys' Verilog backend), or simulation (Icarus Verilog, Verilator, etc.), and often lacks in features, speed, or corner case handling.
- * Migen requires awkward specials for some FPGA features such as asynchronous resets.
-
-It also observes that Yosys' intermediate language, RTLIL, is an ideal target for Migen-style logic, as conversion of FHDL to RTLIL is essentially a 1:1 translation, with the exception of the related issues of naming and hierarchy.
-
-This proposal makes several major changes to Migen that hopefully solve all of these drawbacks:
-
- * nMigen changes FHDL's internal representation to closely match that of RTLIL;
- * nMigen outputs RTLIL and relies on Yosys for conversion to Verilog, EDIF, etc;
- * nMigen uses an exact mapping between FHDL signals and RTLIL names to off-load logic simulation to Icarus Verilog, Verilator, etc;
- * nMigen uses an uniform, composable Python eHDL;
- * nMigen outputs hierarchical RTLIL, automatically threading signals through the hierarchy;
- * nMigen supports asynchronous reset directly;
- * nMigen makes driving a signal from multiple clock domains a precise, hard error.
-
-This proposal keeps in mind but does not make the following major changes:
-
- * nMigen could be easily modified to flatten the hierarchy if a signal is driven simultaneously from multiple modules;
- * nMigen could be easily modified to support `x` values (invalid / don't care) by relying on RTLIL's ability to directly represent them;
- * nMigen could be easily modified to support negative edge triggered flip-flops by relying on RTLIL's ability to directly represent them;
- * nMigen could be easily modified to track Python source locations of primitives and export them to RTLIL/Verilog through the `src` attribute, displaying the Python source locations in timing reports directly.
-
-This proposal also makes the following simplifications:
- * Specials are eliminated. Primitives such as memory ports are represented directly, and primitives such as tristate buffers are lowered to a selectable implementation via ordinary dependency injection (`f.submodules += platform.get_tristate(triple, io)`).
-
-The internals of nMigen in this proposal are cleaned up, yet they are kept sufficiently close to Migen that \~all Migen code should be possible to run directly on nMigen using a syntactic compatibility layer.
-
-One might reasonably expect that a roundtrip through RTLIL would result in unreadable Verilog.
-However, this is not the case, e.g. consider the examples:
-
-<details>
-<summary>alu.v</summary>
-
-```verilog
-module \$1 (co, sel, a, b, o);
- wire [17:0] _04_;
- input [15:0] a;
- input [15:0] b;
- output co;
- reg \co$next ;
- output [15:0] o;
- reg [15:0] \o$next ;
- input [1:0] sel;
- assign _04_ = $signed(+ a) + $signed(- b);
- always @* begin
- \o$next = 16'h0000;
- \co$next = 1'h0;
- casez ({ 1'h1, sel == 2'h2, sel == 1'h1, sel == 0'b0 })
- 4'bzzz1:
- \o$next = a | b;
- 4'bzz1z:
- \o$next = a & b;
- 4'bz1zz:
- \o$next = a ^ b;
- 4'b1zzz:
- { \co$next , \o$next } = _04_[16:0];
- endcase
- end
- assign o = \o$next ;
- assign co = \co$next ;
-endmodule
-```
-</details>
-
-<details>
-<summary>alu_hier.v</summary>
-
-```verilog
-module add(b, o, a);
- wire [16:0] _0_;
- input [15:0] a;
- input [15:0] b;
- output [15:0] o;
- reg [15:0] \o$next ;
- assign _0_ = a + b;
- always @* begin
- \o$next = 16'h0000;
- \o$next = _0_[15:0];
- end
- assign o = \o$next ;
-endmodule
-
-module sub(b, o, a);
- wire [16:0] _0_;
- input [15:0] a;
- input [15:0] b;
- output [15:0] o;
- reg [15:0] \o$next ;
- assign _0_ = a - b;
- always @* begin
- \o$next = 16'h0000;
- \o$next = _0_[15:0];
- end
- assign o = \o$next ;
-endmodule
-
-module top(a, b, o, add_o, sub_o, op);
- input [15:0] a;
- wire [15:0] add_a;
- reg [15:0] \add_a$next ;
- wire [15:0] add_b;
- reg [15:0] \add_b$next ;
- input [15:0] add_o;
- input [15:0] b;
- output [15:0] o;
- reg [15:0] \o$next ;
- input op;
- wire [15:0] sub_a;
- reg [15:0] \sub_a$next ;
- wire [15:0] sub_b;
- reg [15:0] \sub_b$next ;
- input [15:0] sub_o;
- add add (
- .a(add_a),
- .b(add_b),
- .o(add_o)
- );
- sub sub (
- .a(sub_a),
- .b(sub_b),
- .o(sub_o)
- );
- always @* begin
- \o$next = 16'h0000;
- \add_a$next = 16'h0000;
- \add_b$next = 16'h0000;
- \sub_a$next = 16'h0000;
- \sub_b$next = 16'h0000;
- \add_a$next = a;
- \sub_a$next = a;
- \add_b$next = b;
- \sub_b$next = b;
- casez ({ 1'h1, op })
- 2'bz1:
- \o$next = sub_o;
- 2'b1z:
- \o$next = add_o;
- endcase
- end
- assign o = \o$next ;
- assign add_a = \add_a$next ;
- assign add_b = \add_b$next ;
- assign sub_a = \sub_a$next ;
- assign sub_b = \sub_b$next ;
-endmodule
-```
-</details>
-<details>
-<summary>clkdiv.v</summary>
-
-```verilog
-module \$1 (sys_clk, o);
- wire [16:0] _0_;
- output o;
- reg \o$next ;
- input sys_clk;
- wire sys_rst;
- (* init = 16'hffff *)
- reg [15:0] v = 16'hffff;
- reg [15:0] \v$next ;
- assign _0_ = v + 1'h1;
- always @(posedge sys_clk)
- v <= \v$next ;
- always @* begin
- \o$next = 1'h0;
- \v$next = _0_[15:0];
- \o$next = v[15];
- casez (sys_rst)
- 1'h1:
- \v$next = 16'hffff;
- endcase
- end
- assign o = \o$next ;
-endmodule
-```
-</details>
-
-<details>
-<summary>arst.v</summary>
-
-```verilog
-module \$1 (o, sys_clk, sys_rst);
- wire [16:0] _0_;
- output o;
- reg \o$next ;
- input sys_clk;
- input sys_rst;
- (* init = 16'h0000 *)
- reg [15:0] v = 16'h0000;
- reg [15:0] \v$next ;
- assign _0_ = v + 1'h1;
- always @(posedge sys_clk or posedge sys_rst)
- if (sys_rst)
- v <= 16'h0000;
- else
- v <= \v$next ;
- always @* begin
- \o$next = 1'h0;
- \v$next = _0_[15:0];
- \o$next = v[15];
- end
- assign o = \o$next ;
-endmodule
-```
-</details>
-
-<details>
-<summary>pmux.v</summary>
-
-```verilog
-module \$1 (c, o, s, a, b);
- input [15:0] a;
- input [15:0] b;
- input [15:0] c;
- output [15:0] o;
- reg [15:0] \o$next ;
- input [2:0] s;
- always @* begin
- \o$next = 16'h0000;
- casez (s)
- 3'bzz1:
- \o$next = a;
- 3'bz1z:
- \o$next = b;
- 3'b1zz:
- \o$next = c;
- 3'hz:
- \o$next = 16'h0000;
- endcase
- end
- assign o = \o$next ;
-endmodule
-```
-</details>
--- /dev/null
+from nmigen import *
+
+
+class LEDBlinker(Elaboratable):
+ def elaborate(self, platform):
+ m = Module()
+
+ led = platform.request("led")
+
+ half_freq = int(platform.default_clk_frequency // 2)
+ timer = Signal(range(half_freq + 1))
+
+ with m.If(timer == half_freq):
+ m.d.sync += led.eq(~led)
+ m.d.sync += timer.eq(0)
+ with m.Else():
+ m.d.sync += timer.eq(timer + 1)
+
+ return m
+# --- BUILD ---
+from nmigen_boards.icestick import *
+
+
+ICEStickPlatform().build(LEDBlinker(), do_program=True)
--- /dev/null
+from nmigen import *
+
+
+class UpCounter(Elaboratable):
+ """
+ A 16-bit up counter with a fixed limit.
+
+ Parameters
+ ----------
+ limit : int
+ The value at which the counter overflows.
+
+ Attributes
+ ----------
+ en : Signal, in
+ The counter is incremented if ``en`` is asserted, and retains
+ its value otherwise.
+ ovf : Signal, out
+ ``ovf`` is asserted when the counter reaches its limit.
+ """
+ def __init__(self, limit):
+ self.limit = limit
+
+ # Ports
+ self.en = Signal()
+ self.ovf = Signal()
+
+ # State
+ self.count = Signal(16)
+
+ def elaborate(self, platform):
+ m = Module()
+
+ m.d.comb += self.ovf.eq(self.count == self.limit)
+
+ with m.If(self.en):
+ with m.If(self.ovf):
+ m.d.sync += self.count.eq(0)
+ with m.Else():
+ m.d.sync += self.count.eq(self.count + 1)
+
+ return m
+# --- TEST ---
+from nmigen.back.pysim import Simulator
+
+
+dut = UpCounter(25)
+def bench():
+ # Disabled counter should not overflow.
+ yield dut.en.eq(0)
+ for _ in range(30):
+ yield
+ assert not (yield dut.ovf)
+
+ # Once enabled, the counter should overflow in 25 cycles.
+ yield dut.en.eq(1)
+ for _ in range(25):
+ yield
+ assert not (yield dut.ovf)
+ yield
+ assert (yield dut.ovf)
+
+ # The overflow should clear in one cycle.
+ yield
+ assert not (yield dut.ovf)
+
+
+sim = Simulator(dut)
+sim.add_clock(1e-6) # 1 MHz
+sim.add_sync_process(bench)
+with sim.write_vcd("up_counter.vcd"):
+ sim.run()
+# --- CONVERT ---
+from nmigen.back import verilog
+
+
+top = UpCounter(25)
+with open("up_counter.v", "w") as f:
+ f.write(verilog.convert(top, ports=[top.en, top.ovf]))
--- /dev/null
+(* generator = "nMigen" *)
+module top(clk, rst, en, ovf);
+ (* src = "<nmigen-root>/nmigen/hdl/ir.py:526" *)
+ input clk;
+ (* src = "<nmigen-root>/nmigen/hdl/ir.py:526" *)
+ input rst;
+ (* src = "up_counter.py:26" *)
+ input en;
+ (* src = "up_counter.py:27" *)
+ output ovf;
+ (* src = "up_counter.py:30" *)
+ reg [15:0] count = 16'h0000;
+ (* src = "up_counter.py:30" *)
+ reg [15:0] \count$next ;
+ (* src = "up_counter.py:35" *)
+ wire \$1 ;
+ (* src = "up_counter.py:41" *)
+ wire [16:0] \$3 ;
+ (* src = "up_counter.py:41" *)
+ wire [16:0] \$4 ;
+ assign \$1 = count == (* src = "up_counter.py:35" *) 5'h19;
+ assign \$4 = count + (* src = "up_counter.py:41" *) 1'h1;
+ always @(posedge clk)
+ count <= \count$next ;
+ always @* begin
+ \count$next = count;
+ (* src = "up_counter.py:37" *)
+ casez (en)
+ /* src = "up_counter.py:37" */
+ 1'h1:
+ (* src = "up_counter.py:38" *)
+ casez (ovf)
+ /* src = "up_counter.py:38" */
+ 1'h1:
+ \count$next = 16'h0000;
+ /* src = "up_counter.py:40" */
+ default:
+ \count$next = \$3 [15:0];
+ endcase
+ endcase
+ (* src = "<nmigen-root>/nmigen/hdl/xfrm.py:518" *)
+ casez (rst)
+ 1'h1:
+ \count$next = 16'h0000;
+ endcase
+ end
+ assign \$3 = \$4 ;
+ assign ovf = \$1 ;
+endmodule
--- /dev/null
+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 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*
+ - *a=∼*: parameter *a* removed
+ - *.a=→.b*: attribute *a* renamed to *b*
+ - *.a=∼*: attribute *a* removed
+ - *?*: 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` **obs**
+ - (⊕) `decorators` ⇒ `.hdl.xfrm`
+ <br>Note: `transform_*` methods not considered part of public API.
+ - (⊙) `ModuleTransformer` **brk**
+ - (⊙) `ControlInserter` **brk**
+ - (⊕) `CEInserter` → `EnableInserter`
+ - (⊕) `ResetInserter` id
+ - (⊕) `ClockDomainsRenamer` → `DomainRenamer`, `cd_remapping=`→`domain_map=`
+ - (⊙) `edif` **brk**
+ - (⊕) `module` **obs** → `.hdl.dsl`
+ <br>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` **brk**
+ - (⊕) `specials` **obs**
+ - (⊙) `Special` **brk**
+ - (⊕) `Tristate` **obs**
+ - (⊕) `TSTriple` **obs** → `.lib.io.Pin`
+ - (⊕) `Instance` → `.hdl.ir.Instance`
+ - (⊕) `Memory` id
+ <br>Note: nMigen memories should not be added as submodules.
+ - (⊕) `.get_port` **obs** → `.read_port()` + `.write_port()`
+ - (⊕) `_MemoryPort` **obs** → `.hdl.mem.ReadPort` + `.hdl.mem.WritePort`
+ - (⊕) `READ_FIRST`/`WRITE_FIRST` **obs**
+ <br>Note: `READ_FIRST` corresponds to `mem.read_port(transparent=False)`, and `WRITE_FIRST` to `mem.read_port(transparent=True)`.
+ - (⊙) `NO_CHANGE` **brk**
+ <br>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`
+ <br>Note: values no longer valid as keys in `dict` and `set`; use `ValueDict` and `ValueSet` instead.
+ - (⊕) `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**
+ - (⊙) `insert_resets` **brk** → `.hdl.xfrm.ResetInserter`
+ - (⊙) `rename_clock_domain` **brk** → `.hdl.xfrm.DomainRenamer`
+ - (⊙) `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` **brk**
+ - (⊕) `MultiReg` → `.lib.cdc.FFSynchronizer`
+ - (−) `PulseSynchronizer` ?
+ - (−) `BusSynchronizer` ?
+ - (⊕) `GrayCounter` **obs** → `.lib.coding.GrayEncoder`
+ - (⊕) `GrayDecoder` **obs** → `.lib.coding.GrayDecoder`
+ <br>Note: `.lib.coding.GrayEncoder` and `.lib.coding.GrayDecoder` are purely combinatorial.
+ - (−) `ElasticBuffer` ?
+ - (−) `lcm` ?
+ - (−) `Gearbox` ?
+ - (⊕) `coding` id
+ - (⊕) `Encoder` id
+ - (⊕) `PriorityEncoder` id
+ - (⊕) `Decoder` id
+ - (⊕) `PriorityDecoder` id
+ - (−) `divider` ?
+ - (−) `Divider` ?
+ - (⊕) `fifo` → `.lib.fifo`
+ - (⊕) `_FIFOInterface` → `FIFOInterface`
+ - (⊕) `SyncFIFO` id, `.replace=`∼
+ - (⊕) `SyncFIFOBuffered` id, `.fifo=`∼
+ - (⊕) `AsyncFIFO` ?
+ - (⊕) `AsyncFIFOBuffered`, `.fifo=`∼
+ - (⊕) `fsm` **obs**
+ <br>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**
+ <br>Note: all functionality in this module is a part of nMigen platform system.
+ - (−) `misc` ?
+ - (−) `split` ?
+ - (−) `displacer` ?
+ - (−) `chooser` ?
+ - (−) `timeline` ?
+ - (−) `WaitTimer` ?
+ - (−) `BitSlip` ?
+ - (⊕) `record` **obs** → `.hdl.rec.Record`
+ <br>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`
+ <br>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` **brk**
+ <br>Note: the build system has been completely redesigned in nMigen.
+ - (⊙) `util` **brk**
--- /dev/null
+*The text below is the original nMigen implementation proposal. It is provided for illustrative and historical purposes only.*
+
+This repository contains a proposal for the design of nMigen in form of an implementation. This implementation deviates from the existing design of Migen by making several observations of its drawbacks:
+
+ * Migen is strongly tailored towards Verilog, yet translation of Migen to Verilog is not straightforward, leaves much semantics implicit (e.g. signedness, width extension, combinatorial assignments, sub-signal assignments...);
+ * Hierarchical designs are useful for floorplanning and optimization, yet Migen does not support them at all;
+ * Migen's syntax is not easily composable, and something like an FSM requires extending Migen's syntax in non-orthogonal ways;
+ * Migen reimplements a lot of mature open-source tooling, such as conversion of RTL to Verilog (Yosys' Verilog backend), or simulation (Icarus Verilog, Verilator, etc.), and often lacks in features, speed, or corner case handling.
+ * Migen requires awkward specials for some FPGA features such as asynchronous resets.
+
+It also observes that Yosys' intermediate language, RTLIL, is an ideal target for Migen-style logic, as conversion of FHDL to RTLIL is essentially a 1:1 translation, with the exception of the related issues of naming and hierarchy.
+
+This proposal makes several major changes to Migen that hopefully solve all of these drawbacks:
+
+ * nMigen changes FHDL's internal representation to closely match that of RTLIL;
+ * nMigen outputs RTLIL and relies on Yosys for conversion to Verilog, EDIF, etc;
+ * nMigen uses an exact mapping between FHDL signals and RTLIL names to off-load logic simulation to Icarus Verilog, Verilator, etc;
+ * nMigen uses an uniform, composable Python eHDL;
+ * nMigen outputs hierarchical RTLIL, automatically threading signals through the hierarchy;
+ * nMigen supports asynchronous reset directly;
+ * nMigen makes driving a signal from multiple clock domains a precise, hard error.
+
+This proposal keeps in mind but does not make the following major changes:
+
+ * nMigen could be easily modified to flatten the hierarchy if a signal is driven simultaneously from multiple modules;
+ * nMigen could be easily modified to support `x` values (invalid / don't care) by relying on RTLIL's ability to directly represent them;
+ * nMigen could be easily modified to support negative edge triggered flip-flops by relying on RTLIL's ability to directly represent them;
+ * nMigen could be easily modified to track Python source locations of primitives and export them to RTLIL/Verilog through the `src` attribute, displaying the Python source locations in timing reports directly.
+
+This proposal also makes the following simplifications:
+ * Specials are eliminated. Primitives such as memory ports are represented directly, and primitives such as tristate buffers are lowered to a selectable implementation via ordinary dependency injection (`f.submodules += platform.get_tristate(triple, io)`).
+
+The internals of nMigen in this proposal are cleaned up, yet they are kept sufficiently close to Migen that \~all Migen code should be possible to run directly on nMigen using a syntactic compatibility layer.
+
+One might reasonably expect that a roundtrip through RTLIL would result in unreadable Verilog.
+However, this is not the case, e.g. consider the examples:
+
+<details>
+<summary>alu.v</summary>
+
+```verilog
+module \$1 (co, sel, a, b, o);
+ wire [17:0] _04_;
+ input [15:0] a;
+ input [15:0] b;
+ output co;
+ reg \co$next ;
+ output [15:0] o;
+ reg [15:0] \o$next ;
+ input [1:0] sel;
+ assign _04_ = $signed(+ a) + $signed(- b);
+ always @* begin
+ \o$next = 16'h0000;
+ \co$next = 1'h0;
+ casez ({ 1'h1, sel == 2'h2, sel == 1'h1, sel == 0'b0 })
+ 4'bzzz1:
+ \o$next = a | b;
+ 4'bzz1z:
+ \o$next = a & b;
+ 4'bz1zz:
+ \o$next = a ^ b;
+ 4'b1zzz:
+ { \co$next , \o$next } = _04_[16:0];
+ endcase
+ end
+ assign o = \o$next ;
+ assign co = \co$next ;
+endmodule
+```
+</details>
+
+<details>
+<summary>alu_hier.v</summary>
+
+```verilog
+module add(b, o, a);
+ wire [16:0] _0_;
+ input [15:0] a;
+ input [15:0] b;
+ output [15:0] o;
+ reg [15:0] \o$next ;
+ assign _0_ = a + b;
+ always @* begin
+ \o$next = 16'h0000;
+ \o$next = _0_[15:0];
+ end
+ assign o = \o$next ;
+endmodule
+
+module sub(b, o, a);
+ wire [16:0] _0_;
+ input [15:0] a;
+ input [15:0] b;
+ output [15:0] o;
+ reg [15:0] \o$next ;
+ assign _0_ = a - b;
+ always @* begin
+ \o$next = 16'h0000;
+ \o$next = _0_[15:0];
+ end
+ assign o = \o$next ;
+endmodule
+
+module top(a, b, o, add_o, sub_o, op);
+ input [15:0] a;
+ wire [15:0] add_a;
+ reg [15:0] \add_a$next ;
+ wire [15:0] add_b;
+ reg [15:0] \add_b$next ;
+ input [15:0] add_o;
+ input [15:0] b;
+ output [15:0] o;
+ reg [15:0] \o$next ;
+ input op;
+ wire [15:0] sub_a;
+ reg [15:0] \sub_a$next ;
+ wire [15:0] sub_b;
+ reg [15:0] \sub_b$next ;
+ input [15:0] sub_o;
+ add add (
+ .a(add_a),
+ .b(add_b),
+ .o(add_o)
+ );
+ sub sub (
+ .a(sub_a),
+ .b(sub_b),
+ .o(sub_o)
+ );
+ always @* begin
+ \o$next = 16'h0000;
+ \add_a$next = 16'h0000;
+ \add_b$next = 16'h0000;
+ \sub_a$next = 16'h0000;
+ \sub_b$next = 16'h0000;
+ \add_a$next = a;
+ \sub_a$next = a;
+ \add_b$next = b;
+ \sub_b$next = b;
+ casez ({ 1'h1, op })
+ 2'bz1:
+ \o$next = sub_o;
+ 2'b1z:
+ \o$next = add_o;
+ endcase
+ end
+ assign o = \o$next ;
+ assign add_a = \add_a$next ;
+ assign add_b = \add_b$next ;
+ assign sub_a = \sub_a$next ;
+ assign sub_b = \sub_b$next ;
+endmodule
+```
+</details>
+<details>
+<summary>clkdiv.v</summary>
+
+```verilog
+module \$1 (sys_clk, o);
+ wire [16:0] _0_;
+ output o;
+ reg \o$next ;
+ input sys_clk;
+ wire sys_rst;
+ (* init = 16'hffff *)
+ reg [15:0] v = 16'hffff;
+ reg [15:0] \v$next ;
+ assign _0_ = v + 1'h1;
+ always @(posedge sys_clk)
+ v <= \v$next ;
+ always @* begin
+ \o$next = 1'h0;
+ \v$next = _0_[15:0];
+ \o$next = v[15];
+ casez (sys_rst)
+ 1'h1:
+ \v$next = 16'hffff;
+ endcase
+ end
+ assign o = \o$next ;
+endmodule
+```
+</details>
+
+<details>
+<summary>arst.v</summary>
+
+```verilog
+module \$1 (o, sys_clk, sys_rst);
+ wire [16:0] _0_;
+ output o;
+ reg \o$next ;
+ input sys_clk;
+ input sys_rst;
+ (* init = 16'h0000 *)
+ reg [15:0] v = 16'h0000;
+ reg [15:0] \v$next ;
+ assign _0_ = v + 1'h1;
+ always @(posedge sys_clk or posedge sys_rst)
+ if (sys_rst)
+ v <= 16'h0000;
+ else
+ v <= \v$next ;
+ always @* begin
+ \o$next = 1'h0;
+ \v$next = _0_[15:0];
+ \o$next = v[15];
+ end
+ assign o = \o$next ;
+endmodule
+```
+</details>
+
+<details>
+<summary>pmux.v</summary>
+
+```verilog
+module \$1 (c, o, s, a, b);
+ input [15:0] a;
+ input [15:0] b;
+ input [15:0] c;
+ output [15:0] o;
+ reg [15:0] \o$next ;
+ input [2:0] s;
+ always @* begin
+ \o$next = 16'h0000;
+ casez (s)
+ 3'bzz1:
+ \o$next = a;
+ 3'bz1z:
+ \o$next = b;
+ 3'b1zz:
+ \o$next = c;
+ 3'hz:
+ \o$next = 16'h0000;
+ endcase
+ end
+ assign o = \o$next ;
+endmodule
+```
+</details>
--- /dev/null
+/* Some of our section titles are looong */
+.wy-menu-vertical { width: 340px; }
+
+/* Many of our diagnostics are even longer */
+.rst-content pre.literal-block, .rst-content div[class^="highlight"] pre, .rst-content .linenodiv pre { white-space: pre-wrap; }
--- /dev/null
+import os, sys
+sys.path.insert(0, os.path.abspath("."))
+
+import nmigen
+
+project = "nMigen core"
+version = nmigen.__version__
+release = version.split("+")[0]
+copyright = "2020, nMigen developers"
+
+extensions = [
+ "sphinx.ext.intersphinx",
+ "sphinx.ext.doctest",
+ "sphinx.ext.todo",
+ "sphinx_rtd_theme",
+]
+
+with open(".gitignore") as f:
+ exclude_patterns = [line.strip() for line in f.readlines()]
+
+intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
+
+todo_include_todos = True
+
+html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]
+html_css_files = ["custom.css"]
--- /dev/null
+The nMigen core manual
+######################
+
+.. warning::
+
+ This manual is a work in progress and is seriously incomplete!
+
+.. toctree::
+ :maxdepth: 2
+
+ intro
+ install
+ start
+ lang
+
+Index
+=====
+
+* :ref:`genindex`
+
+Search
+======
+
+* :ref:`search`
--- /dev/null
+Installation
+############
+
+System requirements
+===================
+
+nMigen requires Python 3.6; it works on CPython_ 3.6 (or newer), and works faster on PyPy3.6_ 7.2 (or newer).
+
+Simulating nMigen code requires no additional software. However, a waveform viewer like GTKWave_ is invaluable for debugging.
+
+Converting nMigen code to Verilog requires Yosys_ 0.9 (or newer).
+
+Synthesizing, placing and routing an nMigen design for an FPGA requires Yosys_ 0.9 (or newer), as well as the FPGA family specific toolchain.
+
+.. TODO: Link to FPGA family docs here
+
+.. _CPython: https://www.python.org/
+.. _PyPy3.6: https://www.pypy.org/
+.. _Yosys: http://www.clifford.at/yosys/
+.. _GTKWave: http://gtkwave.sourceforge.net/
+
+
+Installing prerequisites
+========================
+
+... on Windows
+--------------
+
+.. todo::
+
+ Determine what's appropriate here (do we put Python in PATH? what about Yosys? is there something better than GTKWave? do we just give up and suggest WSL?)
+
+
+... on Debian Linux
+-------------------
+
+nMigen works on Debian 10 or newer. The required version of Yosys is available in the main repository since Debian 11, but requires the Backports_ repository on Debian 10. Run:
+
+.. note: debian 10 provides: python3 3.7.3, yosys 0.8 (yosys 0.9 in backports)
+.. note: debian 11 provides: python3 3.8.2, yosys 0.9
+
+.. code-block:: shell
+
+ $ sudo apt-get install python3-pip yosys gtkwave
+
+.. _Backports: https://wiki.debian.org/Backports
+
+
+... on Ubuntu Linux
+-------------------
+
+nMigen works on Ubuntu 20.04 LTS or newer.
+
+.. note: ubuntu 20.04 provides: python3 3.8.2, yosys 0.9
+
+.. code-block:: shell
+
+ $ sudo apt-get install python3-pip yosys gtkwave
+
+
+... on macOS
+------------
+
+nMigen works best with Homebrew_. Run:
+
+.. code-block:: shell
+
+ $ brew install python yosys gtkwave
+
+.. _Homebrew: https://brew.sh
+
+
+... on other platforms
+----------------------
+
+Refer to the `Yosys README`_ for detailed build instructions.
+
+.. _Yosys README: https://github.com/YosysHQ/yosys/#setup
+
+
+Installing nMigen
+=================
+
+The latest release of nMigen should work well for most applications. A development snapshot---any commit from the ``master`` branch of nMigen---should be similarly reliable, but is likely to include experimental API changes that will be in flux until the next release. With that in mind, development snapshots can be used to try out new functionality or to avoid bugs fixed since the last release.
+
+
+Latest release
+--------------
+
+To install the latest release of nMigen, run:
+
+.. code-block:: shell
+
+ $ pip3 install --upgrade nmigen
+
+
+Development snapshot
+--------------------
+
+To install a development snapshot of nMigen for the first time, run:
+
+.. code-block:: shell
+
+ $ git clone https://github.com/nmigen/nmigen
+ $ cd nmigen
+ $ pip3 install --editable .
+
+Any changes made to the ``nmigen`` directory will immediately affect any code that uses nMigen. To update the snapshot, run:
+
+.. code-block:: shell
+
+ $ cd nmigen
+ $ git pull --ff-only origin master
+
+
+Installing board definitions
+=============================
+
+.. todo::
+
+ Explain how to install `<https://github.com/nmigen/nmigen-boards>`_.
--- /dev/null
+.. TODO: this introduction is written for people well familiar with HDLs; we likely need
+ another one for people who will use nMigen as their first HDL
+
+Introduction
+############
+
+The core nMigen project provides an open-source toolchain for developing hardware based on synchronous digital logic using the Python programming language. It aims to be easy to learn and use, reduce or eliminate common coding mistakes, and simplify the design of complex hardware with reusable components.
+
+The nMigen toolchain consists of the :ref:`nMigen language <intro-lang>`, the :ref:`standard library <intro-stdlib>`, the :ref:`simulator <intro-sim>`, and the :ref:`build system <intro-build>`, covering all steps of a typical FPGA development workflow. At the same time, it does not restrict the designer's choice of tools: existing industry-standard (System)Verilog or VHDL code can be integrated into an nMigen design flow, or, conversely, nMigen code can be integrated into an existing Verilog-based design flow.
+
+.. TODO: add links to connect_rpc docs once they exist
+
+
+.. _intro-lang:
+
+The nMigen language
+===================
+
+The :doc:`nMigen hardware description language <lang>` is a Python library for register transfer level modeling of synchronous logic. Ordinary Python code is used to construct a netlist of a digital circuit, which can be simulated, directly synthesized via Yosys_, or converted to human-readable Verilog code for use with industry-standard toolchains.
+
+By relying on the flexibility, rich functionality and widespread adoption of the Python language, the nMigen language is focused on a single task: modeling digital logic well. It has first-class support for building blocks like clock domains and finite state machines, and uses simple rules for arithmetic operations that closely match the Python semantics. Python classes, functions, loops and conditionals can be used to build organized and flexible designs; Python libraries can be seamlessly used with nMigen during design or verification; and Python development tools can process nMigen code.
+
+A core design principle of the nMigen language is to be not only easy to use, but also hard to accidentally misuse. Some HDLs provide functionality that has unexpected and undesirable behavior in synthesis, often with expensive consequences, and require a significant effort in learning a "safe" coding style and adopting third-party linting tools. nMigen lacks non-synthesizable constructs and avoids error-prone inference in favor of explicit instantiation. It has many diagnostics (and regularly adds new ones) highlighting potential design issues. Most importantly, all usability issues are considered `reportable bugs`_.
+
+.. _Yosys: http://www.clifford.at/yosys/
+.. _reportable bugs: https://github.com/nmigen/nmigen/issues
+
+
+.. _intro-stdlib:
+
+The nMigen standard library
+===========================
+
+The nMigen language comes with a standard library---a collection of essential digital design components and interfaces. It includes clock domain crossing primitives, synchronous and asynchronous FIFOs, a flexible I/O buffer interface, and more. By providing reliable building blocks out of the box, nMigen allows the designer to focus on their application and avoids subtle differences in behavior between different designs.
+
+.. TODO: link to stdlib here
+
+Clock domain crossing often requires special treatment, such as using vendor-defined attributes or instantiating device-specific primitives. The CDC primitives in the nMigen standard library can be overridden by the platform integration, and every platform integration included with nMigen follows the vendor recommendations for CDC.
+
+High-speed designs usually require the use of registered (and sometimes, geared) I/O buffers. The nMigen standard library provides a common interface to be used between I/O buffers and peripheral implementations. The nMigen build system, if used, can instantiate I/O buffers for every platform integration included with nMigen.
+
+While many designs will use at least some vendor-specific functionality, the components provided by the nMigen standard library reduce the amount of code that needs to be changed when migrating between FPGA families, and the common interfaces simplify peripherals, test benches and simulations.
+
+The nMigen standard library is optional: the nMigen language can be used without it. Conversely, it is possible to use the nMigen standard library components in Verilog or VHDL code, with some limitations.
+
+.. TODO: link to connect_rpc docs here *again*
+
+
+.. _intro-sim:
+
+The nMigen simulator
+====================
+
+The nMigen project includes an advanced simulator for nMigen code implemented in Python with no system dependencies; in this simulator, test benches are written as Python generator functions. Of course, it is always possible to convert an nMigen design to Verilog for use with well-known tool like `Icarus Verilog`_ or Verilator_.
+
+The nMigen simulator is event-driven and can simulate designs with multiple clocks or asynchronous resets. Although it is slower than `Icarus Verilog`_, it compiles the netlist to Python code ahead of time, achieving remarkably high performance for a pure Python implementation---especially when running on PyPy_.
+
+Although nMigen does not support native code simulation or co-simulation at the moment, such support will be added in near future.
+
+.. _Icarus Verilog: http://iverilog.icarus.com/
+.. _Verilator: https://www.veripool.org/wiki/verilator
+.. _GTKWave: http://gtkwave.sourceforge.net/
+.. _PyPy: https://www.pypy.org/
+
+
+.. _intro-build:
+
+The nMigen build system
+=======================
+
+To achieve an end-to-end FPGA development workflow, the nMigen project integrates with all major FPGA toolchains and provides definitions for many common development boards.
+
+.. TODO: link to vendor docs and board docs here
+
+
+FPGA toolchain integration
+--------------------------
+
+Each FPGA family requires the use of synthesis and place & route tools specific for that device family. The nMigen build system directly integrates with every major open-source and commercial FPGA toolchain, and can be easily extended to cover others.
+
+Through this integration, nMigen can specialize the CDC primitives and I/O buffers for a particular device and toolchain; generate I/O and clock constraints from board definition files; synchronize the power-on reset in single-clock designs; include (System)Verilog and VHDL files in the design (if supported by the toolchain); and finally, generate a script running synthesis, placement, routing, and timing analysis. The generated code can be customized to insert additional options, commands, constraints, and so on.
+
+The nMigen build system produces self-contained, portable build trees that require only the toolchain to be present in the environment. This makes builds easier to reproduce, or to run on a remote machine. The generated build scripts are always provided for both \*nix and Windows.
+
+
+Development board definitions
+-----------------------------
+
+Getting started with a new FPGA development board often requires going through a laborous and error-prone process of deriving toolchain configuration and constraint files from the supplied documentation. The nMigen project includes a community-maintained repository of definitions for many open-source and commercial FPGA development boards.
+
+These board definitions contain everything that is necessary to start using the board: FPGA family and model, clocks and resets, descriptions of on-board peripherals (including pin direction and attributes such as I/O standard), connector pinouts, and for boards with a built-in debug probe, the steps required to program the board. It takes a single Python invocation to generate, build, and download a test design that shows whether the board, toolchain, and programmer are working correctly.
+
+nMigen establishes a pin naming convention for many common peripherals (such as 7-segment displays, SPI flashes and SDRAM memories), enabling the reuse of unmodified interface code with many different boards. Further, the polarity of all control signals is unified to be active high, eliminating accidental polarity inversions and making simulation traces easier to follow; active low signals are inverted during I/O buffer instantiation.
--- /dev/null
+Language guide
+##############
+
+.. warning::
+
+ This guide is a work in progress and is seriously incomplete!
+
+This guide introduces the nMigen language in depth. It assumes familiarity with synchronous digital logic and the Python programming language, but does not require experience with any hardware description language.
+
+.. TODO: link to a good synchronous logic tutorial and a Python tutorial?
+
+
+.. _lang-prelude:
+
+The prelude
+===========
+
+Because nMigen is a regular Python library, it needs to be imported before use. The root ``nmigen`` module, called *the prelude*, is carefully curated to export a small amount of the most essential names, useful in nearly every design. In source files dedicated to nMigen code, it is a good practice to use a :ref:`glob import <python:tut-pkg-import-star>` for readability:
+
+.. code-block::
+
+ from nmigen import *
+
+However, if a source file uses nMigen together with other libraries, or if glob imports are frowned upon, it is conventional to use a short alias instead:
+
+.. code-block::
+
+ import nmigen as nm
+
+All of the examples below assume that a glob import is used.
+
+.. testsetup::
+
+ from nmigen import *
+
+
+.. _lang-values:
+
+Values
+======
+
+The basic building block of the nMigen language is a *value*, which is a term for a binary number that is computed or stored anywhere in the design. Each value has a *width*---the amount of bits used to represent the value---and a *signedness*---the interpretation of the value by arithmetic operations---collectively called its *shape*. Signed values always use `two's complement`_ representation.
+
+.. _two's complement: https://en.wikipedia.org/wiki/Two's_complement
+
+
+.. _lang-constants:
+
+Constants
+=========
+
+The simplest nMigen value is a *constant*, representing a fixed number, and introduced using ``Const(...)`` or its short alias ``C(...)``:
+
+.. doctest::
+
+ >>> ten = Const(10)
+ >>> minus_two = C(-2)
+
+The code above does not specify any shape for the constants. If the shape is omitted, nMigen uses unsigned shape for positive numbers and signed shape for negative numbers, with the width inferred from the smallest amount of bits necessary to represent the number. As a special case, in order to get the same inferred shape for ``True`` and ``False``, ``0`` is considered to be 1-bit unsigned.
+
+.. doctest::
+
+ >>> ten.shape()
+ unsigned(4)
+ >>> minus_two.shape()
+ signed(2)
+ >>> C(0).shape()
+ unsigned(1)
+
+The shape of the constant can be specified explicitly, in which case the number's binary representation will be truncated or extended to fit the shape. Although rarely useful, 0-bit constants are permitted.
+
+.. doctest::
+
+ >>> Const(360, unsigned(8)).value
+ 104
+ >>> Const(129, signed(8)).value
+ -127
+ >>> Const(1, unsigned(0)).value
+ 0
+
+
+.. _lang-shapes:
+
+Shapes
+======
+
+A ``Shape`` is an object with two attributes, ``.width`` and ``.signed``. It can be constructed directly:
+
+.. doctest::
+
+ >>> Shape(width=5, signed=False)
+ unsigned(5)
+ >>> Shape(width=12, signed=True)
+ signed(12)
+
+However, in most cases, the shape is always constructed with the same signedness, and the aliases ``signed`` and ``unsigned`` are more convenient:
+
+.. doctest::
+
+ >>> unsigned(5) == Shape(width=5, signed=False)
+ True
+ >>> signed(12) == Shape(width=12, signed=True)
+ True
+
+
+Shapes of values
+----------------
+
+All values have a ``.shape()`` method that computes their shape. The width of a value ``v``, ``v.shape().width``, can also be retrieved with ``len(v)``.
+
+.. doctest::
+
+ >>> Const(5).shape()
+ unsigned(3)
+ >>> len(Const(5))
+ 3
+
+
+.. _lang-shapecasting:
+
+Shape casting
+=============
+
+Shapes can be *cast* from other objects, which are called *shape-castable*. Casting is a convenient way to specify a shape indirectly, for example, by a range of numbers representable by values with that shape.
+
+Casting to a shape can be done explicitly with ``Shape.cast``, but is usually implicit, since shape-castable objects are accepted anywhere shapes are.
+
+
+Shapes from integers
+--------------------
+
+Casting a shape from an integer ``i`` is a shorthand for constructing a shape with ``unsigned(i)``:
+
+.. doctest::
+
+ >>> Shape.cast(5)
+ unsigned(5)
+ >>> C(0, 3).shape()
+ unsigned(3)
+
+
+Shapes from ranges
+------------------
+
+Casting a shape from a :py:class:`range` ``r`` produces a shape that:
+
+ * has a width large enough to represent both ``min(r)`` and ``max(r)``, and
+ * is signed if either ``min(r)`` or ``max(r)`` are negative, unsigned otherwise.
+
+Specifying a shape with a range is convenient for counters, indexes, and all other values whose width is derived from a set of numbers they must be able to fit:
+
+.. doctest::
+
+ >>> Const(0, range(100)).shape()
+ unsigned(7)
+ >>> items = [1, 2, 3]
+ >>> C(1, range(len(items))).shape()
+ unsigned(2)
+
+.. _lang-exclrange:
+
+.. warning::
+
+ Python ranges are *exclusive* or *half-open*, meaning they do not contain their ``.stop`` element. Because of this, values with shapes cast from a ``range(stop)`` where ``stop`` is a power of 2 are not wide enough to represent ``stop`` itself:
+
+ .. doctest::
+
+ >>> fencepost = C(256, range(256))
+ >>> fencepost.shape()
+ unsigned(8)
+ >>> fencepost.value
+ 0
+
+ Be mindful of this edge case!
+
+
+Shapes from enumerations
+------------------------
+
+Casting a shape from an :py:class:`enum.Enum` subclass ``E``:
+
+ * fails if any of the enumeration members have non-integer values,
+ * has a width large enough to represent both ``min(m.value for m in E)`` and ``max(m.value for m in E)``, and
+ * is signed if either ``min(m.value for m in E)`` or ``max(m.value for m in E)`` are negative, unsigned otherwise.
+
+Specifying a shape with an enumeration is convenient for finite state machines, multiplexers, complex control signals, and all other values whose width is derived from a few distinct choices they must be able to fit:
+
+.. testsetup::
+
+ import enum
+
+.. testcode::
+
+ class Direction(enum.Enum):
+ TOP = 0
+ LEFT = 1
+ BOTTOM = 2
+ RIGHT = 3
+
+.. doctest::
+
+ >>> Shape.cast(Direction)
+ unsigned(2)
+
+.. note::
+
+ The enumeration does not have to subclass :py:class:`enum.IntEnum`; it only needs to have integers as values of every member. Using enumerations based on :py:class:`enum.Enum` rather than :py:class:`enum.IntEnum` prevents unwanted implicit conversion of enum members to integers.
+
+
+.. _lang-valuecasting:
+
+Value casting
+=============
+
+Like shapes, values may be *cast* from other objects, which are called *value-castable*. Casting allows objects that are not provided by nMigen, such as integers or enumeration members, to be used in nMigen expressions directly.
+
+.. TODO: link to UserValue
+
+Casting to a value can be done explicitly with ``Value.cast``, but is usually implicit, since value-castable objects are accepted anywhere values are.
+
+
+Values from integers
+--------------------
+
+Casting a value from an integer ``i`` is a shorthand for ``Const(i)``:
+
+.. doctest::
+
+ >>> Value.cast(5)
+ (const 3'd5)
+
+
+Values from enumeration members
+-------------------------------
+
+Casting a value from an enumeration member ``m`` is a shorthand for ``Const(m.value, type(m))``:
+
+.. doctest::
+
+ >>> Value.cast(Direction.LEFT)
+ (const 2'd1)
+
+
+.. _lang-signals:
+
+Signals
+=======
+
+.. |emph:assigned| replace:: *assigned*
+.. _emph:assigned: #lang-assigns
+
+A *signal* is a value representing a (potentially) varying number. Signals can be |emph:assigned|_ in a :ref:`combinatorial <lang-comb>` or :ref:`synchronous <lang-sync>` domain, in which case they are generated as wires or registers, respectively. Signals always have a well-defined value; they cannot be uninitialized or undefined.
+
+
+Signal shapes
+-------------
+
+A signal can be created with an explicitly specified shape (any :ref:`shape-castable <lang-shapecasting>` object); if omitted, the shape defaults to ``unsigned(1)``. Although rarely useful, 0-bit signals are permitted.
+
+.. doctest::
+
+ >>> Signal().shape()
+ unsigned(1)
+ >>> Signal(4).shape()
+ unsigned(4)
+ >>> Signal(range(-8, 7)).shape()
+ signed(4)
+ >>> Signal(Direction).shape()
+ unsigned(2)
+ >>> Signal(0).shape()
+ unsigned(0)
+
+
+.. _lang-signalname:
+
+Signal names
+------------
+
+Each signal has a *name*, which is used in the waveform viewer, diagnostic messages, Verilog output, and so on. In most cases, the name is omitted and inferred from the name of the variable or attribute the signal is placed into:
+
+.. testsetup::
+
+ class dummy(object): pass
+ self = dummy()
+
+.. doctest::
+
+ >>> foo = Signal()
+ >>> foo.name
+ 'foo'
+ >>> self.bar = Signal()
+ >>> self.bar.name
+ 'bar'
+
+However, the name can also be specified explicitly with the ``name=`` parameter:
+
+.. doctest::
+
+ >>> foo2 = Signal(name="second_foo")
+ >>> foo2.name
+ 'second_foo'
+
+The names do not need to be unique; if two signals with the same name end up in the same namespace while preparing for simulation or synthesis, one of them will be renamed to remove the ambiguity.
+
+
+.. _lang-initial:
+
+Initial signal values
+---------------------
+
+Each signal has an *initial value*, specified with the ``reset=`` parameter. If the initial value is not specified explicitly, zero is used by default. An initial value can be specified with an integer or an enumeration member.
+
+Signals :ref:`assigned <lang-assigns>` in a :ref:`combinatorial <lang-comb>` domain assume their initial value when none of the assignments are :ref:`active <lang-active>`. Signals assigned in a :ref:`synchronous <lang-sync>` domain assume their initial value after *power-on reset* and, unless the signal is :ref:`reset-less <lang-resetless>`, *explicit reset*. Signals that are used but never assigned are equivalent to constants of their initial value.
+
+.. TODO: using "reset" for "initial value" is awful, let's rename it to "init"
+
+.. doctest::
+
+ >>> Signal(4).reset
+ 0
+ >>> Signal(4, reset=5).reset
+ 5
+ >>> Signal(Direction, reset=Direction.LEFT).reset
+ 1
+
+
+.. _lang-resetless:
+
+Reset-less signals
+------------------
+
+Signals assigned in a :ref:`synchronous <lang-sync>` domain can be *resettable* or *reset-less*, specified with the ``reset_less=`` parameter. If the parameter is not specified, signals are resettable by default. Resettable signals assume their :ref:`initial value <lang-initial>` on explicit reset, which can be asserted via the clock domain or by using ``ResetInserter``. Reset-less signals are not affected by explicit reset.
+
+.. TODO: link to clock domain and ResetInserter docs
+
+Signals assigned in a :ref:`combinatorial <lang-comb>` domain are not affected by the ``reset_less`` parameter.
+
+.. doctest::
+
+ >>> Signal().reset_less
+ False
+ >>> Signal(reset_less=True).reset_less
+ True
+
+
+.. _lang-operators:
+
+Operators
+=========
+
+To describe computations, nMigen values can be combined with each other or with :ref:`value-castable <lang-valuecasting>` objects using a rich array of arithmetic, bitwise, logical, bit sequence, and other *operators* to form *expressions*, which are themselves values.
+
+
+.. _lang-abstractexpr:
+
+Performing or describing computations?
+--------------------------------------
+
+Code written in the Python language *performs* computations on concrete objects, like integers, with the goal of calculating a concrete result:
+
+.. doctest::
+
+ >>> a = 5
+ >>> a + 1
+ 6
+
+In contrast, code written in the nMigen language *describes* computations on abstract objects, like :ref:`signals <lang-signals>`, with the goal of generating a hardware *circuit* that can be simulated, synthesized, and so on. nMigen expressions are ordinary Python objects that represent parts of this circuit:
+
+.. doctest::
+
+ >>> a = Signal(8, reset=5)
+ >>> a + 1
+ (+ (sig a) (const 1'd1))
+
+Although the syntax is similar, it is important to remember that nMigen values exist on a higher level of abstraction than Python values. For example, expressions that include nMigen values cannot be used in Python control flow structures:
+
+.. doctest::
+
+ >>> if a == 0:
+ ... print("Zero!")
+ Traceback (most recent call last):
+ ...
+ TypeError: Attempted to convert nMigen value to Python boolean
+
+Because the value of ``a``, and therefore ``a == 0``, is not known at the time when the ``if`` statement is executed, there is no way to decide whether the body of the statement should be executed---in fact, if the design is synthesized, by the time ``a`` has any concrete value, the Python program has long finished! To solve this problem, nMigen provides its own :ref:`control structures <lang-control>` that, also, manipulate circuits.
+
+
+.. _lang-widthext:
+
+Width extension
+---------------
+
+Many of the operations described below (for example, addition, equality, bitwise OR, and part select) extend the width of one or both operands to match the width of the expression. When this happens, unsigned values are always zero-extended and signed values are always sign-extended regardless of the operation or signedness of the result.
+
+
+.. _lang-arithops:
+
+Arithmetic operators
+--------------------
+
+Most arithmetic operations on integers provided by Python can be used on nMigen values, too.
+
+Although Python integers have unlimited precision and nMigen values are represented with a :ref:`finite amount of bits <lang-values>`, arithmetics on nMigen values never overflows because the width of the arithmetic expression is always sufficient to represent all possible results.
+
+.. doctest::
+
+ >>> a = Signal(8)
+ >>> (a + 1).shape() # needs to represent 1 to 256
+ unsigned(9)
+
+Similarly, although Python integers are always signed and nMigen values can be either :ref:`signed or unsigned <lang-values>`, if any of the operands of an nMigen arithmetic expression is signed, the expression itself is also signed, matching the behavior of Python.
+
+.. doctest::
+
+ >>> a = Signal(unsigned(8))
+ >>> b = Signal(signed(8))
+ >>> (a + b).shape() # needs to represent -128 to 382
+ signed(10)
+
+While arithmetic computations never result in an overflow, :ref:`assigning <lang-assigns>` their results to signals may truncate the most significant bits.
+
+The following table lists the arithmetic operations provided by nMigen:
+
+============ ========================== ======
+Operation Description Notes
+============ ========================== ======
+``a + b`` addition
+``-a`` negation
+``a - b`` subtraction
+``a * b`` multiplication
+``a // b`` floor division [#opA1]_
+``a % b`` modulo [#opA1]_
+``abs(a)`` absolute value
+============ ========================== ======
+
+.. [#opA1] Divisor must be unsigned; this is an nMigen limitation that may be lifted in the future.
+
+
+.. _lang-cmpops:
+
+Comparison operators
+--------------------
+
+All comparison operations on integers provided by Python can be used on nMigen values. However, due to a limitation of Python, chained comparisons (e.g. ``a < b < c``) cannot be used.
+
+Similar to arithmetic operations, if any operand of a comparison expression is signed, a signed comparison is performed. The result of a comparison is a 1-bit unsigned value.
+
+The following table lists the comparison operations provided by nMigen:
+
+============ ==========================
+Operation Description
+============ ==========================
+``a == b`` equality
+``a != b`` inequality
+``a < b`` less than
+``a <= b`` less than or equal
+``a > b`` greater than
+``a >= b`` greater than or equal
+============ ==========================
+
+
+.. _lang-bitops:
+
+Bitwise, shift, and rotate operators
+------------------------------------
+
+All bitwise and shift operations on integers provided by Python can be used on nMigen values as well.
+
+Similar to arithmetic operations, if any operand of a bitwise expression is signed, the expression itself is signed as well. A shift expression is signed if the shifted value is signed. A rotate expression is always unsigned.
+
+Rotate operations with variable rotate amounts cannot be efficiently synthesized for non-power-of-2 widths of the rotated value. Because of that, the rotate operations are only provided for constant rotate amounts, specified as Python :py:class:`int`\ s.
+
+The following table lists the bitwise and shift operations provided by nMigen:
+
+===================== ========================================== ======
+Operation Description Notes
+===================== ========================================== ======
+``~a`` bitwise NOT; complement
+``a & b`` bitwise AND
+``a | b`` bitwise OR
+``a ^ b`` bitwise XOR
+``a.implies(b)`` bitwise IMPLY_
+``a >> b`` arithmetic right shift by variable amount [#opB1]_, [#opB2]_
+``a << b`` left shift by variable amount [#opB2]_
+``a.rotate_left(i)`` left rotate by constant amount [#opB3]_
+``a.rotate_right(i)`` right rotate by constant amount [#opB3]_
+===================== ========================================== ======
+
+.. _IMPLY: https://en.wikipedia.org/wiki/IMPLY_gate
+.. [#opB1] Logical and arithmetic right shift of an unsigned value are equivalent. Logical right shift of a signed value can be expressed by :ref:`converting it to unsigned <lang-convops>` first.
+.. [#opB2] Shift amount must be unsigned; integer shifts in Python require the amount to be positive.
+.. [#opB3] Rotate amount can be negative, in which case the direction is reversed.
+.. TODO: add constshifts https://github.com/nmigen/nmigen/issues/378
+
+.. _lang-hugeshift:
+
+.. note::
+
+ Because nMigen ensures that the width of a left shift expression is wide enough to represent any possible result, left shift by a wide amount produces exponentially wider intermediate values, stressing the synthesis tools:
+
+ .. doctest::
+
+ >>> (1 << C(0, 32)).shape()
+ unsigned(4294967296)
+
+ Although nMigen will detect and reject expressions wide enough to break other tools, it is a good practice to explicitly limit the width of a non-constant shift amount in a left shift.
+
+
+.. _lang-reduceops:
+
+Reduction operators
+-------------------
+
+Bitwise reduction operations on integers are not provided by Python, but are very useful for hardware. They are similar to bitwise operations applied "sideways"; for example, if bitwise AND is a binary operator that applies AND to each pair of bits between its two operands, then reduction AND is an unary operator that applies AND to all of the bits in its sole operand.
+
+The result of a reduction is a 1-bit unsigned value.
+
+The following table lists the reduction operations provided by nMigen:
+
+============ ============================================= ======
+Operation Description Notes
+============ ============================================= ======
+``a.all()`` reduction AND; are all bits set? [#opR1]_
+``a.any()`` reduction OR; is any bit set? [#opR1]_
+``a.xor()`` reduction XOR; is an odd number of bits set?
+``a.bool()`` conversion to boolean; is non-zero? [#opR2]_
+============ ============================================= ======
+
+.. [#opR1] Conceptually the same as applying the Python :py:func:`all` or :py:func:`any` function to the value viewed as a collection of bits.
+.. [#opR2] Conceptually the same as applying the Python :py:func:`bool` function to the value viewed as an integer.
+
+
+.. _lang-logicops:
+
+Logical operators
+-----------------
+
+Unlike the arithmetic or bitwise operators, it is not possible to change the behavior of the Python logical operators ``not``, ``and``, and ``or``. Due to that, logical expressions in nMigen are written using bitwise operations on boolean (1-bit unsigned) values, with explicit boolean conversions added where necessary.
+
+The following table lists the Python logical expressions and their nMigen equivalents:
+
+================= ====================================
+Python expression nMigen expression (any operands)
+================= ====================================
+``not a`` ``~(a).bool()``
+``a and b`` ``(a).bool() & (b).bool()``
+``a or b`` ``(a).bool() | (b).bool()``
+================= ====================================
+
+When the operands are known to be boolean values, such as comparisons, reductions, or boolean signals, the ``.bool()`` conversion may be omitted for clarity:
+
+================= ====================================
+Python expression nMigen expression (boolean operands)
+================= ====================================
+``not p`` ``~(p)``
+``p and q`` ``(p) & (q)``
+``p or q`` ``(p) | (q)``
+================= ====================================
+
+.. _lang-logicprecedence:
+
+.. warning::
+
+ Because of Python :ref:`operator precedence <python:operator-summary>`, logical operators bind less tightly than comparison operators whereas bitwise operators bind more tightly than comparison operators. As a result, all logical expressions in nMigen **must** have parenthesized operands.
+
+ Omitting parentheses around operands in an nMigen a logical expression is likely to introduce a subtle bug:
+
+ .. doctest::
+
+ >>> en = Signal()
+ >>> addr = Signal(8)
+ >>> en & (addr == 0) # correct
+ (& (sig en) (== (sig addr) (const 1'd0)))
+ >>> en & addr == 0 # WRONG! addr is truncated to 1 bit
+ (== (& (sig en) (sig addr)) (const 1'd0))
+
+ .. TODO: can we detect this footgun automatically? #380
+
+.. _lang-negatebool:
+
+.. warning::
+
+ When applied to nMigen boolean values, the ``~`` operator computes negation, and when applied to Python boolean values, the ``not`` operator also computes negation. However, the ``~`` operator applied to Python boolean values produces an unexpected result:
+
+ .. doctest::
+
+ >>> ~False
+ -1
+ >>> ~True
+ -2
+
+ Because of this, Python booleans used in nMigen logical expressions **must** be negated with the ``not`` operator, not the ``~`` operator. Negating a Python boolean with the ``~`` operator in an nMigen logical expression is likely to introduce a subtle bug:
+
+ .. doctest::
+
+ >>> stb = Signal()
+ >>> use_stb = True
+ >>> (not use_stb) | stb # correct
+ (| (const 1'd0) (sig stb))
+ >>> ~use_stb | stb # WRONG! MSB of 2-bit wide OR expression is always 1
+ (| (const 2'sd-2) (sig stb))
+
+ nMigen automatically detects some cases of misuse of ``~`` and emits a detailed diagnostic message.
+
+ .. TODO: this isn't quite reliable, #380
+
+
+.. _lang-seqops:
+
+Bit sequence operators
+----------------------
+
+Apart from acting as numbers, nMigen values can also be treated as bit :ref:`sequences <python:typesseq>`, supporting slicing, concatenation, replication, and other sequence operations. Since some of the operators Python defines for sequences clash with the operators it defines for numbers, nMigen gives these operators a different name. Except for the names, nMigen values follow Python sequence semantics, with the least significant bit at index 0.
+
+Because every nMigen value has a single fixed width, bit slicing and replication operations require the subscripts and count to be constant, specified as Python :py:class:`int`\ s. It is often useful to slice a value with a constant width and variable offset, but this cannot be expressed with the Python slice notation. To solve this problem, nMigen provides additional *part select* operations with the necessary semantics.
+
+The result of any bit sequence operation is an unsigned value.
+
+The following table lists the bit sequence operations provided by nMigen:
+
+======================= ================================================ ======
+Operation Description Notes
+======================= ================================================ ======
+``len(a)`` bit length; value width [#opS1]_
+``a[i:j:k]`` bit slicing by constant subscripts [#opS2]_
+``iter(a)`` bit iteration
+``a.bit_select(b, i)`` overlapping part select with variable offset
+``a.word_select(b, i)`` non-overlapping part select with variable offset
+``Cat(a, b)`` concatenation [#opS3]_
+``Repl(a, i)`` replication
+======================= ================================================ ======
+
+.. [#opS1] Words "length" and "width" have the same meaning when talking about nMigen values. Conventionally, "width" is used.
+.. [#opS2] All variations of the Python slice notation are supported, including "extended slicing". E.g. all of ``a[0]``, ``a[1:9]``, ``a[2:]``, ``a[:-2]``, ``a[::-1]``, ``a[0:8:2]`` select bits in the same way as other Python sequence types select their elements.
+.. [#opS3] In the concatenated value, ``a`` occupies the least significant bits, and ``b`` the most significant bits.
+
+For the operators introduced by nMigen, the following table explains them in terms of Python code operating on tuples of bits rather than nMigen values:
+
+======================= ======================
+nMigen operation Equivalent Python code
+======================= ======================
+``Cat(a, b)`` ``a + b``
+``Repl(a, i)`` ``a * i``
+``a.bit_select(b, i)`` ``a[b:b+i]``
+``a.word_select(b, i)`` ``a[b*i:b*i+i]``
+======================= ======================
+
+.. warning::
+
+ In Python, the digits of a number are written right-to-left (0th exponent at the right), and the elements of a sequence are written left-to-right (0th element at the left). This mismatch can cause confusion when numeric operations (like shifts) are mixed with bit sequence operations (like concatenations). For example, ``Cat(C(0b1001), C(0b1010))`` has the same value as ``C(0b1010_1001)``, ``val[4:]`` is equivalent to ``val >> 4``, and ``val[-1]`` refers to the most significant bit.
+
+ Such confusion can often be avoided by not using numeric and bit sequence operations in the same expression. For example, although it may seem natural to describe a shift register with a numeric shift and a sequence slice operations, using sequence operations alone would make it easier to understand.
+
+.. note::
+
+ Could nMigen have used a different indexing or iteration order for values? Yes, but it would be necessary to either place the most significant bit at index 0, or deliberately break the Python sequence type interface. Both of these options would cause more issues than using different iteration orders for numeric and sequence operations.
+
+
+.. _lang-convops:
+
+Conversion operators
+--------------------
+
+The ``.as_signed()`` and ``.as_unsigned()`` conversion operators reinterpret the bits of a value with the requested signedness. This is useful when the same value is sometimes treated as signed and sometimes as unsigned, or when a signed value is constructed using slices or concatenations. For example, ``(pc + imm[:7].as_signed()).as_unsigned()`` sign-extends the 7 least significant bits of ``imm`` to the width of ``pc``, performs the addition, and produces an unsigned result.
+
+.. TODO: more general shape conversion? https://github.com/nmigen/nmigen/issues/381
+
+
+.. _lang-muxop:
+
+Choice operator
+---------------
+
+The ``Mux(sel, val1, val0)`` choice expression (similar to the :ref:`conditional expression <python:if_expr>` in Python) is equal to the operand ``val1`` if ``sel`` is non-zero, and to the other operand ``val0`` otherwise. If any of ``val1`` or ``val0`` are signed, the expression itself is signed as well.
+
+
+.. _lang-modules:
+
+Modules
+=======
+
+A *module* is a unit of the nMigen design hierarchy: the smallest collection of logic that can be independently simulated, synthesized, or otherwise processed. Modules associate signals with :ref:`control domains <lang-domains>`, provide :ref:`control structures <lang-control>`, manage clock domains, and aggregate submodules.
+
+.. TODO: link to clock domains
+.. TODO: link to submodules
+
+Every nMigen design starts with a fresh module:
+
+.. doctest::
+
+ >>> m = Module()
+
+
+.. _lang-domains:
+
+Control domains
+---------------
+
+A *control domain* is a named group of :ref:`signals <lang-signals>` that change their value in identical conditions.
+
+All designs have a single predefined *combinatorial domain*, containing all signals that change immediately when any value used to compute them changes. The name ``comb`` is reserved for the combinatorial domain.
+
+A design can also have any amount of user-defined *synchronous domains*, also called *clock domains*, containing signals that change when a specific edge occurs on the domain's clock signal or, for domains with asynchronous reset, on the domain's reset signal. Most modules only use a single synchronous domain, conventionally called ``sync``, but the name ``sync`` does not have to be used, and lacks any special meaning beyond being the default.
+
+The behavior of assignments differs for signals in :ref:`combinatorial <lang-comb>` and :ref:`synchronous <lang-sync>` domains. Collectively, signals in synchronous domains contain the state of a design, whereas signals in the combinatorial domain cannot form feedback loops or hold state.
+
+.. TODO: link to clock domains
+
+
+.. _lang-assigns:
+
+Assigning to signals
+--------------------
+
+*Assignments* are used to change the values of signals. An assignment statement can be introduced with the ``.eq(...)`` syntax:
+
+.. doctest::
+
+ >>> s = Signal()
+ >>> s.eq(1)
+ (eq (sig s) (const 1'd1))
+
+Similar to :ref:`how nMigen operators work <lang-abstractexpr>`, an nMigen assignment is an ordinary Python object used to describe a part of a circuit. An assignment does not have any effect on the signal it changes until it is added to a control domain in a module. Once added, it introduces logic into the circuit generated from that module.
+
+
+.. _lang-assignlhs:
+
+Assignment targets
+------------------
+
+The target of an assignment can be more complex than a single signal. It is possible to assign to any combination of signals, :ref:`bit slices <lang-seqops>`, :ref:`concatenations <lang-seqops>`, and :ref:`part selects <lang-seqops>` as long as it includes no other values:
+
+.. TODO: mention arrays, records, user values
+
+.. doctest::
+
+ >>> a = Signal(8)
+ >>> b = Signal(4)
+ >>> Cat(a, b).eq(0)
+ (eq (cat (sig a) (sig b)) (const 1'd0))
+ >>> a[:4].eq(b)
+ (eq (slice (sig a) 0:4) (sig b))
+ >>> Cat(a, a).bit_select(b, 2).eq(0b11)
+ (eq (part (cat (sig a) (sig a)) (sig b) 2 1) (const 2'd3))
+
+
+.. _lang-assigndomains:
+
+Assignment domains
+------------------
+
+The ``m.d.<domain> += ...`` syntax is used to add assignments to a specific control domain in a module. It can add just a single assignment, or an entire sequence of them:
+
+.. testcode::
+
+ a = Signal()
+ b = Signal()
+ c = Signal()
+ m.d.comb += a.eq(1)
+ m.d.sync += [
+ b.eq(c),
+ c.eq(b),
+ ]
+
+If the name of a domain is not known upfront, the ``m.d["<domain>"] += ...`` syntax can be used instead:
+
+.. testcode::
+
+ def add_toggle(num):
+ t = Signal()
+ m.d[f"sync_{num}"] += t.eq(~t)
+ add_toggle(2)
+
+.. _lang-signalgranularity:
+
+Every signal included in the target of an assignment becomes a part of the domain, or equivalently, *driven* by that domain. A signal can be either undriven or driven by exactly one domain; it is an error to add two assignments to the same signal to two different domains:
+
+.. doctest::
+
+ >>> d = Signal()
+ >>> m.d.comb += d.eq(1)
+ >>> m.d.sync += d.eq(0)
+ Traceback (most recent call last):
+ ...
+ nmigen.hdl.dsl.SyntaxError: Driver-driver conflict: trying to drive (sig d) from d.sync, but it is already driven from d.comb
+
+.. note::
+
+ Clearly, nMigen code that drives a single bit of a signal from two different domains does not describe a meaningful circuit. However, driving two different bits of a signal from two different domains does not inherently cause such a conflict. Would nMigen accept the following code?
+
+ .. testcode::
+
+ e = Signal(2)
+ m.d.comb += e[0].eq(0)
+ m.d.sync += e[1].eq(1)
+
+ The answer is no. While this kind of code is occasionally useful, rejecting it greatly simplifies backends, simulators, and analyzers.
+
+
+.. _lang-assignorder:
+
+Assignment order
+----------------
+
+Unlike with two different domains, adding multiple assignments to the same signal to the same domain is well-defined.
+
+Assignments to different signal bits apply independently. For example, the following two snippets are equivalent:
+
+.. testcode::
+
+ a = Signal(8)
+ m.d.comb += [
+ a[0:4].eq(C(1, 4)),
+ a[4:8].eq(C(2, 4)),
+ ]
+
+.. testcode::
+
+ a = Signal(8)
+ m.d.comb += a.eq(Cat(C(1, 4), C(2, 4)))
+
+If multiple assignments change the value of the same signal bits, the assignment that is added last determines the final value. For example, the following two snippets are equivalent:
+
+.. testcode::
+
+ b = Signal(9)
+ m.d.comb += [
+ b[0:9].eq(Cat(C(1, 3), C(2, 3), C(3, 3))),
+ b[0:6].eq(Cat(C(4, 3), C(5, 3))),
+ b[3:6].eq(C(6, 3)),
+ ]
+
+.. testcode::
+
+ b = Signal(9)
+ m.d.comb += b.eq(Cat(C(4, 3), C(6, 3), C(3, 3)))
+
+Multiple assignments to the same signal bits are more useful when combined with control structures, which can make some of the assignments :ref:`active or inactive <lang-active>`. If all assignments to some signal bits are :ref:`inactive <lang-active>`, their final values are determined by the signal's domain, :ref:`combinatorial <lang-comb>` or :ref:`synchronous <lang-sync>`.
+
+
+.. _lang-control:
+
+Control structures
+------------------
+
+Although it is possible to write any decision tree as a combination of :ref:`assignments <lang-assigns>` and :ref:`choice expressions <lang-muxop>`, nMigen provides *control structures* tailored for this task: If, Switch, and FSM. The syntax of all control structures is based on :ref:`context managers <python:context-managers>` and uses ``with`` blocks, for example:
+
+.. TODO: link to relevant subsections
+
+.. testcode::
+
+ timer = Signal(8)
+ with m.If(timer == 0):
+ m.d.sync += timer.eq(10)
+ with m.Else():
+ m.d.sync += timer.eq(timer - 1)
+
+While some nMigen control structures are superficially similar to imperative control flow statements (such as Python's ``if``), their function---together with :ref:`expressions <lang-abstractexpr>` and :ref:`assignments <lang-assigns>`---is to describe circuits. The code above is equivalent to:
+
+.. testcode::
+
+ timer = Signal(8)
+ m.d.sync += timer.eq(Mux(timer == 0, 10, timer - 1))
+
+Because all branches of a decision tree affect the generated circuit, all of the Python code inside nMigen control structures is always evaluated in the order in which it appears in the program. This can be observed through Python code with side effects, such as ``print()``:
+
+.. testcode::
+
+ timer = Signal(8)
+ with m.If(timer == 0):
+ print("inside `If`")
+ m.d.sync += timer.eq(10)
+ with m.Else():
+ print("inside `Else`")
+ m.d.sync += timer.eq(timer - 1)
+
+.. testoutput::
+
+ inside `If`
+ inside `Else`
+
+
+.. _lang-active:
+
+Active and inactive assignments
+-------------------------------
+
+An assignment added inside an nMigen control structure, i.e. ``with m.<...>:`` block, is *active* if the condition of the control structure is satisfied, and *inactive* otherwise. For any given set of conditions, the final value of every signal assigned in a module is the same as if the inactive assignments were removed and the active assignments were performed unconditionally, taking into account the :ref:`assignment order <lang-assignorder>`.
+
+For example, there are two possible cases in the circuit generated from the following code:
+
+.. testcode::
+
+ timer = Signal(8)
+ m.d.sync += timer.eq(timer - 1)
+ with m.If(timer == 0):
+ m.d.sync += timer.eq(10)
+
+When ``timer == 0`` is true, the code reduces to:
+
+.. code-block::
+
+ m.d.sync += timer.eq(timer - 1)
+ m.d.sync += timer.eq(10)
+
+Due to the :ref:`assignment order <lang-assignorder>`, it further reduces to:
+
+.. code-block::
+
+ m.d.sync += timer.eq(10)
+
+When ``timer == 0`` is false, the code reduces to:
+
+.. code-block::
+
+ m.d.sync += timer.eq(timer - 1)
+
+Combining these cases together, the code above is equivalent to:
+
+.. testcode::
+
+ timer = Signal(8)
+ m.d.sync += timer.eq(Mux(timer == 0, 10, timer - 1))
+
+
+.. _lang-comb:
+
+Combinatorial evaluation
+------------------------
+
+Signals in the combinatorial :ref:`control domain <lang-domains>` change whenever any value used to compute them changes. The final value of a combinatorial signal is equal to its :ref:`initial value <lang-initial>` updated by the :ref:`active assignments <lang-active>` in the :ref:`assignment order <lang-assignorder>`. Combinatorial signals cannot hold any state.
+
+Consider the following code:
+
+.. testsetup::
+ en = Signal()
+ b = Signal(8)
+
+.. testcode::
+
+ a = Signal(8, reset=1)
+ with m.If(en):
+ m.d.comb += a.eq(b + 1)
+
+Whenever the signals ``en`` or ``b`` change, the signal ``a`` changes as well. If ``en`` is false, the final value of ``a`` is its initial value, ``1``. If ``en`` is true, the final value of ``a`` is equal to ``b + 1``.
+
+A combinatorial signal that is computed directly or indirectly based on its own value is a part of a *combinatorial feedback loop*, sometimes shortened to just *feedback loop*. Combinatorial feedback loops can be stable (i.e. implement a constant driver or a transparent latch), or unstable (i.e. implement a ring oscillator). nMigen prohibits using assignments to describe any kind of a combinatorial feedback loop, including transparent latches.
+
+.. warning::
+
+ The current version of nMigen does not detect combinatorial feedback loops, but processes the design under the assumption that there aren't any. If the design does in fact contain a combinatorial feedback loop, it will likely be **silently miscompiled**, though some cases will be detected during synthesis or place & route.
+
+ This hazard will be eliminated in the future.
+
+.. TODO: fix this, either as a part of https://github.com/nmigen/nmigen/issues/6 or on its own
+
+.. note::
+
+ In the exceedingly rare case when a combinatorial feedback loop is desirable, it is possible to implement it by directly instantiating technology primitives (e.g. device-specific LUTs or latches). This is also the only way to introduce a combinatorial feedback loop with well-defined behavior in simulation and synthesis, regardless of the HDL being used.
+
+
+.. _lang-sync:
+
+Synchronous evaluation
+----------------------
+
+Signals in synchronous :ref:`control domains <lang-domains>` change whenever a specific transition (positive or negative edge) occurs on the clock of the synchronous domain. In addition, the signals in clock domains with an asynchronous reset change when such a reset is asserted. The final value of a synchronous signal is equal to its :ref:`initial value <lang-initial>` if the reset (of any type) is asserted, or to its current value updated by the :ref:`active assignments <lang-active>` in the :ref:`assignment order <lang-assignorder>` otherwise. Synchronous signals always hold state.
+
+.. TODO: link to clock domains
--- /dev/null
+sphinx~=3.0
+sphinx-rtd-theme~=0.5.0
+-e git+http://github.com/pygments/pygments.git#egg=pygments
--- /dev/null
+Getting started
+###############
+
+This section demonstrates the basic nMigen workflow to provide a cursory overview of the language and the toolchain. See the :doc:`language guide <lang>` for a detailed introduction to the language.
+
+.. TODO: add link to build system doc
+.. TODO: add link to more complex examples?
+
+
+A counter
+=========
+
+As a first example, consider a counter with a fixed limit, enable, and overflow. The code for this example is shown below. `Download <_code/up_counter.py>`_ and run it:
+
+.. code-block:: shell
+
+ $ python3 up_counter.py
+
+
+Implementing a counter
+----------------------
+
+A 16-bit up counter with enable input, overflow output, and a limit fixed at design time can be implemented in nMigen as follows:
+
+.. literalinclude:: _code/up_counter.py
+ :linenos:
+ :lineno-match:
+ :end-before: # --- TEST ---
+
+The reusable building block of nMigen designs is an ``Elaboratable``: a Python class that includes HDL signals (``en`` and ``ovf``, in this case) as a part of its interface, and provides the ``elaborate`` method that defines its behavior.
+
+.. TODO: link to Elaboratable reference
+
+Most ``elaborate`` implementations use a ``Module`` helper to describe combinatorial (``m.d.comb``) and synchronous (``m.d.sync``) logic controlled with conditional syntax (``m.If``, ``m.Elif``, ``m.Else``) similar to Python's. They can also instantiate vendor-defined black boxes or modules written in other HDLs.
+
+.. TODO: link to DSL reference
+
+
+Testing a counter
+-----------------
+
+To verify its functionality, the counter can be simulated for a small amount of time, with a test bench driving it and checking a few simple conditions:
+
+.. literalinclude:: _code/up_counter.py
+ :linenos:
+ :lineno-match:
+ :start-after: # --- TEST ---
+ :end-before: # --- CONVERT ---
+
+The test bench is implemented as a Python generator function that is co-simulated with the counter itself. The test bench can inspect the simulated signals with ``yield sig``, update them with ``yield sig.eq(val)``, and advance the simulation by one clock cycle with ``yield``.
+
+.. TODO: link to simulator reference
+
+When run, the test bench finishes successfully, since all of the assertions hold, and produces a VCD file with waveforms recorded for every ``Signal`` as well as the clock of the ``sync`` domain:
+
+.. image:: _images/up_counter_gtkwave.png
+ :alt: A screenshot of GTKWave displaying waveforms near the clock cycle where the counter overflows.
+
+
+Converting a counter
+--------------------
+
+Although some nMigen workflows do not include Verilog at all, it is still the de facto standard for HDL interoperability. Any nMigen design can be converted to synthesizable Verilog using the corresponding backend:
+
+.. literalinclude:: _code/up_counter.py
+ :linenos:
+ :lineno-match:
+ :start-after: # --- CONVERT ---
+
+The signals that will be connected to the ports of the top-level Verilog module should be specified explicitly. The rising edge clock and synchronous reset signals of the ``sync`` domain are added automatically; if necessary, the control signals can be configured explicitly. The result is the following Verilog code (lightly edited for clarity):
+
+.. TODO: link to clock domain section of language reference
+
+.. literalinclude:: _code/up_counter.v
+ :language: verilog
+ :linenos:
+
+To aid debugging, the generated Verilog code has the same general structure as the nMigen source code (although more verbose), and contains extensive source location information.
+
+.. note::
+
+ Unfortunately, at the moment none of the supported toolchains will use the source location information in diagnostic messages.
+
+
+A blinking LED
+==============
+
+Although nMigen works well as a standalone HDL, it also includes a build system that integrates with FPGA toolchains, and many board definition files for common developer boards that include pinouts and programming adapter invocations. The following code will blink a LED with a frequency of 1 Hz on any board that has a LED and an oscillator:
+
+.. literalinclude:: _code/led_blinker.py
+ :linenos:
+ :lineno-match:
+ :end-before: # --- BUILD ---
+
+The ``LEDBlinker`` module will use the first LED available on the board, and derive the clock divisor from the oscillator frequency specified in the clock constraint. It can be used, for example, with the `Lattice iCEStick evaluation board <https://www.latticesemi.com/icestick>`_, one of the many boards already supported by nMigen:
+
+.. TODO: link to list of supported boards
+
+.. todo::
+
+ Link to the installation instructions for the FOSS iCE40 toolchain, probably as a part of board documentation.
+
+.. literalinclude:: _code/led_blinker.py
+ :linenos:
+ :lineno-match:
+ :start-after: # --- BUILD ---
+
+With only a single line of code, the design is synthesized, placed, routed, and programmed to the on-board Flash memory. Although not all applications will use the nMigen build system, the designs that choose it can benefit from the "turnkey" built-in workflows; if necessary, the built-in workflows can be customized to include user-specified options, commands, and files.
+
+.. TODO: link to build system reference
+
+.. note::
+
+ The ability to check with minimal effort whether the entire toolchain functions correctly is so important that it is built into every board definition file. To use it with the iCEStick board, run:
+
+ .. code-block:: shell
+
+ $ python3 -m nmigen_boards.icestick
+
+ This command will build and program a test bitstream similar to the example above.
self.src_loc = tracer.get_src_loc(1 + src_loc_at)
def __bool__(self):
- raise TypeError("Attempted to convert nMigen value to boolean")
+ raise TypeError("Attempted to convert nMigen value to Python boolean")
def __invert__(self):
return Operator("~", [self])
# Neither Python nor HDLs implement shifts by negative values; prohibit any shifts
# by a signed value to make sure the shift amount can always be interpreted as
# an unsigned value.
- raise NotImplementedError("Shift by a signed value is not supported")
+ raise TypeError("Shift amount must be unsigned")
def __lshift__(self, other):
other = Value.cast(other)
other.__check_shamt()
width, signed = cond.shape()
if signed:
warnings.warn("Signed values in If/Elif conditions usually result from inverting "
- "Python booleans with ~, which leads to unexpected results: ~True is "
- "-2, which is truthful. Replace `~flag` with `not flag`. (If this is "
- "a false positive, silence this warning with "
- "`m.If(x)` → `m.If(x.bool())`.)",
+ "Python booleans with ~, which leads to unexpected results. "
+ "Replace `~flag` with `not flag`. (If this is a false positive, "
+ "silence this warning with `m.If(x)` → `m.If(x.bool())`.)",
SyntaxWarning, stacklevel=4)
return cond
def test_bool(self):
with self.assertRaises(TypeError,
- msg="Attempted to convert nMigen value to boolean"):
+ msg="Attempted to convert nMigen value to Python boolean"):
if Const(0):
pass
self.assertEqual(v1.shape(), unsigned(11))
def test_shl_wrong(self):
- with self.assertRaises(NotImplementedError,
- msg="Shift by a signed value is not supported"):
+ with self.assertRaises(TypeError,
+ msg="Shift amount must be unsigned"):
1 << Const(0, signed(6))
- with self.assertRaises(NotImplementedError,
- msg="Shift by a signed value is not supported"):
+ with self.assertRaises(TypeError,
+ msg="Shift amount must be unsigned"):
Const(1, unsigned(4)) << -1
def test_shr(self):
self.assertEqual(v1.shape(), unsigned(4))
def test_shr_wrong(self):
- with self.assertRaises(NotImplementedError,
- msg="Shift by a signed value is not supported"):
+ with self.assertRaises(TypeError,
+ msg="Shift amount must be unsigned"):
1 << Const(0, signed(6))
- with self.assertRaises(NotImplementedError,
- msg="Shift by a signed value is not supported"):
+ with self.assertRaises(TypeError,
+ msg="Shift amount must be unsigned"):
Const(1, unsigned(4)) << -1
def test_lt(self):
m = Module()
with self.assertWarns(SyntaxWarning,
msg="Signed values in If/Elif conditions usually result from inverting Python "
- "booleans with ~, which leads to unexpected results: ~True is -2, which is "
- "truthful. Replace `~flag` with `not flag`. (If this is a false positive, "
- "silence this warning with `m.If(x)` → `m.If(x.bool())`.)"):
+ "booleans with ~, which leads to unexpected results. Replace `~flag` with "
+ "`not flag`. (If this is a false positive, silence this warning with "
+ "`m.If(x)` → `m.If(x.bool())`.)"):
with m.If(~True):
pass
pass
with self.assertWarns(SyntaxWarning,
msg="Signed values in If/Elif conditions usually result from inverting Python "
- "booleans with ~, which leads to unexpected results: ~True is -2, which is "
- "truthful. Replace `~flag` with `not flag`. (If this is a false positive, "
- "silence this warning with `m.If(x)` → `m.If(x.bool())`.)"):
+ "booleans with ~, which leads to unexpected results. Replace `~flag` with "
+ "`not flag`. (If this is a false positive, silence this warning with "
+ "`m.If(x)` → `m.If(x.bool())`.)"):
with m.Elif(~True):
pass
projects / nmigen.git / commitdiff
