Emphasise that read_verilog doesn't lint

README.md

@@ -260,6 +260,16 @@ The command ``prep`` provides a good default word-level synthesis script, as
 used in SMT-based formal verification.
 
 
+Additional information
+======================
+
+The ``read_verilog`` command, used by default when calling ``read`` with Verilog
+source input, does not perform any syntax checking.  You should instead lint
+your source with another tool such as
+[Verilator](https://www.veripool.org/verilator/) first, e.g. by calling
+``verilator --lint-only``.
+
+
 Unsupported Verilog-2005 Features
 =================================
 

docs/source/code_examples/fifo/fifo.v

@@ -5,15 +5,15 @@ 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
 	always @(posedge clk or posedge rst)
 		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)

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
 ~~~~~~~~~~~~~~~~~~
 

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
 ----------------