Debug A Running Linux App With XSDK

Table of Contents


The default XSDK debug configuration for Linux applications copies the elf file to the target before running it. It is desirable to be able to debug an application that was launched outside XSDK (e.g. at system startup). This is not shown in the default debug templates but can be done manually, as shown here. A working knowledge of XSDK is assumed, as well as familiarity with the ZCU102 board.

Test environment

You may be able to use a different test setup, so long as the following principles are preserved:

  • The laptop can, via Ethernet, access the ZCU102
  • The application being debugged has its source code available on the laptop
  • If the application was not developed in XSDK or was developed on a different machine, you may need path mappings to locate the sources

SD Card

Use an SD card that was supplied with, or is compatible with, the ZCU102.


  1. USB-to-miniUSB cable supplied with the ZCU102
  2. Two Ethernet cables (RJ45)
  3. Power cable for ZCU102


It establishes a private Ethernet network containing the laptop and the ZCU102. Ensure the router is enabled as a DHCP server and powered on, with two spare RJ45 ports. This test uses up three IP addresses – one for the laptop, one for u-boot and one for Linux on the ZCU102. Ensure the router can serve these three clients. Reboot it if necessary.

ZCU102 hardware configuration

  1. Rev 1.1 board
  2. Boot mode is SD card

Laptop configuration


  1. SD card reader
  2. Spare USB port
  3. Spare Ethernet port configured for DHCP slave


  1. Windows 7
  2. XSDK 2018.2
  3. ZCU102 2018.2 release image
  4. CP210x USB to UART Bridge VCP Drivers

Connect Cables

  1. USB-UART cable between ZCU102 and laptop
  2. Ethernet cable between ZCU102 and router
  3. Ethernet cable between laptop and router
  4. ZCU102 power cable (leave powered down)

Insert SD Card In Card Reader

Ensure the SD card is writeable.

Locate COM port

  • Open 'Device Manager' via Windows -> Control Panel, and open the 'Ports (COM & LPT)' section
  • The line that reads 'Interface 0' has the COM port number (in this case, COM46):

  • It is possible that you may need to power up the ZCU102 for this information to be visible. If so, power it down after obtaining the above information.

Prepare SD Card Image

  • Copy ZCU102 2018.2 release image, uncompressed, to SD card
  • Launch XSDK
  • Select a workspace location
  • Create a Linux application 'hello' using the 'Hello world' template.
  • Change the code to add a forever loop:
Modified hello_world
#include <stdio.h>
#include <unistd.h>

int main()
    for(;;) {
        printf("Hello World\n");
    return 0;
  • Ensure the active Build Configuration is set to 'Debug'
  • Build the application
  • Copy the application 'Debug\hello.elf' to the SD card
  • Safely eject the SD card from the laptop
  • Leave XSDK running

Launch Application

  • Insert the SD card in the ZCU102 SD card slot
  • Open an XSDK terminal for the COM port:

  • You should see 'Connected to COM46 at 115200' if it succeeds.
  • Apply power to the ZCU102.
  • You should see boot messages from Linux. Wait for the prompt: xilinx-zcu102-2018_2 login:
  • Login with user root and password root.
  • Run this command: ifconfig eth0
    • Note the value of 'inet addr'
  • Mount the SD card to a known path: mount /dev/mmcblk0p1 /media
  • Check the SD card contents, you should see hello.elf: ls /media
  • Run the application: /media/hello.elf &
    • It will run forever, sleeping 10 seconds and printing 'Hello World\n' each loop

Setup Remote Systems Explorer in XSDK

  • Select: Window -> Perspective -> Open Perspective -> Other…
  • When the 'Open Perspective' window pops up, select 'Remote System Explorer' and click 'OK'

  • In the 'Remote Systems' tab, click on 'Define a connection to remote system'

  • In the 'New Connection' popup window, select 'Linux' and click 'Next'

  • Fill in connection information as appropriate and click 'Next'

  • Choose 'ssh.files' for the subsystem as shown, and click 'Next'

  • Define process subsystem information as shown, and click 'Next'

  • Define shell information, and click 'Next'

  • Define 'ssh terminals' and click 'Finish':

  • You should now see 'myboard' in the 'Remote Systems' tab

  • Try to open myboard -> Shell Processes -> All Processes, the following popup will show up. Fill in as shown, and click 'OK'

  • You will see a list of all processes running on the target. Scroll down and confirm you can see 'hello.elf' running.

Setup Debug Configuration

  • Right click on the 'hello' application in the 'Project Explorer' tab, and select 'Debug As' -> 'Debug Configurations…'. The 'Debug Configurations' window pops up.

  • Click on 'Filter Launch Configurations…'

  • Unselect 'Filter Configuration Types'. You should now see this:

  • Double click on the highlighted line above: "C/C++ Attach to Application" and fill in the 'Main' tab as follows. Some entries will be pre-filled. You can use the 'Browse' and 'Select Project…' buttons as needed. When all entries are filled, click 'Select other…' at the bottom

  • A 'Select Preferred Launcher' window pops up. Modify it as shown below and select 'OK'.

  • The 'Debug Configurations' window should now show this:

  • Click 'Debug' to launch a debug session
  • A 'Select Peer and Context' window pops up, change selections as shown below and click 'OK'

  • A confirmation window may pop up, click 'Yes' to switch to the Debug perspective

  • The code spends most of the time in 'sleep()', whose source code is unavailable. Thus, very likely, when you click yes, you will be interrupting this call, and you will see assembly code:

  • Left-click on the line for main() in the Debug tab, and you should see the source code line where it is stopped:

  • You should now be able to continue with debug, setting breakpoints, stepping, etc.


  1. Zynq UltraScale+ MPSoC ZCU102 Evaluation Kit
  2. Zynq 2018.2 Release Images
  3. Software Development Kit Standalone WebInstall Client - 2018.2 Lightweight Installer
  4. CP210x USB to UART Bridge VCP Drivers

© Copyright 2019 - 2022 Xilinx Inc. Privacy Policy