Adjusted OPT_STANDALONE and README documents

ZipCPU · Feb 20, 2017 · 9a41a2c · 9a41a2c
1 parent 47b1026
commit 9a41a2c
Show file tree

Hide file tree

Showing 5 changed files with 60 additions and 41 deletions.
diff --git a/bench/README.md b/bench/README.md
@@ -1 +1 @@
-There are two bench testing directories, one for Verilator sources, and one for C++ simulation sources that will work with Verilator.  The Verilog sources may or may not be used with Verilator.  Indeed, they would work nicely as stand--alone top--level files that may be used to test whether or not the UART on a given board works.
+There are two bench testing directories, [one for Verilator sources](verilog), and [one for C++ simulation sources](cpp) that will work with Verilator.  The Verilog sources may or may not be used with Verilator.  Indeed, they would work nicely as stand--alone top--level files that may be used to test whether or not the UART on a given board works.
diff --git a/bench/verilog/README.md b/bench/verilog/README.md
@@ -1,14 +1,15 @@
 This directory contains three basic configurations for testing your UART
 and proving that it works:
-- helloworld: Displays the familiar "Hello, World!" message over and over.  Tests the transmit UART port.
-- linetest: Reads a line of text, then parrots it back.  Tests both receive and transmit UART.
-- speechfifo: Recites the Gettysburg address over and over again.  This can be used to test the transmit UART port, and particularly to test receivers to see if they can receive 1400+ characters at full speed without any problems.
+- [helloworld](helloworld.v): Displays the familiar "Hello, World!" message over and over.  Tests the transmit UART port.
+- [echotest](echotest.v): Echoes any characters received directly back to the transmit port.  Two versions of this exist: one that processes characters and regenerates them, and another that just connects the input port to the output port.  These are good tests to be applied if you already know your transmit UART works.  If the transmitter works, then this will help to verify that your receiver works.  It's one fault is that it tends to support single character UART tests, hence the test below.
+- [linetest](linetest.v): Reads a line of text, then parrots it back.  Tests both receive and transmit UART.
+- [speechfifo](speechfifo.v): Recites the [Gettysburg address](../cpp/speech.txt) over and over again.  This can be used to test the transmit UART port, and particularly to test receivers to see if they can receive 1400+ characters at full speed without any problems.
 
 Each of these configurations has a commented line defining OPT_STANDALONE within
-it.  If you uncomment this line, the configurations may be run as stand alone
-configurations.  (You will probably want to adjust the baud clock divider, to
-be specific to the baud rate you wish to generate as well as the clock rate
-you will be generating this from.)
+it.  This option will automatically be defined if built within Verilator, 
+allowing the Verilator simulation to set the serial port parameters.  Otherwise,
+you should be able to run these files as direct top level design files.  (You
+will probably want to adjust the baud clock divider if so, so that you can set
+to the baud rate you wish to generate as well as the clock rate you will be
+generating this from.)
 
-If you leave OPT_STANDALONE commented, these demo programs should work quite
-nicely with a Verilator based simulation.
diff --git a/bench/verilog/echotest.v b/bench/verilog/echotest.v
@@ -57,13 +57,18 @@
 `define	OPT_DUMBECHO
 //
 //
-// Uncomment the next line if you want this program to work as a standalone
-// (not verilated) RTL "program" to test your UART.  You'll also need to set
-// your setup condition properly, though.  I recommend setting it to the 
-// ratio of your onboard clock to your desired baud rate.  For more information
-// about how to set this, please see the specification.
-//
+// One issue with the design is how to set the values of the setup register.
+// (*This is a comment, not a verilator attribute ... )  Verilator needs to
+// know/set those values in order to work.  However, this design can also be
+// used as a stand-alone top level configuration file.  In this latter case,
+// the setup register needs to be set internal to the file.  Here, we use
+// OPT_STANDALONE to distinguish between the two.  If set, the file runs under
+// (* Another comment still ...) Verilator and we need to get i_setup from the
+// external environment.  If not, it must be set internally.
+//
+`ifndef	VERILATOR
 `define OPT_STANDALONE
+`endif
 //
 module	echotest(i_clk,
 `ifndef	OPT_STANDALONE
@@ -101,7 +106,7 @@ module	echotest(i_clk,
 	//
 	// This code only applies if OPT_DUMBECHO is not defined.
 `ifdef	OPT_STANDALONE
-	wire	[29:0]	i_setup;
+	wire	[30:0]	i_setup;
 	assign		i_setup = 31'd868;	// 115200 Baud, if clk @ 100MHz
 `endif
 

diff --git a/bench/verilog/helloworld.v b/bench/verilog/helloworld.v
@@ -40,33 +40,41 @@
 ////////////////////////////////////////////////////////////////////////////////
 //
 //
-// Uncomment the next line if you want this program to work as a standalone
-// (not verilated) RTL "program" to test your UART.  You'll also need to set
-// your setup condition properly, though.  I recommend setting it to the 
-// ratio of your onboard clock to your desired baud rate.  For more information
-// about how to set this, please see the specification.
-//
-//`define OPT_STANDALONE
+// One issue with the design is how to set the values of the setup register.
+// (*This is a comment, not a verilator attribute ... )  Verilator needs to
+// know/set those values in order to work.  However, this design can also be
+// used as a stand-alone top level configuration file.  In this latter case,
+// the setup register needs to be set internal to the file.  Here, we use
+// OPT_STANDALONE to distinguish between the two.  If set, the file runs under
+// (* Another comment still ...) Verilator and we need to get i_setup from the
+// external environment.  If not, it must be set internally.
+//
+`ifndef	VERILATOR
+`define OPT_STANDALONE
+`endif
 //
 module	helloworld(i_clk,
 `ifndef	OPT_STANDALONE
 			i_setup,
 `endif
 			o_uart_tx);
-	//
 	input		i_clk;
 	output	wire	o_uart_tx;
-`ifndef	OPT_STANDALONE
-	input	[30:0]	i_setup;
-`endif
 
-	// If i_setup isnt set up as an input parameter, it needs to be set.
-	// We do so here, to a setting appropriate to create a 115200 Baud
-	// comms system from a 100MHz clock.  This also sets us to an 8-bit
-	// data word, 1-stop bit, and no parity.
+	// Here we set i_setup to something appropriate to create a 115200 Baud
+	// UART system from a 100MHz clock.  This also sets us to an 8-bit data
+	// word, 1-stop bit, and no parity.  This will be overwritten by
+	// i_setup, but at least it gives us something to start with/from.
+	parameter	INITIAL_UART_SETUP = 31'd868;
+
+	// The i_setup wires are input when run under Verilator, but need to
+	// be set internally if this is going to run as a standalone top level
+	// test configuration.
 `ifdef	OPT_STANDALONE
 	wire	[30:0]	i_setup;
-	assign		i_setup = 31'd868;	// 115200 Baud, if clk @ 100MHz
+	assign	i_setup = INITIAL_UART_SETUP;
+`else
+	input	[30:0]	i_setup;
 `endif
 
 	reg	pwr_reset;

diff --git a/bench/verilog/linetest.v b/bench/verilog/linetest.v
@@ -41,13 +41,18 @@
 ////////////////////////////////////////////////////////////////////////////////
 //
 //
-// Uncomment the next line if you want this program to work as a standalone
-// (not verilated) RTL "program" to test your UART.  You'll also need to set
-// your setup condition properly, though.  I recommend setting it to the 
-// ratio of your onboard clock to your desired baud rate.  For more information
-// about how to set this, please see the specification.
-//
-// `define OPT_STANDALONE
+// One issue with the design is how to set the values of the setup register.
+// (*This is a comment, not a verilator attribute ... )  Verilator needs to
+// know/set those values in order to work.  However, this design can also be
+// used as a stand-alone top level configuration file.  In this latter case,
+// the setup register needs to be set internal to the file.  Here, we use
+// OPT_STANDALONE to distinguish between the two.  If set, the file runs under
+// (* Another comment still ...) Verilator and we need to get i_setup from the
+// external environment.  If not, it must be set internally.
+//
+`ifndef	VERILATOR
+`define OPT_STANDALONE
+`endif
 //
 module	linetest(i_clk,
 `ifndef	OPT_STANDALONE
@@ -66,7 +71,7 @@ module	linetest(i_clk,
 	// comms system from a 100MHz clock.  This also sets us to an 8-bit
 	// data word, 1-stop bit, and no parity.
 `ifdef	OPT_STANDALONE
-	wire	[29:0]	i_setup;
+	wire	[30:0]	i_setup;
 	assign		i_setup = 31'd868;	// 115200 Baud, if clk @ 100MHz
 `endif
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		There are two bench testing directories, one for Verilator sources, and one for C++ simulation sources that will work with Verilator. The Verilog sources may or may not be used with Verilator. Indeed, they would work nicely as stand--alone top--level files that may be used to test whether or not the UART on a given board works.
		There are two bench testing directories, [one for Verilator sources](verilog), and [one for C++ simulation sources](cpp) that will work with Verilator. The Verilog sources may or may not be used with Verilator. Indeed, they would work nicely as stand--alone top--level files that may be used to test whether or not the UART on a given board works.