Getting Started with the TE0802

The TE0802 is an FPGA development board from Trenz Electronic that showcases the Zynq UltraScale+ MPSoC FPGA. It comes equipped with a wide range of peripherals including Gigabit Ethernet RJ45, 2 Pmod connectors, a Grove connector, VGA port, DisplayPort, 4-digit 7-segment display, 8 LEDs, 5 push buttons, 8-bit slide switches, 3.5 mm audio jack, USB 3.0 host port, and Micro-USB JTAG/UART.

For storage, the TE0802 can utilize its onboard 32MB SPI Flash or external sources via the MicroSD card slot or M.2 M-keyed PCIe slot (which allows for corresponding M-keyed M.2 SSDs to be connected to the TE0802).

The goal of this project is to set up the base hardware design for the TE0802 in Vivado to utilize all of its onboard peripherals and run a simple Hello World embedded C application. This will result in the necessary Vivado and Vitis projects to serve as the starting point for any custom RTL or bare metal embedded application to be developed for the TE0802.

Hardware Design in Vivado

Trenz Electronic provides all of the design files necessary to interface with everything on the TE0802 board such as the constraints files, block design TCL script, IP library, board definition files, etc. The files are compiled into a zip file in the downloads area of their site under each specific version of Vivado/Vitis/PetaLinux they have generated the files in.

Currently the latest version of the files for the TE0802 are for Vivado/Vitis/PetaLinux 2019.2, so that is the version I will be using in this project tutorial. I have attached the zip file of the TE0802 2019.2 design files to this project post, so you can download them from here or Trenz website:

Once the design file folder is downloaded and unzipped, start by copying the TE0802 board definition files (located in /test_board/board_files/) into Vivado under /<Vivado installation directory>/data/boards/board_files.

~$ sudo cp -R /<extracted directory>/test_board/board_files/* /tools/Xilinx/Vivado/2019.2/data/boards/board_files/

There is a CSV file in the board_files directory from the Trenz test_board folder that is just a reference of what the board definition files outline, it is not needed in the Vivado board_files directory so remove it from there:

~$ sudo rm /tools/Xilinx/Vivado/2019.2/data/boards/board_files/TE0802_board_files.csv

With the TE0802 board definition files installed, source the Vivado tools & launch Vivado 2019.2:

~$ source /tools/Xilinx/Vivado/2019.2/settings64.sh
~$ vivado

Create a new project targeting the TE0802 board:

As mentioned previously, Trenz provides an IP library of the IP for the peripherals on the TE0802 board. This IP library needs to be made available to the Vivado project. So start by copying TE0802 IP into the Vivado project directory:

~$ cp -R /<extracted directory>/test_board/ip_lib/ /home/parallels/te0802_prj/

Add TE0802 IP library to Vivado project by opening the 'Settings' menu from the Flow Navigator window in Vivado and navigating to IP > Repository. Click on the + icon and point it to the IP library (titled ip_lib) that was copied into the Vivado project directory.

After clicking Select on the ip_lib directory, a new window will pop up displaying the IP blocks Vivado detects in the folder. Click OK and it will return to the Settings menu. Click Apply and then OK to save and close the Settings menu.

Next use the TCL script from the test_board folder (/test_board/block_design/zusys_bd.tcl) to create the block design for the Vivado project. But before running the TCL script, comment out lines 4 - 6 in the Trenz block design TCL script (zusys_bd.tcl) if not using Trenz's version control:

Source the Block Design TCL script from Trenz from the TCL command line in Vivado:

source /<extracted directory>/test_board/block_design/zusys_bd.tcl

This will create a new block design then add all of the necessary IP blocks from both the regular Vivado repository and the TE0802 IP repository (ip_lib) then configure then as necessary.

Regenerate the layout in the block design to make it visually appear a bit clearer:

Validate the block design to check for any errors or critical warnings:

Once the block design has been successfully validated, save it. You can also take a moment to explore the Trenz custom IP blocks controlling peripherals such as the 7-segment display and VGA port.

Next, generate the top level HDL wrapper for the block design in order to instantiate it in the project:

Add the constraints files for the TE0802 to the Vivado project to specify the package pinouts and other timing/hardware related constraints. Click on Add Sources from the Flow Navigator window and select the option to Add or create constraints.

Click on Add Files and select the three constraints files from the test_board directory under /test_board/constraints:

Set the target constraints file for Vivado by right-clicking on vivado_target.xdc in the Sources window and selecting Set as Target Constraints File:

You are free to add any other custom design files or settings to the Vivado project at this point, otherwise the design is ready to be synthesized, place and routed, and a bitstream generated for it.

Run synthesis and implementation (place & route), then generate a bitstream using the icons from the toolbar:

Once the bitstream is successfully generated, you can open the implemented design to see how it was deployed and laid out in the FPGA of the TE0802:

With a bitstream now ready, export hardware such that Vitis can import it in order to generate a software platform on top of it. Click File > Export > Export Hardware...

Be sure to check the box to include the bitstream in the hardware. The hardware is exported as Xilinx's proprietary.XSA file type and you can select your desired directory for it to be sent it. I personally like to keep it inside the Vivado project directory.

Software Design in Vitis

With the hardware design complete and exported for use with Vitis, launch Vitis by clicking Tools > Launch Vitis:

Create a workspace for the new project about to be created. I personally like to create a directory titled vitis_workspace inside the Vivado project directory. This keeps all of my source files for each project for a board in one place.

Select the option to Create Platform Project. Give it the desired name and select the option to generate it from a hardware specification (XSA) file. Point to the XSA file exported from Vivado and leave the default selections for a standalone OS and the zero index ARM processor in the MPSoC.

Once the platform project generates after clicking Finish in the final configuration window, build it using the keyboard shortcut control+B or clicking the Build icon from the toolbar.

The the platform project created and built to outline the hooks for the hardware design, it is time to create the actual bare-metal embedded application that will be running on the TE0802

Create a new application project by clicking New > Application Project...

Give the application the desired name and select the platform created by the platform project to base it on. Then select domain for standalone on the zero-index ARM processor and the desired language to code the embedded application in. Finally, select the Hello World application template to and click Finish.

Once Vitis has populated the Hello World application, open helloworld.c from the Explorer window and make the following modifications such that we can see more than the one "Hello World" print from the UART:

int main(){
    init_platform();

    while(1){
        print("Hello World\n\r");
        for(int i=0;i<10000;i++){}
    }

    cleanup_platform();
    return 0;
}

Save helloworld.c and build the application by right-clicking on the application name from the Explorer window and selecting Build Project:

With the application now fully built, the boot mode of the TE0802 needs to be set to JTAG since we'll be running it using the TCF system debugger.

The TE0802 has its boot mode set using a DIP switch (S1 on the board located next to the VGA port). To set the TE0802 to boot from JTAG, switches 1 and 2 need to be set to the OFF position:

Plug in the 5V power supply to the 2.1mm jack to the wall wart power supply, and the JTAG/UART Micro-USB to your PC.

Next, program the TE0802 FPGA with the bitstream by right-clicking on the application name from the Explorer window and selecting Program FPGA. Vitis will auto-detect the TE0802 board and auto-fill the appropriate bitstream file so you can simply click Program:

Once programmed, launch system debugger on the hardware by right-clicking on the application name from the Explorer window and selecting Debug As > Launch on Hardware (Single Application Debug).

Vitis will switch over to the debug view and run the application up to the init_platform function where it has set a breakpoint.

Connect to the UART serial interface of the TE0802 using the Vitis Serial Terminal from the window along the bottom of the debug view:

At this point you can run (pause/play icon - F8) or step through (u-shaped arrow icon - F6) the code of the Hello World application using the icons from the toolbar across the top:

You can see the Hello World application running and printing out via the serial terminal:

The drivers for the LEDs and 7-segment display are also running in the programmable logic of the Zynq UltraScale+ MPSoC FPGA independently from the Hello World application running on one of its ARM-core processors. Thus you will also see its little counting routine running and incrementing a value on the LEDs and 7-segment display:

And that's it! The TE0802 is up and running!