Set Up Intel® Distribution for GDB* to Debug GPUs on Windows*
Learn how to simultaneously debug cross-platform parallel and threaded applications developed in Data Parallel C++, C, C++, OpenMP*, SYCL*, or Fortran by using kernels offloaded to GPU devices.
Hi, my name is Natalia and in this video I'm going to show you how to set up Intel® Distribution for GDB* on Windows* system for debugging DPC++ applications with the GPU offload.
When we debug the GPU, GPU is halted, and no graphics output is available. For us, that means that we cannot run Visual Studio* on the same machine where your data parallel C++ app is running, and we have to use two machines.
On the host machine, we expect that there is a Visual Studio installed as well as Intel® one API Base Toolkit.
On the target machine, we need to have the Visual Studio Remote Debugger, which matches the version of your Visual Studio, and we also need a recent enough graphics driver. I'm using the one from the beginning of January.
We also need to have the compiler runtime libraries.
So, first of all, we are going to set up our target machine and install our target installer and Intel oneAPI runtime dependencies there. Secondly, we are going to set up and build a sample project in Visual Studio 2019 on our host machine, and we will deploy and run this application on the target.
Once we can run the application, we can set up the Intel Distribution for GDB, and after it is set, we can hit a breakpoint inside the kernel offloaded on GPU.
Now let's set up our machines. First of all, on your host machine, go to the debugger folder. You can do it by using ONEAPI_ROOT variable, which is available after installation of the base kit. And here specify the debugger latest version: ONEAPI_ROOT debugger\latest.
In this folder you can find all the debugger components, but right now I'm interested in the target.
In this folder you can find our target installer. This installer file has to be copied on your remote system and be installed there. Without this installation on your target system, the GPU debugger won't work.
I have already copied it to my remote system, and so let's just install it there. Here's the file.
Once the installation is completed, it will ask you to restart your system. You should do that, but we will do it a bit later.
The second step is to install oneAPI runtime dependencies. To do that, please go to this website. This link can be also found in our Getting Started guide.
Here you need to install the Intel oneAPI DPC++/C++ Compiler Runtime. It is this package here. And for example, it contains the sycl.dll.
I have already downloaded it and let's just install it as well.
Now our target installation is almost finished, and we need to reboot the system.
While our system is rebooting, let's create a simple Visual Studio project. I'm using Visual Studio 2019.
Let's browse Intel one API samples. And there you need to choose the Debugger: Array Transform. Now click OK to create the project.
Once the project is created, please go to the project Property Pages.
And in the Debugging tab, you need to change the debugger to launch. By default, it's a local debugger, but we need the Remote Windows Debugger to run the application remotely.
Here the first thing you need to specify is the deployment directory. This directory will be created on your target system and Visual Studio will copy the executable file into this.
In Remote Command, the full path to the application would be the deployment directory plus the name of the application, which is the array-transform.exe in our case.
Our application takes one argument and it is the Device Type. We want to run the program on GPU, so specify GPU here.
For the remote setup, you also need to set the working directory the same as the deployment directory.
And finally, let's specify the Remote Server Name, which is our target machine.
Here you also have to specify the port number, which is used by the Visual Studio Remote Debugger. For Visual Studio 2019, it is 4024.
Let's now save our changes. You need to click the Apply button here.
After you save the changes, go to Configuration Manager. Before, the Deploy checkbox was disabled. Once you saved the changes, it is enabled and we need to check it. This is required to make the deployment.
Now, we are almost ready to run our application. And, actually, the only thing which is missing is the running Remote Visual Studio Debugger.
Let's go back to the target machine. And here we need to run the Remote Debugger for Visual Studio 2019. You can see that the default port is 4024.
And now we are ready to run our application. We can, actually, specify a breakpoint outside of the kernel. Let's put it somewhere here.
And let's run the application. Now, Visual Studio is going to build it. Then it's going to deploy it and run it on the target system.
So now the application is running. We hit our breakpoint.
And if we go to the target system, we see the application. It was using the Intel graphics device, and as a SYCL* back end, it was using Intel Level 0.
Let's now quit the debugger.
And now we want to have a stop inside the kernel offloaded to GPU. To do that, you need to set up the Intel Distribution for GDB.
Go to Tools > Options. And here under Intel oneAPI, you have Intel Distribution for GDB. To enable debugging, you need to set Enable Debugging to True. And here you also need to specify the target name, which is the remote.computer.name in my case.
All other settings can be left as default.
Now we are ready to run the application.
Once you enabled our debugger, you see several pop-ups, which are popping up at the beginning.
And we hit the breakpoint inside the kernel. In the output tab, you can see some output, which is very similar to one you see on Linux*. So, this is the output from GDB.
And now you can use standard Visual Studio interface to do debugging. For example, you can see local variables.
You can also go to Debug window and, for example, look into disassembly.
You can also go to the Registers window. And here you can see the general purpose registers, and in order to see ARF registers, you should check the Other Registers checkbox. This menu opens on the right click. Once you select this, you can also see the ARF registers.
Let's close this window. This one as well.
We can step through the program.
If we continue, another thread will hit the same breakpoint. We have, actually, I think, eight threads. We have eight threads and one dummy thread.
Let's remove that breakpoint and continue until the end.
And we hit the breakpoint outside of the kernel.
Let's remove this breakpoint and continue.
If you see this message, it's OK. It's coming from GDB and it is a known bug, but it shouldn't affect your debugging.
And that was it.
Thank you very much for your attention. I hope this video will help you to set up the Intel Distribution for GDB on Windows for GPU debugging and, at the end I attached two links: the first one is for our Getting Started guide where the process is described in a bit more detail, and the second one is the link for our runtime Data Parallel C++ dependencies.