From b788de932972074e58df9b11db40cfb574dcf12e Mon Sep 17 00:00:00 2001
From: George Rennie <georgerennie@gmail.com>
Date: Tue, 24 Sep 2024 03:01:49 +0100
Subject: [PATCH 01/30] smtbmc: escape path identifiers

* also changes the print format for cover statements to be more uniform
  with the asserts, allowing easier parsing of cover path
* this allows diambiguation of properties with the same name but
  different paths (see https://github.com/YosysHQ/sby/issues/296)
---
 backends/smt2/smtbmc.py | 27 +++++++++++++++++++--------
 1 file changed, 19 insertions(+), 8 deletions(-)

diff --git a/backends/smt2/smtbmc.py b/backends/smt2/smtbmc.py
index c3bdcebbe..d17bad3fb 100644
--- a/backends/smt2/smtbmc.py
+++ b/backends/smt2/smtbmc.py
@@ -1454,6 +1454,10 @@ def write_trace(steps_start, steps_stop, index, allregs=False):
     if outywfile is not None:
         write_yw_trace(steps, index, allregs)
 
+def escape_path_segment(segment):
+    if "." in segment:
+        return f"\\{segment} "
+    return segment
 
 def print_failed_asserts_worker(mod, state, path, extrainfo, infomap, infokey=()):
     assert mod in smt.modinfo
@@ -1464,7 +1468,8 @@ def print_failed_asserts_worker(mod, state, path, extrainfo, infomap, infokey=()
 
     for cellname, celltype in smt.modinfo[mod].cells.items():
         cell_infokey = (mod, cellname, infokey)
-        if print_failed_asserts_worker(celltype, "(|%s_h %s| %s)" % (mod, cellname, state), path + "." + cellname, extrainfo, infomap, cell_infokey):
+        cell_path = path + "." + escape_path_segment(cellname)
+        if print_failed_asserts_worker(celltype, "(|%s_h %s| %s)" % (mod, cellname, state), cell_path, extrainfo, infomap, cell_infokey):
             found_failed_assert = True
 
     for assertfun, assertinfo in smt.modinfo[mod].asserts.items():
@@ -1497,7 +1502,7 @@ def print_anyconsts_worker(mod, state, path):
     assert mod in smt.modinfo
 
     for cellname, celltype in smt.modinfo[mod].cells.items():
-        print_anyconsts_worker(celltype, "(|%s_h %s| %s)" % (mod, cellname, state), path + "." + cellname)
+        print_anyconsts_worker(celltype, "(|%s_h %s| %s)" % (mod, cellname, state), path + "." + escape_path_segment(cellname))
 
     for fun, info in smt.modinfo[mod].anyconsts.items():
         if info[1] is None:
@@ -1517,18 +1522,21 @@ def print_anyconsts(state):
     print_anyconsts_worker(topmod, "s%d" % state, topmod)
 
 
-def get_cover_list(mod, base):
+def get_cover_list(mod, base, path=None):
+    path = path or mod
     assert mod in smt.modinfo
 
     cover_expr = list()
+    # A tuple of path and cell name
     cover_desc = list()
 
     for expr, desc in smt.modinfo[mod].covers.items():
         cover_expr.append("(ite (|%s| %s) #b1 #b0)" % (expr, base))
-        cover_desc.append(desc)
+        cover_desc.append((path, desc))
 
     for cell, submod in smt.modinfo[mod].cells.items():
-        e, d = get_cover_list(submod, "(|%s_h %s| %s)" % (mod, cell, base))
+        cell_path = path + "." + escape_path_segment(cell)
+        e, d = get_cover_list(submod, "(|%s_h %s| %s)" % (mod, cell, base), cell_path)
         cover_expr += e
         cover_desc += d
 
@@ -1544,7 +1552,8 @@ def get_assert_map(mod, base, path, key_base=()):
         assert_map[(expr, key_base)] = ("(|%s| %s)" % (expr, base), path, desc)
 
     for cell, submod in smt.modinfo[mod].cells.items():
-        assert_map.update(get_assert_map(submod, "(|%s_h %s| %s)" % (mod, cell, base), path + "." + cell, (mod, cell, key_base)))
+        cell_path = path + "." + escape_path_segment(cell)
+        assert_map.update(get_assert_map(submod, "(|%s_h %s| %s)" % (mod, cell, base), cell_path, (mod, cell, key_base)))
 
     return assert_map
 
@@ -1903,7 +1912,9 @@ elif covermode:
                     new_cover_mask.append(cover_mask[i])
                     continue
 
-                print_msg("Reached cover statement at %s in step %d." % (cover_desc[i], step))
+                path = cover_desc[i][0]
+                name = cover_desc[i][1]
+                print_msg("Reached cover statement in step %d at %s: %s" % (step, path, name))
                 new_cover_mask.append("0")
 
             cover_mask = "".join(new_cover_mask)
@@ -1933,7 +1944,7 @@ elif covermode:
     if "1" in cover_mask:
         for i in range(len(cover_mask)):
             if cover_mask[i] == "1":
-                print_msg("Unreached cover statement at %s." % cover_desc[i])
+                print_msg("Unreached cover statement at %s: %s" % (cover_desc[i][0], cover_desc[i][1]))
 
 else:  # not tempind, covermode
     active_assert_keys = get_assert_keys()

From 997cb30f1fe2c14a16463a9e3bad969dd89a52b6 Mon Sep 17 00:00:00 2001
From: "Emil J. Tywoniak" <emil@tywoniak.eu>
Date: Tue, 1 Oct 2024 13:25:07 +0200
Subject: [PATCH 02/30] cxxrtl: test stream operator

---
 tests/cxxrtl/test_value.cc | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/tests/cxxrtl/test_value.cc b/tests/cxxrtl/test_value.cc
index 0750d412e..b6fe3cf4a 100644
--- a/tests/cxxrtl/test_value.cc
+++ b/tests/cxxrtl/test_value.cc
@@ -49,4 +49,12 @@ int main()
         cxxrtl::value<1> sel(0u);
         assert(val.template bmux<4>(sel).get<uint64_t>() == 0xfu);
     }
+
+    {
+        // stream operator smoke test
+        cxxrtl::value<8> val(0x1fu);
+        std::ostringstream oss;
+        oss << val;
+        assert(oss.str() == "8'1f");
+    }
 }

From 2e1181a0923c5d2cb596a086d3435ffd1b476fb1 Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Mon, 7 Oct 2024 21:25:15 +1300
Subject: [PATCH 03/30] ci: Run make docs on PRs

---
 .github/workflows/prepare-docs.yml | 25 +++++++++++++++++++++++--
 1 file changed, 23 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/prepare-docs.yml b/.github/workflows/prepare-docs.yml
index 19680e992..e2689d4df 100644
--- a/.github/workflows/prepare-docs.yml
+++ b/.github/workflows/prepare-docs.yml
@@ -1,12 +1,32 @@
 name: Build docs artifact with Verific
 
-on: push
+on: [push, pull_request]
 
 jobs:
+  check_docs_rebuild:
+    runs-on: ubuntu-latest
+    outputs:
+      skip_check: ${{ steps.skip_check.outputs.should_skip }}
+      docs_export: ${{ steps.docs_var.outputs.docs_export }}
+    env:
+      docs_export: ${{ github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/heads/docs-preview') || startsWith(github.ref, 'refs/tags/') }}
+    steps:
+      - id: skip_check
+        uses: fkirc/skip-duplicate-actions@v5
+        with:
+          paths_ignore: '["**/README.md"]'
+          # don't cancel in case we're updating docs
+          cancel_others: 'false'
+          # only run on push *or* pull_request, not both
+          concurrent_skipping: ${{ env.docs_export && 'never' || 'same_content_newer'}}
+      - id: docs_var
+        run: echo "docs_export=${{ env.docs_export }}" >> $GITHUB_OUTPUT
+
   prepare-docs:
     # docs builds are needed for anything on main, any tagged versions, and any tag
     # or branch starting with docs-preview
-    if: ${{ github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/heads/docs-preview') || startsWith(github.ref, 'refs/tags/') }}
+    needs: check_docs_rebuild
+    if: ${{ needs.check_docs_rebuild.outputs.should_skip != 'true' }}
     runs-on: [self-hosted, linux, x64, fast]
     steps:
       - name: Checkout Yosys
@@ -45,6 +65,7 @@ jobs:
             docs/source/code_examples
 
       - name: Trigger RTDs build
+        if: ${{ needs.check_docs_rebuild.outputs.docs_export == 'true' }}
         uses: dfm/rtds-action@v1.1.0
         with:
           webhook_url: ${{ secrets.RTDS_WEBHOOK_URL }}

From 468a019c30381b3cf5877430a934b139f6457a52 Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Mon, 7 Oct 2024 21:56:23 +1300
Subject: [PATCH 04/30] docs: Makefile tidying

examples and dots are now orthogonal.
---
 docs/Makefile                                 | 2 +-
 docs/source/code_examples/extensions/Makefile | 5 +++--
 docs/source/code_examples/fifo/Makefile       | 4 +++-
 docs/source/code_examples/intro/Makefile      | 4 +++-
 docs/source/code_examples/macc/Makefile       | 4 +++-
 docs/source/code_examples/opt/Makefile        | 8 ++++----
 docs/source/code_examples/scrambler/Makefile  | 5 +++--
 docs/source/code_examples/selections/Makefile | 5 +++--
 docs/source/code_examples/show/Makefile       | 5 +++--
 docs/source/code_examples/stubnets/Makefile   | 5 +++--
 docs/source/code_examples/synth_flow/Makefile | 5 +++--
 docs/source/code_examples/techmap/Makefile    | 5 +++--
 12 files changed, 35 insertions(+), 22 deletions(-)

diff --git a/docs/Makefile b/docs/Makefile
index 21fcd9623..6dbf6f490 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -238,7 +238,7 @@ Makefile-%: FORCE
 	$(MAKE) -C $(@D) $(*F)
 
 CODE_EXAMPLES := $(wildcard source/code_examples/*/Makefile)
-TEST_EXAMPLES := $(addsuffix -all,$(CODE_EXAMPLES))
+TEST_EXAMPLES := $(addsuffix -examples,$(CODE_EXAMPLES))
 CLEAN_EXAMPLES := $(addsuffix -clean,$(CODE_EXAMPLES))
 test-examples: $(TEST_EXAMPLES)
 clean-examples: $(CLEAN_EXAMPLES)
diff --git a/docs/source/code_examples/extensions/Makefile b/docs/source/code_examples/extensions/Makefile
index 8b5fa106a..2e621d70b 100644
--- a/docs/source/code_examples/extensions/Makefile
+++ b/docs/source/code_examples/extensions/Makefile
@@ -2,9 +2,10 @@ PROGRAM_PREFIX :=
 
 YOSYS ?= ../../../../$(PROGRAM_PREFIX)yosys
 
-.PHONY: all dots
-all: dots test0.log test1.log test2.log
+.PHONY: all dots examples
+all: dots examples
 dots: test1.dot
+examples: test0.log test1.log test2.log
 
 CXXFLAGS=$(shell $(YOSYS)-config --cxxflags)
 DATDIR=$(shell $(YOSYS)-config --datdir)
diff --git a/docs/source/code_examples/fifo/Makefile b/docs/source/code_examples/fifo/Makefile
index 0a1186a62..de3abfd99 100644
--- a/docs/source/code_examples/fifo/Makefile
+++ b/docs/source/code_examples/fifo/Makefile
@@ -10,8 +10,10 @@ MAPDOT_NAMES += rdata_map_ffs rdata_map_luts rdata_map_cells
 DOTS := $(addsuffix .dot,$(DOT_NAMES))
 MAPDOTS := $(addsuffix .dot,$(MAPDOT_NAMES))
 
-all: dots fifo.out fifo.stat
+.PHONY: all dots examples
+all: dots examples
 dots: $(DOTS) $(MAPDOTS)
+examples: fifo.out fifo.stat
 
 $(DOTS) fifo.out: fifo.v fifo.ys
 	$(YOSYS) fifo.ys -l fifo.out -Q -T
diff --git a/docs/source/code_examples/intro/Makefile b/docs/source/code_examples/intro/Makefile
index 009c82c62..31df6b623 100644
--- a/docs/source/code_examples/intro/Makefile
+++ b/docs/source/code_examples/intro/Makefile
@@ -4,8 +4,10 @@ YOSYS ?= ../../../../$(PROGRAM_PREFIX)yosys
 
 DOTS = counter_00.dot counter_01.dot counter_02.dot counter_03.dot
 
-all: dots
+.PHONY: all dots examples
+all: dots examples
 dots: $(DOTS)
+examples:
 
 $(DOTS): counter.v counter.ys mycells.lib
 	$(YOSYS) counter.ys
diff --git a/docs/source/code_examples/macc/Makefile b/docs/source/code_examples/macc/Makefile
index e93fe0657..f06c623a5 100644
--- a/docs/source/code_examples/macc/Makefile
+++ b/docs/source/code_examples/macc/Makefile
@@ -4,8 +4,10 @@ YOSYS ?= ../../../../$(PROGRAM_PREFIX)yosys
 
 DOTS = macc_simple_xmap.dot macc_xilinx_xmap.dot
 
-all: dots
+.PHONY: all dots examples
+all: dots examples
 dots: $(DOTS)
+examples:
 
 macc_simple_xmap.dot: macc_simple_*.v macc_simple_test.ys
 	$(YOSYS) macc_simple_test.ys
diff --git a/docs/source/code_examples/opt/Makefile b/docs/source/code_examples/opt/Makefile
index 12c1c93b1..aa7962ca5 100644
--- a/docs/source/code_examples/opt/Makefile
+++ b/docs/source/code_examples/opt/Makefile
@@ -6,13 +6,13 @@ DOT_NAMES = opt_share opt_muxtree opt_merge opt_expr
 
 DOTS := $(addsuffix .dot,$(DOT_NAMES))
 
-all: dots
+.PHONY: all dots examples
+all: dots examples
 dots: $(DOTS)
+examples:
 
-%_full.dot: %.ys
+%.dot: %.ys
 	$(YOSYS) $<
-
-%.dot: %_full.dot
 	gvpack -u -o $@ $*_full.dot
 
 .PHONY: clean
diff --git a/docs/source/code_examples/scrambler/Makefile b/docs/source/code_examples/scrambler/Makefile
index de475b8b1..a9b56f8d3 100644
--- a/docs/source/code_examples/scrambler/Makefile
+++ b/docs/source/code_examples/scrambler/Makefile
@@ -2,9 +2,10 @@ PROGRAM_PREFIX :=
 
 YOSYS ?= ../../../../$(PROGRAM_PREFIX)yosys
 
-.PHONY: all dots
-all: dots
+.PHONY: all dots examples
+all: dots examples
 dots: scrambler_p01.dot scrambler_p02.dot
+examples:
 
 scrambler_p01.dot scrambler_p02.dot: scrambler.ys scrambler.v
 	$(YOSYS) scrambler.ys
diff --git a/docs/source/code_examples/selections/Makefile b/docs/source/code_examples/selections/Makefile
index bb506ff38..3ad1bcf20 100644
--- a/docs/source/code_examples/selections/Makefile
+++ b/docs/source/code_examples/selections/Makefile
@@ -11,9 +11,10 @@ MEMDEMO_DOTS := $(addsuffix .dot,$(MEMDEMO))
 SUBMOD = submod_00 submod_01 submod_02 submod_03
 SUBMOD_DOTS := $(addsuffix .dot,$(SUBMOD))
 
-.PHONY: all dots
-all: dots
+.PHONY: all dots examples
+all: dots examples
 dots: select.dot $(SUMPROD_DOTS) $(MEMDEMO_DOTS) $(SUBMOD_DOTS)
+examples:
 
 select.dot: select.v select.ys
 	$(YOSYS) select.ys
diff --git a/docs/source/code_examples/show/Makefile b/docs/source/code_examples/show/Makefile
index 4b269a4ab..6c1906cce 100644
--- a/docs/source/code_examples/show/Makefile
+++ b/docs/source/code_examples/show/Makefile
@@ -8,9 +8,10 @@ EXAMPLE_DOTS := $(addsuffix .dot,$(EXAMPLE))
 CMOS = cmos_00 cmos_01
 CMOS_DOTS := $(addsuffix .dot,$(CMOS))
 
-.PHONY: all dots
-all: dots example.out
+.PHONY: all dots examples
+all: dots examples
 dots: splice.dot $(EXAMPLE_DOTS) $(CMOS_DOTS)
+examples: example.out
 
 splice.dot: splice.v
 	$(YOSYS) -p 'prep -top splice_demo; show -format dot -prefix splice' splice.v
diff --git a/docs/source/code_examples/stubnets/Makefile b/docs/source/code_examples/stubnets/Makefile
index ec501f006..17f700c88 100644
--- a/docs/source/code_examples/stubnets/Makefile
+++ b/docs/source/code_examples/stubnets/Makefile
@@ -1,6 +1,7 @@
-.PHONY: all dots
-all: dots
+.PHONY: all dots examples
+all: dots examples
 dots:
+examples:
 
 .PHONY: test
 test: stubnets.so
diff --git a/docs/source/code_examples/synth_flow/Makefile b/docs/source/code_examples/synth_flow/Makefile
index 7db1c12f4..0dd37ed4d 100644
--- a/docs/source/code_examples/synth_flow/Makefile
+++ b/docs/source/code_examples/synth_flow/Makefile
@@ -9,9 +9,10 @@ YOSYS ?= ../../../../$(PROGRAM_PREFIX)yosys
 
 DOTS = $(addsuffix .dot,$(DOT_TARGETS))
 
-.PHONY: all dots
-all: dots
+.PHONY: all dots examples
+all: dots examples
 dots: $(DOTS)
+examples:
 
 %.dot: %.v %.ys
 	$(YOSYS) -p 'script $*.ys; show -notitle -prefix $* -format dot'
diff --git a/docs/source/code_examples/techmap/Makefile b/docs/source/code_examples/techmap/Makefile
index e900fea4c..6736b0f1d 100644
--- a/docs/source/code_examples/techmap/Makefile
+++ b/docs/source/code_examples/techmap/Makefile
@@ -2,9 +2,10 @@ PROGRAM_PREFIX :=
 
 YOSYS ?= ../../../../$(PROGRAM_PREFIX)yosys
 
-.PHONY: all dots
-all: dots
+.PHONY: all dots examples
+all: dots examples
 dots: red_or3x1.dot sym_mul.dot mymul.dot mulshift.dot addshift.dot
+examples:
 
 red_or3x1.dot: red_or3x1_*
 	$(YOSYS) red_or3x1_test.ys

From 0b1b94d85eebabddd6155ed26e802f8f5927ea87 Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Mon, 7 Oct 2024 22:00:28 +1300
Subject: [PATCH 05/30] Docs: Clean example outputs

---
 docs/source/code_examples/fifo/Makefile       |   1 +
 docs/source/code_examples/fifo/fifo.out       | 425 ------------------
 docs/source/code_examples/fifo/fifo.stat      |  57 ---
 docs/source/code_examples/selections/Makefile |   5 +-
 .../code_examples/selections/sumprod.out      |  38 --
 docs/source/code_examples/show/Makefile       |   1 +
 docs/source/code_examples/show/example.out    |  54 ---
 7 files changed, 5 insertions(+), 576 deletions(-)
 delete mode 100644 docs/source/code_examples/fifo/fifo.out
 delete mode 100644 docs/source/code_examples/fifo/fifo.stat
 delete mode 100644 docs/source/code_examples/selections/sumprod.out
 delete mode 100644 docs/source/code_examples/show/example.out

diff --git a/docs/source/code_examples/fifo/Makefile b/docs/source/code_examples/fifo/Makefile
index de3abfd99..4836dac06 100644
--- a/docs/source/code_examples/fifo/Makefile
+++ b/docs/source/code_examples/fifo/Makefile
@@ -24,3 +24,4 @@ $(MAPDOTS) fifo.stat: fifo.v fifo_map.ys
 .PHONY: clean
 clean:
 	rm -f *.dot
+	rm -f fifo.out fifo.stat
diff --git a/docs/source/code_examples/fifo/fifo.out b/docs/source/code_examples/fifo/fifo.out
deleted file mode 100644
index ac132ee6c..000000000
--- a/docs/source/code_examples/fifo/fifo.out
+++ /dev/null
@@ -1,425 +0,0 @@
-
--- Executing script file `fifo.ys' --
-$ yosys fifo.v
-
--- Parsing `fifo.v' using frontend ` -vlog2k' --
-
-1. Executing Verilog-2005 frontend: fifo.v
-Parsing Verilog input from `fifo.v' to AST representation.
-Storing AST representation for module `$abstract\addr_gen'.
-Storing AST representation for module `$abstract\fifo'.
-Successfully finished Verilog frontend.
-echo on
-
-yosys> hierarchy -top addr_gen
-
-2. Executing HIERARCHY pass (managing design hierarchy).
-
-3. Executing AST frontend in derive mode using pre-parsed AST for module `\addr_gen'.
-Generating RTLIL representation for module `\addr_gen'.
-
-3.1. Analyzing design hierarchy..
-Top module:  \addr_gen
-
-3.2. Analyzing design hierarchy..
-Top module:  \addr_gen
-Removing unused module `$abstract\fifo'.
-Removing unused module `$abstract\addr_gen'.
-Removed 2 unused modules.
-
-yosys> select -module addr_gen
-
-yosys [addr_gen]> select -list
-addr_gen
-addr_gen/$1\addr[7:0]
-addr_gen/$add$fifo.v:19$3_Y
-addr_gen/$eq$fifo.v:16$2_Y
-addr_gen/$0\addr[7:0]
-addr_gen/addr
-addr_gen/rst
-addr_gen/clk
-addr_gen/en
-addr_gen/$add$fifo.v:19$3
-addr_gen/$eq$fifo.v:16$2
-addr_gen/$proc$fifo.v:0$4
-addr_gen/$proc$fifo.v:12$1
-
-yosys [addr_gen]> select t:*
-
-yosys [addr_gen]*> select -list
-addr_gen/$add$fifo.v:19$3
-addr_gen/$eq$fifo.v:16$2
-
-yosys [addr_gen]*> select -set new_cells %
-
-yosys [addr_gen]*> select -clear
-
-yosys> show -format dot -prefix addr_gen_show addr_gen
-
-4. Generating Graphviz representation of design.
-Writing dot description to `addr_gen_show.dot'.
-Dumping module addr_gen to page 1.
-
-yosys> show -format dot -prefix new_cells_show -notitle @new_cells
-
-5. Generating Graphviz representation of design.
-Writing dot description to `new_cells_show.dot'.
-Dumping selected parts of module addr_gen to page 1.
-
-yosys> show -color maroon3 @new_cells -color cornflowerblue p:* -notitle -format dot -prefix addr_gen_hier
-
-6. Generating Graphviz representation of design.
-Writing dot description to `addr_gen_hier.dot'.
-Dumping module addr_gen to page 1.
-
-yosys> proc -noopt
-
-7. Executing PROC pass (convert processes to netlists).
-
-yosys> proc_clean
-
-7.1. Executing PROC_CLEAN pass (remove empty switches from decision trees).
-Cleaned up 0 empty switches.
-
-yosys> proc_rmdead
-
-7.2. Executing PROC_RMDEAD pass (remove dead branches from decision trees).
-Marked 2 switch rules as full_case in process $proc$fifo.v:12$1 in module addr_gen.
-Removed a total of 0 dead cases.
-
-yosys> proc_prune
-
-7.3. Executing PROC_PRUNE pass (remove redundant assignments in processes).
-Removed 0 redundant assignments.
-Promoted 1 assignment to connection.
-
-yosys> proc_init
-
-7.4. Executing PROC_INIT pass (extract init attributes).
-Found init rule in `\addr_gen.$proc$fifo.v:0$4'.
-  Set init value: \addr = 8'00000000
-
-yosys> proc_arst
-
-7.5. Executing PROC_ARST pass (detect async resets in processes).
-Found async reset \rst in `\addr_gen.$proc$fifo.v:12$1'.
-
-yosys> proc_rom
-
-7.6. Executing PROC_ROM pass (convert switches to ROMs).
-Converted 0 switches.
-<suppressed ~2 debug messages>
-
-yosys> proc_mux
-
-7.7. Executing PROC_MUX pass (convert decision trees to multiplexers).
-Creating decoders for process `\addr_gen.$proc$fifo.v:0$4'.
-Creating decoders for process `\addr_gen.$proc$fifo.v:12$1'.
-     1/1: $0\addr[7:0]
-
-yosys> proc_dlatch
-
-7.8. Executing PROC_DLATCH pass (convert process syncs to latches).
-
-yosys> proc_dff
-
-7.9. Executing PROC_DFF pass (convert process syncs to FFs).
-Creating register for signal `\addr_gen.\addr' using process `\addr_gen.$proc$fifo.v:12$1'.
-  created $adff cell `$procdff$10' with positive edge clock and positive level reset.
-
-yosys> proc_memwr
-
-7.10. Executing PROC_MEMWR pass (convert process memory writes to cells).
-
-yosys> proc_clean
-
-7.11. Executing PROC_CLEAN pass (remove empty switches from decision trees).
-Removing empty process `addr_gen.$proc$fifo.v:0$4'.
-Found and cleaned up 2 empty switches in `\addr_gen.$proc$fifo.v:12$1'.
-Removing empty process `addr_gen.$proc$fifo.v:12$1'.
-Cleaned up 2 empty switches.
-
-yosys> select -set new_cells t:$mux t:*dff
-
-yosys> show -color maroon3 @new_cells -notitle -format dot -prefix addr_gen_proc
-
-8. Generating Graphviz representation of design.
-Writing dot description to `addr_gen_proc.dot'.
-Dumping module addr_gen to page 1.
-
-yosys> opt_expr
-
-9. Executing OPT_EXPR pass (perform const folding).
-Optimizing module addr_gen.
-
-yosys> clean
-Removed 0 unused cells and 4 unused wires.
-
-yosys> select -set new_cells t:$eq
-
-yosys> show -color cornflowerblue @new_cells -notitle -format dot -prefix addr_gen_clean
-
-10. Generating Graphviz representation of design.
-Writing dot description to `addr_gen_clean.dot'.
-Dumping module addr_gen to page 1.
-
-yosys> design -reset
-
-yosys> read_verilog fifo.v
-
-11. Executing Verilog-2005 frontend: fifo.v
-Parsing Verilog input from `fifo.v' to AST representation.
-Generating RTLIL representation for module `\addr_gen'.
-Generating RTLIL representation for module `\fifo'.
-Successfully finished Verilog frontend.
-
-yosys> hierarchy -check -top fifo
-
-12. Executing HIERARCHY pass (managing design hierarchy).
-
-12.1. Analyzing design hierarchy..
-Top module:  \fifo
-Used module:     \addr_gen
-Parameter \MAX_DATA = 256
-
-12.2. Executing AST frontend in derive mode using pre-parsed AST for module `\addr_gen'.
-Parameter \MAX_DATA = 256
-Generating RTLIL representation for module `$paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000'.
-Parameter \MAX_DATA = 256
-Found cached RTLIL representation for module `$paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000'.
-
-12.3. Analyzing design hierarchy..
-Top module:  \fifo
-Used module:     $paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000
-
-12.4. Analyzing design hierarchy..
-Top module:  \fifo
-Used module:     $paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000
-Removing unused module `\addr_gen'.
-Removed 1 unused modules.
-
-yosys> proc
-
-13. Executing PROC pass (convert processes to netlists).
-
-yosys> proc_clean
-
-13.1. Executing PROC_CLEAN pass (remove empty switches from decision trees).
-Cleaned up 0 empty switches.
-
-yosys> proc_rmdead
-
-13.2. Executing PROC_RMDEAD pass (remove dead branches from decision trees).
-Marked 2 switch rules as full_case in process $proc$fifo.v:62$24 in module fifo.
-Marked 1 switch rules as full_case in process $proc$fifo.v:36$16 in module fifo.
-Marked 2 switch rules as full_case in process $proc$fifo.v:12$32 in module $paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000.
-Removed a total of 0 dead cases.
-
-yosys> proc_prune
-
-13.3. Executing PROC_PRUNE pass (remove redundant assignments in processes).
-Removed 0 redundant assignments.
-Promoted 6 assignments to connections.
-
-yosys> proc_init
-
-13.4. Executing PROC_INIT pass (extract init attributes).
-Found init rule in `\fifo.$proc$fifo.v:0$31'.
-  Set init value: \count = 9'000000000
-Found init rule in `$paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000.$proc$fifo.v:0$35'.
-  Set init value: \addr = 8'00000000
-
-yosys> proc_arst
-
-13.5. Executing PROC_ARST pass (detect async resets in processes).
-Found async reset \rst in `\fifo.$proc$fifo.v:62$24'.
-Found async reset \rst in `$paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000.$proc$fifo.v:12$32'.
-
-yosys> proc_rom
-
-13.6. Executing PROC_ROM pass (convert switches to ROMs).
-Converted 0 switches.
-<suppressed ~5 debug messages>
-
-yosys> proc_mux
-
-13.7. Executing PROC_MUX pass (convert decision trees to multiplexers).
-Creating decoders for process `\fifo.$proc$fifo.v:0$31'.
-Creating decoders for process `\fifo.$proc$fifo.v:62$24'.
-     1/1: $0\count[8:0]
-Creating decoders for process `\fifo.$proc$fifo.v:36$16'.
-     1/3: $1$memwr$\data$fifo.v:38$15_EN[7:0]$22
-     2/3: $1$memwr$\data$fifo.v:38$15_DATA[7:0]$21
-     3/3: $1$memwr$\data$fifo.v:38$15_ADDR[7:0]$20
-Creating decoders for process `$paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000.$proc$fifo.v:0$35'.
-Creating decoders for process `$paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000.$proc$fifo.v:12$32'.
-     1/1: $0\addr[7:0]
-
-yosys> proc_dlatch
-
-13.8. Executing PROC_DLATCH pass (convert process syncs to latches).
-
-yosys> proc_dff
-
-13.9. Executing PROC_DFF pass (convert process syncs to FFs).
-Creating register for signal `\fifo.\count' using process `\fifo.$proc$fifo.v:62$24'.
-  created $adff cell `$procdff$55' with positive edge clock and positive level reset.
-Creating register for signal `\fifo.\rdata' using process `\fifo.$proc$fifo.v:36$16'.
-  created $dff cell `$procdff$56' with positive edge clock.
-Creating register for signal `\fifo.$memwr$\data$fifo.v:38$15_ADDR' using process `\fifo.$proc$fifo.v:36$16'.
-  created $dff cell `$procdff$57' with positive edge clock.
-Creating register for signal `\fifo.$memwr$\data$fifo.v:38$15_DATA' using process `\fifo.$proc$fifo.v:36$16'.
-  created $dff cell `$procdff$58' with positive edge clock.
-Creating register for signal `\fifo.$memwr$\data$fifo.v:38$15_EN' using process `\fifo.$proc$fifo.v:36$16'.
-  created $dff cell `$procdff$59' with positive edge clock.
-Creating register for signal `$paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000.\addr' using process `$paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000.$proc$fifo.v:12$32'.
-  created $adff cell `$procdff$60' with positive edge clock and positive level reset.
-
-yosys> proc_memwr
-
-13.10. Executing PROC_MEMWR pass (convert process memory writes to cells).
-
-yosys> proc_clean
-
-13.11. Executing PROC_CLEAN pass (remove empty switches from decision trees).
-Removing empty process `fifo.$proc$fifo.v:0$31'.
-Found and cleaned up 2 empty switches in `\fifo.$proc$fifo.v:62$24'.
-Removing empty process `fifo.$proc$fifo.v:62$24'.
-Found and cleaned up 1 empty switch in `\fifo.$proc$fifo.v:36$16'.
-Removing empty process `fifo.$proc$fifo.v:36$16'.
-Removing empty process `$paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000.$proc$fifo.v:0$35'.
-Found and cleaned up 2 empty switches in `$paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000.$proc$fifo.v:12$32'.
-Removing empty process `$paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000.$proc$fifo.v:12$32'.
-Cleaned up 5 empty switches.
-
-yosys> opt_expr -keepdc
-
-13.12. Executing OPT_EXPR pass (perform const folding).
-Optimizing module fifo.
-Optimizing module $paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000.
-
-yosys> select -set new_cells t:$memrd
-
-yosys> show -color maroon3 c:fifo_reader -color cornflowerblue @new_cells -notitle -format dot -prefix rdata_proc o:rdata %ci*
-
-14. Generating Graphviz representation of design.
-Writing dot description to `rdata_proc.dot'.
-Dumping selected parts of module fifo to page 1.
-
-yosys> flatten
-
-15. Executing FLATTEN pass (flatten design).
-Deleting now unused module $paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000.
-<suppressed ~2 debug messages>
-
-yosys> clean
-Removed 3 unused cells and 25 unused wires.
-
-yosys> select -set rdata_path o:rdata %ci*
-
-yosys> select -set new_cells @rdata_path o:rdata %ci3 %d i:* %d
-
-yosys> show -color maroon3 @new_cells -notitle -format dot -prefix rdata_flat @rdata_path
-
-16. Generating Graphviz representation of design.
-Writing dot description to `rdata_flat.dot'.
-Dumping selected parts of module fifo to page 1.
-
-yosys> opt_dff
-
-17. Executing OPT_DFF pass (perform DFF optimizations).
-Adding EN signal on $procdff$55 ($adff) from module fifo (D = $0\count[8:0], Q = \count).
-Adding EN signal on $flatten\fifo_writer.$procdff$60 ($adff) from module fifo (D = $flatten\fifo_writer.$procmux$51_Y, Q = \fifo_writer.addr).
-Adding EN signal on $flatten\fifo_reader.$procdff$60 ($adff) from module fifo (D = $flatten\fifo_reader.$procmux$51_Y, Q = \fifo_reader.addr).
-
-yosys> select -set new_cells t:$adffe
-
-yosys> show -color maroon3 @new_cells -notitle -format dot -prefix rdata_adffe o:rdata %ci*
-
-18. Generating Graphviz representation of design.
-Writing dot description to `rdata_adffe.dot'.
-Dumping selected parts of module fifo to page 1.
-
-yosys> wreduce
-
-19. Executing WREDUCE pass (reducing word size of cells).
-Removed top 31 bits (of 32) from port B of cell fifo.$add$fifo.v:66$27 ($add).
-Removed top 23 bits (of 32) from port Y of cell fifo.$add$fifo.v:66$27 ($add).
-Removed top 31 bits (of 32) from port B of cell fifo.$sub$fifo.v:68$30 ($sub).
-Removed top 23 bits (of 32) from port Y of cell fifo.$sub$fifo.v:68$30 ($sub).
-Removed top 1 bits (of 2) from port B of cell fifo.$auto$opt_dff.cc:195:make_patterns_logic$66 ($ne).
-Removed cell fifo.$flatten\fifo_writer.$procmux$53 ($mux).
-Removed top 31 bits (of 32) from port B of cell fifo.$flatten\fifo_writer.$add$fifo.v:19$34 ($add).
-Removed top 24 bits (of 32) from port Y of cell fifo.$flatten\fifo_writer.$add$fifo.v:19$34 ($add).
-Removed cell fifo.$flatten\fifo_reader.$procmux$53 ($mux).
-Removed top 31 bits (of 32) from port B of cell fifo.$flatten\fifo_reader.$add$fifo.v:19$34 ($add).
-Removed top 24 bits (of 32) from port Y of cell fifo.$flatten\fifo_reader.$add$fifo.v:19$34 ($add).
-Removed top 23 bits (of 32) from wire fifo.$add$fifo.v:66$27_Y.
-Removed top 24 bits (of 32) from wire fifo.$flatten\fifo_reader.$add$fifo.v:19$34_Y.
-
-yosys> show -notitle -format dot -prefix rdata_wreduce o:rdata %ci*
-
-20. Generating Graphviz representation of design.
-Writing dot description to `rdata_wreduce.dot'.
-Dumping selected parts of module fifo to page 1.
-
-yosys> opt_clean
-
-21. Executing OPT_CLEAN pass (remove unused cells and wires).
-Finding unused cells or wires in module \fifo..
-Removed 0 unused cells and 4 unused wires.
-<suppressed ~1 debug messages>
-
-yosys> memory_dff
-
-22. Executing MEMORY_DFF pass (merging $dff cells to $memrd).
-Checking read port `\data'[0] in module `\fifo': merging output FF to cell.
-    Write port 0: non-transparent.
-
-yosys> select -set new_cells t:$memrd_v2
-
-yosys> show -color maroon3 @new_cells -notitle -format dot -prefix rdata_memrdv2 o:rdata %ci*
-
-23. Generating Graphviz representation of design.
-Writing dot description to `rdata_memrdv2.dot'.
-Dumping selected parts of module fifo to page 1.
-
-yosys> alumacc
-
-24. Executing ALUMACC pass (create $alu and $macc cells).
-Extracting $alu and $macc cells in module fifo:
-  creating $macc model for $add$fifo.v:66$27 ($add).
-  creating $macc model for $flatten\fifo_reader.$add$fifo.v:19$34 ($add).
-  creating $macc model for $flatten\fifo_writer.$add$fifo.v:19$34 ($add).
-  creating $macc model for $sub$fifo.v:68$30 ($sub).
-  creating $alu model for $macc $sub$fifo.v:68$30.
-  creating $alu model for $macc $flatten\fifo_writer.$add$fifo.v:19$34.
-  creating $alu model for $macc $flatten\fifo_reader.$add$fifo.v:19$34.
-  creating $alu model for $macc $add$fifo.v:66$27.
-  creating $alu cell for $add$fifo.v:66$27: $auto$alumacc.cc:485:replace_alu$80
-  creating $alu cell for $flatten\fifo_reader.$add$fifo.v:19$34: $auto$alumacc.cc:485:replace_alu$83
-  creating $alu cell for $flatten\fifo_writer.$add$fifo.v:19$34: $auto$alumacc.cc:485:replace_alu$86
-  creating $alu cell for $sub$fifo.v:68$30: $auto$alumacc.cc:485:replace_alu$89
-  created 4 $alu and 0 $macc cells.
-
-yosys> select -set new_cells t:$alu t:$macc
-
-yosys> show -color maroon3 @new_cells -notitle -format dot -prefix rdata_alumacc o:rdata %ci*
-
-25. Generating Graphviz representation of design.
-Writing dot description to `rdata_alumacc.dot'.
-Dumping selected parts of module fifo to page 1.
-
-yosys> memory_collect
-
-26. Executing MEMORY_COLLECT pass (generating $mem cells).
-
-yosys> select -set new_cells t:$mem_v2
-
-yosys> select -set rdata_path @new_cells %ci*:-$mem_v2[WR_DATA,WR_ADDR,WR_EN] @new_cells %co* %%
-
-yosys> show -color maroon3 @new_cells -notitle -format dot -prefix rdata_coarse @rdata_path
-
-27. Generating Graphviz representation of design.
-Writing dot description to `rdata_coarse.dot'.
-Dumping selected parts of module fifo to page 1.
diff --git a/docs/source/code_examples/fifo/fifo.stat b/docs/source/code_examples/fifo/fifo.stat
deleted file mode 100644
index 263c618e3..000000000
--- a/docs/source/code_examples/fifo/fifo.stat
+++ /dev/null
@@ -1,57 +0,0 @@
-
-yosys> stat
-
-2. Printing statistics.
-
-=== fifo ===
-
-   Number of wires:                 28
-   Number of wire bits:            219
-   Number of public wires:           9
-   Number of public wire bits:      45
-   Number of memories:               1
-   Number of memory bits:         2048
-   Number of processes:              3
-   Number of cells:                  9
-     $add                            1
-     $logic_and                      2
-     $logic_not                      2
-     $memrd                          1
-     $sub                            1
-     addr_gen                        2
-
-=== addr_gen ===
-
-   Number of wires:                  8
-   Number of wire bits:             60
-   Number of public wires:           4
-   Number of public wire bits:      11
-   Number of memories:               0
-   Number of memory bits:            0
-   Number of processes:              2
-   Number of cells:                  2
-     $add                            1
-     $eq                             1
-
-
-yosys> stat -top fifo
-
-17. Printing statistics.
-
-=== fifo ===
-
-   Number of wires:                 94
-   Number of wire bits:            260
-   Number of public wires:          94
-   Number of public wire bits:     260
-   Number of memories:               0
-   Number of memory bits:            0
-   Number of processes:              0
-   Number of cells:                138
-     $scopeinfo                      2
-     SB_CARRY                       26
-     SB_DFF                         26
-     SB_DFFER                       25
-     SB_LUT4                        58
-     SB_RAM40_4K                     1
-
diff --git a/docs/source/code_examples/selections/Makefile b/docs/source/code_examples/selections/Makefile
index 3ad1bcf20..46a09060a 100644
--- a/docs/source/code_examples/selections/Makefile
+++ b/docs/source/code_examples/selections/Makefile
@@ -14,12 +14,12 @@ SUBMOD_DOTS := $(addsuffix .dot,$(SUBMOD))
 .PHONY: all dots examples
 all: dots examples
 dots: select.dot $(SUMPROD_DOTS) $(MEMDEMO_DOTS) $(SUBMOD_DOTS)
-examples:
+examples: sumprod.out
 
 select.dot: select.v select.ys
 	$(YOSYS) select.ys
 
-$(SUMPROD_DOTS): sumprod.v sumprod.ys
+$(SUMPROD_DOTS) sumprod.out: sumprod.v sumprod.ys
 	$(YOSYS) sumprod.ys
 
 $(MEMDEMO_DOTS): memdemo.v memdemo.ys
@@ -31,3 +31,4 @@ $(SUBMOD_DOTS): memdemo.v submod.ys
 .PHONY: clean
 clean:
 	rm -rf *.dot
+	rm -f sumprod.out
diff --git a/docs/source/code_examples/selections/sumprod.out b/docs/source/code_examples/selections/sumprod.out
deleted file mode 100644
index f7c259499..000000000
--- a/docs/source/code_examples/selections/sumprod.out
+++ /dev/null
@@ -1,38 +0,0 @@
-
-
-  attribute \src "sumprod.v:4.21-4.25"
-  wire width 8 output 5 \prod
-
-  attribute \src "sumprod.v:10.17-10.26"
-  cell $mul $mul$sumprod.v:10$4
-    parameter \A_SIGNED 0
-    parameter \A_WIDTH 8
-    parameter \B_SIGNED 0
-    parameter \B_WIDTH 8
-    parameter \Y_WIDTH 8
-    connect \A $mul$sumprod.v:10$3_Y
-    connect \B \c
-    connect \Y \prod
-  end
-
-
-  attribute \src "sumprod.v:10.17-10.22"
-  wire width 8 $mul$sumprod.v:10$3_Y
-
-  attribute \src "sumprod.v:3.21-3.22"
-  wire width 8 input 3 \c
-
-  attribute \src "sumprod.v:4.21-4.25"
-  wire width 8 output 5 \prod
-
-  attribute \src "sumprod.v:10.17-10.26"
-  cell $mul $mul$sumprod.v:10$4
-    parameter \A_SIGNED 0
-    parameter \A_WIDTH 8
-    parameter \B_SIGNED 0
-    parameter \B_WIDTH 8
-    parameter \Y_WIDTH 8
-    connect \A $mul$sumprod.v:10$3_Y
-    connect \B \c
-    connect \Y \prod
-  end
diff --git a/docs/source/code_examples/show/Makefile b/docs/source/code_examples/show/Makefile
index 6c1906cce..649691299 100644
--- a/docs/source/code_examples/show/Makefile
+++ b/docs/source/code_examples/show/Makefile
@@ -28,3 +28,4 @@ $(CMOS_DOTS): cmos.v cmos.ys
 .PHONY: clean
 clean:
 	rm -rf *.dot
+	rm -f example.out
diff --git a/docs/source/code_examples/show/example.out b/docs/source/code_examples/show/example.out
deleted file mode 100644
index b8569e640..000000000
--- a/docs/source/code_examples/show/example.out
+++ /dev/null
@@ -1,54 +0,0 @@
-
--- Executing script file `example_lscd.ys' --
-
-1. Executing Verilog-2005 frontend: example.v
-Parsing Verilog input from `example.v' to AST representation.
-Generating RTLIL representation for module `\example'.
-Successfully finished Verilog frontend.
-echo on
-
-yosys> ls
-
-1 modules:
-  example
-
-yosys> cd example
-
-yosys [example]> ls
-
-8 wires:
-  $0\y[1:0]
-  $add$example.v:5$2_Y
-  $ternary$example.v:5$3_Y
-  a
-  b
-  c
-  clk
-  y
-
-2 cells:
-  $add$example.v:5$2
-  $ternary$example.v:5$3
-
-1 processes:
-  $proc$example.v:3$1
-
-yosys [example]> dump $2
-
-
-  attribute \src "example.v:5.22-5.27"
-  cell $add $add$example.v:5$2
-    parameter \Y_WIDTH 2
-    parameter \B_WIDTH 1
-    parameter \A_WIDTH 1
-    parameter \B_SIGNED 0
-    parameter \A_SIGNED 0
-    connect \Y $add$example.v:5$2_Y
-    connect \B \b
-    connect \A \a
-  end
-
-yosys [example]> cd ..
-
-yosys> echo off
-echo off

From 13d7b5fd6aab92e1f28900e778bff1c9505f5e34 Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Mon, 7 Oct 2024 22:01:01 +1300
Subject: [PATCH 06/30] Docs: Ignore example outputs

---
 docs/source/code_examples/.gitignore | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/docs/source/code_examples/.gitignore b/docs/source/code_examples/.gitignore
index b4a858a01..0eca4be80 100644
--- a/docs/source/code_examples/.gitignore
+++ b/docs/source/code_examples/.gitignore
@@ -1,2 +1,5 @@
 *.dot
 *.pdf
+*.out
+*.log
+*.stat

From edf29e725e82a1bf5914089374f4a0e237ae51db Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Mon, 7 Oct 2024 22:20:22 +1300
Subject: [PATCH 07/30] Docs: Add functional_ir to index

---
 docs/source/yosys_internals/extending_yosys/index.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/source/yosys_internals/extending_yosys/index.rst b/docs/source/yosys_internals/extending_yosys/index.rst
index 2a4d2dfef..88f36d526 100644
--- a/docs/source/yosys_internals/extending_yosys/index.rst
+++ b/docs/source/yosys_internals/extending_yosys/index.rst
@@ -10,5 +10,6 @@ of interest for developers looking to customise Yosys builds.
 
    extensions
    build_verific
+   functional_ir
    test_suites
 

From 33930e44ac70313b12fe6945450cceb45b7b1202 Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Mon, 7 Oct 2024 22:22:10 +1300
Subject: [PATCH 08/30] ci: Test build docs

---
 .github/workflows/test-build.yml | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/.github/workflows/test-build.yml b/.github/workflows/test-build.yml
index e5aed6af3..41e197424 100644
--- a/.github/workflows/test-build.yml
+++ b/.github/workflows/test-build.yml
@@ -189,3 +189,8 @@ jobs:
         shell: bash
         run: |
           make -C docs test -j${{ env.procs }}
+
+      - name: Test build docs
+        shell: bash
+        run: |
+          make -C docs -j${{ env.procs }} TARGETS= EXTRA_TARGETS=

From f72d0219d151183ced4de2fe2be533c102b645b3 Mon Sep 17 00:00:00 2001
From: KrystalDelusion <93062060+KrystalDelusion@users.noreply.github.com>
Date: Mon, 7 Oct 2024 22:52:33 +1300
Subject: [PATCH 09/30] Update test-build.yml

Call make docs from root
---
 .github/workflows/test-build.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/test-build.yml b/.github/workflows/test-build.yml
index 41e197424..1502d8aa0 100644
--- a/.github/workflows/test-build.yml
+++ b/.github/workflows/test-build.yml
@@ -193,4 +193,4 @@ jobs:
       - name: Test build docs
         shell: bash
         run: |
-          make -C docs -j${{ env.procs }} TARGETS= EXTRA_TARGETS=
+          make docs -j${{ env.procs }} TARGETS= EXTRA_TARGETS=

From 407343a7a12385bba40e406f68270b95afabb09b Mon Sep 17 00:00:00 2001
From: Mohamed Gaber <donn@efabless.com>
Date: Mon, 12 Aug 2024 14:21:05 +0300
Subject: [PATCH 10/30] Pyosys Wheels

* Created `setup.py`: Python package manifest to build `pyosys` wheels with a custom extension to build and include `libyosys.so` using Make
* `.gitignore`: Added byproducts of the Python wheel build process
* `Makefile`: Added `-undefined dynamic_lookup` to `libyosys.so` so missing symbols can be resolved by importing into a Python interpreter
* `kernel/yosys.cc`: Gated `PyImport_AppendInittab` with `!Py_IsInitialized`; as of Python 3.12, the interpreter is already initialized and `PyImport_AppendInittab` would cause an exception to be raised
* Created `wheels.yml`: CI workflow for building wheels for CPython on:
  * Linux (glibc, musl) and Darwin
  * x86-64 and arm64
---
 .github/workflows/wheels.yml | 111 +++++++++++++++++++++++++++++++++++
 .gitignore                   |   7 ++-
 Makefile                     |   2 +-
 kernel/yosys.cc              |  13 ++--
 setup.py                     |  97 ++++++++++++++++++++++++++++++
 5 files changed, 224 insertions(+), 6 deletions(-)
 create mode 100644 .github/workflows/wheels.yml
 create mode 100644 setup.py

diff --git a/.github/workflows/wheels.yml b/.github/workflows/wheels.yml
new file mode 100644
index 000000000..9f3394d84
--- /dev/null
+++ b/.github/workflows/wheels.yml
@@ -0,0 +1,111 @@
+name: Build Wheels for PyPI
+on:
+  workflow_dispatch:
+  push:
+    # tags: ["yosys-*"]
+jobs:
+  build_wheels:
+    strategy:
+      matrix:
+        os: [
+            # You can't cross-compile on Linux, so might as well do the emulated
+            # workload on its own
+            {
+              name: "Ubuntu 22.04",
+              family: "linux",
+              runner: "ubuntu-22.04",
+              archs: "x86_64",
+            },
+            {
+              name: "Ubuntu 22.04",
+              family: "linux",
+              runner: "ubuntu-22.04",
+              archs: "aarch64",
+            },
+            # While you can cross-compile on macOS, this is less of a headache
+            {
+              name: "macOS 13",
+              family: "macos",
+              runner: "macos-13",
+              archs: "x86_64",
+            },
+            {
+              name: "macOS 14",
+              family: "macos",
+              runner: "macos-14",
+              archs: "arm64",
+            },
+            # TODO: Make Windows Work
+            # {
+            #   name: "Windows Server 2019",
+            #   family: "windows",
+            #   runner: "windows-2019",
+            #   archs: "AMD64 ARM64",
+            # },
+          ]
+    name: Build Wheels | ${{ matrix.os.name }} | ${{ matrix.os.archs }}
+    runs-on: ${{ matrix.os.runner }}
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+          submodules: true
+      - if: ${{ matrix.os.family == 'linux' }}
+        name: "[Linux] Set up QEMU"
+        uses: docker/setup-qemu-action@v2
+      - uses: actions/setup-python@v3
+      - name: Get Boost Source
+        run: |
+          mkdir -p boost
+          curl -L https://sourceforge.net/projects/boost/files/boost/1.83.0/boost_1_83_0.tar.bz2 | tar --strip-components=1 -xjC boost
+      - name: Seed Makefile.bak
+        # For every sed, a .bak is created so it can be copied over Makefile to
+        # rever the change for the next Python version to be built.
+        #
+        # This creates a .bak for the first Python version's cp to consume.
+        run: |
+          cp Makefile Makefile.bak
+      - if: ${{ matrix.os.family == 'macos' }}
+        name: "[macOS] Flex/Bison"
+        run: |
+          brew install flex bison
+          echo "PATH=$(brew --prefix flex)/bin:$PATH" >> $GITHUB_ENV
+          echo "PATH=$(brew --prefix bison)/bin:$PATH" >> $GITHUB_ENV
+      - if: ${{ matrix.os.family == 'macos' && matrix.os.archs == 'arm64' }}
+        name: "[macOS/arm64] Install Python 3.8 (see: https://cibuildwheel.pypa.io/en/stable/faq/#macos-building-cpython-38-wheels-on-arm64)"
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.8
+      - name: Build wheels
+        uses: pypa/cibuildwheel@v2.20.0
+        env:
+          # Explaining the build steps:
+          #   1. Revert previous seds (if any)
+          #   2. Delete the libboost static archives from previous builds (if any)
+          #   3. Navigate to boost source extracted in previous GHA step
+          #   4-5. Build Boost against current version of Python, only for
+          #        static linkage
+          #        (Boost is statically linked because system boost packages
+          #         wildly vary in versions, including the libboost_python3
+          #         version)
+          #   6-7. Return to package directory and sed the Makefile to point at
+          #        the newly compiled libboost_python
+          CIBW_SKIP: pp* # The Makefile requires python3-config which is not in pypy
+          CIBW_ARCHS: ${{ matrix.os.archs }}
+          CIBW_BUILD_VERBOSITY: "1"
+          CIBW_BEFORE_ALL_LINUX: yum install -y libffi-devel flex bison || apk add libffi-dev flex bison
+          CIBW_BEFORE_ALL_MAC: brew install libffi
+          CIBW_BEFORE_BUILD: |
+            cp Makefile.bak Makefile &&\
+              cd ./boost &&\
+              rm -rf ./pfx &&\
+              ./bootstrap.sh --prefix=./pfx &&\
+              ./b2 --prefix=./pfx --with-filesystem --with-system --with-python cxxflags="$(python3-config --includes) -std=c++17 -fPIC" cflags="$(python3-config --includes) -fPIC" link=static variant=release install &&\
+              ls ./pfx/lib/libboost_python*.a &&\
+              cd {package} &&\
+              sed -i'.bak' -e "1i\\
+                LINKFLAGS = -L./boost/pfx/lib" -e "1i\\
+                CXXFLAGS = -I./boost/pfx/include" -e "s@BOOST_PYTHON_LIB ?=@BOOST_PYTHON_LIB = $(ls ./boost/pfx/lib/libboost_python*.a)\nTrash =@" Makefile
+      - uses: actions/upload-artifact@v3
+        with:
+          path: ./dist/*.whl
diff --git a/.gitignore b/.gitignore
index e82343e89..5d6a466db 100644
--- a/.gitignore
+++ b/.gitignore
@@ -45,4 +45,9 @@ __pycache__
 /tests/unit/bintest/
 /tests/unit/objtest/
 /tests/ystests
-/result
\ No newline at end of file
+/result
+/dist
+/*.egg-info
+/build
+/venv
+/boost
diff --git a/Makefile b/Makefile
index 5b6fc3ff2..ebea193cf 100644
--- a/Makefile
+++ b/Makefile
@@ -742,7 +742,7 @@ $(PROGRAM_PREFIX)yosys$(EXE): $(OBJS)
 
 libyosys.so: $(filter-out kernel/driver.o,$(OBJS))
 ifeq ($(OS), Darwin)
-	$(P) $(CXX) -o libyosys.so -shared -Wl,-install_name,$(LIBDIR)/libyosys.so $(LINKFLAGS) $^ $(LIBS) $(LIBS_VERIFIC)
+	$(P) $(CXX) -o libyosys.so -shared -undefined dynamic_lookup -Wl,-install_name,$(LIBDIR)/libyosys.so $(LINKFLAGS) $^ $(LIBS) $(LIBS_VERIFIC)
 else
 	$(P) $(CXX) -o libyosys.so -shared -Wl,-soname,$(LIBDIR)/libyosys.so $(LINKFLAGS) $^ $(LIBS) $(LIBS_VERIFIC)
 endif
diff --git a/kernel/yosys.cc b/kernel/yosys.cc
index efdc54b79..510151479 100644
--- a/kernel/yosys.cc
+++ b/kernel/yosys.cc
@@ -555,10 +555,15 @@ void yosys_setup()
 #undef X
 
 	#ifdef WITH_PYTHON
-		PyImport_AppendInittab((char*)"libyosys", INIT_MODULE);
-		Py_Initialize();
-		PyRun_SimpleString("import sys");
-		signal(SIGINT, SIG_DFL);
+		// With Python 3.12, calling PyImport_AppendInittab on an already
+		// initialized platform fails (such as when libyosys is imported
+		// from a Python interpreter)
+		if (!Py_IsInitialized()) {
+			PyImport_AppendInittab((char*)"libyosys", INIT_MODULE);
+			Py_Initialize();
+			PyRun_SimpleString("import sys");
+			signal(SIGINT, SIG_DFL);
+		}
 	#endif
 
 	Pass::init_register();
diff --git a/setup.py b/setup.py
new file mode 100644
index 000000000..02e6e5843
--- /dev/null
+++ b/setup.py
@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+# Copyright (C) 2024 Efabless Corporation
+#
+# Permission to use, copy, modify, and/or distribute this software for any
+# purpose with or without fee is hereby granted, provided that the above
+# copyright notice and this permission notice appear in all copies.
+#
+# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+import os
+import re
+import shlex
+import shutil
+from setuptools import setup, Extension
+from setuptools.command.build_ext import build_ext
+
+__dir__ = os.path.dirname(os.path.abspath(__file__))
+
+yosys_version_rx = re.compile(r"YOSYS_VER\s*:=\s*([\w\-\+\.]+)")
+
+version = yosys_version_rx.search(
+    open(os.path.join(__dir__, "Makefile"), encoding="utf8").read()
+)[1]
+
+
+class libyosys_so_ext(Extension):
+    def __init__(
+        self,
+    ) -> None:
+        super().__init__(
+            "libyosys.so",
+            [],
+        )
+        self.args = [
+            "ENABLE_PYOSYS=1",
+            # Wheel meant to be imported from interpreter
+            "ENABLE_PYTHON_CONFIG_EMBED=0",
+            # Would need to be installed separately by the user
+            "ENABLE_TCL=0",
+            # Would need to be installed separately by the user
+            "ENABLE_READLINE=0",
+            # Show compile commands
+            "PRETTY=0",
+        ]
+
+    def custom_build(self, bext: build_ext):
+        bext.spawn(
+            ["make", f"-j{os.cpu_count() or 1}", self.name]
+            + shlex.split(os.getenv("makeFlags", ""))
+            + self.args
+        )
+        build_path = os.path.dirname(os.path.dirname(bext.get_ext_fullpath(self.name)))
+        pyosys_path = os.path.join(build_path, "pyosys")
+        target = os.path.join(pyosys_path, os.path.basename(self.name))
+        os.makedirs(pyosys_path, exist_ok=True)
+        shutil.copyfile(self.name, target)
+
+        # I don't know how debug info is getting here.
+        bext.spawn(["strip", "-S", target])
+
+
+class custom_build_ext(build_ext):
+    def build_extension(self, ext) -> None:
+        if not hasattr(ext, "custom_build"):
+            return super().build_extension(ext)
+        return ext.custom_build(self)
+
+
+setup(
+    name="pyosys",
+    packages=["pyosys"],
+    version=version,
+    description="Python access to libyosys",
+    long_description=open(os.path.join(__dir__, "README.md")).read(),
+    long_description_content_type="text/markdown",
+    author="Claire Xenia Wolf",
+    author_email="claire@yosyshq.com",
+    install_requires=["wheel", "setuptools"],
+    classifiers=[
+        "License :: OSI Approved :: MIT License",
+        "Programming Language :: Python :: 3",
+        "Intended Audience :: Developers",
+        "Operating System :: POSIX :: Linux",
+        "Operating System :: MacOS :: MacOS X",
+    ],
+    package_dir={"pyosys": "misc"},
+    python_requires=">=3.8",
+    ext_modules=[libyosys_so_ext()],
+    cmdclass={
+        "build_ext": custom_build_ext,
+    },
+)

From ab4ea84679a9af5fa6172a4b4ce55c86d7a1ac5c Mon Sep 17 00:00:00 2001
From: Mohamed Gaber <donn@efabless.com>
Date: Sat, 28 Sep 2024 21:03:43 +0300
Subject: [PATCH 11/30] wheels: more compatibility

* Update manylinux images
* FFI now built as a per-platform static library
* Explicitly set minimum macOS deployment target, use clang on macOS
* Try enabling Windows (as an experiment)
* Disable aarch64-linux, aarch64-windows
---
 .github/workflows/_run_cibw_linux.py   | 44 ++++++++++++
 .github/workflows/cibw_before_all.sh   | 21 ++++++
 .github/workflows/cibw_before_build.sh | 23 +++++++
 .github/workflows/wheels.yml           | 92 +++++++++++++-------------
 .gitignore                             |  1 +
 5 files changed, 134 insertions(+), 47 deletions(-)
 create mode 100644 .github/workflows/_run_cibw_linux.py
 create mode 100644 .github/workflows/cibw_before_all.sh
 create mode 100644 .github/workflows/cibw_before_build.sh

diff --git a/.github/workflows/_run_cibw_linux.py b/.github/workflows/_run_cibw_linux.py
new file mode 100644
index 000000000..675817ae0
--- /dev/null
+++ b/.github/workflows/_run_cibw_linux.py
@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+# Copyright (C) 2024 Efabless Corporation
+#
+# Permission to use, copy, modify, and/or distribute this software for any
+# purpose with or without fee is hereby granted, provided that the above
+# copyright notice and this permission notice appear in all copies.
+#
+# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+"""
+This runs the cibuildwheel step from the wheels workflow locally.
+"""
+
+import os
+import yaml
+import platform
+import subprocess
+
+__dir__ = os.path.dirname(os.path.abspath(__file__))
+
+
+workflow = yaml.safe_load(open(os.path.join(__dir__, "wheels.yml")))
+
+env = os.environ.copy()
+
+steps = workflow["jobs"]["build_wheels"]["steps"]
+cibw_step = None
+for step in steps:
+    if (step.get("uses") or "").startswith("pypa/cibuildwheel"):
+        cibw_step = step
+        break
+
+for key, value in cibw_step["env"].items():
+    if key.endswith("WIN") or key.endswith("MAC"):
+        continue
+    env[key] = value
+
+env["CIBW_ARCHS"] = os.getenv("CIBW_ARCHS") or platform.machine()
+subprocess.check_call(["cibuildwheel"], env=env)
diff --git a/.github/workflows/cibw_before_all.sh b/.github/workflows/cibw_before_all.sh
new file mode 100644
index 000000000..934902380
--- /dev/null
+++ b/.github/workflows/cibw_before_all.sh
@@ -0,0 +1,21 @@
+set -e
+set -x
+
+# Build-time dependencies
+## Linux Docker Images
+if command -v yum &> /dev/null; then
+    yum install -y flex bison
+fi
+
+if command -v apk &> /dev/null; then
+    apk add flex bison
+fi
+
+## macOS/Windows -- install in GitHub Action itself, not container
+
+# Build Static FFI (platform-dependent but not Python version dependent)
+cd ffi
+SHELL=bash CFLAGS=-fPIC CXXFLAGS=-fPIC ./configure --prefix=$PWD/pfx
+
+make install -j$(getconf _NPROCESSORS_ONLN 2>/dev/null || sysctl -n hw.ncpu)
+sed -i.bak 's@-L${toolexeclibdir} -lffi@${toolexeclibdir}/libffi.a@' ./pfx/lib/pkgconfig/libffi.pc
diff --git a/.github/workflows/cibw_before_build.sh b/.github/workflows/cibw_before_build.sh
new file mode 100644
index 000000000..03baf110b
--- /dev/null
+++ b/.github/workflows/cibw_before_build.sh
@@ -0,0 +1,23 @@
+set -e
+set -x
+
+# Build boost
+cd ./boost
+## Delete the artefacts from previous builds (if any)
+rm -rf ./pfx
+## Bootstrap bjam
+./bootstrap.sh --prefix=./pfx
+## Build Boost against current version of Python, only for
+## static linkage (Boost is statically linked because system boost packages
+## wildly vary in versions, including the libboost_python3 version)
+./b2\
+    -j$(getconf _NPROCESSORS_ONLN 2>/dev/null || sysctl -n hw.ncpu)\
+    --prefix=./pfx\
+    --with-filesystem\
+    --with-system\
+    --with-python\
+    cxxflags="$(python3-config --includes) -std=c++17 -fPIC"\
+    cflags="$(python3-config --includes) -fPIC"\
+    link=static\
+    variant=release\
+    install
diff --git a/.github/workflows/wheels.yml b/.github/workflows/wheels.yml
index 9f3394d84..5961f364a 100644
--- a/.github/workflows/wheels.yml
+++ b/.github/workflows/wheels.yml
@@ -6,23 +6,25 @@ on:
 jobs:
   build_wheels:
     strategy:
+      fail-fast: false
       matrix:
         os: [
-            # You can't cross-compile on Linux, so might as well do the emulated
-            # workload on its own
             {
               name: "Ubuntu 22.04",
               family: "linux",
               runner: "ubuntu-22.04",
               archs: "x86_64",
             },
-            {
-              name: "Ubuntu 22.04",
-              family: "linux",
-              runner: "ubuntu-22.04",
-              archs: "aarch64",
-            },
-            # While you can cross-compile on macOS, this is less of a headache
+            ## Aarch64 is disabled for now: GitHub is committing to EOY
+            ## for free aarch64 runners for open-source projects and
+            ## emulation times out:
+            ## https://github.com/orgs/community/discussions/19197#discussioncomment-10550689
+            # {
+            #   name: "Ubuntu 22.04",
+            #   family: "linux",
+            #   runner: "ubuntu-22.04",
+            #   archs: "aarch64",
+            # },
             {
               name: "macOS 13",
               family: "macos",
@@ -35,13 +37,12 @@ jobs:
               runner: "macos-14",
               archs: "arm64",
             },
-            # TODO: Make Windows Work
-            # {
-            #   name: "Windows Server 2019",
-            #   family: "windows",
-            #   runner: "windows-2019",
-            #   archs: "AMD64 ARM64",
-            # },
+            {
+              name: "Windows Server 2019",
+              family: "windows",
+              runner: "windows-2019",
+              archs: "AMD64",
+            },
           ]
     name: Build Wheels | ${{ matrix.os.name }} | ${{ matrix.os.archs }}
     runs-on: ${{ matrix.os.runner }}
@@ -55,22 +56,27 @@ jobs:
         uses: docker/setup-qemu-action@v2
       - uses: actions/setup-python@v3
       - name: Get Boost Source
+        shell: bash
         run: |
           mkdir -p boost
-          curl -L https://sourceforge.net/projects/boost/files/boost/1.83.0/boost_1_83_0.tar.bz2 | tar --strip-components=1 -xjC boost
-      - name: Seed Makefile.bak
-        # For every sed, a .bak is created so it can be copied over Makefile to
-        # rever the change for the next Python version to be built.
-        #
-        # This creates a .bak for the first Python version's cp to consume.
+          curl -L https://github.com/boostorg/boost/releases/download/boost-1.86.0/boost-1.86.0-b2-nodocs.tar.gz | tar --strip-components=1 -xzC boost
+      - name: Get FFI
+        shell: bash
         run: |
-          cp Makefile Makefile.bak
+          mkdir -p ffi
+          curl -L https://github.com/libffi/libffi/releases/download/v3.4.6/libffi-3.4.6.tar.gz | tar --strip-components=1 -xzC ffi
+      ## Software installed by default in GitHub Action Runner VMs:
+      ##  https://github.com/actions/runner-images
       - if: ${{ matrix.os.family == 'macos' }}
         name: "[macOS] Flex/Bison"
         run: |
           brew install flex bison
           echo "PATH=$(brew --prefix flex)/bin:$PATH" >> $GITHUB_ENV
           echo "PATH=$(brew --prefix bison)/bin:$PATH" >> $GITHUB_ENV
+      - if : ${{ matrix.os.family == 'windows' }}
+        name: "[Windows] Flex/Bison"
+        run: |
+          choco install winflexbison3
       - if: ${{ matrix.os.family == 'macos' && matrix.os.archs == 'arm64' }}
         name: "[macOS/arm64] Install Python 3.8 (see: https://cibuildwheel.pypa.io/en/stable/faq/#macos-building-cpython-38-wheels-on-arm64)"
         uses: actions/setup-python@v5
@@ -79,33 +85,25 @@ jobs:
       - name: Build wheels
         uses: pypa/cibuildwheel@v2.20.0
         env:
-          # Explaining the build steps:
-          #   1. Revert previous seds (if any)
-          #   2. Delete the libboost static archives from previous builds (if any)
-          #   3. Navigate to boost source extracted in previous GHA step
-          #   4-5. Build Boost against current version of Python, only for
-          #        static linkage
-          #        (Boost is statically linked because system boost packages
-          #         wildly vary in versions, including the libboost_python3
-          #         version)
-          #   6-7. Return to package directory and sed the Makefile to point at
-          #        the newly compiled libboost_python
           CIBW_SKIP: pp* # The Makefile requires python3-config which is not in pypy
           CIBW_ARCHS: ${{ matrix.os.archs }}
           CIBW_BUILD_VERBOSITY: "1"
-          CIBW_BEFORE_ALL_LINUX: yum install -y libffi-devel flex bison || apk add libffi-dev flex bison
-          CIBW_BEFORE_ALL_MAC: brew install libffi
-          CIBW_BEFORE_BUILD: |
-            cp Makefile.bak Makefile &&\
-              cd ./boost &&\
-              rm -rf ./pfx &&\
-              ./bootstrap.sh --prefix=./pfx &&\
-              ./b2 --prefix=./pfx --with-filesystem --with-system --with-python cxxflags="$(python3-config --includes) -std=c++17 -fPIC" cflags="$(python3-config --includes) -fPIC" link=static variant=release install &&\
-              ls ./pfx/lib/libboost_python*.a &&\
-              cd {package} &&\
-              sed -i'.bak' -e "1i\\
-                LINKFLAGS = -L./boost/pfx/lib" -e "1i\\
-                CXXFLAGS = -I./boost/pfx/include" -e "s@BOOST_PYTHON_LIB ?=@BOOST_PYTHON_LIB = $(ls ./boost/pfx/lib/libboost_python*.a)\nTrash =@" Makefile
+          # manylinux2014 (default) does not have a modern enough C++ compiler for Yosys
+          CIBW_MANYLINUX_X86_64_IMAGE: manylinux_2_28
+          CIBW_MANYLINUX_AARCH64_IMAGE: manylinux_2_28
+          CIBW_BEFORE_ALL: bash ./.github/workflows/cibw_before_all.sh
+          CIBW_ENVIRONMENT: >
+            CXXFLAGS=-I./boost/pfx/include
+            LINKFLAGS=-L./boost/pfx/lib
+            PKG_CONFIG_PATH=./ffi/pfx/lib/pkgconfig
+            makeFlags='BOOST_PYTHON_LIB=./boost/pfx/lib/libboost_python*.a'
+          CIBW_ENVIRONMENT_MACOS: >
+            CXXFLAGS=-I./boost/pfx/include
+            LINKFLAGS=-L./boost/pfx/lib
+            PKG_CONFIG_PATH=./ffi/pfx/lib/pkgconfig
+            MACOSX_DEPLOYMENT_TARGET=11
+            makeFlags='BOOST_PYTHON_LIB=./boost/pfx/lib/libboost_python*.a CONFIG=clang'
+          CIBW_BEFORE_BUILD: bash ./.github/workflows/cibw_before_build.sh
       - uses: actions/upload-artifact@v3
         with:
           path: ./dist/*.whl
diff --git a/.gitignore b/.gitignore
index 5d6a466db..5c3d8f4e9 100644
--- a/.gitignore
+++ b/.gitignore
@@ -51,3 +51,4 @@ __pycache__
 /build
 /venv
 /boost
+/ffi

From ab84c105c14bfca00a6b87828cb665b40740b35b Mon Sep 17 00:00:00 2001
From: Mohamed Gaber <donn@efabless.com>
Date: Sat, 28 Sep 2024 23:11:45 +0300
Subject: [PATCH 12/30] Add test, shell for windows

---
 .github/workflows/wheels.yml                        |  5 +++--
 .github/workflows/{ => wheels}/_run_cibw_linux.py   |  2 +-
 .github/workflows/{ => wheels}/cibw_before_all.sh   | 10 ++++++----
 .github/workflows/{ => wheels}/cibw_before_build.sh |  7 +++++++
 4 files changed, 17 insertions(+), 7 deletions(-)
 rename .github/workflows/{ => wheels}/_run_cibw_linux.py (94%)
 rename .github/workflows/{ => wheels}/cibw_before_all.sh (55%)
 rename .github/workflows/{ => wheels}/cibw_before_build.sh (80%)

diff --git a/.github/workflows/wheels.yml b/.github/workflows/wheels.yml
index 5961f364a..c6af2c8b2 100644
--- a/.github/workflows/wheels.yml
+++ b/.github/workflows/wheels.yml
@@ -91,7 +91,7 @@ jobs:
           # manylinux2014 (default) does not have a modern enough C++ compiler for Yosys
           CIBW_MANYLINUX_X86_64_IMAGE: manylinux_2_28
           CIBW_MANYLINUX_AARCH64_IMAGE: manylinux_2_28
-          CIBW_BEFORE_ALL: bash ./.github/workflows/cibw_before_all.sh
+          CIBW_BEFORE_ALL: bash ./.github/workflows/wheels/cibw_before_all.sh
           CIBW_ENVIRONMENT: >
             CXXFLAGS=-I./boost/pfx/include
             LINKFLAGS=-L./boost/pfx/lib
@@ -103,7 +103,8 @@ jobs:
             PKG_CONFIG_PATH=./ffi/pfx/lib/pkgconfig
             MACOSX_DEPLOYMENT_TARGET=11
             makeFlags='BOOST_PYTHON_LIB=./boost/pfx/lib/libboost_python*.a CONFIG=clang'
-          CIBW_BEFORE_BUILD: bash ./.github/workflows/cibw_before_build.sh
+          CIBW_BEFORE_BUILD: bash ./.github/workflows/wheels/cibw_before_build.sh
+          CIBW_TEST_COMMAND: python3 -c "from pyosys import libyosys as ys;d=ys.Design();ys.run_pass('help', d)"
       - uses: actions/upload-artifact@v3
         with:
           path: ./dist/*.whl
diff --git a/.github/workflows/_run_cibw_linux.py b/.github/workflows/wheels/_run_cibw_linux.py
similarity index 94%
rename from .github/workflows/_run_cibw_linux.py
rename to .github/workflows/wheels/_run_cibw_linux.py
index 675817ae0..894470a5a 100644
--- a/.github/workflows/_run_cibw_linux.py
+++ b/.github/workflows/wheels/_run_cibw_linux.py
@@ -24,7 +24,7 @@ import subprocess
 __dir__ = os.path.dirname(os.path.abspath(__file__))
 
 
-workflow = yaml.safe_load(open(os.path.join(__dir__, "wheels.yml")))
+workflow = yaml.safe_load(open(os.path.join(os.path.dirname(__dir__), "wheels.yml")))
 
 env = os.environ.copy()
 
diff --git a/.github/workflows/cibw_before_all.sh b/.github/workflows/wheels/cibw_before_all.sh
similarity index 55%
rename from .github/workflows/cibw_before_all.sh
rename to .github/workflows/wheels/cibw_before_all.sh
index 934902380..28aae85ac 100644
--- a/.github/workflows/cibw_before_all.sh
+++ b/.github/workflows/wheels/cibw_before_all.sh
@@ -11,11 +11,13 @@ if command -v apk &> /dev/null; then
     apk add flex bison
 fi
 
-## macOS/Windows -- install in GitHub Action itself, not container
+## macOS/Windows -- installed in GitHub Action itself, not container
 
 # Build Static FFI (platform-dependent but not Python version dependent)
 cd ffi
-SHELL=bash CFLAGS=-fPIC CXXFLAGS=-fPIC ./configure --prefix=$PWD/pfx
-
-make install -j$(getconf _NPROCESSORS_ONLN 2>/dev/null || sysctl -n hw.ncpu)
+## Ultimate libyosys.so will be shared, so we need fPIC for the static libraries
+CFLAGS=-fPIC CXXFLAGS=-fPIC ./configure --prefix=$PWD/pfx
+## Without this, SHELL has a space in its path which breaks the makefile
+make install -j$(getconf _NPROCESSORS_ONLN 2>/dev/null || sysctl -n hw.ncpu) SHELL=bash
+## Forces static library to be used in all situations
 sed -i.bak 's@-L${toolexeclibdir} -lffi@${toolexeclibdir}/libffi.a@' ./pfx/lib/pkgconfig/libffi.pc
diff --git a/.github/workflows/cibw_before_build.sh b/.github/workflows/wheels/cibw_before_build.sh
similarity index 80%
rename from .github/workflows/cibw_before_build.sh
rename to .github/workflows/wheels/cibw_before_build.sh
index 03baf110b..29fffe090 100644
--- a/.github/workflows/cibw_before_build.sh
+++ b/.github/workflows/wheels/cibw_before_build.sh
@@ -1,6 +1,13 @@
 set -e
 set -x
 
+# Don't use objects from previous compiles on Windows/macOS
+make clean
+
+# DEBUG: show python3 and python3-config outputs
+python3 --version
+python3-config --includes
+
 # Build boost
 cd ./boost
 ## Delete the artefacts from previous builds (if any)

From 67f17a1c97a097eb59d8a7d1b81fc5aff66f0da8 Mon Sep 17 00:00:00 2001
From: Mohamed Gaber <donn@efabless.com>
Date: Sun, 29 Sep 2024 12:28:18 +0300
Subject: [PATCH 13/30] wheels: symlink python3-config

---
 .github/workflows/wheels.yml                  | 2 +-
 .github/workflows/wheels/cibw_before_build.sh | 4 ++++
 2 files changed, 5 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/wheels.yml b/.github/workflows/wheels.yml
index c6af2c8b2..eafaa957f 100644
--- a/.github/workflows/wheels.yml
+++ b/.github/workflows/wheels.yml
@@ -83,7 +83,7 @@ jobs:
         with:
           python-version: 3.8
       - name: Build wheels
-        uses: pypa/cibuildwheel@v2.20.0
+        uses: pypa/cibuildwheel@v2.21.1
         env:
           CIBW_SKIP: pp* # The Makefile requires python3-config which is not in pypy
           CIBW_ARCHS: ${{ matrix.os.archs }}
diff --git a/.github/workflows/wheels/cibw_before_build.sh b/.github/workflows/wheels/cibw_before_build.sh
index 29fffe090..018b0e0df 100644
--- a/.github/workflows/wheels/cibw_before_build.sh
+++ b/.github/workflows/wheels/cibw_before_build.sh
@@ -5,6 +5,10 @@ set -x
 make clean
 
 # DEBUG: show python3 and python3-config outputs
+if [ "$(uname)" != "Linux" ]; then
+    # https://github.com/pypa/cibuildwheel/issues/2021
+    ln -s $(dirname $(readlink -f $(which python3)))/python3-config $(dirname $(which python3))/python3-config
+fi
 python3 --version
 python3-config --includes
 

From 08c23b7632a744c1bf3a42f035611757cb64a1ea Mon Sep 17 00:00:00 2001
From: Mohamed Gaber <donn@efabless.com>
Date: Sun, 29 Sep 2024 16:02:37 +0300
Subject: [PATCH 14/30] wheels: skip musllinux for now

---
 .github/workflows/wheels.yml                | 8 ++++++--
 .github/workflows/wheels/cibw_before_all.sh | 2 +-
 2 files changed, 7 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/wheels.yml b/.github/workflows/wheels.yml
index eafaa957f..a91c873fb 100644
--- a/.github/workflows/wheels.yml
+++ b/.github/workflows/wheels.yml
@@ -85,7 +85,11 @@ jobs:
       - name: Build wheels
         uses: pypa/cibuildwheel@v2.21.1
         env:
-          CIBW_SKIP: pp* # The Makefile requires python3-config which is not in pypy
+          # * APIs not supported by PyPy
+          # * Musllinux temporarily disabled because it takes too much time
+          CIBW_SKIP: >
+            pp*
+            *musllinux*
           CIBW_ARCHS: ${{ matrix.os.archs }}
           CIBW_BUILD_VERBOSITY: "1"
           # manylinux2014 (default) does not have a modern enough C++ compiler for Yosys
@@ -107,4 +111,4 @@ jobs:
           CIBW_TEST_COMMAND: python3 -c "from pyosys import libyosys as ys;d=ys.Design();ys.run_pass('help', d)"
       - uses: actions/upload-artifact@v3
         with:
-          path: ./dist/*.whl
+          path: ./wheelhouse/*.whl
diff --git a/.github/workflows/wheels/cibw_before_all.sh b/.github/workflows/wheels/cibw_before_all.sh
index 28aae85ac..fbb8dcad8 100644
--- a/.github/workflows/wheels/cibw_before_all.sh
+++ b/.github/workflows/wheels/cibw_before_all.sh
@@ -18,6 +18,6 @@ cd ffi
 ## Ultimate libyosys.so will be shared, so we need fPIC for the static libraries
 CFLAGS=-fPIC CXXFLAGS=-fPIC ./configure --prefix=$PWD/pfx
 ## Without this, SHELL has a space in its path which breaks the makefile
-make install -j$(getconf _NPROCESSORS_ONLN 2>/dev/null || sysctl -n hw.ncpu) SHELL=bash
+make install -j$(getconf _NPROCESSORS_ONLN 2>/dev/null || sysctl -n hw.ncpu)
 ## Forces static library to be used in all situations
 sed -i.bak 's@-L${toolexeclibdir} -lffi@${toolexeclibdir}/libffi.a@' ./pfx/lib/pkgconfig/libffi.pc

From 0bb1f899e84f97b53a765581a5e91450a8074215 Mon Sep 17 00:00:00 2001
From: Mohamed Gaber <donn@efabless.com>
Date: Fri, 4 Oct 2024 16:14:26 +0300
Subject: [PATCH 15/30] wheels: convert versions to match pypa spec, add
 uploading

* wheel versions now replace `+` with `.post` to match spec at https://packaging.python.org/en/latest/specifications/version-specifiers/
* CI updates:
  * Bump action versions
  * Disabled Windows for now and documented why
  * Added a new job to upload all wheels
  * Added new variable, `PYPI_INDEX`: fallback 'https://pypi.org/' if unset
  * Added new secret, `PYPI_TOKEN`
* .editorconfig now uses 2 spaces for YML (it kept setting mine to tabs
  and GitHub Actions doesn't like that)
---
 .editorconfig                |  4 +++
 .github/workflows/wheels.yml | 49 +++++++++++++++++++++++++-----------
 setup.py                     |  2 +-
 3 files changed, 40 insertions(+), 15 deletions(-)

diff --git a/.editorconfig b/.editorconfig
index f5444d81a..572b73bd2 100644
--- a/.editorconfig
+++ b/.editorconfig
@@ -10,3 +10,7 @@ insert_final_newline = true
 indent_style = space
 indent_size = 2
 trim_trailing_whitespace = false
+
+[*.yml]
+indent_style = space
+indent_size = 2
diff --git a/.github/workflows/wheels.yml b/.github/workflows/wheels.yml
index a91c873fb..c6132685b 100644
--- a/.github/workflows/wheels.yml
+++ b/.github/workflows/wheels.yml
@@ -1,8 +1,7 @@
 name: Build Wheels for PyPI
 on:
   workflow_dispatch:
-  push:
-    # tags: ["yosys-*"]
+
 jobs:
   build_wheels:
     strategy:
@@ -37,24 +36,27 @@ jobs:
               runner: "macos-14",
               archs: "arm64",
             },
-            {
-              name: "Windows Server 2019",
-              family: "windows",
-              runner: "windows-2019",
-              archs: "AMD64",
-            },
+            ## Windows is disabled because of an issue with compiling FFI as
+            ## under MinGW in the GitHub Actions environment (SHELL variable has
+            ## whitespace.)
+            # {
+            #   name: "Windows Server 2019",
+            #   family: "windows",
+            #   runner: "windows-2019",
+            #   archs: "AMD64",
+            # },
           ]
     name: Build Wheels | ${{ matrix.os.name }} | ${{ matrix.os.archs }}
     runs-on: ${{ matrix.os.runner }}
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           fetch-depth: 0
           submodules: true
       - if: ${{ matrix.os.family == 'linux' }}
         name: "[Linux] Set up QEMU"
-        uses: docker/setup-qemu-action@v2
-      - uses: actions/setup-python@v3
+        uses: docker/setup-qemu-action@v3
+      - uses: actions/setup-python@v5
       - name: Get Boost Source
         shell: bash
         run: |
@@ -73,7 +75,7 @@ jobs:
           brew install flex bison
           echo "PATH=$(brew --prefix flex)/bin:$PATH" >> $GITHUB_ENV
           echo "PATH=$(brew --prefix bison)/bin:$PATH" >> $GITHUB_ENV
-      - if : ${{ matrix.os.family == 'windows' }}
+      - if: ${{ matrix.os.family == 'windows' }}
         name: "[Windows] Flex/Bison"
         run: |
           choco install winflexbison3
@@ -86,7 +88,7 @@ jobs:
         uses: pypa/cibuildwheel@v2.21.1
         env:
           # * APIs not supported by PyPy
-          # * Musllinux temporarily disabled because it takes too much time
+          # * Musllinux disabled because it increases build time from 48m to ~3h
           CIBW_SKIP: >
             pp*
             *musllinux*
@@ -109,6 +111,25 @@ jobs:
             makeFlags='BOOST_PYTHON_LIB=./boost/pfx/lib/libboost_python*.a CONFIG=clang'
           CIBW_BEFORE_BUILD: bash ./.github/workflows/wheels/cibw_before_build.sh
           CIBW_TEST_COMMAND: python3 -c "from pyosys import libyosys as ys;d=ys.Design();ys.run_pass('help', d)"
-      - uses: actions/upload-artifact@v3
+      - uses: actions/upload-artifact@v4
         with:
+          name: python-wheels
           path: ./wheelhouse/*.whl
+  upload_wheels:
+    name: Upload Wheels
+    runs-on: ubuntu-latest
+    needs: build_wheels
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-wheels
+          path: "."
+      - run: |
+          ls
+          mkdir -p ./dist
+          mv *.whl ./dist
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_TOKEN }}
+          repository-url: ${{ vars.PYPI_INDEX || 'https://upload.pypi.org/legacy/' }}
diff --git a/setup.py b/setup.py
index 02e6e5843..f9d455f0b 100644
--- a/setup.py
+++ b/setup.py
@@ -25,7 +25,7 @@ yosys_version_rx = re.compile(r"YOSYS_VER\s*:=\s*([\w\-\+\.]+)")
 
 version = yosys_version_rx.search(
     open(os.path.join(__dir__, "Makefile"), encoding="utf8").read()
-)[1]
+)[1].replace("+", ".post")
 
 
 class libyosys_so_ext(Extension):

From 43128f628311e7dd69fc5aab802b9a0242efef87 Mon Sep 17 00:00:00 2001
From: Mohamed Gaber <donn@efabless.com>
Date: Mon, 7 Oct 2024 16:51:17 +0300
Subject: [PATCH 16/30] wheels: move from postreleases to minor versions,
 remove authors

---
 setup.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/setup.py b/setup.py
index f9d455f0b..221965971 100644
--- a/setup.py
+++ b/setup.py
@@ -25,7 +25,9 @@ yosys_version_rx = re.compile(r"YOSYS_VER\s*:=\s*([\w\-\+\.]+)")
 
 version = yosys_version_rx.search(
     open(os.path.join(__dir__, "Makefile"), encoding="utf8").read()
-)[1].replace("+", ".post")
+)[1].replace(
+    "+", "."
+)  # Convert to patch version
 
 
 class libyosys_so_ext(Extension):
@@ -78,8 +80,6 @@ setup(
     description="Python access to libyosys",
     long_description=open(os.path.join(__dir__, "README.md")).read(),
     long_description_content_type="text/markdown",
-    author="Claire Xenia Wolf",
-    author_email="claire@yosyshq.com",
     install_requires=["wheel", "setuptools"],
     classifiers=[
         "License :: OSI Approved :: MIT License",

From d7cf0238fda76e6a7f565dc4b521828e164c00f6 Mon Sep 17 00:00:00 2001
From: Mohamed Gaber <donn@efabless.com>
Date: Mon, 7 Oct 2024 20:17:05 +0300
Subject: [PATCH 17/30] wheels: properly migrate to artifact@v4

---
 .github/workflows/wheels.yml | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/wheels.yml b/.github/workflows/wheels.yml
index c6132685b..d59f8e1ec 100644
--- a/.github/workflows/wheels.yml
+++ b/.github/workflows/wheels.yml
@@ -113,7 +113,7 @@ jobs:
           CIBW_TEST_COMMAND: python3 -c "from pyosys import libyosys as ys;d=ys.Design();ys.run_pass('help', d)"
       - uses: actions/upload-artifact@v4
         with:
-          name: python-wheels
+          name: python-wheels-${{ matrix.os.runner }}
           path: ./wheelhouse/*.whl
   upload_wheels:
     name: Upload Wheels
@@ -122,8 +122,9 @@ jobs:
     steps:
       - uses: actions/download-artifact@v4
         with:
-          name: python-wheels
           path: "."
+          pattern: python-wheels-*
+          merge-multiple: true
       - run: |
           ls
           mkdir -p ./dist

From b15103625b4161f41c9c468c1e71c58df24f4884 Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Tue, 8 Oct 2024 07:49:14 +1300
Subject: [PATCH 18/30] ci: Switch test build docs to our runner

---
 .github/workflows/prepare-docs.yml | 5 +++++
 .github/workflows/test-build.yml   | 5 -----
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/prepare-docs.yml b/.github/workflows/prepare-docs.yml
index e2689d4df..6d3f4ecea 100644
--- a/.github/workflows/prepare-docs.yml
+++ b/.github/workflows/prepare-docs.yml
@@ -64,6 +64,11 @@ jobs:
             docs/source/_images
             docs/source/code_examples
 
+      - name: Test build docs
+        shell: bash
+        run: |
+          make docs -j${{ env.procs }} TARGETS= EXTRA_TARGETS=
+
       - name: Trigger RTDs build
         if: ${{ needs.check_docs_rebuild.outputs.docs_export == 'true' }}
         uses: dfm/rtds-action@v1.1.0
diff --git a/.github/workflows/test-build.yml b/.github/workflows/test-build.yml
index 1502d8aa0..e5aed6af3 100644
--- a/.github/workflows/test-build.yml
+++ b/.github/workflows/test-build.yml
@@ -189,8 +189,3 @@ jobs:
         shell: bash
         run: |
           make -C docs test -j${{ env.procs }}
-
-      - name: Test build docs
-        shell: bash
-        run: |
-          make docs -j${{ env.procs }} TARGETS= EXTRA_TARGETS=

From c1604424aad3116c435bfb08c12f92447e140f6b Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Tue, 8 Oct 2024 08:11:35 +1300
Subject: [PATCH 19/30] ci: Call make html directly

Since `docs/prep` is a prerequisite of `docs`, and should be the *only* prerequisite, calling `make docs` could end up hiding a problem with files missing from the uploaded artifact. Instead, call `make` from the docs directory which should be closer to what will run on RTDs.
---
 .github/workflows/prepare-docs.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/prepare-docs.yml b/.github/workflows/prepare-docs.yml
index 6d3f4ecea..e0388c7a3 100644
--- a/.github/workflows/prepare-docs.yml
+++ b/.github/workflows/prepare-docs.yml
@@ -67,7 +67,7 @@ jobs:
       - name: Test build docs
         shell: bash
         run: |
-          make docs -j${{ env.procs }} TARGETS= EXTRA_TARGETS=
+          make -C docs html -j${{ env.procs }} TARGETS= EXTRA_TARGETS=
 
       - name: Trigger RTDs build
         if: ${{ needs.check_docs_rebuild.outputs.docs_export == 'true' }}

From 1e3973c5cb009944ed65eb6117d548fc17c78639 Mon Sep 17 00:00:00 2001
From: Mike Inouye <mikeinouye@google.com>
Date: Mon, 7 Oct 2024 21:57:30 +0000
Subject: [PATCH 20/30] Explictly #include <variant> for std::variant usage.

Signed-off-by: Mike Inouye <mikeinouye@google.com>
---
 kernel/hashlib.h | 1 +
 1 file changed, 1 insertion(+)

diff --git a/kernel/hashlib.h b/kernel/hashlib.h
index 157ccf4ce..859115829 100644
--- a/kernel/hashlib.h
+++ b/kernel/hashlib.h
@@ -15,6 +15,7 @@
 #include <stdexcept>
 #include <algorithm>
 #include <string>
+#include <variant>
 #include <vector>
 
 #include <stdint.h>

From 408597b478f884681254f07a25c14f9485a7b5e6 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Tue, 8 Oct 2024 00:20:07 +0000
Subject: [PATCH 21/30] Bump version

---
 Makefile | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Makefile b/Makefile
index 5b6fc3ff2..92274a56d 100644
--- a/Makefile
+++ b/Makefile
@@ -154,7 +154,7 @@ ifeq ($(OS), Haiku)
 CXXFLAGS += -D_DEFAULT_SOURCE
 endif
 
-YOSYS_VER := 0.45+153
+YOSYS_VER := 0.45+217
 
 # Note: We arrange for .gitcommit to contain the (short) commit hash in
 # tarballs generated with git-archive(1) using .gitattributes. The git repo

From f079772ade52cedb30f056fa5819cd9df92d8356 Mon Sep 17 00:00:00 2001
From: Miodrag Milanovic <mmicko@gmail.com>
Date: Tue, 8 Oct 2024 08:47:51 +0200
Subject: [PATCH 22/30] Add TODO for missing help messages

---
 backends/functional/cxx.cc          | 2 ++
 backends/functional/test_generic.cc | 2 ++
 passes/cmds/example_dt.cc           | 2 ++
 3 files changed, 6 insertions(+)

diff --git a/backends/functional/cxx.cc b/backends/functional/cxx.cc
index b8b25df8b..1f677120a 100644
--- a/backends/functional/cxx.cc
+++ b/backends/functional/cxx.cc
@@ -246,6 +246,8 @@ struct FunctionalCxxBackend : public Backend
 	{
 		//   |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|
 		log("\n");
+		log("TODO: add help message\n");
+		log("\n");
     }
 
 	void printCxx(std::ostream &stream, std::string, Module *module)
diff --git a/backends/functional/test_generic.cc b/backends/functional/test_generic.cc
index 10a7a50f0..dc235d79a 100644
--- a/backends/functional/test_generic.cc
+++ b/backends/functional/test_generic.cc
@@ -122,6 +122,8 @@ struct FunctionalTestGeneric : public Pass
 	{
 		//   |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|
 		log("\n");
+		log("TODO: add help message\n");
+		log("\n");
     }
 
 	void execute(std::vector<std::string> args, RTLIL::Design *design) override
diff --git a/passes/cmds/example_dt.cc b/passes/cmds/example_dt.cc
index aaf07dadd..1912d7da1 100644
--- a/passes/cmds/example_dt.cc
+++ b/passes/cmds/example_dt.cc
@@ -27,6 +27,8 @@ struct ExampleDtPass : public Pass
 	{
 		//   |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|
 		log("\n");
+		log("TODO: add help message\n");
+		log("\n");
     }
 
 

From b4fd8e7ed837a86ee205cdf8766387239880743a Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Wed, 9 Oct 2024 00:20:28 +0000
Subject: [PATCH 23/30] Bump version

---
 Makefile | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Makefile b/Makefile
index f4276b94d..4985bbade 100644
--- a/Makefile
+++ b/Makefile
@@ -154,7 +154,7 @@ ifeq ($(OS), Haiku)
 CXXFLAGS += -D_DEFAULT_SOURCE
 endif
 
-YOSYS_VER := 0.45+217
+YOSYS_VER := 0.45+240
 
 # Note: We arrange for .gitcommit to contain the (short) commit hash in
 # tarballs generated with git-archive(1) using .gitattributes. The git repo

From e97731b9dda91fa5fa53ed87df7c34163ba59a41 Mon Sep 17 00:00:00 2001
From: Miodrag Milanovic <mmicko@gmail.com>
Date: Wed, 9 Oct 2024 08:08:00 +0200
Subject: [PATCH 24/30] Release version 0.46

---
 CHANGELOG           | 22 +++++++++++++++++++++-
 Makefile            |  4 ++--
 docs/source/conf.py |  2 +-
 3 files changed, 24 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG b/CHANGELOG
index 03bf5ac57..ab7690b4b 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -2,8 +2,28 @@
 List of major changes and improvements between releases
 =======================================================
 
-Yosys 0.45 .. Yosys 0.46-dev
+Yosys 0.45 .. Yosys 0.46
 --------------------------
+ * Various
+    - Added new "functional backend" infrastructure with three example
+      backends (C++, SMTLIB and Rosette).
+    - Added new coarse-grain buffer cell type "$buf" to RTLIL.
+    - Added "-y" command line option to execute a Python script with 
+      libyosys available as a built-in module.
+    - Added support for casting to type in Verilog frontend.
+
+ * New commands and options
+    - Added "clockgate" pass for automatic clock gating cell insertion.
+    - Added "bufnorm" experimental pass to convert design into
+      buffered-normalized form.
+    - Added experimental "aiger2" and "xaiger2" backends, and an 
+      experimental "abc_new" command
+    - Added "-force-detailed-loop-check" option to "check" pass.
+    - Added "-unit_delay" option to "read_liberty" pass.
+
+ * Verific support
+    - Added left and right bound properties to wires when using
+      specific VHDL types.
 
 Yosys 0.44 .. Yosys 0.45
 --------------------------
diff --git a/Makefile b/Makefile
index 4985bbade..fe07074eb 100644
--- a/Makefile
+++ b/Makefile
@@ -154,7 +154,7 @@ ifeq ($(OS), Haiku)
 CXXFLAGS += -D_DEFAULT_SOURCE
 endif
 
-YOSYS_VER := 0.45+240
+YOSYS_VER := 0.46
 
 # Note: We arrange for .gitcommit to contain the (short) commit hash in
 # tarballs generated with git-archive(1) using .gitattributes. The git repo
@@ -170,7 +170,7 @@ endif
 OBJS = kernel/version_$(GIT_REV).o
 
 bumpversion:
-	sed -i "/^YOSYS_VER := / s/+[0-9][0-9]*$$/+`git log --oneline 9ed031d.. | wc -l`/;" Makefile
+#	sed -i "/^YOSYS_VER := / s/+[0-9][0-9]*$$/+`git log --oneline 9ed031d.. | wc -l`/;" Makefile
 
 ABCMKARGS = CC="$(CXX)" CXX="$(CXX)" ABC_USE_LIBSTDCXX=1 ABC_USE_NAMESPACE=abc VERBOSE=$(Q)
 
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 4371b79f1..8e30fcc7c 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -5,7 +5,7 @@ import os
 project = 'YosysHQ Yosys'
 author = 'YosysHQ GmbH'
 copyright ='2024 YosysHQ GmbH'
-yosys_ver = "0.45"
+yosys_ver = "0.46"
 
 # select HTML theme
 html_theme = 'furo'

From 8893dadc4b6be686f84870292f3182290325f7ad Mon Sep 17 00:00:00 2001
From: Miodrag Milanovic <mmicko@gmail.com>
Date: Wed, 9 Oct 2024 08:12:44 +0200
Subject: [PATCH 25/30] Next dev cycle

---
 CHANGELOG | 3 +++
 Makefile  | 4 ++--
 2 files changed, 5 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG b/CHANGELOG
index ab7690b4b..4106885fa 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -2,6 +2,9 @@
 List of major changes and improvements between releases
 =======================================================
 
+Yosys 0.46 .. Yosys 0.47-dev
+--------------------------
+
 Yosys 0.45 .. Yosys 0.46
 --------------------------
  * Various
diff --git a/Makefile b/Makefile
index fe07074eb..f81e1fea2 100644
--- a/Makefile
+++ b/Makefile
@@ -154,7 +154,7 @@ ifeq ($(OS), Haiku)
 CXXFLAGS += -D_DEFAULT_SOURCE
 endif
 
-YOSYS_VER := 0.46
+YOSYS_VER := 0.46+0
 
 # Note: We arrange for .gitcommit to contain the (short) commit hash in
 # tarballs generated with git-archive(1) using .gitattributes. The git repo
@@ -170,7 +170,7 @@ endif
 OBJS = kernel/version_$(GIT_REV).o
 
 bumpversion:
-#	sed -i "/^YOSYS_VER := / s/+[0-9][0-9]*$$/+`git log --oneline 9ed031d.. | wc -l`/;" Makefile
+	sed -i "/^YOSYS_VER := / s/+[0-9][0-9]*$$/+`git log --oneline e97731b.. | wc -l`/;" Makefile
 
 ABCMKARGS = CC="$(CXX)" CXX="$(CXX)" ABC_USE_LIBSTDCXX=1 ABC_USE_NAMESPACE=abc VERBOSE=$(Q)
 

From c93c7f8307f1d8ec81b71aabe9c761280752338d Mon Sep 17 00:00:00 2001
From: Miodrag Milanovic <mmicko@gmail.com>
Date: Wed, 9 Oct 2024 09:50:36 +0200
Subject: [PATCH 26/30] CI: lld is now separate brew package

---
 .github/actions/setup-build-env/action.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/actions/setup-build-env/action.yml b/.github/actions/setup-build-env/action.yml
index c5a0d14ab..12ae883bd 100644
--- a/.github/actions/setup-build-env/action.yml
+++ b/.github/actions/setup-build-env/action.yml
@@ -14,7 +14,7 @@ runs:
       if: runner.os == 'macOS'
       shell: bash
       run: |
-        HOMEBREW_NO_INSTALLED_DEPENDENTS_CHECK=1 brew install bison flex gawk libffi pkg-config bash autoconf llvm
+        HOMEBREW_NO_INSTALLED_DEPENDENTS_CHECK=1 brew install bison flex gawk libffi pkg-config bash autoconf llvm lld
 
     - name: Linux runtime environment
       if: runner.os == 'Linux'

From 3d6b8b8e1a350ae1ec688d41b8d8eae0109e5119 Mon Sep 17 00:00:00 2001
From: Mohamed Gaber <donn@efabless.com>
Date: Wed, 9 Oct 2024 12:44:52 +0300
Subject: [PATCH 27/30] wheels: fix missing yosys-abc/share directory

* `misc/__init__.py`:
  * checks if there's a `yosys-abc` in the same directory - if yes, sets the variable `sys._pyosys_abc`
  * checks if there's a `share` in the same directory - if yes, sets the variable `sys._pyosys_share_dirname`
* `yosys.cc::init_share_dirname`: check for `sys._pyosys_share_dirname`, use it at the highest priority if Python is enabled
* `yosys.cc::init_abc_executable_name`: check for `sys._pyosys_abc`, use it at at the highest priority if Python is enabled
* `Makefile`: add new target, `share`, to only create the extra targets
* `setup.py`: compile libyosys.so, yosys-abc and share, and copy them all as part of the pyosys build
* `test/arch/ecp5/add_sub.py`: ported `add_sub.ys` to Python to act as a test for the share directory and abc with Python wheels, used in CI
---
 .github/workflows/wheels.yml |  2 +-
 Makefile                     |  6 +++++
 kernel/yosys.cc              | 52 ++++++++++++++++++++++++------------
 misc/__init__.py             | 14 ++++++++++
 setup.py                     | 34 +++++++++++++++++++----
 tests/arch/ecp5/add_sub.py   | 20 ++++++++++++++
 6 files changed, 105 insertions(+), 23 deletions(-)
 create mode 100644 tests/arch/ecp5/add_sub.py

diff --git a/.github/workflows/wheels.yml b/.github/workflows/wheels.yml
index d59f8e1ec..d66239a16 100644
--- a/.github/workflows/wheels.yml
+++ b/.github/workflows/wheels.yml
@@ -110,7 +110,7 @@ jobs:
             MACOSX_DEPLOYMENT_TARGET=11
             makeFlags='BOOST_PYTHON_LIB=./boost/pfx/lib/libboost_python*.a CONFIG=clang'
           CIBW_BEFORE_BUILD: bash ./.github/workflows/wheels/cibw_before_build.sh
-          CIBW_TEST_COMMAND: python3 -c "from pyosys import libyosys as ys;d=ys.Design();ys.run_pass('help', d)"
+          CIBW_TEST_COMMAND: python3 {project}/tests/arch/ecp5/add_sub.py
       - uses: actions/upload-artifact@v4
         with:
           name: python-wheels-${{ matrix.os.runner }}
diff --git a/Makefile b/Makefile
index f81e1fea2..0be664b9a 100644
--- a/Makefile
+++ b/Makefile
@@ -737,6 +737,12 @@ compile-only: $(OBJS) $(GENFILES) $(EXTRA_TARGETS)
 	@echo "  Compile successful."
 	@echo ""
 
+.PHONY: share
+share: $(EXTRA_TARGETS)
+	@echo ""
+	@echo "  Share directory created."
+	@echo ""
+
 $(PROGRAM_PREFIX)yosys$(EXE): $(OBJS)
 	$(P) $(CXX) -o $(PROGRAM_PREFIX)yosys$(EXE) $(EXE_LINKFLAGS) $(LINKFLAGS) $(OBJS) $(LIBS) $(LIBS_VERIFIC)
 
diff --git a/kernel/yosys.cc b/kernel/yosys.cc
index 510151479..374b07d06 100644
--- a/kernel/yosys.cc
+++ b/kernel/yosys.cc
@@ -554,17 +554,17 @@ void yosys_setup()
 #include "kernel/constids.inc"
 #undef X
 
-	#ifdef WITH_PYTHON
-		// With Python 3.12, calling PyImport_AppendInittab on an already
-		// initialized platform fails (such as when libyosys is imported
-		// from a Python interpreter)
-		if (!Py_IsInitialized()) {
-			PyImport_AppendInittab((char*)"libyosys", INIT_MODULE);
-			Py_Initialize();
-			PyRun_SimpleString("import sys");
-			signal(SIGINT, SIG_DFL);
-		}
-	#endif
+#ifdef WITH_PYTHON
+	// With Python 3.12, calling PyImport_AppendInittab on an already
+	// initialized platform fails (such as when libyosys is imported
+	// from a Python interpreter)
+	if (!Py_IsInitialized()) {
+		PyImport_AppendInittab((char*)"libyosys", INIT_MODULE);
+		Py_Initialize();
+		PyRun_SimpleString("import sys");
+		signal(SIGINT, SIG_DFL);
+	}
+#endif
 
 	Pass::init_register();
 	yosys_design = new RTLIL::Design;
@@ -1013,6 +1013,16 @@ void init_share_dirname()
 #else
 void init_share_dirname()
 {
+#  ifdef WITH_PYTHON
+	PyObject *sys_obj = PyImport_ImportModule("sys");
+
+	if (PyObject_HasAttrString(sys_obj, "_pyosys_share_dirname")) {
+		PyObject *share_path_obj = PyObject_GetAttrString(sys_obj, "_pyosys_share_dirname");
+		const char *share_path = PyUnicode_AsUTF8(share_path_obj);
+		yosys_share_dirname = std::string(share_path);
+		return;
+	}
+#  endif
 	std::string proc_self_path = proc_self_dirname();
 #  if defined(_WIN32) && !defined(YOSYS_WIN32_UNIX_DIR)
 	std::string proc_share_path = proc_self_path + "share\\";
@@ -1058,12 +1068,20 @@ void init_abc_executable_name()
 	}
 #else
 	yosys_abc_executable = proc_self_dirname() + proc_program_prefix()+ "yosys-abc";
-#endif
-#ifdef _WIN32
-#ifndef ABCEXTERNAL
+#  ifdef _WIN32
 	if (!check_file_exists(yosys_abc_executable + ".exe") && check_file_exists(proc_self_dirname() + "..\\" + proc_program_prefix() + "yosys-abc.exe"))
 		yosys_abc_executable = proc_self_dirname() + "..\\" + proc_program_prefix() + "yosys-abc";
-#endif
+#  endif
+
+#  ifdef WITH_PYTHON
+	PyObject *sys_obj = PyImport_ImportModule("sys");
+
+	if (PyObject_HasAttrString(sys_obj, "_pyosys_abc")) {
+		PyObject *abc_path_obj = PyObject_GetAttrString(sys_obj, "_pyosys_abc");
+		const char *abc_path = PyUnicode_AsUTF8(abc_path_obj);
+		yosys_abc_executable = std::string(abc_path);
+	}
+#  endif
 #endif
 }
 
@@ -1132,7 +1150,7 @@ bool run_frontend(std::string filename, std::string command, RTLIL::Design *desi
 
 	if (command == "auto") {
 	  std::string filename_trim = filename;
-	  
+
 	  auto has_extension = [](const std::string& filename, const std::string& extension) {
 	    if (filename.size() >= extension.size()) {
 	      return filename.compare(filename.size() - extension.size(), extension.size(), extension) == 0;
@@ -1143,7 +1161,7 @@ bool run_frontend(std::string filename, std::string command, RTLIL::Design *desi
 	  if (has_extension(filename_trim, ".gz")) {
 	    filename_trim.erase(filename_trim.size() - 3);
 	  }
-	  
+
 	  if (has_extension(filename_trim, ".v")) {
 	    command = " -vlog2k";
 	  } else if (has_extension(filename_trim, ".sv")) {
diff --git a/misc/__init__.py b/misc/__init__.py
index 330fd6d86..d74e3f5bd 100644
--- a/misc/__init__.py
+++ b/misc/__init__.py
@@ -1,5 +1,19 @@
 import os
 import sys
+
 sys.setdlopenflags(os.RTLD_NOW | os.RTLD_GLOBAL)
 
+__dir__ = os.path.abspath(os.path.dirname(__file__))
+sys._pyosys_dir = os.path.abspath(__dir__)
+
+bin_ext = ".exe" if os.name == "nt" else ""
+
+_share_candidate = os.path.join(__dir__, "share")
+if os.path.isdir(_share_candidate):
+    sys._pyosys_share_dirname = _share_candidate + os.path.sep
+
+_abc_candidate = os.path.join(__dir__, f"yosys-abc{bin_ext}")
+if os.path.isfile(_abc_candidate):
+    sys._pyosys_abc = _abc_candidate
+
 __all__ = ["libyosys"]
diff --git a/setup.py b/setup.py
index 221965971..b3a6a9280 100644
--- a/setup.py
+++ b/setup.py
@@ -44,26 +44,50 @@ class libyosys_so_ext(Extension):
             "ENABLE_PYTHON_CONFIG_EMBED=0",
             # Would need to be installed separately by the user
             "ENABLE_TCL=0",
-            # Would need to be installed separately by the user
             "ENABLE_READLINE=0",
+            "ENABLE_EDITLINE=0",
+            # Always compile and include ABC in wheel
+            "ABCEXTERNAL=",
             # Show compile commands
             "PRETTY=0",
         ]
 
     def custom_build(self, bext: build_ext):
         bext.spawn(
-            ["make", f"-j{os.cpu_count() or 1}", self.name]
+            [
+                "make",
+                f"-j{os.cpu_count() or 1}",
+                self.name,
+                "yosys-abc",
+                "share",
+            ]
             + shlex.split(os.getenv("makeFlags", ""))
             + self.args
         )
         build_path = os.path.dirname(os.path.dirname(bext.get_ext_fullpath(self.name)))
         pyosys_path = os.path.join(build_path, "pyosys")
-        target = os.path.join(pyosys_path, os.path.basename(self.name))
         os.makedirs(pyosys_path, exist_ok=True)
-        shutil.copyfile(self.name, target)
+
+        # libyosys.so
+        target = os.path.join(pyosys_path, os.path.basename(self.name))
+        shutil.copy(self.name, target)
+        bext.spawn(["strip", "-S", target])
+
+        # yosys-abc
+        yosys_abc_target = os.path.join(pyosys_path, "yosys-abc")
+        shutil.copy("yosys-abc", yosys_abc_target)
+        bext.spawn(["strip", "-S", "yosys-abc"])
+
+        # share directory
+        share_target = os.path.join(pyosys_path, "share")
+        try:
+            shutil.rmtree(share_target)
+        except FileNotFoundError:
+            pass
+
+        shutil.copytree("share", share_target)
 
         # I don't know how debug info is getting here.
-        bext.spawn(["strip", "-S", target])
 
 
 class custom_build_ext(build_ext):
diff --git a/tests/arch/ecp5/add_sub.py b/tests/arch/ecp5/add_sub.py
new file mode 100644
index 000000000..0232ac1db
--- /dev/null
+++ b/tests/arch/ecp5/add_sub.py
@@ -0,0 +1,20 @@
+import os
+from pyosys import libyosys as ys
+
+__dir__ = os.path.dirname(os.path.abspath(__file__))
+add_sub = os.path.join(__dir__, "..", "common", "add_sub.v")
+
+base = ys.Design()
+ys.run_pass(f"read_verilog {add_sub}", base)
+ys.run_pass("hierarchy -top top", base)
+ys.run_pass("proc", base)
+ys.run_pass("equiv_opt -assert -map +/ecp5/cells_sim.v synth_ecp5", base)
+
+postopt = ys.Design()
+ys.run_pass("design -load postopt", postopt)
+ys.run_pass("cd top", postopt)
+ys.run_pass("select -assert-min 25 t:LUT4", postopt)
+ys.run_pass("select -assert-max 26 t:LUT4", postopt)
+ys.run_pass("select -assert-count 10 t:PFUMX", postopt)
+ys.run_pass("select -assert-count 6 t:L6MUX21", postopt)
+ys.run_pass("select -assert-none t:LUT4 t:PFUMX t:L6MUX21 %% t:* %D", postopt)

From a6ccf2204787fb264dbd8cc23b998939ac5e41f6 Mon Sep 17 00:00:00 2001
From: Miodrag Milanovic <mmicko@gmail.com>
Date: Wed, 9 Oct 2024 14:09:10 +0200
Subject: [PATCH 28/30] force brew formula update

---
 .github/actions/setup-build-env/action.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.github/actions/setup-build-env/action.yml b/.github/actions/setup-build-env/action.yml
index 12ae883bd..0c8cd281c 100644
--- a/.github/actions/setup-build-env/action.yml
+++ b/.github/actions/setup-build-env/action.yml
@@ -14,6 +14,7 @@ runs:
       if: runner.os == 'macOS'
       shell: bash
       run: |
+        HOMEBREW_NO_INSTALLED_DEPENDENTS_CHECK=1 brew update
         HOMEBREW_NO_INSTALLED_DEPENDENTS_CHECK=1 brew install bison flex gawk libffi pkg-config bash autoconf llvm lld
 
     - name: Linux runtime environment

From a761999579c64aab33f359e1c02b02518959361b Mon Sep 17 00:00:00 2001
From: Robin Ole Heinemann <robin.ole.heinemann@gmail.com>
Date: Wed, 9 Oct 2024 14:07:37 +0200
Subject: [PATCH 29/30] cxxrtl: fix formatting of UNICHAR

This caused compilation to fail when the argument of any, not just
UNICHAR formatting operations, is bigger than 32 bits.

Fixes #4644
---
 backends/cxxrtl/runtime/cxxrtl/cxxrtl.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/backends/cxxrtl/runtime/cxxrtl/cxxrtl.h b/backends/cxxrtl/runtime/cxxrtl/cxxrtl.h
index d1d6bd8dc..9634b833b 100644
--- a/backends/cxxrtl/runtime/cxxrtl/cxxrtl.h
+++ b/backends/cxxrtl/runtime/cxxrtl/cxxrtl.h
@@ -1127,7 +1127,7 @@ struct fmt_part {
 			}
 
 			case UNICHAR: {
-				uint32_t codepoint = val.template get<uint32_t>();
+				uint32_t codepoint = val.template zcast<32>().template get<uint32_t>();
 				if (codepoint >= 0x10000)
 					buf += (char)(0xf0 |  (codepoint >> 18));
 				else if (codepoint >= 0x800)

From eef1319e70fe847b169e922d92452733c606366c Mon Sep 17 00:00:00 2001
From: Miodrag Milanovic <mmicko@gmail.com>
Date: Wed, 9 Oct 2024 18:06:58 +0200
Subject: [PATCH 30/30] Update Brewfile, since lld is now separate formula

---
 Brewfile | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Brewfile b/Brewfile
index 18e4e2917..3696e40b0 100644
--- a/Brewfile
+++ b/Brewfile
@@ -11,3 +11,4 @@ brew "xdot"
 brew "bash"
 brew "boost-python3"
 brew "llvm"
+brew "lld"