feat: refactor UART implementation to support flow control and enhance functionality

- Removed UART files from clusterip and updated file lists accordingly.
- Added new UART flow control module and interface to manage RTS/CTS signals.
- Updated UART formal verification files to include new flow control signals.
- Modified UART testbench to validate flow control behavior and updated test cases.
- Adjusted top-level design to integrate new UART interface and signal connections.
- Enhanced GPIO pin mapping to accommodate new UART control signals.
- Updated linting and formal generation scripts to reflect changes in UART structure.

tests/rtl/uart_tb.sv

@@ -69,7 +69,10 @@ module uart_tb;
     end
   endtask
 
-  task automatic configure_uart(input logic [4:0] line_control, input logic [3:0] control);
+  task automatic configure_uart_flow(input logic [4:0] line_control, input logic [1:0] flow_control,
+                                     input logic [6:0] rts_assert_level,
+                                     input logic [6:0] rts_deassert_level,
+                                     input logic [3:0] control);
     begin
       write_ok(`RIBP_UART_CTRL, 0);
       repeat (4) @(posedge clk_i);
@@ -77,10 +80,18 @@ module uart_tb;
       write_ok(`RIBP_UART_BAUD_INT, 16);
       write_ok(`RIBP_UART_BAUD_FRAC, 0);
       write_ok(`RIBP_UART_LINE_CTRL, line_control);
+      write_ok(`RIBP_UART_RTS_WATERMARK, {9'd0, rts_deassert_level, 9'd0, rts_assert_level});
+      write_ok(`RIBP_UART_FLOW_CTRL, flow_control);
       write_ok(`RIBP_UART_CTRL, control);
     end
   endtask
 
+  task automatic configure_uart(input logic [4:0] line_control, input logic [3:0] control);
+    begin
+      configure_uart_flow(line_control, 2'd0, 7'd32, 7'd48, control);
+    end
+  endtask
+
   task automatic send_external_8n1(input logic [7:0] data, input logic bad_stop);
     integer bit_index;
     begin
@@ -101,23 +112,30 @@ module uart_tb;
     logic   [31:0] value;
     integer        index;
 
-    ribp.valid = 1'b0;
-    ribp.addr  = '0;
-    ribp.wdata = '0;
-    ribp.wstrb = '0;
-    uart.rx_i  = 1'b1;
+    ribp.valid   = 1'b0;
+    ribp.addr    = '0;
+    ribp.wdata   = '0;
+    ribp.wstrb   = '0;
+    uart.rx_i    = 1'b1;
+    uart.cts_n_i = 1'b1;
     repeat (4) @(posedge clk_i);
     rst_n_i = 1'b1;
     repeat (4) @(posedge clk_i);
 
+    if (uart.rts_n_o !== 1'b1) $fatal(1, "UART RTS_n was not released after reset");
     ribp_read(`RIBP_UART_IP_VERSION, 1'b0, value);
-    if (value != 32'h0002_0000) $fatal(1, "UART IP version mismatch");
+    if (value != 32'h0003_0000) $fatal(1, "UART IP version mismatch");
     ribp_read(`RIBP_UART_CAPABILITY, 1'b0, value);
-    if (value != 32'h00FF_4040) $fatal(1, "UART capability mismatch");
+    if (value != 32'h03FF_4040) $fatal(1, "UART capability mismatch");
     ribp_read(32'h0000_0002, 1'b1, value);
     ribp_read(`RIBP_UART_RXDATA, 1'b1, value);
 
-    configure_uart(5'd3, 4'b0111);
+    ribp_write(`RIBP_UART_RTS_WATERMARK, 32'h0002_0002, 4'hF, 1'b1);
+    ribp_read(`RIBP_UART_ERROR_STATUS, 1'b0, value);
+    if (!value[`UART_ERROR_CONFIG]) $fatal(1, "UART invalid RTS watermark was not reported");
+    write_ok(`RIBP_UART_ERROR_STATUS, 7'h7F);
+
+    configure_uart_flow(5'd3, 2'b01, 7'd32, 7'd48, 4'b0111);
     write_ok(`RIBP_UART_TXDATA, 8'hA5);
     repeat (220) @(posedge clk_i);
     ribp_read(`RIBP_UART_RXDATA, 1'b0, value);
@@ -135,11 +153,48 @@ module uart_tb;
       $fatal(1, "UART TX did not finish its active frame after disable: %h", value);
     end
 
-    write_ok(`RIBP_UART_INTR_ENABLE, 6'h3F);
-    write_ok(`RIBP_UART_INTR_TEST, 6'h20);
+    write_ok(`RIBP_UART_INTR_ENABLE, 7'h7F);
+    write_ok(`RIBP_UART_INTR_TEST, 7'h20);
     ribp_read(`RIBP_UART_INTR_STATUS, 1'b0, value);
     if (!value[`UART_INTR_BREAK] || !uart.irq_o) $fatal(1, "UART interrupt test failed");
-    write_ok(`RIBP_UART_INTR_STATE, 6'h3F);
+    write_ok(`RIBP_UART_INTR_STATE, 7'h7F);
+
+    configure_uart_flow(5'd3, 2'b01, 7'd32, 7'd48, 4'b0001);
+    write_ok(`RIBP_UART_INTR_ENABLE, 7'h40);
+    write_ok(`RIBP_UART_TXDATA, 8'hC3);
+    write_ok(`RIBP_UART_TXDATA, 8'h5C);
+    repeat (32) @(posedge clk_i);
+    ribp_read(`RIBP_UART_STATUS, 1'b0, value);
+    if (!value[`UART_STATUS_TX_FLOW_BLOCKED] || value[`UART_STATUS_TX_BUSY] ||
+        value[`UART_STATUS_CTS_ASSERTED]) begin
+      $fatal(1, "UART CTS did not block a new frame: %h", value);
+    end
+    ribp_read(`RIBP_UART_FIFO_LEVEL, 1'b0, value);
+    if (value[6:0] != 7'd2) $fatal(1, "UART CTS-blocked FIFO count mismatch: %h", value);
+
+    uart.cts_n_i = 1'b0;
+    repeat (32) @(posedge clk_i);
+    ribp_read(`RIBP_UART_STATUS, 1'b0, value);
+    if (!value[`UART_STATUS_CTS_ASSERTED] || !value[`UART_STATUS_TX_BUSY]) begin
+      $fatal(1, "UART did not start after CTS assertion: %h", value);
+    end
+    uart.cts_n_i = 1'b1;
+    repeat (200) @(posedge clk_i);
+    ribp_read(`RIBP_UART_STATUS, 1'b0, value);
+    if (!value[`UART_STATUS_TX_FLOW_BLOCKED] || value[`UART_STATUS_TX_BUSY]) begin
+      $fatal(1, "UART CTS did not stop at the frame boundary: %h", value);
+    end
+    ribp_read(`RIBP_UART_FIFO_LEVEL, 1'b0, value);
+    if (value[6:0] != 7'd1) $fatal(1, "UART frame-boundary FIFO count mismatch: %h", value);
+    ribp_read(`RIBP_UART_INTR_STATUS, 1'b0, value);
+    if (!value[`UART_INTR_CTS_CHANGE] || !uart.irq_o) begin
+      $fatal(1, "UART CTS change interrupt failed: %h", value);
+    end
+    write_ok(`RIBP_UART_INTR_STATE, 7'h7F);
+    uart.cts_n_i = 1'b0;
+    repeat (220) @(posedge clk_i);
+    ribp_read(`RIBP_UART_FIFO_LEVEL, 1'b0, value);
+    if (value[6:0] != 7'd0) $fatal(1, "UART did not resume after CTS assertion: %h", value);
 
     configure_uart(5'd3, 4'b0010);
     fork
@@ -150,6 +205,21 @@ module uart_tb;
       $fatal(1, "UART frame error was not retained: %h", value);
     end
 
+    configure_uart_flow(5'd3, 2'b10, 7'd1, 7'd2, 4'b0010);
+    repeat (4) @(posedge clk_i);
+    if (uart.rts_n_o !== 1'b0) $fatal(1, "UART RTS_n was not asserted for an empty RX FIFO");
+    send_external_8n1(8'h12, 1'b0);
+    if (uart.rts_n_o !== 1'b0) $fatal(1, "UART RTS_n asserted state did not hold below watermark");
+    send_external_8n1(8'h34, 1'b0);
+    if (uart.rts_n_o !== 1'b1) $fatal(1, "UART RTS_n was not released at high watermark");
+    ribp_read(`RIBP_UART_RXDATA, 1'b0, value);
+    repeat (2) @(posedge clk_i);
+    if ((value[7:0] != 8'h12) || (uart.rts_n_o !== 1'b0)) begin
+      $fatal(1, "UART RTS hysteresis did not reassert below low watermark: %h", value);
+    end
+    ribp_read(`RIBP_UART_RXDATA, 1'b0, value);
+    if (value[7:0] != 8'h34) $fatal(1, "UART RTS test RX ordering mismatch: %h", value);
+
     write_ok(`RIBP_UART_CTRL, 0);
     repeat (4) @(posedge clk_i);
     write_ok(`RIBP_UART_FIFO_CTRL, 3);
@@ -164,7 +234,7 @@ module uart_tb;
     write_ok(`RIBP_UART_DMA_CTRL, 3);
     if (!dma_tx_stall || !dma_rx_stall) $fatal(1, "Disabled UART asserted a DMA request");
 
-    $display("UART V2 register, FIFO, loopback, error, interrupt, and DMA test passed");
+    $display("UART V3 register, FIFO, loopback, flow-control, interrupt, and DMA test passed");
     $finish;
   end
 

tests/test_soc_topology.py

@@ -83,10 +83,11 @@ def test_topology_generates_complete_rib_apb_and_gpio_bindings(tmp_path: Path) -
     assert "assign u_sdio_ribp_if.valid = 1'b0;" in routes
     assert gpio.count("// GPIO") == 64
     assert "u_uart1_if" not in gpio
+    assert "assign u_uart0_if.cts_n_i = u_gpio_if.di_i[0];" in gpio
     assert "assign u_gpio_if.alt0_do_i[0] = 1'b0;" in gpio
     assert "assign u_gpio_if.alt0_oe_i[0] = 1'b0;" in gpio
-    assert "assign u_gpio_if.alt0_do_i[1] = 1'b0;" in gpio
-    assert "assign u_gpio_if.alt0_oe_i[1] = 1'b0;" in gpio
+    assert "assign u_gpio_if.alt0_do_i[1] = u_uart0_if.rts_n_o;" in gpio
+    assert "assign u_gpio_if.alt0_oe_i[1] = 1'b1;" in gpio
     assert "assign u_gpio_if.alt1_do_i[0] = u_ps2_if.ps2_clk_o;" in gpio
     assert "assign u_gpio_if.alt1_oe_i[0] = u_ps2_if.ps2_clk_oe_o;" in gpio
     assert "assign u_gpio_if.alt1_do_i[1] = u_ps2_if.ps2_dat_o;" in gpio

tests/test_uart.py

@@ -1,4 +1,4 @@
-"""UART V2 register, FIFO, framing, interrupt, and DMA request tests."""
+"""UART V3 register, FIFO, framing, flow-control, interrupt, and DMA tests."""
 
 from __future__ import annotations
 
@@ -11,7 +11,7 @@ from pathlib import Path
 ROOT = Path(__file__).resolve().parents[1]
 
 
-def test_uart_v2_register_fifo_loopback_and_errors(tmp_path: Path) -> None:
+def test_uart_v3_register_fifo_loopback_flow_control_and_errors(tmp_path: Path) -> None:
     iverilog = shutil.which("iverilog")
     vvp = shutil.which("vvp")
     if iverilog is None or vvp is None:
@@ -19,7 +19,6 @@ def test_uart_v2_register_fifo_loopback_and_errors(tmp_path: Path) -> None:
 
     common = ROOT / "rtl/managed/clusterip/common/rtl"
     serial = ROOT / "rtl/ip/ribp/serial"
-    cluster_uart = ROOT / "rtl/managed/clusterip/uart/rtl"
     source_list = tmp_path / "uart.fl"
     source_list.write_text(
         "\n".join(
@@ -27,15 +26,19 @@ def test_uart_v2_register_fifo_loopback_and_errors(tmp_path: Path) -> None:
                 "+define+SV_ASSRT_DISABLE",
                 f"+incdir+{common}",
                 f"+incdir+{common / 'interface'}",
+                f"+incdir+{common / 'cdc'}",
                 f"+incdir+{common / 'utils'}",
                 f"+incdir+{serial}",
                 str(common / "interface/ribp_if.sv"),
+                str(common / "cdc/cdc_sync.sv"),
                 str(common / "utils/register.sv"),
+                str(common / "utils/edge_det.sv"),
                 str(common / "utils/fifo.sv"),
-                str(cluster_uart / "uart_if.sv"),
+                str(serial / "uart_if.sv"),
                 str(serial / "uart_baudgen.sv"),
                 str(serial / "ribp_uart_tx.sv"),
                 str(serial / "ribp_uart_rx.sv"),
+                str(serial / "uart_flow_ctrl.sv"),
                 str(serial / "uart_core.sv"),
                 str(serial / "uart_reg.sv"),
                 str(serial / "ribp_uart.sv"),
@@ -63,4 +66,4 @@ def test_uart_v2_register_fifo_loopback_and_errors(tmp_path: Path) -> None:
         check=True,
     )
     result = subprocess.run([vvp, str(simulation)], text=True, capture_output=True, check=True)
-    assert "UART V2 register, FIFO, loopback, error, interrupt, and DMA test passed" in result.stdout
+    assert "UART V3 register, FIFO, loopback, flow-control, interrupt, and DMA test passed" in result.stdout