From b14a651142c1aaabdd8a6536c23923bc60c5ff22 Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Tue, 5 Nov 2024 13:29:45 +1300
Subject: [PATCH] Docs: Mention verilator for linting

Link to verilator in the introduction.
Include `verilator --lint-only fifo.v` in the example synth doc.
Fix linter warnings in fifo.v.
---
 docs/source/code_examples/fifo/fifo.v         | 6 +++---
 docs/source/getting_started/example_synth.rst | 8 ++++++++
 docs/source/introduction.rst                  | 5 +++++
 3 files changed, 16 insertions(+), 3 deletions(-)

diff --git a/docs/source/code_examples/fifo/fifo.v b/docs/source/code_examples/fifo/fifo.v
index 769dfafd4..86f292406 100644
--- a/docs/source/code_examples/fifo/fifo.v
+++ b/docs/source/code_examples/fifo/fifo.v
@@ -5,7 +5,7 @@ module addr_gen
 ) ( input en, clk, rst,
 	output reg [AWIDTH-1:0] addr
 );
-	initial addr <= 0;
+	initial addr = 0;
 
 	// async reset
 	// increment address when enabled
@@ -13,7 +13,7 @@ module addr_gen
 		if (rst)
 			addr <= 0;
 		else if (en) begin
-			if (addr == MAX_DATA-1)
+			if ({'0, addr} == MAX_DATA-1)
 				addr <= 0;
 			else
 				addr <= addr + 1;
@@ -57,7 +57,7 @@ module fifo
 	);
 
 	// status signals
-	initial count <= 0;
+	initial count = 0;
 
 	always @(posedge clk or posedge rst) begin
 		if (rst)
diff --git a/docs/source/getting_started/example_synth.rst b/docs/source/getting_started/example_synth.rst
index f8530b45b..189eaddfa 100644
--- a/docs/source/getting_started/example_synth.rst
+++ b/docs/source/getting_started/example_synth.rst
@@ -30,6 +30,14 @@ First, let's quickly look at the design we'll be synthesizing:
 
 .. todo:: fifo.v description
 
+While the open source `read_verilog` frontend generally does a pretty good job
+at processing valid Verilog input, it does not provide very good error handling
+or reporting.  Using an external tool such as `verilator`_ before running Yosys
+is highly recommended. We can quickly check the Verilog syntax of our design by
+calling ``verilator --lint-only fifo.v``.
+
+.. _verilator: https://www.veripool.org/verilator/
+
 Loading the design
 ~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst
index 7261d8edb..946a54563 100644
--- a/docs/source/introduction.rst
+++ b/docs/source/introduction.rst
@@ -69,9 +69,14 @@ Things you can't do
 
   - Check out `nextpnr`_ for that
 
+- Rely on built-in syntax checking
+
+   - Use an external tool like `verilator`_ instead
+
 .. todo:: nextpnr for FPGAs, consider mentioning openlane, vpr, coriolis
 
 .. _nextpnr: https://github.com/YosysHQ/nextpnr
+.. _verilator: https://www.veripool.org/verilator/
 
 The Yosys family
 ----------------