Add a simple cocotb example

This commit adds an example that uses the Cocotb framework to validate
behavior of the Verilog file converted from a simple DSLX code

Internal-tag: [#46586]
Signed-off-by: Robert Winkler <rwinkler@antmicro.com>

Author: rw1nkler

xls/examples/cocotb/BUILD

@@ -0,0 +1,52 @@
+# Copyright 2023 The XLS Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+load("@rules_hdl//cocotb:cocotb.bzl", "cocotb_test")
+load("@xls_pip_deps//:requirements.bzl", "requirement")
+load("//xls/build_rules:xls_build_defs.bzl", "xls_dslx_verilog")
+
+xls_dslx_verilog(
+    name = "running_counter_verilog",
+    srcs = ["running_counter.x"],
+    deps = [],
+    codegen_args = {
+        "delay_model": "unit",
+        "clock_period_ps": "5000",
+        "reset": "rst",
+        "module_name": "RunningCounter",
+        "use_system_verilog": "false",
+        "streaming_channel_data_suffix": "_data",
+    },
+    dslx_top = "RunningCounter",
+    verilog_file = "running_counter.v",
+)
+
+cocotb_test(
+    name = "running_counter_cocotb",
+    hdl_toplevel = "RunningCounter",
+    hdl_toplevel_lang = "verilog",
+    test_module = [
+        "cocotb_running_counter.py",
+    ],
+    verilog_sources = [
+        "timescale.v",
+        "dumpvcd.v",
+        ":running_counter.v",
+    ],
+    deps = [
+        requirement("cocotb"),
+        requirement("cocotb_bus"),
+        "//xls/simulation/cocotb:cocotb_xls",
+    ],
+)

xls/examples/cocotb/cocotb_running_counter.py

@@ -0,0 +1,70 @@
+# Copyright 2023 The XLS Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import cocotb
+
+from cocotb.clock import Clock
+from cocotb.triggers import Event, ClockCycles
+from cocotb.binary import BinaryValue
+
+from cocotb_bus.scoreboard import Scoreboard
+from cocotb_xls import XLSChannelDriver, XLSChannelMonitor
+
+from typing import List, Any
+
+
+def list_to_binary_value(data: List, n_bits: int = 32, bigEndian=False) -> List[BinaryValue]:
+    return [BinaryValue(x, n_bits, bigEndian) for x in data]
+
+
+def init_sim(dut, data_to_send: List[BinaryValue], data_to_recv: List[BinaryValue]):
+    clock = Clock(dut.clk, 10, units="us")
+
+    driver = XLSChannelDriver(dut, "running_counter__base_r", dut.clk)
+    monitor = XLSChannelMonitor(dut, "running_counter__cnt_s", dut.clk)
+
+    scoreboard = Scoreboard(dut, fail_immediately=True)
+    scoreboard.add_interface(monitor, data_to_recv)
+
+    total_of_packets = len(data_to_recv)
+    terminate = Event("Last packet of data received")
+
+    def terminate_cb(transaction):
+        if monitor.stats.received_transactions == total_of_packets:
+            terminate.set()
+
+    monitor.add_callback(terminate_cb)
+    monitor.bus.rdy.setimmediatevalue(1)
+
+    return (clock, driver, terminate)
+
+
+@cocotb.coroutine
+async def reset(clk, rst, cycles=1):
+    rst.setimmediatevalue(1)
+    await ClockCycles(clk, cycles)
+    rst.value = 0
+
+
+@cocotb.test(timeout_time=10, timeout_unit="ms")
+async def counter_test(dut):
+    data_to_send = list_to_binary_value([0x100, 0x100, 0x100])
+    data_to_recv = list_to_binary_value([0x102, 0x103, 0x104])
+
+    (clock, driver, terminate) = init_sim(dut, data_to_send, data_to_recv)
+
+    cocotb.start_soon(clock.start())
+    await reset(dut.clk, dut.rst, 10)
+    await driver.write(data_to_send)
+    await terminate.wait()

xls/examples/cocotb/dumpvcd.v

@@ -0,0 +1,20 @@
+// Copyright 2023 The XLS Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+module wavedump();
+initial begin
+    $dumpfile("dump.vcd");
+    $dumpvars(0, RunningCounter);
+end
+endmodule

xls/examples/cocotb/running_counter.x

@@ -0,0 +1,67 @@
+// Copyright 2023 The XLS Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import std
+
+proc RunningCounter {
+  base_r: chan<u32> in;
+  cnt_s: chan<u32> out;
+
+  init { u32:0 }
+
+  config(base_r: chan<u32> in, cnt_s: chan<u32> out) {
+    (base_r, cnt_s)
+  }
+
+  next(tok: token, cnt: u32) {
+    let (tok, base, base_valid) = recv_non_blocking(tok, base_r, u32:0);
+    let tok = send_if(tok, cnt_s, base_valid,  cnt + base);
+    let cnt_next = cnt + u32:1;
+    cnt_next
+  }
+}
+
+#[test_proc]
+proc RunningCounterTester {
+  terminator: chan<bool> out;
+  base_s: chan<u32> out;
+  cnt_r: chan<u32> in;
+
+  init { u32:0 }
+
+  config (terminator: chan<bool> out) {
+    let (base_s, base_r) = chan<u32>;
+    let (cnt_s, cnt_r) = chan<u32>;
+
+    spawn RunningCounter(base_r, cnt_s);
+    (terminator, base_s, cnt_r)
+  }
+
+  next(tok: token, recv_cnt: u32) {
+    let next_state = if (recv_cnt < u32:10) {
+      let tok = send(tok, base_s, u32:1);
+      let (tok, cnt) = recv(tok, cnt_r);
+
+      trace_fmt!("Received {} cnt", recv_cnt);
+      assert_lt(u32:1, cnt);
+
+      recv_cnt + u32:1
+    } else {
+      send(tok, terminator, true);
+      u32:0
+    };
+
+    (next_state)
+  }
+}