Debugging programs that use the libpynq library with Visual Studio Code

Visual Studio Code is used to log in to the PYNQ board, compile, and run C programs. It also has good debugging capabilities for C programs that do not use the PYNQ board's hardware, i.e. do not use the libpynq library, as described here. However, when using the libpynq library some additional steps must be taken, which are explained below. Steps 1-3 only have to be done once.

1. Install Visual Studio Code on your laptop

You should have already installed Visual Studio Code.

Start Visual Studio Code.
Boot the PYNQ board.
If you haven't already done so, install the "C/C++ extension pack" from Microsoft on your laptop.
If you haven't already done so, install the "Makefile tools" from Microsoft on your laptop.

2. Install libpynq on the PYNQ board

Log in to the PYNQ board with Visual Studio Code.
Download the right version of libpynq, and copy it to the PYNQ board by just dragging and dropping on Explorer sidebar in Visual Studion Code.
In the terminal on the PYNQ board execute the following commands. (Replace libpynq-5EWC0-2023-v0.2.5 by the name of your libpynq version.)
```
unzip -DD -q libpynq-5EWC0-2023-v0.2.5.zip
```

3. Install Visual Studio Code extensions on the PYNQ board

Install the "C/C++ extension pack" from Microsoft on the PYNQ board. Note the "Install in SSH: pynq" in the screen shot:
Install the "Makefile tools" from Microsoft on the PYNQ board. Note the "Install in SSH: pynq" in the screen shot:

In a terminal on the PYNQ board execute:

[ -d .vscode ] && mv .vscode .vscode.backup
[ -d .vscode ] || mkdir .vscode
cp libpynq-5EWC0-2023-v0.2.5/vscode/* .vscode/

(Replace libpynq-5EWC0-2023-v0.2.5 by the name of your libpynq version.)

Getting started

Buy a PYNQ kit

First-year Electrical Engineering (EE) and Automotive Technology (AT) bachelor students buy the PYNQ kit from the Thor study association at the same time as their books. The SD card in the kit is already flashed with the right SD-card image (currently the latest version is 5EWC0-2023-v0.2.5).
All other TU/e students following 5EWC0 can buy a 5EWC0 PYNQ kit from the Thor study association (sixth floor of the Flux building). Make sure that you buy the full 5EWC0 PYNQ kit that includes a flashed SD card and the display plugin board. The SD card in the kit is already flashed with the right SD-card image (currently the latest version is 5EWC0-2023-v0.2.5).
⚠️ Warning

If you already have a PYNQ board from a previous academic year then you will need to buy a display plugin board from the Thor study association. You also need to download the latest SD-card image for 5EWC0 (currently 5EWC0-v0.2.2) and flash it on your SD card.

Prerequisites

All of the following are part of the 5EWC0 PYNQ kit, except for the laptop and Ethernet cable that are part of the University Laptop Programme.

Your laptop with an active internet connection.
A PYNQ-Z2 board.
An SD card of at least 8 GB.

ℹ️ Information

If you buy your own SD card, then make sure that it is a high-reliability SD card because it is heavily used by the board. Cheap SD cards quickly become corrupt and fail.
A USB-A to micro-USB cable to connect to the PYNQ.

If your laptop has no USB-A connector then either use an adaptor (USB-A to USB-C) or use a micro-USB to USB-C cable. Ensure that the cable is compatible with your operating system.
An Ethernet cable to connect to the PYNQ.

If your laptop doesn't have an Ethernet port, then you also need an Ethernet to USB-A/C cable. Ensure that the cable is compatible with your operating system.
A plugin module with a display as shown below.

Set up the PYNQ

These steps need to be done only once per course.

Make sure you have the latest version of the SD-card image. This is necessary only if you do not have a pre-flashed SD card or are taking the course again. If not given a pre-flashed SD card, download the PYNQ image and flash the SD card.
Before booting (i.e. starting) the PYNQ, configure the PYNQ board.

Use your PYNQ

Every time you wish to use your PYNQ board after setting it up, you'll need to:

Connect the PYNQ board to your laptop.
Write and run your own application.
Shut down and disconnect the PYNQ.
Log out from the PYNQ board (close the Visual Studio Code window or application).

4. Debugging

Steps 1-3 installed the following libpynq-specific tasks:
1. libpynq Clean that runs make clean. This cleans up all directories, i.e. removes all generated files such as executables. This is useful when you want to submit your program as homework or project. In that case only the program is useful, and the executables can be deleted. (This task is the same as running make clean in the terminal.)
2. libpynq Build. This is default "Terminal > Run Build Task" that compiles your program to generate an executable called main. (This task is the same as running make in the terminal.)
3. You can run these tasks by selecting "Terminal > Run Task"; you should see "libpynq Clean" and "libpynq Build".
Log in to the PYNQ using Visual Studio Code.
Open the C program that you want to run or debug in Visual Studio Code. (See how to edit and run a C program if you haven't done this yet.)
To run your program without debugging select "Run > Run Without Debugging" from the Visual Studio Code menu. Click on the "Run and Debug" button on the left side bar to show the debugging side bar (variables, breakpoints, etc.). (This task is the same as running ./main in the terminal.)
To run your program with debugging select "Run > Start Debugging" from the Visual Studio Code menu.

ℹ️ Information

It takes some time to start running (with or without debugging). Be patient and don't click other menu items before the TERMINAL window is showing that your program is running. The DEBUG CONSOLE will also have displayed a lot of output (even when not debugging).

5. Explanation of debugging panes when starting

Debugging

6. Explanation of debugging panes when debugging

Debugging