Lots of fun UART testing code

[D@n]

Hello Digilent Community!

I just finished putting the finishing touches on a UART demonstration project that you can find here.  The project was originally intended to share a C++ class that could work with Verilator to prove that anyone's UART implementation was working.  However, after I got into it, I realized the project had a lot of value that others might appreciate.  As an example, consider this post by @martin16.  Had he used any of the testing mechanisms listed below, he might have known which side of the RS232 port he was working with was at fault.

• The core contains a complete implementation of both a transmit and receive UART encoder/decoder.  These can be easily taken from my project and placed within your own.  (Subject, of course, to the limits of the GPL v3)
• The core also contains a (fairly) generic FIFO implementation.  For those wondering how to implement a FIFO, you may find this valuable as well.
• For those who would rather interact with a serial port over a bus, such as the wishbone bus, there are two approaches within the project that can be used to hook it up to a wishbone bus.

One can be used within a larger wishbone slave module, the second as a standalone module.  Both are Wishbone B4 compliant, and both use the pipeline mode--allowing you to read/write multiple values on consecutive clocks from/to the controller.  Of course, this only really makes sense when using the FIFO.

Those might be valuable enough on their own, but you can probably find without too much additional work other implementations of the above.  Therefore this project includes some even more valuable files:

• It includes a series of test programs/configurations that can be used to determine if the hardware on your board is working properly.  If you are like me, you've struggled every time you've tried to get a serial port working on a new board.  Should you connect your output to the TX or to the RX line?  Do you have the UART set up properly, at the right baud rate?  Can you handle more than just single values at once?  How fast can you transmit/receive?  To help you answer these questions, the project file contains the following test configurations:
  • Hello World: You know, that old fashioned hello world program?  I would recommend trying this program on your board after you can blink an LED at your favorite rate, or equivalently after you know that your clock works.  This particular project is so simple that it depends upon only the clock input and the UART transmit output.

Getting this program running on your board will demonstrate that you understand your clock, and that you can modify your I/O constraint file properly, and that you know how to connect a terminal program to your board in order to observe the results.

• Line Test: Once you've got a hello world program running, so that you know the output UART pin works, then it is time to test the input UART pin.  This is the purpose of the line test testing program.  It works by reading a line of data (either until a newline or 80--characters), and then dumping that line to the output.  (Don't forget to turn off  hardware flow control, and be aware of the differences between a new line and a carriage return!)
• SpeechFifo: Finally, there's a program that can be used to test the FIFO capabilities found within the wishbone UART peripheral.  This program uses the FIFO capability to make certain the transmitter stays fully loaded for over a thousand characters of output bytes.  (No, this isn't computer speech generation, but rather a computer dumping a Abraham Lincoln's Gettysburg Address across the UART port.)

Each of these configurations has a corresponding Verilator simulation file associated with it, allowing you to simulate the functionality within them as part of Verilator.

• The project includes, like I mentioned above, a C++ class that can be used to determine if your own UART is transmitting correctly under a Verilator simuation.  This class can also be used generate UART signaling in order to test if your RTL can receive it properly.  (See the line test C++ harness discussed below for an example of this.)
• As complements to each of the testing configurations above, the project contains C++ files to drive each of those within a Verilator context.  Some unique features include:
  • The Line Test C++ test harness automatically generates a linetest.vcd file that can be used together with GTKwave to study how the core works.  Further, it can be run in either an interactive or an automated mode.
  • The Speech Test C++ test harness can be used in an automated mode, or with the -i switch in a more interactive mode.  In this latter mode, the speech test program generates a speechtrace.vcd file that can be used with GTK wave to understand how the UART transmitter, FIFO, the wishbone bus decoder, or even the test harness itself.

I hope you find these as valuable as I have.  Please feel free to post any questions or comments you might have about this project below.

Dan

[D@n]

The UART demo code has been updated to now use flow control.  Functionality has been demonstrated/proved using the PModUSBUART, with active low RTS and CTS pins.  (For an example using flow control, please see the OpenArty project, wishbone bus master file.)

Dan