Zybo Z7 - UART over one of the PMOD ports example

[engrpetero]

Any chance someone could point me to an example of creating a UART (or UART Lite) using pins exposed by one of the PMOD ports?  I'm using a ZyboZ7-10 platform.

[Kvass]

It should be as easy as setting the Rx and Tx pins of the UARTlite IP core to output pins and assign them to the Pmod pins in your constraints file.

[JColvin]

HI @engrpetero,

Kvass is correct. Here is a post describing the process in a bit more detail (for a non-zynq board but the general process is the same):

And this post has some basic Vitis code that does external UART loopback (PC -> board -> external loopback to board -> PC) for a different Zynq based board

Thanks,
JColvin

[engrpetero]

Thanks, KVass and JColvin.  I'll take a look at the link.  Much appreciated!

[engrpetero]

Wow - either I've misunderstood, or the process is pretty easy (or perhaps neither or both! :-)).  I believe I followed the @JColvin post (and @Kvass comment) about adding the AXI UartLite IP, making the rx and tx pins external, and then editing the constraints file to put the signals represented the newly external pins on one of the PMOD headers.  See the pics below.  I haven't been able to test yet as I need do put some wiring together (my plan is to simply connect these two pins to a serial port on my pc) but two questions...

1. Can I choose any two unused pins on any PMOD header (I've obviously chosen the first two pins on JA in the pictures below)?
2. Any other obvious issues based on the simple pictures provided?

Edited February 20, 2023 by engrpetero

[engrpetero]

I should have added one more question.  I sort-of expected that once I ran synthesis, implementation, and generate bitstream to update the hardware wrapper, then when I opened my development project in Vitis and 'Update Hardware Specification', I would have been able to find some reference to the 'xuartlite' header file. 

I did some googling to learn how to use the xuartlite and search results seemed to indicate I'd be interacting with methods identified in that header file.  No such header file was found though after the hardware spec update.  Should I have expected to find such a reference in the Vitis project?

[Tim S.]

@engrpetero, after running Generate Bitstream, did you Export your Design as a Fixed Platform from Vivado to create an .XSA file, and then import that file with Update Hardware Specification (right-click on the Vitis platform project)? Also, after you update the platform in Vitis, you may need to Regenerate BSP Headers/Sources by opening the BSP project file (located under the platform's hierarchy in Vitis' workarea) and clicking that button.

[engrpetero]

I edited this post at 10:54 to include a better picture...

Funny you should ask...  The first two times yesterday I generated the bitstream, I did indeed forget to export the XSA file.  But I did finally remember (and then to 'Update Hardware Specification' again).  The BSP Headers/Sources regeneration though... I did not do that.  Haven't played with that 'section' of Vitis in a year or two so unfortunately, I've forgotten about it.  Was the suggestion to 'Reset BSP Sources' (which I just did and which the console seems to indicate happened) or am I totally in the wrong section?  The UartLite item seems to show up correctly in the BSP shown in the picture but I don't see the header file I was expecting.

Edited February 21, 2023 by engrpetero

[Tim S.]

@engrpetero, you may need to Reset Sources for both of those Board Support Package definitions show in your screenshot. Note that the FSBL isn't your bare metal project; it's Xilinx's own First Stage BootLoader that loads your Zynq PL (FPGA) bitstream and Zynq PS (processor) ARM program from flash memory. The standalone definition is your bare metal program's Xilinx/3rd-party BSP sources exported from the IP blocks in Vivado.

Also, you will to create an Application project with configuration that points to the standalone platform as the platform it is using. That Application Project is where your bare metal + standalone main() would go.

If that isn't enough for the right header file appearing, others on the forum may also have ideas...

[engrpetero]

Thanks for the additional reply @Tim S..  I should have noted that I added the UartLite to a baremetal project I was already working on and for which I had a functional Vitis program.  I left out this detail because I didn't think it important - I should have mentioned that though - my mistake.  So to recap...

1. I had a simple Digilent baremetal example project (the PMOD example from the website) working in Vivado and Vitis.
2. In Vivado, I added some HW features to the example project, re-synthesised, re-implemented, regenerated bit stream, exported XSA file.
3. In Vitis I updated the hardware spec, added some additional C code, got the expected results from the HW features I added in 2.
4. In Vivado, I added the UartLite IP to the Vivado project that started this thread, resynthesised, reimplemented, regenerated bit stream, exported XSA file.
5. In Vitis I updated the hardware spec.
6. Now I've also Reset the BPS Sources (did not Modify BSP Settings, just reset the sources) for the 'zynq_fsbl' and 'standalone_ps7...' domains in Vitis.

From my online searches, I was expecting (maybe I shouldn't be) to find a uartlite header file appropriate methods would be exposed.  However, I don't see one and searching all files in the Vitis project for the word 'lite' returns no results - which makes me think I've done something wrong.

[Tim S.]

@engrpetero, the following is the main() routine of a MicroBlaze with UART Lite that I put together in the past.

https://github.com/timothystotts/fpga-serial-acl-tester-3/blob/main/ACL-Tester-Design-MB/Vitis-Sources/ACL-Tester-Design-App/freertos_acl2_main.c

It appears that I did not include a UART Lite header, but only "xil_printf.h".

I recommend tracing the contents of your platform's xil_printf.h to a UART call; but you'll need to expect that for your platform, the #define parts of xil_printf will use the Zynq PS and not a Zynq PL peripheral, and that the sources may be entirely different.

You could also try GIT cloning that full example:

https://github.com/timothystotts/fpga-serial-acl-tester-3

and generate the Arty A7-100 MicroBlaze example, and trace the xil_printf to MicroBlaze sources, which may be the same as for your UART Lite added to Zynq PL. Such an approach would be recommended if you can't find an online example; and I'm not sure what to suggest beyond that.

[Tim S.]

@engrpetero,

I used Vivado and Vitis on Ubuntu, mostly. I noticed that xil_printf.h just references an extern.

To assist you:

$ find /opt/Xilinx/Vitis/2021.2 -name '*.[hc]' -exec grep -i -l 'XUartLite_CfgInitialize' '{}' ';'
/opt/Xilinx/Vitis/2021.2/data/embeddedsw/XilinxProcessorIPLib/drivers/uartlite_v3_6/src/xuartlite_sinit.c
/opt/Xilinx/Vitis/2021.2/data/embeddedsw/XilinxProcessorIPLib/drivers/uartlite_v3_6/src/xuartlite.c
/opt/Xilinx/Vitis/2021.2/data/embeddedsw/XilinxProcessorIPLib/drivers/uartlite_v3_6/src/xuartlite.h
/opt/Xilinx/Vitis/2021.2/data/embeddedsw/XilinxProcessorIPLib/drivers/uartlite_v3_4/src/xuartlite_sinit.c
/opt/Xilinx/Vitis/2021.2/data/embeddedsw/XilinxProcessorIPLib/drivers/uartlite_v3_4/src/xuartlite.c
/opt/Xilinx/Vitis/2021.2/data/embeddedsw/XilinxProcessorIPLib/drivers/uartlite_v3_4/src/xuartlite.h
/opt/Xilinx/Vitis/2021.2/data/embeddedsw/XilinxProcessorIPLib/drivers/uartlite_v3_5/src/xuartlite_sinit.c
/opt/Xilinx/Vitis/2021.2/data/embeddedsw/XilinxProcessorIPLib/drivers/uartlite_v3_5/src/xuartlite.c
/opt/Xilinx/Vitis/2021.2/data/embeddedsw/XilinxProcessorIPLib/drivers/uartlite_v3_5/src/xuartlite.h

There should be a "xuartlite.h" in your BSP.

[EDIT.]

Your platform might have headers located in more than one location under the folder structure. Try using File Explorer to search for xuartlite* .

Edited February 22, 2023 by Tim S.

[engrpetero]

@Tim S. - thanks for the additional posts.  I have the afternoon available to work on this project so I'll dig into your example shortly but also consider your last item - specifically looking for that header file in the directory structure.  For my example project, the UartLite is indeed a second Uart instance (the first being the Uart that uses the USB port on the Zybo Z7 - I'm leaving that intact for a separate purpose).  So the project will be receiving/transmitting over both Uart instances.

[engrpetero]

Some progress - intermediate post and question (and maybe better posted on a Xilinx forum).  I almost gave up looking for xuartlite.h in the folder structure.  Turns out I'm an idiot and was searching in the Vivado project folder structure instead of the Vitis project folder structure.  So it is there.  And I can add an include for it in my main.c file to continue playing. 

On to my intermediate question...  Is there a reference somewhere that more clearly defines the folder structure for the Vitis wrapper project and the Vitis app project?  Maybe it isn't important to know all the details since it seems much of this is auto-generated but I can't help but believe the more I understand here, the more this will make sense and the fewer questions I'll have in the future (and the more I can help others).

I do desire to use a similar method to xil_printf with this uartlite instance as the target.  Now to continue brushing up on my C skills (been writing C# code too long).

[Tim S.]

@engrpetero, that's an excellent question: Is the Vitis folder structure documented? Honestly, I would assume it is, in one of Xilinx's Vitis or methodology documents; but I actually don't know. (I worked with software and FPGA hardware, separate ICs of separate manufacturers, long enough that I found it intuitive enough to keep going. Vitis is based on Eclipse, which is the same basic tool flow for may tools now.) I learned SDK from the Digilent tutorials, and before they provided Vitis tutorials, I jumped in and found my way around by reading all information provided by the Vitis tool's Dialogs, as well as intuition from using other Eclipse-based tools. I hope you find that documentation to help you along. Cheers, Tim S.

[engrpetero]

The Xilinx documentation can be overwhelming! :-)  I'll keep looking around and learning.  And will continue to work on getting this second Uart (first instance of UartLite) working with the ZYbo in the manner mentioned in the rest of this thread and post an update when I'm successful.

For those who responded @JColvin, @Tim S., thanks again.  I know it takes time and effort to respond to these posts and it's much appreciated.

Edited February 23, 2023 by engrpetero

[artvvb]

Some more random related info:

My perspective is a bit biased, but digging around in the folder structure is extremely useful, particularly when you run across issues in drivers that you want to fix locally, or are developing your own. This is a decent overview of the different kinds of projects in the workspace, even if it doesn't get into the specifics of the folder structure: https://docs.xilinx.com/r/en-US/ug1400-vitis-embedded/Workspace-Structure-in-the-Vitis-Software-Platform

The biggest single thing is that if you want to edit driver sources, you need to find the BSP libsrc folders, rather than any of the include folders, and just opening driver headers through a control-click on the include in your application source doesn't necessarily get you there. Everything outside of libsrc is either a link or automatically overwritten whenever a build is performed, whereas the stuff in libsrc should only be overwritten when you manually trigger BSP sources to be regenerated. If you want a permanent change for all of your new projects, the drivers need to be modified in your tool installation (the embeddedsw/XilinxProcessorIPLib folders), or in IP sources (in the case of vivado-library IP).

Also if you're taking the approach of editing sources in libsrc, you need to make sure that the change is applied in all BSPs that contain it (at least if the change is fixing a build error). It can be annoying when needing to update a file across multiple BSPs and it feels like this used to show up less often with SDK, but that might just be because it was more effort to create a bootloader than it is now, with the one checkbox that Zynq requires.

The platform.spr file also contains a bunch of relevant stuff, software examples for all of the Xilinx drivers in a BSP for example.

Cheers,

Arthur

 

[engrpetero]

@artvvb- thanks for this additional information.  I didn't mean to wait so long to respond but I continue to play with Vitis and review content in some files associated with this folder structure and got distracted from responding.  The comment about editing the 'BSP libsrc folders' files directly is much appreciated.  I wish there was a way (perhaps there is) to be able to edit one of the files in one of the libsrc folders and 'apply' those changes to that similar file in the other BSP folders.  Seems unfortunate to have to edit them all to include the same functionality.

I'll continue working on this - I've gotten distracted with just using the second PS UART (normally not enabled) and routing that through the MIO pins to the JF connector to do further work on the Vitis app before getting back to...

1. implementing another UART with a UartLite IP block in the PL
2. running the second PS UART through the PL to allow connection on other Zybo connectors/pins

Edited March 1, 2023 by engrpetero

[artvvb]

Quote

I wish there was a way (perhaps there is) to be able to edit one of the files in one of the libsrc folders and 'apply' those changes to that similar file in the other BSP folders.

You could probably replace one of the files with a link to the other one or to a file outside of the workspace, though you'd still need to do it again whenever the BSP is reset.