Getting Started with AMD Spartan™ 7 FPGA in Vitis™ 2023.2

In my previous two project posts on getting started with the AMD Spartan™ 7 SP701 FPGA development board with the 2023.2 version of the AMD FPGA tools, I outlined how to create a base hardware design for the SP701 in Vivado and how to build the corresponding Linux image to run on it using PetaLinux. This project post follows up those with the process of using the new Vitis Unified IDE to develop and debug software applications to run on the Linux OS of the SP701.

This project series is specific to the 2023.2 version of the AMD FPGA toolset. I'm using an Ubuntu 22.04 host development environment, for which I've documented the entire 2023.2 AMD FPGA tools installation process here.

Create New Workspace

The AMD Vitis™ Unified IDE can be launched directly from the AMD Vivado™ IDE by selecting the Tools menu then Launch Vitis IDE. Or it can be launched from the command line in Linux:

~$ source /tools/Xilinx/Vitis/2023.2/settings64.sh
~$ vitis

A project in Vitis is contained to a directory referred to as a workspace. When Vitis is launched initially, a workspace has to be selected as the target working directory.

When creating a new project in the Vitis Unified IDE, while there isn't a specific option to create a new workspace, the option to Open Workspace is still selected:

Then the desired directory can be created and/or selected with the file explorer.

Personally, I prefer to organize my project files such that both the PetaLinux project and the Vitis workspace are located in the top level of the corresponding Vivado project directory.

So I always create a folder titled "vitis_workspace" in the top level of the corresponding Vivado project directory.

Create Platform Component

For those familiar with AMD Vitis™ Classic IDE, the overall workflow of creating a platform project to pull in all of the settings from the XSA file exported from Vivado followed by creating the application project for the software is still the same. One of the biggest differences in the new Vitis Unified IDE however is that the term "project" has been replaced with the term "component".

Therefore, the first thing to do in a new Vitis workspace is to create a new platform component to pull in all of the settings from the XSA file exported from Vivado.

Since I'm developing a Linux-based application, a bit of directory prep work needs to be done by creating the local copy of the SP701's working directory and extracting the sysroot into it built by PetaLinux for Vitis to use to build the application source code against.

Create a directory to extract the sysroot to, as well as directories to act as the boot and root directories.

~$ cd ./sp701_prj/xilinx-sp701-2023.2/
~/sp701_prj/xilinx-sp701-2023.2$ mkdir -p sysroot
~/sp701_prj/xilinx-sp701-2023.2$ cd ./sysroot
~/sp701_prj/xilinx-sp701-2023.2/sysroot$ mkdir -p pfm
~/sp701_prj/xilinx-sp701-2023.2/sysroot$ cd ./pfm
~/sp701_prj/xilinx-sp701-2023.2/sysroot/pfm$ mkdir -p boot
~/sp701_prj/xilinx-sp701-2023.2/sysroot/pfm$ mkdir -p root

Then source the PetaLinux tools to the environment and extract sysroot to target directory:

~/sp701_prj/xilinx-sp701-2023.2$ source /tools/Xilinx/PetaLinux/2023.2/settings.sh
~/sp701_prj/xilinx-sp701-2023.2$ cd ./images/linux/
~/sp701_prj/xilinx-sp701-2023.2/images/linux$ ./sdk.sh -d ../../sysroot/

With the sysroot in place, create a new platform component in Vitis by selecting Create Platform Component:

Give the platform component the desired name:

Then point it to the corresponding hardware definition XSA file that was exported from the SP701's Vivado project:

Select Linux for the Operation System and MicroBlaze for the target Processor:

Review the selections on the summary page and click Finish to generate the platform component.

It's always a good idea to run a quick build on a newly created platform component just to generate those initial output files and make sure there are no gross errors. But first, the platform needs to be pointed to the SP701's working directory on the host along with it's device tree file generated by PetaLinux.

Open the platform's vitis-comp.json file under platform component name > mircroblaze > Linux on mircroblaze then fill in the following (substituting custom file directory names if different from what I chose):

• Bif file: N/A
• Pre-Built Image Directory: ~/sp701_prj/xilinx-sp701-2023.2/sysroot/pfm/boot
• DTB File: ~/sp701_prj/xilinx-sp701-2023.2/images/linux/system.dtb
• FAT32 Partition Directory: ~/sp701_prj/xilinx-sp701-2023.2/sysroot/pfm/root
• Qemu Data: ~/sp701_prj/xilinx-sp701-2023.2/sysroot/pfm/boot
• Qemu Args File: N/A
• Pmu Args File: N/A

Then build the platform component by clicking Build in the Flow window.

Create Application Component

With the platform component completed, the next step is to create the application component for the software application that will be running on the SP701.

Select File > New Component > Application

Give the application component the desired name:

And point it to the platform component created in the previous step:

Since there is only the one Linux domain in the platform component, it will be the only domain option to select for the application component:

The platform component was pointed to the host's recreated boot/root directories and the device tree file, the application component is pointed to the sysroot extracted with that directory. For the MicroBlaze processor, that is the microblazeel-v11.0-bs-cmp-re-mh-div-fb-xilinx-linux directory.

Sysroot: ~/sp701_prj/xilinx-sp701-2023.2/sysroot/sysroots/microblazeel-v11.0-bs-cmp-re-mh-div-fb-xilinx-linux

Again, review the selections on the summary page and click Finish to generate the application component.

Once the application competent has generated, I recommend running an initial build before making any changes to get the initial output files and verify there are no gross errors.

If you forget to build the platform component first like I did initially, a warning will pop up stating that the platform will be built prior to the application component:

The source files for the application component live in the ./vitis_workspace/applicaiton component name/Sources/src directory. So any additional C or header source files need to be placed here for your application.

Debug Application on Hardware

Once the application builds successfully, the easiest debug route to utilize is to launch a debug run on hardware. To debug on hardware, first boot SP701 with Linux image running on it that the sysroot is based on.

Connect the SP701 to local network via the Ethernet 1 J9 port on the board, and connect it to the host PC via the USB/JTAG J5 port as shown:

Then connect to the SP701 from the Vitis Unified IDE. Under the Vitis menu, select Target Connections...

Select Linux Agent (Default) - (double-click).

Connect the Linux TCF agent to the local address of the SP701 as the Host.

They verify using the Test Connection option before clicking OK to close the window.

To launch a debug run of an application in the new Vitis Unified IDE, set the application as the target component in the Flow window. A single-click on the word Debug will launch the debug run.

If any settings need to be adjusted to the debug configuration, hover over the word Debug which will cause a gear icon to appear.

A single-click on the gear icon will open the debug run configuration window (its launch.json file).

I found that in the debug run configuration (launch.json), the default Work Directory where Vitis launches the application in, does not exist in my SP701 Linux image that I built in PetaLinux.

This resulted in a super generic error when I tried to launch a debug run saying "Cannot download program file" in the Debug Console and the Vitis Server said "ERROR: An error while reading the project at '~/sp701_prj/vitis_workspace/hello_linux'."

The default is /run/media/mmcblk0p1, I changed it to just /media for use in my SP701 Linux image as that was the closest similar directory that existed (which I verified by checking in the sysroot directory and from the serial terminal connected to the SP701).

Once I had updated the Work Directory where Vitis launches the application in on the SP701, I was able to launch a debug run. This switched Vitis Unified over to the debug view where the application can be stepped through as usual.

Once complete, click the red square to disconnect the run. Then click the house icon to return to the regular development view.

Add Application to PetaLinux Project

Once the application is completed and debugged, the final step is to add it back into the PetaLinux project for the SP701 so that it is built into its Linux image.

Use the petalinux-create command with apps option passed to the -t flag. Since the application was written in C, I specified that in the application using the --template flag.

The application must also have the desired name specified with the --name flag.

The --enable flag automatically includes the application in the next build run without have to manually configure it in the root filesystem configuration editor.

~/sp701_prj/xilinx-sp701-2023.2$ petalinux-create -t apps --template c --name hello-linux --enable

Since this creates a generic application, the actual code from the application developed in Vitis Unified IDE needs to be moved into the PetaLinux project directory. In this case, that means the source code from the Vitis workspace in "hello world.c" needs to be copied to the main source file in the created application in PetaLinux "hello-linux.c".

Since the file name in the apps recipe needs to match everything (ie - all be "hello-linux), that's why I just copied the contents of "hello world.c" into "hello-linux.c":

~/sp701_prj/xilinx-sp701-2023.2$ cp ../vitis_workspace/hello_linux/src/helloworld.c ./project-spec/meta-user/recipes-apps/hello-linux/files/hello-linux.c

If your application has any additional C or header source files, also copy them to the application file directory in the PetaLinux apps recipe (which in this case would be ./project-spec/meta-user/recipes-apps/hello-linux/files/) and add them to the bitbake file for the application (which in this case would be ./project-spec/meta-user/recipes-apps/hello-linux/hello-linux.bb).

Once all of the source code has been added to the application and bitbake file updated in the apps recipe, the PetaLinux project needs to be rebuilt:

~/sp701_prj/xilinx-sp701-2023.2$ petalinux-build

At this point, the same steps to create a new boot binary and program the QSPI flash on the SP701 can be followed as in the previous PetaLinux tutorial starting here.

This wraps up my getting started series for the Spartan 7 and MicroBlaze in the AMD toolset version 2023.2.

Disclaimer/Disclosure

Whitney Knitter is an independent engineer, hired as an independent contractor by AMD. Although AMD sponsored this project write-up, including engineering hours and writing production, the opinions expressed are those of Whitney Knitter, which may not reflect the positions, strategies, or opinions of AMD. GD-5.

AMD, the AMD Arrow logo, Spartan, Vitis, Vivado, and combinations thereof are trademarks of Advanced Micro Devices, Inc. Other product names are for identification purposes only and may be trademarks of their respective owners.