Vivado Tcl Build Scripts

[Flux]

Hello,

I've posted a new tutorial on Project F covering Tcl build scripts with Vivado:

https://projectf.io/posts/vivado-tcl-build-script/

It's surprisingly easy to automate building your design with Tcl. I wish I'd known this when starting out with my Arty board back in 2018. Anyway, I hope you find this useful, and please do let me know if you have any suggestions or spot any errors.

Cheers,

Flux

[zygot]

Most people who visit this site use the IPI flow, because that's what the FPGA vendors want to promote, and it's for product vendors to easily to throw a simple demo together.

For simple HDL flow designs, with no vendor IP ( not even BRAM or FIFOs ) a simple tcl script is a great idea. If you have any sources that are subject to vendor tool version changes then the tcl build script can get very messy. Digilent has proven that over and over with IPI demo tcl scripts that only work with one Vivado tool version. You don't even have to have any vendor dependent sources in your design as Xilinx has a habit of rendering projects created in one tool version into a whole new project by changing the syntax of constraints, or changing the tool database structure, etc., etc. Still, even for simple projects that don't need timing closure effort, even for hobby use, avoiding the GUI can be a really good idea. Of course, for commercial development text based build scripts are the only reasonable option.

My view is that posts like this are only useful for getting people to think about things that they might not have experience with, or didn't think that they had time to explore. With that thought, great post. Someone should have started it long ago. even on an IPI, MicroBlaze oriented forum like this one.

[artvvb]

Great post! It's always shocking just how simple a straightforward tcl build script is. It's subjectively so much easier to "just get in and start designing" when you don't need to fire up multiple heavy applications just to use a text editor, or go ten levels of UI deep to change some IP setting in a wizard.

Worth noting here that the write_bd_tcl command that is often used to automatically generate scripts to recreate block designs has some optional flags that allows you to ignore the version numbers of IP being included into a project. That doesn't get around the fact that IP changing versions between Vivado versions comes with the possibility that the ports and parameters don't match up, but at least the script can try to add it.

Also with regards to the IP integrator, the following shows up in every block design TCL script, and really underscores how valuable just going in and seeing what you can make happen in text editors, without the Vivado GUI, really is.

Quote

################################################################
# This is a generated script based on design: design_1
#
# Though there are limitations about the generated script,
# the main purpose of this utility is to make learning
# IP Integrator Tcl commands easier.
################################################################

There are several similar posts that have been floating around, hwjedi and starware design's come to mind.

[Flux]

Thank you for your thoughtful comments, @zygot. I realise my post is scratching the surface of a complex and often frustrating topic. I hope it at least makes new users consider Tcl scripting.

My viewpoint may differ from the vendor norm because I rarely use IP cores (except for memory controllers). For the hobbyist projects I work on, the arrival of RISC-V has made it practical to work almost entirely in Verilog. I use primitives, MMCME2, OSERDES2 etc., but via templates in Verilog.

[zygot]

I hope that you didn't think that my thoughts were being critical. You are right that using tcl scripts to generate FPGA projects, and obtain configuration files, that work for any version of one vendors tools can be complicated and frustrating. That's why it's great that you started a thread on the subject. I don't know about you, but I'm hoping that it generates some constructive posts from a variety of people bothering to read it. Gems are usually easy to miss lying in the grass.

FPGA design flow for a published project meant to enlighten a wide range of readers or just pose a concept to think about is generally different than that for paid commercial work. For me, it's usually get an idea implemented with a reasonable amount of time and effort and publish it or never get around to the publish part. Sharing a project that only requires running a script to reproduce may be ideal.. or maybe not. I guess that it depends, depending on what your aim is.

I agree with you that an all text source HDL project is a preferred goal. It generally involves a lot more work. Sometimes, the GUI IP is informative and might make for better designs. I believe that this is the case for MMCM or PLL clocking resource instantiation. Of course you can always do a design using a clocking "wizard" and then instantiate a macro or primitive in your published design. The same argument can be made for hard multipliers or DSP blocks; perhaps more so as tool support for these has gotten worse and more constrained, in terms of feature use, over the years. Vivado doesn't even support primitive instantiation of DSP blocks officially anymore. Then there are external memory controllers. There are transceiver based interfaces like PCIe and serial communications.

Push-button bitstream creation ( running one script ) hides a lot of details that might be good to be aware of... even for the designer who might want to update an old design in a newer tool version, even when they think that they've previously covered all of the details. There are usually a lot of unseen things going one behind the scripting text that have more importance or risk then one might reasonable assume. And a really complicated set of scripts can be as hard to follow as any other project flow.

All of those thoughts are for one FPGA vendor projects. Trying to create vendor agnostic projects can drive one crazy.

One thing that I know for sure, my preference is to have all sources for a project in a text format ( not HTML ) that I can read through and run utilities that help manage text files.

I'm more comfortable designing in VHDL. I think that, for a variety of reasons, Verilog design is superior. VHDL just hasn't gotten the love, and updating, that it deserves....

Last thought for now is that Quartus will be happy to create a tcl script for your project, if you like excitement. But it will help with the boilerplate.

Edited April 30, 2023 by zygot

[Flux]

On 4/30/2023 at 8:13 PM, zygot said:

I hope that you didn't think that my thoughts were being critical. You are right that using tcl scripts to generate FPGA projects, and obtain configuration files, that work for any version of one vendors tools can be complicated and frustrating. That's why it's great that you started a thread on the subject. I don't know about you, but I'm hoping that it generates some constructive posts from a variety of people bothering to read it. Gems are usually easy to miss lying in the grass.

I didn’t take your thoughts negatively. On the contrary, I value thoughtful feedback and insight. Stars, likes, up-votes, etc. are ten a penny, but thoughtful replies like yours are rare. As you say, I hope this thread garners further constructive responses.

 

[zygot]

1 hour ago, Flux said:

Stars, likes, up-votes, etc. are ten a penny, but thoughtful replies like yours are rare.

Gee, that's refreshing to read. Perhaps I'm not wasting my time trying to help people with their problems after all...

[zygot]

Doesn't seem that there a very many people interested in joining this conversation but I've thought of something to add.

If you have any interest in partial configuration for AMD/Xilinx devices you will need to understand  DFX, the latest version of their partial configuration schema. Partial configuration is pretty important for ZYNQ developers running an embedded version of Linux or even perhaps an RTOS as it would be nice if you you could change HW functionality on the fly depending on what you want to accomplish. It's also of interest to anyone trying to develop applications that involve connecting an FPGA to a PC host via PCIe. In this case the logic that implements the PCIe functionality can't be disturbed on the fly.

So, why am I bothering to mention this?  Well, DFX appears to be complicated enough that trying to do it without tcl scripts would be a daunting challenge. I am by no means competent in using DXF at this moment. If I have a point, it is that even those of us who are convinced that becoming comfortable with script writing as a normal development flow will have to make adjustments as the tools get more complex. As new products, like the Kria are introduced, you can be sure that the development flow is going to get more complicated.

DFX is now at the top of my personal improvement list. Fortunately I have a KC705 which is one of the boards supported by the tutorial. I have a ZCU106 running Ubuntu 20 that sorely need it..

Edited June 14, 2023 by zygot