API-Level Debugging Basics

Work with Breakpoints

Enter kernel debugging

View Values from Different Work Items

API-Level Debugging Basics

gDEBugger’s API-level debugging is how gDEBugger displays the CPU (client) side of your OpenCL or OpenGL application. gDEBugger can suspend the debugged application at any OpenCL and OpenGL API function, display the call stack for these function calls, and give many analysis options for debugging this part of the application.

To run the debugged application, press the Go button (F5).

The most important view in gDEBugger is the gDEBugger Explorer tree view. When the debugged application has been suspended (by a breakpoint, a step command, a break command, etc.), this view fills with the hierarchy of all OpenCL and OpenGL objects allocated in the debugged application. Each context or category can be expanded to show its contained objects, and the gDEBugger Properties view updates with the details of the selected object. Double-clicking any of the objects will usually bring up a view to show the contents of the object in some form.

Work with Breakpoints

API function breakpoints

Any gDEBugger-supported OpenCL or OpenGL function can be set as a breakpoint in the Breakpoints dialog.
The API Functions list contains all the supported functions. The Active Breakpoints list contains all the currently selected breakpoints. Each selected breakpoint has a checkbox next to it, representing whether the breakpoint is currently enabled or not. Disabling breakpoints instead of removing them saves the time of finding the function each time you want to enable the breakpoint.

To add a function to the breakpoints list, select it in the API functions list and press Add or double-click it. To remove a breakpoint, select it in the breakpoints list and press Remove or double click it.

Using breakpoints can help you see the exact API status before the function is called, also allowing a comparison of the status before and after the function call (by pressing the Step Over button (F10) after the breakpoint hit). You can also use breakpoints to find where in your code each function is called, by looking at the Call Stack view after the breakpoint is hit (If you have debug information for the stack item, you can even double-click it to see the exact location in the MDI source view).

Kernel function name breakpoints

Add the kernel function name as a kernel function breakpoint in the Breakpoints dialog, by switching to the Kernel Functions tab or by manually typing in the kernel name in the Active Breakpoints list. When a kernel matching the function name starts executing, the debugged process will stop at its beginning.

Kernel source breakpoints

You can set kernel source breakpoints by selecting a line in the kernel and pressing Add Breakpoint (F9) or clicking in the margin next to the line. Press Continue (F5) to run up to the breakpoint.
You can also set breakpoint inside a function to enter that function (as with stepping in).

Enter Kernel Debugging

There are three options for doing this:

  1. After starting debugging with gDEBugger and suspending the process (with “Break All” / Ctrl+Alt+Break or an API function breakpoint), use the Step command or an API function breakpoint to get to an API call of clEnqueueNDRangeKernel or clEnqueueTask. Then press “Step Into” (F11) to start debugging the kernel.
  2. Add the kernel function name as a kernel function breakpoint in the breakpoints dialog (Alt+Shift+B). When a kernel matching the function name starts executing, the debugged process will stop at its beginning.
  3. From the gDEBugger Explorer view, open the OpenCL program and set a breakpoint inside the code. The application will stop inside the kernel when it hits the breakpoint.

View Values from Different Work Items

gDEBugger’s Current Work Item toolbar allows you to select a single work item to focus on in gDEBugger. The combo boxes for X, Y and Z coordinates will become enabled and will offer values depending on the currently debugged kernel’s N-Dimensional global work size. Selecting a work item has the following effects:

  • The Locals and Watch views will display variable values for this work item
  • When stepping through kernel debugging, “if” or “else” clauses not entered by the selected work item will be skipped.
  • The work item will be selected in the Multi-Watch views.