Jump to content

A UART Based Debugger Tool


Recommended Posts

Here's a utility for debugging and testing your code in hardware and uses any IO pin to send an ASCII representation of any signal through a hardware UART interface. If you don't have a UART on you FPGA board there are TTL USB UART breakout boards and cables that allow any spare IO pin to become a UART interface.

This code is functionally the same as one recently released by Hamster but developed independently for the Fast Data Interface project. I recommend comparing the different coding styles. I decided to release this as a separate project as there are likely more people interested in this one that the other.

This project contains test bench code.




Link to comment
Share on other sites


You beat me to the punch!  ;) 

I've been slowly building a UART interface on my blog at zipcpu.com, and posting the code on github online.  I'm just now writing up the description of the build interface so that users can run it and try it in simulation--should have that posted in a couple of days, even though the Makefiles are already in the repo. 

I've still got a couple of lessons to go to describe how to place transmit and receive FIFO's into the interface, to forward the interface over a TCP/IP port, and to create a software library which can then be used to request information from various "addresses" within the design.  Indeed, I've been somewhat "surprised" at the number of lessons required to describe how to get an interface like the one I've designed up and running.

Key features I'm including are 1) the ability to fully simulate the design using open source tools with no FPGA required, 2) the ability to forward the debugging interface across a network, and 3) the ability to get information from a scope contained within the interface.  Oh, and one more ... I'm using Verilog.  :D

I expect I'll fully post my work in another week or so at the rate I'm going, as long as the trip to Grandma's house this summer doesn't get in the way.  ;)


Link to comment
Share on other sites

Funny how people around the world can be working on the same thing at the same time.

One advantage of Verilog over VHDL is its simulation features. I know people who write code for synthesis in VHDL and simulate in Verilog.

This project offers a freely available Uart to test my code. It's not perfect but usable.

Look out for wolves dressed as Gma!


Link to comment
Share on other sites


I didn't notice the first line of your post until a second look. "You beat me to the punch" matched my comment to " Sending 16-bit Values over RS-232" project that @Hamster submitted a few days ago. His came while I was busy preparing to release my UART_DEBUGGER. 

Your UART effort is unique and definitely deserves a hearty recommendation to be read by everyone regardless of expertise.

Link to comment
Share on other sites

  • zygot changed the title to A UART Based Debugger Tool
  • 1 year later...

Hi Zygot, I'm a bit of a newbie with this and am struggling a bit with your Debugger.

At the moment I'm getting some data out but its garbled.

Just wondering if you could give me a few pointers to get it running?

You define these values in the program : 

     CLK_RATE        => 100000000,
     BAUD_RATE       => 921600,  

but if I wanted to define a 50Hz input clock and a baud rate of 115,200 as I want to use RS232, so I'm using the following values :

     CLK_RATE        => 50000000
     BAUD_RATE       => 115200  

This seems to make sense but as I say  I just see garbled characters, which are consistent and repeatable so I believe the timing is off somewhere.


I've checked all of the occurrences of CLK_RATE and BAUD_RATE so I know its not that.

Also I'm a bit confused by the 'data_in' port. I get that I'll feed data in to the port eventually but is there something I can do just so send it a test byte?

Unfortunately I'm just completely stumped by the testbench I can't get that working at all unfortunately. I'll keep plugging away but its quite hard for me to follow as a newbie :(



Link to comment
Share on other sites


Thanks for posting your question.

My first suggestion is that you figure out how to use the testbench in Vivado. You can create a special Vivado project using just the UART_DEBUGGER,vhd and YASUTX.vhd source files. It doesn't matter what device you use. Just make sure to add the T_* testbench files as simulation sources after the project has been created. Both Vivado and ISE mark source files as implementation or simulation or both and it's important that VIvado knows which are which. All of this was easier in ISE. ( in a lot of ways Vivado is a really badly conceived software application ) In Vivado Simulation Settings you can select which of the testbenches you want to simulate. I strongly suggest that you get to know how to do simulation in Vivado or ISE ( simulation is actually easier in ISE ). None of the code uses a particular feature of any particular FPGA device so you could use the free version of ModelSim that comes with Quartus to run the simulations as well. If you really can't get the simulation running let's work on that first. Once you have the simulator working it will, by default, show you the toplevel (in this case the testbench) signals. You can then add any or all of the lower level code in the hierarchy to the simulation waveform viewer. Just understand that the more signal you show and the finer the time resolution the longer the simulation takes. For this code what takes time is the slow uart output.

You did read the commentary at the top of the source files, right?

You should be able to use a 50 MHz clk and get out a message at a 115200 baud rate. I've used this component often and with a few baud rates ( I haven't tested it exhaustively at lots of different baud rates ).

The idea is to send a string of hex numbers in ascii form so that you can read the value of a register in your code at a particular event or time. This particular tool isn't meant to send text, only hex numbers in ascii format. The number of hex digits displayed in the terminal should match your DATA_CHARS assignment.

Are you sure that the clock that drives the UART_DEBUGGER matches the generic CLK_RATE?

From what you depict as your output it looks as though your problem is not with baud rates ( clearly there are recognizable characters being printed ) but in using the data_write_stb and busy signals. data_write_stb should not be asserted until after busy is de-asserted (low). The busy signal indicates that the YASUTX transmitter is in the process of sending a set of characters and not ready for another set. Make sure to strobe data_write_stb for only 1 'clk' clock period. 

In your code you will decide what conditions or event starts a message. It should be obvious that any baud rate is going to be pretty slow relative to whatever is going on in your design at 50 MHz so you need to make logic to select the instant where your data is captured and sent. By the way you can capture multiple data states in successive clocks by putting a fifo between your data and the UART_DEBUGGER; that way you can feed say, 1000, snapshots of your data to the fifo and let the UART_DEBUGGER read them at its own slow uart time frame. I have an example of this lying around somewhere around here... Oh, if you look at S3_PGMR_D.vhd in the S3_PROGRAMMER_R1.zip source in the S3 Starter Board Programmer project that I've posted here in the Project Vault you can see an example of using a FIFO with UART_DEBUGGER.

You may wonder why you'd want to print out data faster than you can read it but if your use Putty as your terminal it can be set up to fork all incoming and outgoing text to a file so that you can read it later... how cool is that?

Once you get the code simulated you will quickly figure out what's going on. Hopefully, you will be encouraged to start on creating your own debugging IP. You can, with a bit of skill and practice make better and more useful debugging tools than Vivado provides.

[edit] Xilinx has a number of helpful guides to using the Vivado simulator in tutorial, reference manual or user guide formats. There's a lot of information about the devices and tools to digest but you don't have to understand everything in order to learn enough to do a specific thing. Being able to use the Documentation Navigator and material is key to success with FPGA development.


Link to comment
Share on other sites

Hi Zygot, I really wanted to thank you for taking the time to provide such a detailed answer for me, its hugely appreciated ?
I have everything working now and your tool is absolutely incredible. For years I've been relying on a bunch of LED's to try and figure out what was going on in my designs. This tool is like replacing a stick with a machine gun. Its amazing!

I was basically over thinking things and had made some changes to the TB which broke it. After your note, I removed my changes, fired up the TB which worked first time of course and then was able to build another TB which better tested my IO. The other thing that had me stumped for a while is that your TB code has another UART in it and I just couldn't figure what that was doing there until I had the preverbal 'light bulb moment' and thought how stupid I was being :)

I'm actually on ISE 14.5 but haven't touched it for a long while because I only have an old Spartan 3A Starter Kit which is several years old and the USB drivers
stopped working under Windows 10. Thanks Xilinx for abandoning us all btw !

Anyway, I finally managed to create a Windows 10 driver workaround and was therefore able to go back to one of my old projects which is the conversion of an ancient arcade machine
to FPGA - The arcade game Gorf from 1981. One major part of the puzzle was getting a circa 1970's Votrax SC01 speech synthesizer chip interfaced to the FPGA.
Previously I'd managed to do this with an Arduino by just simply building a circuit and sending it the correct sequence of bytes.

What I really wanted to do however was to use my FPGA to do the same thing. I've been building or should I say tinkering with (for years) a full board reproduction of the machine which consists of several custom chips and a Z80 CPU.
The problem was that although I could see what I thought was the right data coming from the machine by feeding it to the LED's on my board, I didn't know if this was just garbage or the Z80 sending the speech synthesizer the correct data. I ran the Debugger at both 115,200 and 9,600 baud with a 50Khz clock and although I've not yet built the circuitry to interface the FPGA to the Votrax, I was able send those bytes I captured with your UART Debugger and simply edit the data in to the correct format and paste it in to my Arduino sketch to test.
Low and behold, there was a talking Gorf arcade machine straight out of 1984, truly awesome!

Zygot - This is a really great tool. Most of the UARTS I've tried tie the input to the output of your keyboard and echo what's typed straight back to the user.
That's all well and good, but when there is no input that sync's up with the output, its quite difficult (at least for me) to just get the output part working.
I will be able to use this tool in loads of projects, I just wanted to say thank you once again ?

Link to comment
Share on other sites


Glad to hear that you got things working. I also really appreciate your background story; thanks for taking the time to share!

ISE 14.7 is the last version of ISE and I believe that you can still download it as Vivado doesn't support the older FPGA families. I still use ISE on a regular basis with WIN7. I do have a laptop with WIN10 but I don't consider WIN10 to be a real OS so I've never tried doing development on it; in fact I will never put any significant development on WIN10 as it ( or the company that makes it ) just isn't reliable enough to risk losing years ( or even a few days ) of work. I have installed Digilent tools and ported a few of my own PC FPGA applications to WIN10 so that I can use the laptop with some dedicated FPGA hardware projects that I need from time to time.

So now you know what I know. You can make very useful debugging tools that are often better than what is provided by tool vendors. Keep on Truckin'!

Link to comment
Share on other sites

  • 1 year later...


This topic is now archived and is closed to further replies.

  • Create New...