Name	Name	Last commit message	Last commit date
parent directory ..
images	images
scripts	scripts
src	src
README.md	README.md

Debugging Linux Applications

Version: Vitis 2023.2

The AMD Vitis™ IDE provides a familiar environment for debugging Linux applications for a target platform. This section covers the following Linux application debug features:

Setting breakpoints
Stepping through program execution
Viewing program variables, memory contents, and the stack

The following diagram illustrates the general Linux application debug flow. The Vitis Debugger an integrated debugger supporting AMD Zynq™ 7000 SoC, AMD Zynq™ UltraScale+™ MPSoC, and MicroBlaze™ and AMD Versal™ processors.

Note: Refer to the Appendix section for supplementary information about creating a hardware design and building software boot images.

Limitations

Xen aware and OS aware debugging is not supported in Vitis Unified IDE 2023.2. If you require this feature, then it is recommended that you use Vitis Classic 2023.2.

Getting Started

Linux debug setup is a mandatory step. Setup allows you to create platform and application projects in the Vitis IDE.

Open a terminal and navigate to your desired work directory.
Copy scripts/petalinux_build.sh to your desired working directory; for example, linux_debug/petalinux_prj.
Source the PetaLinux tool.
Follow the steps in the PetaLinux Build section to complete the PetaLinux build and configuration manually.
Note: You can skip the manual steps by using the automated petalinux_build.sh script to generate Linux images. However, make sure to select the appropriate configuration whenever prompted.
Navigate to zcu102 in your AMD Vivado™ project and copy mpsoc_preset_wrapper.xsa to your desired Vitis work directory (in the following example, it is vitis_work_dir) as zcu102.xsa.
```
$ cd zcu102/mpsoc_preset_wrapper.xsa
$ cp mpsoc_preset_wrapper.xsa vitis_work_dir/zcu102.xsa
```
Note: If you create a custom ZCU102 XSA by following the steps in Vivado Design, you can use it as it is here.

Create the sysroot

$ cd xilinx-zcu102-2023.2/images/linux
$ ./sdk.sh

Note: When prompted for the Enter target directory for SDK, enter the path to vitis_work_dir

Copy scripts/unified_workspace.py to your Vitis work directory (in this example, vitis_work_dir) as you did for zcu102.xsa. Copy src/linux_test_application.c to vitis_work_dir/src. These files are required to set up the Vitis workspace. Your Vitis work directory should be structured like the example below after downloading these files.
```
vitis_work_dir
|
|_ zcu102.xsa
|
|_ unified_workspace.py
|
|_ sysroot
|  |
|  |_ cortexa72-cortexa53-xilinx-linux
|  |
|  |_ x86_64-petalinux-linux
|
|_ src
  |
  |_ linux_test_application.c
```
Run the Vitis-workspace.py script for workspace setup in Vitis Unified CommandLine Interface (CLI). After successful execution of the script, a Vitis worskpace named linux_debug_ws is created with a ZCU102 based platform and a Linux test application.
```
vitis_work_dir
|
|_ zcu102.xsa
|
|_ vitis-workspace.py
|
|_ src
|   |
|   |_ linux_test_application.c
|
|_ linux_debug_ws
```
Launch the Vitis IDE linux_debug_ws workspace.

Error 1: Failed in Validating the test connection

In the Vitis workspace under FLOW, select the Build and click the Open Settings icon to open the Launch Configurations.
Select Debug icon

Setting Up the Ethernet Connection

Select the settings based on your connection

Connecting to Physical Board

Set your host machine's Ethernet address to a static IP (suggested: 192.168.1.10).
Using the serial terminal, configure the board's IP address to 192.168.1.11:
```
ifconfig eth0 192.168.1.11
```
Note: This can be any address other than the one that the host is configured to on the same Subnet LAN.
Ping the host machine using the terminal to verify connectivity.
```
ping 192.168.1.10 –c 1
```

Connecting to QEMU

Petalinux supports the Quick EMUlation (QEMU) emulator. This is useful if you do not have access to Physical board. You can use the following steps to boot Linux on the QEMU. You can pass qemu-args to pass the network information. The hardware used in this tutorial is for a ZCU102 which has the GEM enabled at GEM3. This command will look slightly different GEM is used.

The hostfwd definitions along with user network arguments, that is , -net nic -net nic -net nic -net nic,vlan=1 -net user,vlan=1) hostfwd=tcp:<host address>:<host port used for forwarding>-<guest address>:<guest port>

petalinux-boot --qemu --kernel --qemu-args "-net nic -net nic -net nic -net nic,netdev=gem3 -netdev user,id=gem3,hostfwd=tcp:127.0.0.1:1540-10.0.2.15:1534"

Note Use Ctrl A + x to exit the QEMU

Setting Up the TCF Agent

Physical Board Linux Agent

Vitis -> Target Connections.
Right click on Linux TCF Agent option and select New Target.
Change the host IP address to localhost or 127.0.0.1.
change the Port to 1540
Click OK.

QEMU Linux Agent

Vitis -> Target Connections.
Right click on Linux TCF Agent option and select New Target.
Change the host IP address to 192.168.1.11.
Click OK.

Error 2: Multithread Application Debug

Enable the _ERROR5_ macro in the application source file linux_test_application.c and disable _ERROR3_ and _ERROR6_ as shown below.

//#define _ERROR3_
#define _ERROR5_
//#define _ERROR6_

The goal of multithread application debugging is to make the application thread-safe. You need to debug the application and identify the locations to protect read/write operations.

Under FLOW, highlight the linux_test_app, and Build.
Under FLOW, highlight the linux_test_app, and Debug to launch a Launch Configuration.
Select, the Target Connection; either physical_zcu102, or qemu_zcu102 and the Work Directory to /home/petalinux`

The code stops at the program entry. There are various debugging techniques such as breakpoints, stepping, and so on to identify the data that must be protected. This example will use the breakpoint inside thread function.

Put a breakpoint at below two lines.

printf("\n Job %d started\n", counter);
.......
.......
printf("\n Job %d finished\n", counter);

Click Resume and check the Job ID printed in the console. Here, the job to be done is not thread-safe.
Open the Variables view to track the counter variable value.
Use a synchronization mechanism (mutex, for example) to ensure that two or more concurrent threads do not simultaneously execute read/writes.

Uncomment the mutex code lines listed below from the application to make it thread-safe.

............................
............................

#ifdef _ERROR5_
void* doSomeThing(void *arg)
{
  //  pthread_mutex_lock(&lock);
  .................
  .................
  // pthread_mutex_unlock(&lock);
  .................
}
#endif
............................
............................
#ifdef _ERROR5_
/* if (pthread_mutex_init(&lock, NULL) != 0)
    {
        printf("\n mutex init failed\n");
        return 1;
    }
*/
...............
...............
...............
//    pthread_mutex_destroy(&lock);

Rebuild the application.
Relaunch the Launch Configuration
Observe the output.

Error 3 : Dynamic Memory Allocation

Enable the _ERROR6_ macro in the application source file linux_test_application.c and disable _ERROR3_ and _ERROR5_ as shown below.

//#define _ERROR3_
//#define _ERROR5_
#define _ERROR6_

The goal of dynamic memory allocation debugging is to understand memory management.

Under FLOW, highlight the linux_test_app, and Build.
Under FLOW, highlight the linux_test_app, and Debug to launch a Launch Configuration.
Select, the Target Connection; either physical_zcu102, or qemu_zcu102 and the Work Directory to /home/petalinux`

The code stops at the program entry.
Use debugging techniques such as the Variables view, step over, breakpoints, and so on to identify the incorrect memory assignment.
Place a breakpoint at the following lines.
```
*ptr = i + 1;
ptr++;
```
Click Resume and let the tool stop at the breakpoint.
Open Variables view to check the ptr value. Observe that a value is not correctly assigned to a pointer.

Comment out the following code lines:

#ifdef _ERROR6_
................
................
................
//ptr = i + 1;
//ptr++;
................

Uncomment the following line of code to make the appropriate pointer assignment.

#ifdef _ERROR6_
................
................
................
................
ptr[i] = i + 1;
................

Rebuild the application.
Relaunch the Launch Configuration
Observe the output.

Appendix

Vivado Design explains how to use a Vivado example design to create a Vivado project. This set of steps gives you the XSA file from Vivado to export. You can skip the manual steps and use this Tcl script to create an XSA directly.

PetaLinux Build explains how to create a PetaLinux project, and how to configure and build boot images.

Vivado Design

Note: You can skip these steps by running the automation steps instead.

Creating the Block Design

The first step is to create a block design. You can create this according to your specific requirements, but here you will create a Zynq UltraScale+ MPSoC based example project using a template, as explained below.

On the Welcome screen, navigate to Quick Start and click Open Example Project.
The Create Example Project wizard will be launched. Click Next.
In the Select Project Template window, click Refresh to install templates.
You will now be able to see the Zynq Ultrascale+ MPSoC Design Presets template. Select the template and click Next.
Update the Project Name to "zcu102" and update the path.
In the next window, select Zynq UltraScale+ MPSoC ZCU102 Evaluation Board and click Next. Here, you can see two preset designs. Select the second option, Processing System and Programmable Logic (PS+PL) with GPIO and Block RAM, and click Finish.

The block design you have created for the example project is shown in the following figure.

Generating the Bitstream

The preset example creates an HDL wrapper and also generates output products. You can directly perform synthesis and implementation, and you can generate a bitstream. To generate a bitstream, click Generate Bitstream.

Exporting the XSA

After successful bitsream generation, navigate to File > Export > Export Hardware to launch the Export Hardware Platform wizard. Click Next and export the hardware with the Include bitstream option. Enter the desired XSA name and complete the wizard.

Automation Steps

Launch the Vivado Tcl console. Source vivado_design.tcl.

PetaLinux Build

It is required to configure the PetaLinux project to support Linux application debug. Run the following commands for each step listed below. You can use the BSP for their board. However, the steps below uses ZynqMP template, and the MACHINE_NAME is updated. This would be a more generic flow

Create the PetaLinux project:

petalinux-create -t project --template -n xilinx-zcu102-2023.2

Configure the hardware description:

cd xilinx-zcu102-2023.2
petalinux-config --get-hw-description <path to XSA>

Configure the DTG Options
- Select DTG Options:
```
(zcu102-rev1.0) MACHINE_NAME
```
Configure the root file system to enable TCF agent:
```
petalinux-config -c rootfs
```
- Select Filesystem Packages:
```
Filesystem Packages ---> 
```
- Scroll down to select misc.
```
misc --->
```
- Scroll down to select tcf-agent. Ensure that the tcf-agent is enabled.
```
[*] tcf-agent 
[ ] tcf-agent-dev 
[ ] tcf-agent-dbg
```
Go back to the Filesystem Packages menu and click console.
```
console --->
```
Navigate to network.
```
network --->
```
Click into the dropbear submenu and make sure that dropbear is enabled:
```
[*] dropbear
```

Go back to the previous menu to select OpenSSH and ensure that openssh-sftp-server is enabled.

[ ] openssh 
[ ] openssh-ssh 
[ ] openssh-sftp 
[*] openssh-sftp-server 
[ ] openssh-keygen 
[ ] openssh-dbg 
[ ] openssh-dev 
[ ] openssh-misc 
[ ] openssh-sshd 
[ ] openssh-scp

Save the configuration and exit.
Build:
```
petalinux-build
```

Sysroot:

petalinux-package --boot --u-boot
petalinux-build --sdk
petalinux-package --sysroot

Note: You can skip all the above steps by using the petalinux_build.sh script to build the Linux images.

^{Terms and Conditions}

FilesExpand file tree

2-debugging-linux-applications

Directory actions

More options