From b9b19a7e1590a1d1b77b37fb22efa1f086cf42c5 Mon Sep 17 00:00:00 2001
From: Liu Yonggang <liuyonggang@icubecorp.cn>
Date: Mon, 12 Dec 2022 15:23:37 +0800
Subject: [PATCH] Added tutorial

---
 tutorial/elaborate_main.py | 19 +++++++++++
 tutorial/thing.cc          | 65 ++++++++++++++++++++++++++++++++++++++
 tutorial/thing.il          | 17 ++++++++++
 tutorial/thing.v           | 20 ++++++++++++
 tutorial/thing_block.py    | 11 +++++++
 5 files changed, 132 insertions(+)
 create mode 100644 tutorial/elaborate_main.py
 create mode 100644 tutorial/thing.cc
 create mode 100644 tutorial/thing.il
 create mode 100644 tutorial/thing.v
 create mode 100644 tutorial/thing_block.py

diff --git a/tutorial/elaborate_main.py b/tutorial/elaborate_main.py
new file mode 100644
index 0000000..6aac247
--- /dev/null
+++ b/tutorial/elaborate_main.py
@@ -0,0 +1,19 @@
+from amaranth import ClockDomain, Module
+from amaranth.cli import main
+from amaranth_boards.arty_a7 import ArtyA7_100Platform
+
+from thing_block import ThingBlock
+
+# Usage: python3 elaborate_main.py generate -t [v|il|cc] > thing.[v|il|cc]
+# ArtyA7_100Platform
+
+if __name__ == "__main__":
+    sync = ClockDomain()
+
+    block = ThingBlock()
+
+    m = Module()
+    m.domains += sync
+    m.submodules += block
+
+    main(m, ports=[sync.clk, sync.rst], platform=None """ArtyA7_100Platform""")
diff --git a/tutorial/thing.cc b/tutorial/thing.cc
new file mode 100644
index 0000000..deda531
--- /dev/null
+++ b/tutorial/thing.cc
@@ -0,0 +1,65 @@
+#include <backends/cxxrtl/cxxrtl.h>
+
+#if defined(CXXRTL_INCLUDE_CAPI_IMPL) || \
+    defined(CXXRTL_INCLUDE_VCD_CAPI_IMPL)
+#include <backends/cxxrtl/cxxrtl_capi.cc>
+#endif
+
+#if defined(CXXRTL_INCLUDE_VCD_CAPI_IMPL)
+#include <backends/cxxrtl/cxxrtl_vcd_capi.cc>
+#endif
+
+using namespace cxxrtl_yosys;
+
+namespace cxxrtl_design {
+
+// \amaranth.hierarchy: top
+// \top: 1
+// \generator: Amaranth
+struct p_top : public module {
+	// \src: elaborate_main.py:9
+	/*input*/ value<1> p_rst;
+	// \src: elaborate_main.py:9
+	/*input*/ value<1> p_clk;
+	p_top() {}
+	p_top(adopt, p_top other) {}
+
+	void reset() override {
+		*this = p_top(adopt {}, std::move(*this));
+	}
+
+	bool eval() override;
+	bool commit() override;
+
+	void debug_eval();
+
+	void debug_info(debug_items &items, std::string path = "") override;
+}; // struct p_top
+
+bool p_top::eval() {
+	bool converged = true;
+	return converged;
+}
+
+bool p_top::commit() {
+	bool changed = false;
+	return changed;
+}
+
+void p_top::debug_eval() {
+}
+
+CXXRTL_EXTREMELY_COLD
+void p_top::debug_info(debug_items &items, std::string path) {
+	assert(path.empty() || path[path.size() - 1] == ' ');
+	items.add(path + "rst", debug_item(p_rst, 0, debug_item::INPUT|debug_item::UNDRIVEN));
+	items.add(path + "clk", debug_item(p_clk, 0, debug_item::INPUT|debug_item::UNDRIVEN));
+}
+
+} // namespace cxxrtl_design
+
+extern "C"
+cxxrtl_toplevel cxxrtl_design_create() {
+	return new _cxxrtl_toplevel { std::unique_ptr<cxxrtl_design::p_top>(new cxxrtl_design::p_top) };
+}
+
diff --git a/tutorial/thing.il b/tutorial/thing.il
new file mode 100644
index 0000000..4165425
--- /dev/null
+++ b/tutorial/thing.il
@@ -0,0 +1,17 @@
+attribute \generator "Amaranth"
+attribute \amaranth.hierarchy "top.U$$0"
+module \U$$0
+  wire width 1 $empty_module_filler
+end
+attribute \generator "Amaranth"
+attribute \top 1
+attribute \amaranth.hierarchy "top"
+module \top
+  attribute \src "elaborate_main.py:9"
+  wire width 1 input 0 \clk
+  attribute \src "elaborate_main.py:9"
+  wire width 1 input 1 \rst
+  cell \U$$0 \U$$0
+  end
+end
+
diff --git a/tutorial/thing.v b/tutorial/thing.v
new file mode 100644
index 0000000..14b3ba6
--- /dev/null
+++ b/tutorial/thing.v
@@ -0,0 +1,20 @@
+/* Generated by Amaranth Yosys 0.10.0 (PyPI ver 0.10.0.dev47, git sha1 dca8fb54a) */
+
+(* \amaranth.hierarchy  = "top.U$$0" *)
+(* generator = "Amaranth" *)
+module \U$$0 ();
+  wire \$empty_module_filler ;
+endmodule
+
+(* \amaranth.hierarchy  = "top" *)
+(* top =  1  *)
+(* generator = "Amaranth" *)
+module top(rst, clk);
+  (* src = "elaborate_main.py:8" *)
+  input clk;
+  (* src = "elaborate_main.py:8" *)
+  input rst;
+  \U$$0  \U$$0  (
+  );
+endmodule
+
diff --git a/tutorial/thing_block.py b/tutorial/thing_block.py
new file mode 100644
index 0000000..836d5b3
--- /dev/null
+++ b/tutorial/thing_block.py
@@ -0,0 +1,11 @@
+from amaranth import Elaboratable, Module
+from amaranth.build import Platform
+
+
+class ThingBlock(Elaboratable):
+    def __init__(self):
+        pass
+
+    def elaborate(self, platform: Platform) -> Module:
+        m = Module()
+        return m