~~TechArticle~~
====== Using a Digilent FPGA Github Demo's Releases (2020.1) ======

<WRAP round important>
==Warning==
This page is for internal use only. It is intended to be embedded within other wiki pages and does not provide the full context necessary to use these steps
</WRAP>

===== Hardware Only Release (Before Programming) =====
**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 and extract the '*.xpr.zip' file from the demo release, linked above.
----
--> Open a Vivado Project from a Release #
<WRAP group>
{{page>programmable-logic:guides:vivado-launch&showheader}}

<WRAP group>
<WRAP column half>
In Vivado's welcome screen, use the **Open Project** button to navigate to and open the XPR file contained in the folder the release was extracted into.
</WRAP> <WRAP column half>
{{ :learn:programmable-logic:tutorials:2020.1:using-releases:choose-xpr.png?600 |}}
</WRAP> </WRAP>
----
</WRAP>
<--
--> Build a Vivado Project #
<WRAP group>
Note that if your project already has a generated bitstream, as indicated by the status in the top right corner of the window reading "write_bitstream Complete!", then you can skip this section.

{{ :programmable-logic:guides:write-bitstream-complete.png |}}

{{section>programmable-logic:guides:getting-started-with-vivado#generate_a_bitstream&showheader}}
</WRAP>
<--
===== Hardware Only Release (Programming) =====
--> Program a Bitstream onto an FPGA Board #
<WRAP group>
{{page>programmable-logic:guides:vivado-hardware-manager}}
</WRAP>
<--

===== Baremetal Release (Before Programming, XSCT Scripts) =====

**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 '*-hw.xpr.zip' and "Software source archive" files from the demo release, linked above. Note that the hardware is included in the Assets list, while the software is linked from the description of the release. 

The hardware (-hw) 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 software archive contains the software sources, hardware description file (XSA), and a set of scripts that can be used to rebuild the workspace.

Both files should be extracted.

**Note:** //You may notice "-sw" archives in the release's downloads list. These importable archives should be ignored - a bug in Vitis 2020.1 prevents their use in some situations, and as such, the scripted method here is to be used instead.//

----	

--> Recreate a Vitis Workspace from Source #
<WRAP group>
**Important:** //When selecting a workspace to open Vitis into, the use of the extracted software archive's "ws" folder is recommended. The use of this folder simplifies the process of invoking the script that recreates the projects.//

{{page>programmable-logic:guides:vitis-launch&noheader}}

<WRAP group> <WRAP column half>
With Vitis open, in the menu bar at the top of the window, use the **Xilinx -> XSCT Console** option to launch the Xilinx Software Command-line Tool.
</WRAP> <WRAP column half>
{{ :reference:programmable-logic:guides:using-releases:open-xsct.png?600 |}}
</WRAP> </WRAP>
----
<WRAP group> <WRAP column half>
In the XSCT Console, if you used the software archive's ws folder, enter the command below to run a script that recreates each of the projects and platforms associated with the demo from their sources.
<code>source [getws]/../src/checkout.tcl</code>

If you did not use the ws folder, find the path to the extracted archive, and enter the commands below. Note that all slashes in the path must be forward slashes ("/") or the entire path must be enclosed in curly braces ("{}").
<code>source (path to software)/src/checkout.tcl</code>

The checkout process may some time, though not more than a few minutes, as the projects are recreated and built. When complete, the "xsct%" prompt will reappear.
</WRAP> <WRAP column half>
{{ :reference:programmable-logic:guides:source-checkout.png?600 |}}
</WRAP> </WRAP>
----
</WRAP>
<--

===== Baremetal Release (Before Programming) =====

**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, 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//, then navigate to and select the IDE zip file you downloaded.
</WRAP> <WRAP column half>
{{ :learn:programmable-logic:tutorials:2020.1:using-releases:import-project.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:2020.1:using-releases:select-all.png?600 |}}
</WRAP> </WRAP>
----
</WRAP>
<--

--> Build a Vitis Application #
<WRAP group>
{{page>programmable-logic:guides:vitis-build-software&noheader}}
</WRAP>
<--

===== Baremetal Release (No Build) =====

**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, 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//, then navigate to and select the IDE zip file you downloaded.
</WRAP> <WRAP column half>
{{ :learn:programmable-logic:tutorials:2020.1:using-releases:import-project.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:2020.1:using-releases:select-all.png?600 |}}
</WRAP> </WRAP>
----
</WRAP>
<--

===== Baremetal Release (No Build, Direct File Download) =====

**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, 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//, then navigate to and select the IDE zip file you downloaded.
</WRAP> <WRAP column half>
{{ :learn:programmable-logic:tutorials:2020.1:using-releases:import-project.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:2020.1:using-releases:select-all.png?600 |}}
</WRAP> </WRAP>
----
</WRAP>
<--
===== Baremetal Release (Programming) =====
--> Launch a Vitis Application #
<WRAP group>
{{page>programmable-logic:guides:vitis-launch-app&noheader}}
</WRAP>
<--
===== Baremetal Update Specification =====
In order to modify and switch out the hardware platform for a baremetal demo, you should first open the Vivado project from the release. Extract the previously downloaded '*.xpr.zip' file.
----
--> Open a Block Design Project in Vivado #
<WRAP group>
{{page>programmable-logic:guides:vivado-launch&showheader}}

<WRAP group> <WRAP column half>
In Vivado's welcome screen, use the **Open Project** button to navigate to and open the XPR file contained in the folder the release was extracted into.
</WRAP> <WRAP column half>
{{ :learn:programmable-logic:tutorials:2020.1:using-releases:choose-xpr.png?600 |}}
</WRAP> </WRAP>
----
<WRAP group> <WRAP column half>
The project's block diagram, which contains the design, with all of the existing components and their connections, can be opened by either double-clicking on the "*.bd" file in the sources pane (which also includes other source files, such as constraints), or by clicking the **Open Block Design** button in the //Flow Navigator// pane.
</WRAP> <WRAP column half>
{{ :learn:programmable-logic:tutorials:2020.1:using-releases:open-bd.png?600 |}}
</WRAP> </WRAP>
----
Making changes to the design is out of the scope of this particular document. More information on how to use IP Integrator to create or modify a project can be found through [[programmable-logic:guides:getting-started-with-ipi]]. The remainder of this document will discuss how to generate a bitstream, export a new hardware platform, and load it into Vitis.
----
{{page>programmable-logic:guides:vivado-validate-block-design}}
</WRAP>
<--
--> Build a Vivado Project #
<WRAP group>
{{page>programmable-logic:guides:vivado-generate-bitstream}}
</WRAP>
<--
--> Export a Hardware Platform #
<WRAP group>
{{page>programmable-logic:guides:vivado-export-fixed-platform}}
</WRAP>
<--
--> Update a Hardware Platform in Vitis #
<WRAP group>
{{page>programmable-logic:guides:vitis-update-hardware-specification}}
</WRAP>
<--

===== Petalinux Release (Before Programming) =====
**Note:** //This workflow is common across many Digilent Petalinux 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 '*.bsp' file from the demo release, linked above.
----
--> Open a Petalinux Project from a Release #
<WRAP group>
Open a terminal and run the following commands. The install path is /opt/pkg/petalinux/ as exemplified in [[https://docs.xilinx.com/v/u/2020.1-English/ug1144-petalinux-tools-reference-guide|UG1144 v.2020.1]]. This will set up the Petalinux environment for this terminal only.
<code>
source <path-to-installed-PetaLinux>/settings.sh
</code>
----
<WRAP group>
<WRAP column half>
In the same terminal navigate to the desired project folder and create the Petalinux project using the '*.bsp' by executing the following command. The resulting folder structure will contain a **pre-built** folder which has the necessary boot binaries for the current Demo
<code>
cd <path-to-project-folder>
petalinux-create -t project -s <path-to-bsp>
</code>
</WRAP> <WRAP column half>
{{:reference:programmable-logic:guides:bsp_folders.png?600|}}
</WRAP> </WRAP>
----
</WRAP>
<--
--> Build a Petalinux Project #
<WRAP group>
In order to rebuild the project without changing anything in the configuration, first navigate to the root of the Petalinux project using the terminal which has the Petalinux environment set up. 

**Note:** //If the Petalinux environment is not set up it will not recognize the petalinux-* commands.//

The root folder will contain the following folders and file: components, project-spec, //pre-built (optional)//, config.project. Once in this folder execute the build command. This will start building the Petalinux project based on the current configuration. The execution time of the build command will depend on PC performance, project complexity, execution iteration (it takes longer for a clean project to build). Depending on the project complexity after the build, the project folder might take several GB of free space.
<code>
petalinux-build
</code>

After the build completion, the Boot.bin has to be explicitly built in order to have a Second Stage Boot Loader (SSBL) from Petalinux. This can be obtained by executing the command below from the root folder.

**Note:** //<zynq_type> may vary depending on Zynq7000 or Zynq Ultra Scale//

<code>
petalinux-package --boot --force --fsbl images/linux/<zynq_type>_fsbl.elf --fpga images/linux/system.bit --u-boot
</code>
----
</WRAP>
<--
===== Petalinux Release (Programming) =====
--> Booting Petalinux on a Zynq Board #
<WRAP group>
Copy the **BOOT.BIN, boot.scr, image.ub** files from the //<path-to-project-folder>/images/linux// or the //<path-to-project-folder>/pre-built// folder onto a FAT32 formatted MicroSD Card. Once this has been done, safely remove the SD Card from the PC and slide it into the development board's MicroSD Card slot. Make sure that the board is set up to boot from SD Card.

**Note:** //Some projects might contain an extra file,// **uEnv.txt**//, which should be added to the SD Card//

Boot up the board and set up your preferred serial console to listen on the serial port using the default baud rate of 115200. On the console, you should be able to see the boot-up sequence of the board starting from U-Boot (SSBL) up to the login prompt of Linux. 

**Note:** //The default login username and password is// **root:root**
</WRAP>
----
<--
===== Petalinux Configurations =====

**Note:** //This a brief summary of what Petalinux can do. For more details please refer to the [[https://docs.xilinx.com/v/u/2020.1-English/ug1144-petalinux-tools-reference-guide|UG1144 v.2020.1]]//

There are some components that can be modified in Petalinux in order to customize your Linux environment. These include the user space application, kernel drivers, u-boot configuration, generic Petalinux settings, and Hardware update components. Most of these changes can be done by executing the //petalinux-config// command with different parameters.

**Note:** //By using petalinux-config -c <COMPONENT> the component changes will be stored in the workspace directory (<project-root-dir>/components/yocto/workspace). To apply workspace changes to the recipe in the meta-user, the user must run the -x finish command to return their build location, for example, "petalinux-build -c <COMPONENT> -x finish".//

----
--> Making Hardware Changes and Adding Them to Petalinux #
<WRAP group>
In order to modify and switch out the hardware platform for a baremetal demo, you should first open the Vivado project from the release. Extract the previously downloaded '*.xpr.zip' file. Exporting the Vivado project for Petalinux is the same as exporting it for Vitis, therefore the instructions are identical.
----
--> Open a Block Design Project in Vivado #
<WRAP group>
{{page>programmable-logic:guides:vivado-launch&showheader}}

<WRAP group> <WRAP column half>
In Vivado's welcome screen, use the **Open Project** button to navigate to and open the XPR file contained in the folder the release was extracted into.
</WRAP> <WRAP column half>
{{ :learn:programmable-logic:tutorials:2020.1:using-releases:choose-xpr.png?600 |}}
</WRAP> </WRAP>
----
<WRAP group> <WRAP column half>
The project's block diagram, which contains the design, with all of the existing components and their connections, can be opened by either double-clicking on the "*.bd" file in the sources pane (which also includes other source files, such as constraints), or by clicking the **Open Block Design** button in the //Flow Navigator// pane.
</WRAP> <WRAP column half>
{{ :learn:programmable-logic:tutorials:2020.1:using-releases:open-bd.png?600 |}}
</WRAP> </WRAP>
----
Making changes to the design is out of the scope of this particular document. More information on how to use IP Integrator to create or modify a project can be found through [[programmable-logic:guides:getting-started-with-ipi]]. The remainder of this document will discuss how to generate a bitstream, export a new hardware platform, and load it into Vitis.
----
{{page>programmable-logic:guides:vivado-validate-block-design}}
</WRAP>
<--
--> Build a Vivado Project #
<WRAP group>
{{page>programmable-logic:guides:vivado-generate-bitstream}}
</WRAP>
<--
--> Export a Hardware Platform #
<WRAP group>
{{page>programmable-logic:guides:vivado-export-fixed-platform}}
</WRAP>
<--
--> Importing the New Hardware #
<WRAP group>
<WRAP column half>
In order to import the new hardware description to Petalinux, the following command must be executed. This will prompt a configuration window where all the new Zynq generic changes for the new hardware will be visible.
<code>
petalinux-config --get-hw-description=<path-to-new-xsa>
</code>
Other changes which can be configured from this window are: boot-flow, default password, FPGA reconfiguration, image packaging, and other important settings. This window can also be accessed by simply executing //petalinux-config// without any parameters.
<code>
petalinux-config
</code>
</WRAP><WRAP column half>
{{:reference:programmable-logic:guides:petalinux-config.png?600|}}
</WRAP></WRAP>
----
<--
</WRAP>
<--
--> Configuring U-boot #
<WRAP group><WRAP column half>
When first importing the hardware, some U-boot customization is generated by the import feature. U-boot customization includes drivers for boot mediums, file system support, boot console arguments, network support, and many more. In order to bring up the configuration window, the following command must be executed.
<code>
petalinux-config -c u-boot
</code>
</WRAP><WRAP column half>
{{:reference:programmable-logic:guides:petalinux-config_u-boot.png?600|}}
</WRAP></WRAP>
----
<--
--> Configuring the Kernel #
<WRAP group><WRAP column half>
When first importing the hardware, some kernel customization is generated by the import feature, which usually includes supported drivers for PL IPs. U-boot customization includes drivers for drivers, logging levels, debugging flags, and many more. In order to bring up the configuration window, the following command must be executed:
<code>
petalinux-config -c kernel
</code>
</WRAP><WRAP column half>
{{:reference:programmable-logic:guides:petalinux-config_kernel.png?600|}}
</WRAP></WRAP>
----
<--
--> Configuring the RootFS #
<WRAP group><WRAP column half>
The packages which will be built into the rootfs need to be added manually by the user. The default package manager for Petalinux currently is RPM and any additional packages which the user wants to add need to be built using Petalinux. In order to bring up the configuration window, the following command must be executed:
<code>
petalinux-config -c rootfs
</code>
</WRAP><WRAP column half>
{{:reference:programmable-logic:guides:petalinux-config_rootfs.png?600|}}
</WRAP></WRAP>
----
<--
--> Changes to the Device Tree #
<WRAP group>
When first building the project by executing //petalinux-build// or if you are using the *.bsp version of the project, the generated device tree will be available in //<path-to-project-folder>/components/plnx_workspace/device-tree/device-tree//. Any changes to this folder will be overwritten at the next build. In order to make permanent changes, the //<path-to-project-folder>/project-spec/meta-user/recipes-bsp/device-tree/files/*.dtsi// need to be changed. 

**Note:** //Changes to the device tree components will have to be done by referring to the already existing nodes in the auto-generated device trees.//
----
</WRAP>
<--
<WRAP round important>
==Warning==
After configuring some of the previous settings might be lost. This is a known issue in Petalinux 2019.2 and 2020.1; more information about the workaround can be found here: [[https://support.xilinx.com/s/question/0D52E00006iHqLBSA0/20201-kernel-config-always-overwritten|Xilinx Support Case]]
</WRAP>
----
===== Baremetal Release Workaround (Before programming) =====
--> Apply Fix for Linker Script Import Bug #
<WRAP round important>
Due to a bug in some versions of Xilinx's Vitis IDE, two more steps are needed for the project to import correctly. If your projects build without errors, ignore this section.
</WRAP>
<WRAP group><WRAP column half>
After importing the project, open the **.sprj** file. In the System Project Settings, select a platform by clicking on the **''...''** icon, as shown in the image. Select the platform presented and click Ok. 
</WRAP><WRAP column half>
{{:reference:programmable-logic:guides:workaround1.png?600|}}
</WRAP></WRAP>
----
<WRAP group><WRAP column half>
Right click on the **.prj** file and select **Properties**. In the opened window, go into **C/C++ Build** and select **Settings**, as shown in the image. After opening the Settings tab, select **Linker Script** and change the existing path to ''../src/lscript.ld''. Click Apply and Close.

The project is now imported correctly.
</WRAP><WRAP column half>
{{:reference:programmable-logic:guides:workaround2.png?600|}}
</WRAP></WRAP>
----
<--