Main Page

Welcome to the main wiki page for CprE 488! See below for relevant information for the weekly labs, and the Project Page for information regarding the course project.

We hope that, as this wiki develops, you will find useful information as you work on the CprE 488 labs. Also, as you discover new tips and tricks, consider contributing as well. Editing is very straightforward - click the "log in" link in the upper right-hand corner and use your usual university ID and password. Please see the MediaWiki page for further details on how to edit.

ZedBoard Tricks and Tips

Auto-loading a design using the sdcard

When jumpers MIO 4 and MIO 5 on the ZedBoard are shorted to 3v3, the board looks for a BOOT.BIN file in the top-level directory of the sdcard. The BOOT.BIN needs to contain the following three files, in this order:

A First Stage Boot Loader (FSBL) executable that checks system configuration registers and programs the programmable logic with the appropriate bitfile.
A system.bit file created during the conventional XPS build process.
An application that will be loaded after the bitfile programming.

Xilinx provides a template for generating the FSBL project. Select "New -> Application Project" in XSDK, name the project zynq_fsbl, and choose the First Stage Bootloader as one of the project template. You should not have to change any of the files in the project, and it will automatically build.

Assuming you then have some other application you would like to load during the boot process, first select that application, then select "Xilinx Tools -> Create Boot Image". This utility should automatically find the three files needed to generate the BOOT.BIN file. Select where you'd like the output files to be generated. Once the .bin file is generated, rename it to BOOT.BIN and copy to your sdcard.

Board Jumpers

If your board is not booting an SD card, you may have an engineering sample board. Check to see if JP6 (just below the top PMOD on the left side of the board) has a jumper connect. The engineering sample boards require this jumper to boot from SD Card.

Furthermore, if you can boot to linux but your usb port doesn't appear to be working, be sure that JP2 is jumped. This provides power to the usb +5v rail.

XPS Tricks and Tips

Multiple XPS sessions. When you open up XSDK, it (very quickly, nearly invisibly) copies the SDK_Export/ from your currently-open XPS project into your system_hw_platform project. This can lead to some seriously painful bugs:

You do a normal export from your project and open up SDK, but while working on SDK you also decide to open up a previous project to see where you might have gone wrong.
You open up two XPS (or two XSDK) projects to compare approaches.

A bitfile / .elf mismatch can cause all sorts of problems, because at the very least you are going to be driving signals that correspond to unmapped memory regions which can lock the CPU. Keep it to 1 XPS + 1 XSDK session, and open up other files you want to simultaneously inspect outside the Xilinx tools.

I don't see a drop-down menu to connect ports together. When XPS runs on Windows 10, this seems to be a recurring issue. There are 2 possible solutions that might help:

Expand the XPS window to cover both monitor screens
Add the "Nets" column to the Ports tab (right-click on the headers). Then the drop-down menu will appear if you click on the Nets column.

SDK Tricks, Tips, and Common Errors

Matching a BSP to a software project. When an XPS system is exported to SDK, a Board Support Package (BSP) is created that provides drivers for the various peripherals in your design. Any new software projects will be based on this BSP, but on occasion, any existing (or newly imported) projects will still access older BSPs. This is a common cause of missing header files during compilation. To resolve this, right-click on your software project in XSDK, and select "Change Referenced BSP". Selecting the appropriate BSP will update your project to look at the right headers and libraries.

Fixing Cairo Error. On some configurations there is a problem when the JVM running XSDK tries to render graphics using Cairo causing the following error: cairo-misc.c:380: _cairo_operator_bounded_by_source: Assertion `NOT_REACHED' failed. To fix this problem we simply tell the JVM to disable rendering using Cairo by calling XSDK with the following command: xsdk -vmargs -Dorg.eclipse.swt.internal.gtk.cairoGraphics=false. The -vmargs is needed to tell Eclipse to pass the next argument to the JVM.

No Active System Dialog Box. This dialog opens occasionally in XSDK if you rebuild the program while one was already running. Unfortunately, this confuses XSDK to the point where it needs to be restarted. To fix this error do the following:

Close XSDK, turn off the Zedboard
Re-open XSDK and open the workspace with your project
Turn on the Zedboard, reprogram it with the FPGA file and your softwae
Continue the lab

To avoid this problem from happening, always stop the program running on the Zedboard before you build a new version of the software (yes, this gets annoying). There are 2 ways to stop the program:

Press the Red square on the right-side of the console's task bar
Make a switch/button able to end the main while loop and return from the main function

Fatal error: No Input Files. This error can occur on Windows when XSDK can't get to the file system path where your source files are located. The root cause of this issue is using UNC paths (aka. \\my.files.iastate.edu\users...) to store and access the project. XSDK requires that a drive letter be used to access the project instead of UNC path. To fix this error do the following:

File -> Switch Workspace -> Other
Click Browse
Expand the U: drive letter (under My PC)
Navigate to the folder the workspace was located in. There is a folder for the Desktop, Documents folder, etc. there that contains the same files as your Windows profile folder
Click Ok, the path displayed should now start with "U:\"
Click Ok, XSDK should now restart and be at the proper directory
Re-compile the code and continue working

Invalid Command Name: "ps7_init" or No Target with ID 64 in the System. This error occurs when moving an XSDK workspace from one directory to another (such as moving between people's accounts). The root cause is the program launcher cannot find a file it needs to start the processor cores, so it errors. Luckily the fix is very simple:

Click Run -> Run Configurations
Select the configuration you are using (usually project_name.elf under the Xilinx C/C++ application heading) from the list on the Left
Under the Device Initialization tab, modify the field labeled "Path to initialization TCL file" to have the new path to your workspace
Run the program, and it should now work

MP-4 Frequently Asked Questions (FAQ)

Q: I would like to record the time between GPS updates for my PID code.

A: Your PID code can assume a constant update rate of 1. This greatly simplifies the PID code.

Q: Why is the SDK compiler giving errors when I try to use math functions such as atan, pow, sqrt?

A: You need to make sure you have included <math.h>, also you need to link to the math library to your project. Here is a link that talks about this: http://www.zedboard.org/content/problems-fpu-commands-sqrt-atan. Here is the summary: 1) right click on your application project, 2) select the C/C++ Build Settings option, 3) click on the Tool Settings tab, 4)locate the ARM Linux gcc linker-->Libraries pane, 4)add the 'm' library

Q: My quad is ARMing and responding to Bluetooth commands when I have a printf placed in my "send quad commands" loop, but if I remove the printf things stop working.

A: It appears the Zedboard can send commands to the quad faster than it can process. Try placing a usleep(10000) (i.e. about 10ms) in your send loop in order to slow the Zedboard down a little. In other words, make sure there is a delay between sending an "RC channel" message.

Q: I'm sending ARM commands to the Quad, but the Quad is not ARMing (i.e. the red light on the Quad's main board does not come on, which will often start the blades spinning, but not always).

A: There are several possible issues: 1) The channel commands are 2-bytes each, when you write each channel into your communication buffer you need to write the least significant byte first, 2) You should be continuously sending commands to the quad (faster than once per second), if you just send a single ARM command the quad will not respond, 3) Have your Roll, Pitch, AUX1, AUX2, AUX3, AUX4 set to about 1500, this is equivalent to having an RC controller stick dead-center.

Q: For the set RC channel command, the multiWii command wiki says to send 16 uint16_t values, but only shows 8 channels. I'm confused.

A: The multiWii website has a typo. Since you are only sending 8 channels, it should say send 8 uint16_t values.

Q: It's great that the GPS client will send my Zedboad X,Y,Z,Yaw information, but what is the format....

A: When your Zedboard requests GPS information from the client, the client will respond with a 16-byte buffer of data. Each X,Y,Z,Yaw value (in that order) are floats, thus each is 4-bytes long. To verify you get the byte order correct you will want to send a debug message back to the GPS client that displays the GPS values that you received.

Q: I'm initializing my UART0 correctly with XUartPs_CfgInitialize(), but when I call XUartPS_RecvByte(), I am often receiving garbage data. What am I doing wrong?

A: There are several possible issues at this stage of MP-4. 1) Check that you are initializing your pointer to the XUartPs_Config structure properly using XUartPs_LookupConfig(). 2) Either call XUartPs_SetBaudRate() or XUartPs_EnableUart(). 3) Explicitly reset the TX and RX data paths in the UART0, by setting the appropriate bits in the control register to '1'. This last part is probably a Xilinx bug, since the system reset should also reset the UARTs.

Q: After adding UART0, how can I continue to print out debug messages to PuTTy?

A: Since we are using both of the PS7 UARTs in MP-4, you will need to be careful with regards to what STDIN and STDOUT are pointing to (and serial communication in general). Right-click your application's BSP, and select "Modify BSP Settings". Under the "standalone" option, set both stdin and stdout to point to ps7_uart_1.

Q: How can I determine the Bluetooth MAC address for my quad?

A: You can connect to it using your laptop (if it has Bluetooth) and view the MAC address that way. Or, lookup the corresponding entry in this table:

Quad-ID	Bluetooth MAC
1	`81:eb:b6:8b:79:13`
2	`81:eb:b6:86:e1:d4`
3	`81:eb:b6:81:b3:6c`
4	`81:eb:ad:e7:a8:ce`
5	`81:e9:9f:00:f1:a3`
6	`81:eb:ad:cd:9a:1e`
7	`81:eb:b6:90:6a:6d`

Note: Quad 2 is currently the one on the stand in the back of the lab.

MP-3 Frequently Asked Questions (FAQ)

Q: When I added the camera libraries to the FSBL, it fails to compile.

A: Depending on your hardware setup and usage of BSP libraries, the compiled elf may be over the maximum size for a FSBL executable. The following may help reduce the size:

Remove any video buffers that you may have allocated for your MP2 software project.
Comment out libraries that may not be absolutely necessary (e.g., xrgb2ycrcb.h, xv_demosaic.h, xtpg_app.h, and xvprocess.h) from your camera.h. This will exclude these libraries from being built with your FSBL.
Try to build. You will likely have errors complaining about missing sources. Which it is! Most of these errors will be with your custom pipeline init stuff (ipipe()). Replace all references to these libraries with hard coded values/addresses. It may be beneficial to run your modified camera code by itself to make sure your changes are correct.

Attempt to rebuild the fsbl project. The size of the code compiled needs to be less, than about 250KB. If it is still to big, try changing the build optimization setting to compile for size (-Os)

Q: When I boot Linux with my MP-2 based hardware, the camera starts running as expected, but at some point during the Linux boot up process, the camera abruptly turns off?

A: There is a good chance that during the boot process, Linux is overwriting so of the data space that was being used by the camera hardware. A tell-tale sign of this is if before you camera shuts off you see odd artifacts display to the monitor, this is basically what part of your Linux rootfs looks like in YCrCb format. This can be dealt with my having U-boot load your Linux kernel starting from a different location. One way of accomplishing this is to provide a boot.scr script to U-boot that tells U-boot where to load the Linux root file system. Here are two way you can do this:

Option 1: Try using this pre-built boot.scr file ([1]) instead of the one provided by petalinux. It contains the following commands:

fatload mmc 0 0x15000000 image.ub
bootm 0x15000000

Option 2: Built your own boot.scr file by preforming the following steps.

Locate the mkimage for targeting the ARM processor

<project-location>/avnet-digilent-zedboard-2020.1/build/tmp/work/zedboard_zynq7-xilinx-linux-gnueabi/linux-xlnx/5.4+git999-r0/recipe-sysroot-native/usr/bin/mkimage

avnet-digilent-zedboard-2020.1/build/tmp/work/zedboard_zynq7-xilinx-linux-gnueabi/linux-xlnx/5.4+gitAUTOINC+22b71b4162-r0/recipe-sysroot-native/usr/bin/mkimage

Place the u-boot commands you want to execute into a .txt file, let us call it boot.txt
Build a boot.scr file, by running the following command:

<PATH-to-mkimage>/mkimage -A arm -O linux -T script -C none -n "My Boot" -d boot.txt boot.scr

Q: I'm sick of constantly taking out the SD card, copying over my driver, booting Linux back up, and then testing my driver. Is there a better way?

A: Yes, yes there is! You can transfer files to Linux using the XModem protocol. Unfortunately, the version of PuTTY installed on the computers doesn't support XModem. First, download the ExtraPuTTY program:

Original Link:link.
Local Link: [2]

Unzip ExtraPuTTY and run the putty.exe program in it.

To transfer a file to Linux, first run the rx program in Linux and give it the file name you want your transferred file saved as (rx [filename]). A "C" will be displayed on the terminal. Then, open the "File Transfer" -> "XModem1K" -> "Send" menu on ExtraPuTTY and choose the file you want to transfer. A few seconds later, the file will be transferred!

Note: If RX is not installed/configured for you Linux, see the FAQ on how to configure Linux to enable it.

Q: RX does not appear to exist in Linux configuration that I am running on the Zedboad. How can I enable it.

A: The flowing step show you how to check if RX is installed, and if not how to configure the Linux rootfs to enable RX.

List supported Busybox applets while running Linux on the ZedboardCheck to check if RX has been enabled for busybox:

busybox --list options

If RX is not found, then in Petalinux RX needs to be enabled, built, and packaged into the rootfs.

Go to: <project-root>/meta-user
Create the following sub-direcoty recipes-core/busybox :

mkdir recipes-core
cd recipes-core
mkdir busybox

Inside of the busybox subdirectory create a file called "busybox_1%.bbappend", and a subdirectory called "files":

touch busybox_1%.bbappend
mkdir files

Inside of the "files" directory create a file called "user.cfg":

touch user.cfg

Open the file "user.cfg", and add the following line. Note: The label for the config option to turn on was found in <project-root>/components/yocto/layers/core/meta-poky/recipes-core/busybox/busybox/poky-tiny/defconfig :

CONFIG_RX=y

Open the file "busybox_1%.bbappend" , and add the following lines:

FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
SRC_URI += "file://user.cfg"

Build busybox:

petalinux-build -c busybox

Copy the updated "image.ub" to your SD card:
Boot Linux from the SD card. Once you have logged run the following command, it should show RX as one of the options:

busybox --list options

Q: How do I share a folder between by Virtualbox Linux, and Windows?

A: Here are several options for sharing data between you Virtualbox guest OS, and host OS:

Creating a shared folder: https://www.youtube.com/watch?v=FYmck1G0fqY
Setting permission in Ubuntu to access the shared folder: https://www.youtube.com/watch?v=u2Ha0peg9V4
A few other options: https://pureinfotech.com/create-shared-folder-virtual-machine-virtualbox/

Q: When trying to boot from the SD card, my output from PuTTY mentions something about xillydemo.bit and fails to load.

A: This is likely due to the misconfigured environment variables on the zedboard. After the failure message shows, you will also get an interactive terminal for the board. In this terminal, you can reset the environment variables with the command "env default -a" and save them to the boards memory with the command "saveenv". Power Cycling the board should allow the correct boot file to run.

Q: I get an error saying line 1: syntax error: unexpected "(" when I run my code on a Zedboard.

A: This means that the file you compiled to run on the Zedboard was not built for the ARM architecture, probably because the cross-compilation environment was not setup. Run the setup.sh script from MP-3 to set it up, and try making the code again. To verify it built correctly, you can use "file [filename]" command on a linux server (not the Zedboard) and it should give you an output that says "[filename]: ELF 32-bit LSB Executable, ARM, Version 1".

Q: When I try to read a pixel value from the memory mapped address (mmap(2)), the value stays constant.

A: This means Linux is caching the values from the memory location instead of re-reading them on every access. Include the O_SYNC flag when opening the file to force it to fetch the values on every read and write (which may make accesses slower).

Q: When I plug in the launcher, there are no debug messages that appear from Linux.

A: Double check that you have the usb debug messages flag set in the kernel config. Make sure the JP2 jumper on the Zedboard is shorted as well, this enables the 5V power connection for the USB port.

Q: non-Petalinux: I keep forgetting the commands for setting up the cross-compiler environment

A: Setting up cross compiler environment needs to be run inside of each new Linux terminal you open. Here are the commands to run

Setting up cross compiler environment. Needs to be run inside of each new Linux terminal you open:

source /remote/Xilinx/2018.3/SDK/2018.3/settings64.sh
export CROSS_COMPILE=arm-linux-gnueabihf-
export ARCH=arm

Q: non-Petalinux: I have downloaded the Linux Kernel OS source code, how do I compile it?

A: Go to the top-level Linux source directory, and then run these commands.

make ARCH=arm xilinx_zynq_defconfig
make ARCH=arm menuconfig
Under “Device Drivers -> USB support”, select the “Announce new device” option.
make ARCH=arm UIMAGE_LOADADDR=0x8000 uImage -j 24 (Note the 24 should be the number of processing cores your machine has)

Q: non-Petalinux: How can I speed up the SLOW Linux kernel compile process?

A: Add a -j[number of threads] flag to the command where you compile the kernel. For example, if you want to build the kernel with 16 threads, the command would be "make UIMAGE_LOADADDR=0x8000 uImage -j16". A reasonable rule is to build the kernel with the same number of threads that your computer has cores.

Q: non-Petalinux: What if I encounter an error when trying to convert the device tree to a binary file?

A: Check that the xilinx.dts file does not contain any duplicate entries and try again.

A list of required packages for compiling the Linux kernel on an ECpE remote machine can be found here: Packages. This list was compiled by running through the lab on a new RHEL7 machine.

MP-2 Frequently Asked Questions (FAQ)

Q: I'm having trouble understanding the relationship between the video timing controller(s), video in/out, and the VDMA. What's a good resource to look through?

A: The AXI4-Stream Video IP and System Design Guide provides a very nice overview of how these components work together: ug934_axi_videoIP.pdf

Q: How does converting from RGB to YCbCr work?

A: Some good information on this topic can be found in the datasheets for the RGB2YCrCb and Chroma Resample components found in the MP-2 assignment. Also, take a look at this document for more information about theory of operation ch03.pdf.

Q: What is the starting color sensor for the Bayer pattern we are applying?

A: Look at the datasheets for both the CFA (the hardware module that applies the Bayer filter) and the VITA sensor.

Q: Regenerating HDL Wrapper - After adding/removing components to/from our Block Diagram or adding/removing an externally connected signal/port, we start see weird warnings/errors during synthesis (e.g., "Port 'signal name' is missing in component declaration", "tying undriven pin clk to constant 0")

A: Some teams may have run into this issue in MP0, and/or some in MP1, when you add a component to your block diagram (or make a signal an External Port) your top level HDL wrapper does not update. When you start getting odd errors in VIVADO it is always a good idea to examine your HDL wrapper to make sure it looks reasonable. If it does not, then remove and regenerate it.

Generally speaking, when trying to debug issues with the Xilinx Tools, the log files are your friend. They tend to give much more detail than the console summary messages. I have saved and attached two logfiles. One logfile with the warnings/errors that some teams have seen after adding components, and one that is a somewhat clean logfile after deleting and regenerated the HDL wrapper.

You will notice near the beginning of the error log file a ton of warnings of the form:

"Port 'signal name' is missing in component declaration"

This is a pretty huge red flag that something is amiss, and one of the first places to check is if your xdc file, and HDL wrapper are matching. If you were to open your HDL wrapper file, you should see that indeed many of the ports for those new IP cores are not there. By deleting the HDL wrapper, and regenerating you should see those ports in the newly generated HDL wrapper.

Since many of the ports of your IP block that were to be external where not recognized by the HDL wrapper, the tool just tied them to constants. Then later the tool for example noticed things like clocks being tied to a constant values, thus threw errors.

Example error logfile: [3]

Example Clean logfile: [4]

Q: We're seeing multiple compile errors when creating the First Stage Boot Loader (FSBL) design. It's worked all semester long - what gives?

A: The MP-2 FMC-IMAGEON infrastructure only works with an older version of the "standalone" Xilinx library we have been using for our bare-metal software development. That version (3.06.a) is not fully API-compatible with the v14.6 FSBL code. You can either create your own 3.10.a BSP for the FSBL project, or directly fix the compile errors:

The QSPI library is generating most of the errors, so replace every instance of "XPAR_PS7_QSPI_LINEAR_0_S_AXI_BASEADDR" with "XPAR_PS7_QSPI_FSBL_HACK", or something else that is not currently defined. There are 4 places in the FSBL code to make this change.
The XDcfg_GetPsVersion() function isn't defined in the 3.06.a standalone BSP. In function GetSiliconVersion(), directly set variable "Silicon_Version" to SILICON_VERSION_3_1, and comment out the call to XDcfg_GetPsVersion().

We will be integrating the camera_app code into the MP-3 FSBL directly, so upgrading the standalone BSP won't work at that point and you'll have to fix the compile errors.

MP-1 Frequently Asked Questions (FAQ)

Q: When using the picoscope to anaylze the RC controller's PPM signal, I can't seem to get the PPM to stay in one place?

A: Here are some simple picoscope adjustments to make while observing the PPM waveforms:

Set the trigger to repeat or auto
Click the square wave looking button next to the trigger selection
Select pulse wave from the left hand menu
Adjust the time setting (a vale from 8ms-20ms has typically worked well for the RC's PPM)
Adjust the window zoom, make sure that the view is not scrolled past the signal (using the scroll wheel to get an appropriate window size seems to work well) (in the zoom selection window, the size and position of the zoom selection can be adjusted)

This can all be done while running to make sure what you want to observe is in the window.

Q: How do I bind a transmitter to the quad receiver?

A: Follow this YouTube Link [5]

Q: How do I get my changes to my axi_ppm MPD file to be reflected in the XPS project?

A: XPS caches all the pcore metadata when it first launches. Select "Project -> Rescan User Repositories" to see your changes.

Q: How do I get my changes to my axi_ppm IP core to be reflected in Vivado?

A: After packaging the IP, go back to the MP Vivado project and select Reports>Report IP Status. Your axi_ppm should report itself as obsolete and have an option to upgrade.

Q: What is the MPD file format? How do I add my external signals to the auto-generated IP core?

A: Check out the EDK Platform Specification Reference Manual - the MPD file syntax starts on page 27.

Q: How do I use the logic level converters?

A: See the SparkFun Logic Level Converter Guide to understand the interface. For the cables we use, black/brown is ground, red is high, and other colors are data lines.

Q: My simulation has a "component instance is not bound" error. What does this mean? Why can't I see the signals of my user_logic component?

A: This error occurs because the user_logic file is not in the working library of the simulation and it does not recognize the interface or because the generics and ports of the instantiated component do not EXACTLY match the declaration. To fix this problem you need to include the library of the component you want to use; in this case the library is "axi_ppm_v1_00_a" and the part we want from it is "user_logic". To use this library in your created testbench design, you can take the following 2 lines of code from the top of the file in axi_ppm.vhd:

library axi_ppm_v1_00_a;

use axi_ppm_v1_00_a.user_logic;

Q: Which transmitter should I use for flight testing, and how should it be configured?

A: Note: for safety reasons, do not perform ANY flight testing without the TA or instructor present. We are using transmitter #2, also labelled as "To Quad". There are two switches of note on this transmitter. The upper-left switch is the throttle kill-switch: keep this set to "Off" (toggled forward). The upper-right switch is the trainer switch: keep this set to "Slave" (toggled forward) so that this can act as a flight test master kill switch.

MP-0 Frequently Asked Questions (FAQ)

Q: After making an update to my Hardware in VIVADO, my VITIS software project is not seeing these changes?

A: Anytime you make an update to your hardware in VIVADO and export an updated .xsa file, you need to make VITIS aware of this. This link explains how to update your VITIS platform project using the Update Hardware Specification option to point the VITIS platform project to the updated .xsa file [6] . Remember to rebuild your Application project.

Note: If this does not sync your VITIS software up with the hardware changes you made in VIVADO, you can always just make a new Application project, and tell it to use the .xsa that you exported from VIVADO, and copy your C files over to the that new Application project.

Q: What is this ERROR message about: "set_property expects at least one object"

A: The set_property expects that there exists one thing for it to operate on. A common place this error has occurred for students is when you add the master .xdc file to your project. The following line:

set_property IOSTANDARD LVCMOS33 [get_ports -of_objects [get_iobanks 13]];

is wanting to act upon FPGA pins that are in Bank 13. If you do not have any signals connect to the Zedboard PMODs to monitor signals for debugging or using the Virtual Zedboard interface (which uses PMOD C and D), then you will want to comment out this line from the .xcd.

Q: When I tried to connect the virtual switches / buttons using PMOD C, and PMOD D, I am getting weird errors bout "tri" signals. Where did this come from?

A: The tools are trying to be "smart"/"helpful", and are noticing that the GPIO IP block has the ability to be a tri-state interface. In response to this, during the bitfile generation (or synthesis) process it updates your VHDL wrapper file to append "_tri_i" to the end of the name you gave the external pin in your Block Diagram. This causes the VHDL wrapper name not to match the name you gave in your .xdc file.

There are a number of ways you can resolved this mismatch from occurring. The following is the cleanest method I have found:

Add your GPIO IP block,
Make the output External,
Give this output a name,
Save your block diagram,
Click the option to create an HDL Wrapper. This will make/update the wrapper to include this newly added external pin,
Open the HDL wrapper file that was created/updated,
Check the name the wrapper gives the external pin. You should see that it has appended _tir_i to the pin name that you gave,
Use the name that the wrapper gives in your .xdc file.

One may ask: Why did the physical buttons and switches not give this issue? You will notice that for the physical buttons / switches / leds you did not have to add these to your .xdc file. This is because they are known by the Zedboard settings, thus takes care of this details behind the scene . You can see this if you open your VHDL wrapper file, you will notice that the physical buttons / switches / leds, have had "_tri_i" or "_tri_o" appended to the name shown in the block diagram's external pin name.

Q: When running the vga_test application, why am I only seeing green and blue bars? Where is my red channel?

A: Your VTC timing is slightly off, leading to non-blank pixels being transmitted during the horizontal and/or vertical blanking period. See the wikipedia entry on Raster bar for an example of the effects that are possible by messing with the blanking period. Assuming you are only off by 1 pixel, the easiest solution is to tweak vga_test (and any other software application using this VGA setup) to set the first column of your 640x480 framebuffer to black (and perhaps the last column).

Q: How do I get a 12-bit RGB signal? The settings in axis_vid_out seem to provide separate channels for Red, Blue, and Green, and there's no 4-bit option there.

A: For our purposes, the vid_out doesn't really need any knowledge of the data format, other than it should be taking in the 16-bit signal off the AXI stream and outputting 12-bit pixels. The ug934_axi_videoIP.pdf guide provides a nice overview of the different video out modes, and how you could configure a 12-bit signal.

Q: I'm not seeing anything on my VGA monitor, and I've hooked up everything correctly (as far as I can tell). What should I do next?

A: There are three main points of failure in the design: the v_tc timing controller, the axi_vdma module, and the video out. Connect some internal signals in your design (e.g. the vTIMING_OUT) to the Integrated Logic Analyzer (ILA) (or you could use available PMOD ports) so that you can probe them. Keep in mind that the vid_out only will start transmitting when it synchronizes the data coming in on the AXI video stream with the timing data.

Q: I can't see all the signals that are being discussed in the MP-0 document. What gives?

A: Even in the "Ports" tab, VIVADO may hide some connections if they have a default assignment. Click the "Filter" button on the right of the "Ports" tab, and select all the options, including "Default".

Q: What do a correct v_sync and h_sync look like?

A: Check the two links in the prelab portion of MP-0. Your signals, including timing information and pulse polarity, should match exactly what is shown in the digilent datasheet.

Q: I don't understand whether or not I need to connect signal X in component Y.

A: Check the datasheets, either directly in VIVADO or in the docs/IP/ sub-directory of your MP-0 install. For example, pg044_v_axis_vid_out.pdf provides nice, and clear architectural diagrams for the axis_vid_out component. For example, do you need to connect the aclk port to something? Check out the diagram on page 6.

Q: I am trying to compile the NES code, and it is giving a TON of compiler errors! Any pointers for how to address these errors?

A: Yes this will be the case right after you copy the code into your project. This is due to two key things:

Since the code base added subdiretories for source and include files, you need to let the build system know where to look for these files. Here is how to do this:

Right click on your application project, and select properties
Click to expand "C/C++ General"
Select "Path and Symbols", then click the "Includes" tab
Click "Add..." to add 3 folders to your Include directories: src, NESCore, src/xilsd
Click "Apply and Close"

Here is an image of what it looks like after you click "Add..." and select to added "xilsd":

Here is an image of what the include tab should look like after you have added these folders to the Include path:

Error creating thumbnail: File missing

Click to Enlarge

You will notice in the "mapper" folder there are many .c files throwing errors. These .c files are used in an unconventional manner, and need to be ignored by the build system. You can mark this folder to be ignored as follows

Right click on the "mapper" folder
Select "Properties"
Click on "C/C++ Build"
Check "Exclude resource from build", then click "Apply and Close"

The "mapper" folder should now have a grey slash through it, and the name "mapper" should be greyed out.

Q: OK. I have the NES code happily compiling, and I think I have made the needed updates to load the default game, and have its start up screen (sequence) display. But the debug print statements we see using PuTTY are showing that the code is getting stuck during the "Boot/Load" stages. What are some things I can do to get past this issue?

A: There are a couple things going on that need to be taken care of, and both involve updating the loader script (i.e. lscript.ld) of your project.

The "Stack" and "Heap" size that was set by initial "Hello" application is too small. You will need to increase both of these.
A trickier issue is noticing that this application does some fixed location static memory allocation. Take a look near the bottom of mmap.h. You will notice a comment indicating that it is performing static memory allocation. Which is fine, but the part we need to deal with using the lscript is that fixed locations are specified. We will deal with this by adding an offset to what we tell the build tool is the base address of DDR memory. This ensures the build tools will not try allocate memory were we have already manually allocated. Basically we are tricking the tool to thing DDR memory starts at a higher address in memory. You can figure out what address to give this script by printing out the value of "WAV_BASEADDR" (e.g. xil_printf("WAV_BASEADDR = %X \r\n", WAV_BASEADDR);). You will notice the value shown in the screen shot is a bit larger that the value printed. This was done to make the math easier for for ensuring that "Base Address" + "Size" adds so that the end of the DDR memory does not change.

The values show in this screen shot should be fine to use in your NES lscript:

Error creating thumbnail: File missing

NES setting: Click to Enlarge

Here are the values the the "Hello" application originally specified:

Error creating thumbnail: File missing

Hello settings: Click to Enlarge

Q: This assignment is too hard!

A: Not really a question, but in any case the sentiment is understood. MP-0 is about learning more about the platform and the tools, and it accomplishes that goal. The first design is always the most frustrating, and in MP-0 we wanted to introduce as many Xilinx VIVADO/VITIS features as possible, including some of the bugs.

Q: I am feeling lost with how to get my VDMA, VTC, VID_OUT hardware design to do anything. Do you have any suggestions for how to move forward?

A: MP-0: Recommended Approach, Mindset, and Rules of Thumb

Class,

As you work on MP-0, you will (or have) found that Part 6 is much more challenging than parts 1-5. For Part 6, you are required to form a clear picture of how data is moving through the system and implement that system based on 1) the high-level objective of Part 6, and 2) the documentation of the IP cores needed to complete this part of MP-0 (i.e. VTC, Video Out, and VDMA).

Recommended approach: Some of these steps will be done in parallel.

A) Draw out the system:

Get out sheets of paper and a pencil (or better have an MP notebook for this class). As you read through the IP core documentation, sketch how these components connect together. First at a high-level, and then at lower-levels as you learn more details about each IP core.

B) Understand the technology you are dealing with (write notes about your understanding):

1) What does each IP cores do?

2) What is the purpose of each of IP core in the system you are creating?

3) How does each IP core go about doing its job?

4) Make notes on which parts of the Datasheets are appearing to be helpful to your understanding.

5) Recommendation:

a) In general, make a quick 20 minute scan through each datasheet doing the following: i) read introduction/overview pages of each datasheet, ii) scan the whole document to get a sense of the type of architecture and time diagrams present, iii) if there are configuration registers scan them to see their nature, and iv) check if there are usage scenarios described.

b) Specifically for part 6 of MP-0:

i) Video Out: A good starting place, as chapter 1 gives a nice short overview of how this component fits with others, and chapter 2 gives good details on the interfaces that connect Video Out to other IP.

ii) VTC: Chapter 1 gives a nice short overview, and Chapter 2 gives nice descriptions of the interface signals and registers.

iii) VDMA: This core is the most feature-rich of these 3 IP cores. Chapter 1 gives a quick overview, and Chapter 2 gives very useful timing diagrams, among other details (register descriptions, etc.). You will find yourself coming back to Chapter 2 often. ug934_axi_videoIP Chapter 1 is also useful for learning about the AXI-Stream protocol/interface.

C) Don’t get paralyzed by not knowing everything: Datasheets can be loaded with MUCH detail, and parts may be written in a manner for which it is difficult to know with certainty if you are interpreting some aspects correctly or misunderstanding. For your sanity sake, keep in mind those writing these datasheets often may only be a few years ahead of you in terms of work experience.

1)Move forward: For MP-0, I would recommend spending about 2 hours reading through each of the datasheets for the primary IP cores (VDMA, VTC, Video Out). This does not mean reading each IP core datasheet sequentially. You will need to skip between them to help build your overall view of the system, and to build your understanding of how they should work together to complete the task at hand (i.e. get an image frame stored in DRAM to display on a monitor). So I would allocate on the order of 6 hours total for this process, before going to 2).

2) Build the system: Once you have spent time doing parts A, B, and C.1, then build the system as a VIVADO Block Diagram, use VIVADO to build a hardware configuration file, and program the FPGA. You will find there are a number of configuration options for the IP Blocks that you do not understand. Make your best guess using the information and level of understanding you have.

3) Don’t get stuck on Error messages given by the tools: The VIVADO tool chain is very powerful, and there is a large learning curve to use it like a pro. This is where your TAs (i.e. me) and the Discord discussion form come in. Here is a rule of thumb: Do not spend more than 30-45 minutes struggling own your own to fix VIVADO error messages before posting to or checking Discord (or class wiki) Note: You will want to spend at least 20 minutes struggling and poking around the tools. This is the best way to get use to the tools

D) Extract evidence from the system: The first time you configure the FPGA with your hardware design, and run your software on it (test_vga.c), the most likely outcome is you will be staring at a blank screen! Yes, this can be depressing. And anyone entering the field of embedded systems design has to get use to this initial feeling, and learn how to push through it. Here are actions you can take to work your way from a blank screen to working system:

1) Software side:

a) Add print statements to see at point in the SW the system may be getting locked up.

b) Add print statements to read the status of registers available for a given IP core. This could give insight into where things are going wrong (either for SW or HW).

2) Hardware side: OK, you have just downloaded your hardware to the FPGA, ran your software on the hardware, and now you are staring at a blank screen. Is the FPGA completely dead? Is the hardware doing anything? Let’s find out:

a) Search for life: Modify your hardware design to connect “important” signals of your design to ports of the Zedboad (PMOD ports). For example, various clock signals. If you probe a clock signal with an oscilloscope and you get a constant value, then look into why that may be the case (e.g. maybe you have a reset tied to a constant 0, when it is an active-low reset).

b) Search for intelligent life: Check the data sheets for timing-diagrams, and connect some of these related signals to a Zedboad PMOD to see if they are behaving as expected. If not, then dive into the datasheets to find out why, or for hints on what other evidence you can extract from the system to help you isolate the problem.

E) Work with your TAs/me: Once you have spent time extracting evidence from your system. Ping your TAs/me (over Discord) to share what you are seeing, and your theories for why this may be occurring. TAs/me will be able to help you think about what you are seeing, and help suggest next steps you can take to track down what is going wrong with your system.

F) Stay hopeful: Be prepared to not get the results you expect, when trying something. Each time you test a hypothesis, you get one step closer to an operational system. Always keep in mind a list of next step options for forming a clearer picture of what the system is doing, and for discovering why it is behaving in that manner.

General Software Help

Remote Linux access:

Use Remote Desktop to remote to any of the remote linux machines (ISU Remote Access Servers)
Run the following in bash:

   source /remote/Xilnx/2018.3/Vivado/2018.3/settings64.sh
   'vivado &' or 'xsdk &'

Q: I type xsdk & or xps & in the terminal and nothing is appearing on the display.

A: There have been issues using the Xilinx tools on a KDE desktop environment. For best results be sure you are using GNOME. To change the environment, click configure on the NX session login prompt, then change the drop-down box under Desktop to say GNOME.

Q: The setup.sh script is erroring when run saying either if: Expression Syntax or ZED_SETUP not defined.

A: You are running the wrong shell on your terminal. Type bash , then rerun the script.