====== Genesys ZU Hello World Demo ======

<WRAP todo important>
== Under Construction ==
</WRAP>

----
===== Description =====
This project is a simple demo that configures the Zynq Ultrascale+ MPSoc with the given board file, and outputs "Hello World" on the serial terminal.
----
===== Inventory =====

  * Genesys ZU-5EV with a MicroUSB Programming Cable and a Power Supply
  * Vivado installation compatible with the latest release of this demo (2023.1)
    * //See [[programmable-logic:guides:installing-vivado-and-vitis|Installing Vivado, Vitis, and Digilent Board Files]] for installation instructions.//

----
===== Download and Usage Instructions =====

First and foremost, releases - consisting of a set of files for download - are only compatible with a specific version of the Xilinx tools, as specified in the name of the release (referred to as a //release tag//). In addition, releases are only compatible with the specified variant of the board. For example, a release tagged "20/DMA/2020.1" for the Zybo Z7 is only to be used with the -20 variant of the board and Vivado 2020.1.

The latest release version for this demo is highlighted in green.

**Note:** //Releases for FPGA demos from before 2020.1 used a different git structure, and used a different release tag naming scheme.//

^ Board Variant   ^ Release Tag                       ^ Release Downloads                                                                                        ^ Setup Instructions                       ^
| Genesys ZU-5EV  | @#C0EEBD: 5EV/HELLO-WORLD/2023.1  | {{https://github.com/Digilent/Genesys-ZU/releases/download/5EV/HELLO-WORLD/2023.1/hw.xpr.zip}}   \\ {{https://github.com/Digilent/Genesys-ZU/releases/download/5EV/HELLO-WORLD/2023.1/sw.zip}}    | See //Using the Latest Release//, below  |
| Genesys ZU-3EG  | @#C0EEBD: 3EG/HELLO-WORLD/2023.1  | {{https://github.com/Digilent/Genesys-ZU/releases/download/3EG/HELLO-WORLD/2023.1/hw.xpr.zip}}   \\ {{https://github.com/Digilent/Genesys-ZU/releases/download/3EG/HELLO-WORLD/2023.1/sw.zip}}    | See //Using the Latest Release//, below  |
| Genesys ZU-5EV  | 5EV/HELLO-WORLD/2022.1-3          | {{https://github.com/Digilent/Genesys-ZU/releases/download/5EV/HELLO-WORLD/2022.1-3/hw.xpr.zip}} \\ {{https://github.com/Digilent/Genesys-ZU/releases/download/5EV/HELLO-WORLD/2022.1-3/sw.zip}}  | See //Using the Latest Release//, below  |
| Genesys ZU-5EV  | 5EV/HELLO-WORLD/2021.1-1          | {{https://github.com/Digilent/Genesys-ZU/releases/download/5EV/HELLO-WORLD/2021.1-1/Genesys-ZU-5EV-HELLO-WORLD-hw.xpr.zip}} \\ {{https://github.com/Digilent/Genesys-ZU/releases/download/5EV/HELLO-WORLD/2021.1-1/Genesys-ZU-5EV-HELLO-WORLD-sw.ide.zip}}  | See //Using the Latest Release//, below  |
| Genesys ZU-5EV  | 5EV/HELLO-WORLD/2020.1-2          | {{https://github.com/Digilent/Genesys-ZU/releases/download/5EV/HELLO-WORLD/2020.1-2/Genesys-ZU-5EV-HELLO-WORLD-hw.xpr.zip}} \\ {{https://github.com/Digilent/Genesys-ZU/releases/download/5EV/HELLO-WORLD/2020.1-2/Genesys-ZU-5EV-HELLO-WORLD-sw.ide.zip}}  | See //Using the Latest Release//, below  |
| Genesys ZU-3EG  | 3EG/HELLO-WORLD/2020.1-2          | {{https://github.com/Digilent/Genesys-ZU/releases/download/3EG/HELLO-WORLD/2020.1-2/Genesys-ZU-3EG-HELLO-WORLD-hw.xpr.zip}} \\ {{https://github.com/Digilent/Genesys-ZU/releases/download/3EG/HELLO-WORLD/2020.1-2/Genesys-ZU-3EG-HELLO-WORLD-sw.ide.zip}}  | See //Using the Latest Release//, below  |
| Genesys ZU-5EV  | 5EV/HELLO-WORLD/2020.1-1          | {{https://github.com/Digilent/Genesys-ZU/releases/download/5EV/HELLO-WORLD/2020.1-1/Genesys-ZU-5EV-HELLO-WORLD-hw.xpr.zip}} \\ {{https://github.com/Digilent/Genesys-ZU/releases/download/5EV/HELLO-WORLD/2020.1-1/Genesys-ZU-5EV-HELLO-WORLD-sw.ide.zip}}  | See //Using the Latest Release//, below  |

**Note for Advanced Users:** //GitHub sources for this demo can be found in the [[https://github.com/digilent/genesys-zu/tree/3EG/HELLO-WORLD/master|3EG/HELLO-WORLD/master]] and [[https://github.com/digilent/genesys-zu/tree/5EV/HELLO-WORLD/master|5EV/HELLO-WORLD/master]] branches of the Genesys-ZU repository. Further documentation on the structure of this repository can be found on this wiki's [[programmable-logic:documents:git]] page.//
----
Instructions on the use of the latest release can be found in this dropdown:

--> Using the Latest Release #^
<WRAP group>

**Note:** //This workflow is common across many Digilent FPGA demos. Screenshots may not match the demo you are working with.//

**Important:** //These steps are only to be used with releases for Xilinx tools versions 2020.1 and newer. Older releases may require other flows, as noted in the table of releases.//

First, download the '*.xpr.zip' and '*.ide.zip' files from the demo release page, linked above. The XPR archive contains the Vivado project used to build the hardware platform for this demo. The project can be opened, modified, and used to update the hardware platform later if so desired, but this is optional. The IDE archive contains a set of projects to be imported into a Vitis workspace.

**Note:** //Unlike with Vivado XPR archives, do NOT extract the Vitis project archive ('*.ide.xip'). Vitis imports sources from the archive file directly.//
----
--> Import Vitis Projects from a Release #
<WRAP group>
{{page>programmable-logic:guides:vitis-launch&noheader}}

<WRAP group> <WRAP column half>
With Vitis open, click the **Import Project** button to import projects from a //Vitis project exported zip file//.
</WRAP> <WRAP column half>
{{ :learn:programmable-logic:tutorials:genesys-zu-demo-hello-world:import_vitis_project_2020_1_zoomed.png?600|}}
</WRAP> </WRAP>
----
<WRAP group> <WRAP column half>
With Vitis open, please make sure that **Vitis project exported zip file** button is selected, then click Next and navigate to and select the IDE zip file you downloaded.
</WRAP> <WRAP column half>
{{ :learn:programmable-logic:tutorials:genesys-zu-demo-hello-world:import_vitis_project_type_2020_1_zoomed2.png?600|}}
</WRAP> </WRAP>
----
<WRAP group> <WRAP column half>
Make sure each project in the archive is checked, then click **Finish** to import them into your workspace.
</WRAP> <WRAP column half>
{{ :learn:programmable-logic:tutorials:genesys-zu-demo-hello-world:import_vitis_project_type_2020_1_1.png?600|}}
</WRAP> </WRAP>
----
<WRAP group> <WRAP column half>
After the import, you should see all the sources into the workspace.  
</WRAP> <WRAP column half>
{{ :learn:programmable-logic:tutorials:genesys-zu-demo-hello-world:import_vitis_project_type_2020_1_3_zoomed.png?600|}}
</WRAP> </WRAP>
----
</WRAP>
<--

--> Build a Vitis Application #
**Note:** //Depending the case, //*// stays either for 3EG or 5EV.//
----
<WRAP group> <WRAP column half>
Double-click on //*_boot// in order to see all the sub-directories, then double-click *_boot.sprj and single-click on //Change target platform for the current project// tab. 
</WRAP> <WRAP column half>
{{ :learn:programmable-logic:tutorials:genesys-zu-demo-hello-world:import_vitis_project_type_2020_1_4.png?600|}}
</WRAP> </WRAP>
----
<WRAP group> <WRAP column half>
Without change anything, click //OK//.
</WRAP> <WRAP column half>
{{ :learn:programmable-logic:tutorials:genesys-zu-demo-hello-world:import_vitis_project_type_2020_1_5.png?600|}}
</WRAP> </WRAP>
----
<WRAP group> <WRAP column half>
A warning message will pop-up saying that all the build configurations will be cleaned. This is what we actually want to happen, so click //YES//.  
</WRAP> <WRAP column half>
{{ :learn:programmable-logic:tutorials:genesys-zu-demo-hello-world:import_vitis_project_type_2020_1_6.png?600|}}
</WRAP> </WRAP>
----
<WRAP group> <WRAP column half>
Right-click on *_fsbl.prj and select //Properties//. Go to //C/C++ Build// and double click on //Settings//, then single-click on //Linker Script// from the ARM v8 gcc linker tool. Modify the Linker Script path to //../src/lscript.ld//.
</WRAP> <WRAP column half>
{{ :learn:programmable-logic:tutorials:genesys-zu-demo-hello-world:import_vitis_project_type_2020_1_6_1.png?600|}}
</WRAP> </WRAP>
----
<WRAP group> <WRAP column half>
Right-click on *_boot project and select //Build Project//.  
</WRAP> <WRAP column half>
{{ :learn:programmable-logic:tutorials:genesys-zu-demo-hello-world:import_vitis_project_type_2020_1_7.png?600|}}
</WRAP> </WRAP>
----
<WRAP group> <WRAP column half>
You can see the progress on the bottom-right side of the screen. 
</WRAP> <WRAP column half>
{{ :learn:programmable-logic:tutorials:genesys-zu-demo-hello-world:import_vitis_project_type_2020_1_8.png?600|}}
</WRAP> </WRAP>
----
<WRAP group> <WRAP column half>
After the build, an error should be reported into the console regarding the missing platform fsbl.elf file.
</WRAP> <WRAP column half>
{{ :learn:programmable-logic:tutorials:genesys-zu-demo-hello-world:import_vitis_project_type_2020_1_9.png?600|}}
</WRAP> </WRAP>
----
<WRAP group> <WRAP column half>
Browse for the //*_fsbl.elf// file. The hw platform comes without generating its boot components, so the user needs to manually select a valid boot elf file. Double click on platform.spr and browse to the fsbl.file. The fsbl.elf file should be located in your workspace directory in: *_fsbl/Debug/*_fsbl.elf if the project configuration was set on //Debug// or *_fsbl/Release/*_fsbl.elf if the project configuration was set on //Release//. Right click on the *_hw_pf project and select //Build Project//.
</WRAP> <WRAP column half>
{{ :learn:programmable-logic:tutorials:genesys-zu-demo-hello-world:import_vitis_project_type_2020_1_10_1.png?600|}}
</WRAP> </WRAP>
----

<WRAP group> <WRAP column half>
Next we have to build the *_master project, and for that we have to set the path for the lscript.ld. Right-click on *_master.prj and select //Properties//. Go to //C/C++ Build// and double click on //Settings//, then single-click on //Linker Script// from the ARM v8 gcc linker tool. Modify the Linker Script path to //../src/lscript.ld//.
</WRAP> <WRAP column half>
{{ :learn:programmable-logic:tutorials:genesys-zu-demo-hello-world:import_vitis_project_type_2020_1_16_1.png?600|}}
</WRAP> </WRAP>
----
<WRAP group> <WRAP column half>
Right-click on *_master_system project and select //Build Project//.
</WRAP> <WRAP column half>
{{ :learn:programmable-logic:tutorials:genesys-zu-demo-hello-world:import_vitis_project_type_2020_1_17_1.png?600|}}
</WRAP> </WRAP>
----
<WRAP group> <WRAP column half>
The build should take a couple of seconds.
</WRAP> <WRAP column half>
{{ :learn:programmable-logic:tutorials:genesys-zu-demo-hello-world:import_vitis_project_type_2020_1_18_1.png?600|}}
</WRAP> </WRAP>
----
<--

--> Set up the Genesys ZU #

--> Set up the Genesys ZU-5EV#
Plug the microUSB programming cable into the Genesys ZU-5EV's PROG/UART port.
<--


--> Set up the Genesys ZU-3EG#
Plug the microUSB programming cable into the Genesys ZU-3EG's PROG/UART port.
<--
<--
--> Launch the Vitis Baremetal Software Application#

<WRAP group> <WRAP column half>
First, many applications require that a serial console is connected to the board, so that standard output (from print statements) can be viewed. For this purpose, a serial terminal should be used. Use a serial terminal application to connect to the board's serial port. Unless otherwise stated, Zynq designs use a baud rate of 115200 and Microblaze designs with an AXI UART Lite IP use a baud rate of 9600.

**Note:** //While Vitis has a built in serial terminal included in its Debug view, it sends characters to a board on a line-by-line basis. Some software examples require the use of character-by-character reception of data. [[https://ttssh2.osdn.jp/index.html.en|Tera Term]] or [[https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html|PuTTY]] are recommended if you are not sure what will work.//
</WRAP> <WRAP column half>
{{ :learn:programmable-logic:tutorials:2020.1:launch-vitis-application:set-baud.png?600 |}}
</WRAP> </WRAP>
----
<WRAP group> <WRAP column half>
In the //Explorer// pane at the left side of the screen, right click on the application or system project that is to be run, and select //Run as -> 1 Launch on Hardware //. The FPGA will be programmed with the bitstream, the ELF file previously selected is loaded into system memory, and the application project will begin to run. You will need to click back over to the //Vitis Serial Terminal// from the //Console// tab.

**Note:** //Once the project has been run at least once, you can use the green run button ({{:learn:programmable-logic:tutorials:2020.1:launch-vitis-application:run-button.png?nolink|}}) in the toolbar at the top of the screen to program the board instead.//
</WRAP> <WRAP column half>
{{ :learn:programmable-logic:tutorials:genesys-zu-demo-hello-world:import_vitis_project_type_2020_1_19.png?600|}}
</WRAP> </WRAP>
<--
----
At this point, the demo is now running on your board. Refer to the [[#description|Description]] section of this document for more information on what it does.
----
Additional steps beyond here present how you can use the other archive provided in the release, containing the hardware project, to rebuild the Vivado project, and use a newly exported XSA file to update the platform in Vitis.
----

{{page>programmable-logic:guides:using-github-releases#baremetal_update_specification&noheader}}

<WRAP center round important 100%>
After every Platform Specification update, please make sure you follow these steps, to ensure the Platform Specification changes are correctly applied to your software project:
  -  Open [3eg|5ev]_hw_pf -> platform.spr and make sure the FSBL file location is correctly set ([..]\ws\[3eg|5ev]_fsbl\Release\[3eg|5ev]_fsbl.elf).
  - Right click on [3eg|5ev]_hw_pf and select Update Hardware Specification. Make sure the path is correct ([..]/sw/src/[3eg|5ev]_hw_pf/system_wrapper.xsa).
  - Right click on [3eg|5ev]_hw_pf and select Build Project.
  - Right click on [3eg|5ev]_boot and select Build Project.
  - Genesys ZU workspaces externalize FSBL into a stand-alone application project to work around the wrong FSBL BSP optimization flag bug when it is generated as part of a hardware platform project. The ZynqMP FSBL is a template project that gets recreated upon checkout with local copies of sources from the local "embeddedsw" fork and the hardware platform. The "psu_init.*" files are copied and not linked from the platform. Therefore, after every platform specification update the "psu_init.*" files in [3eg|5ev]_fsbl/src need to be manually overwritten from the built platform project directory [3eg|5ev]_hw_pf/export/[3eg|5ev]_hw_pf/hw/.
  - Right click on [3eg|5ev]_boot and select Build Project.
  - If you still encounter an error saying that fsbl.elf is not found, copy the [..]\ws\[3eg|5ev]_fsbl\Release\[3eg|5ev]_fsbl.elf file to [..]\ws\[3eg|5ev]_hw_pf\export\[3eg|5ev]_hw_pf\sw\[3eg|5ev]_hw_pf\boot\, renaming it to fsbl.elf and overwriting the existing file, if it does exist. Then right click on [3eg|5ev]_boot and select Build Project again.
  - Right click on [3eg|5ev]_master_system and select Build Project.
</WRAP>

</WRAP>
<--
----
===== Functionality =====

==== 1. Serial Terminal ====

The "Hello World" and "Successfully ran Hello World application" messages should appear on the serial terminal. 
 

===== Additional Resources =====

All materials related to the use of the Genesys ZU can be found on its [[learn:programmable-logic:tutorials:start|Resource Center]].

For a walkthrough of the process of creating a simple HDL project in Vivado, see [[programmable-logic:guides:getting-started-with-vivado]]. Information on important parts of the GUI, and indirect discussion of the steps required to modify, rebuild, and run this demo in hardware can also be found here.

For technical support, please visit the [[https://forum.digilent.com/forum/4-fpga/|FPGA]] section of the Digilent Forum.

{{tag>learn programmable-logic project genesys-zu}}