gDEBugger CL Tutorial| gDEBugger CL Tutorial |
This section of the tutorial will guide you through your first steps in using gDEBugger.
gDEBugger CL supports the following platforms, for both the i386 (32 bit) and x86_64 (64 bit) architectures:
gDEBugger CL is tested using the latest versions of NVIDIAs GPU Computing SDK and AMDs ATI Stream SDK. gDEBugger CL should be able to work on top of any OpenCL platform that supports the Khronos ICD OpenCL extension (cl_khr_icd).
Make sure that you system meets the above system requirements. Then:
Windows: go to the Graphic Remedy website, and choose "Download" from the menu on the left hand side.
Click the "download here" link.
After the download has finished, double click the installer (.msi file) and follow its instructions.
Linux: go to the Graphic Remedy website, and choose "Download" then "Linux" from the menu on the left hand side.
Click the "download here" link next the computer configuration you'd like to use (if you are unsure of the right configuration, read the explanation at the bottom of the download page).
After the download has finished, extract the archive to your preferred install location.
Mac: go to the Graphic Remedy website, and choose "Download" then "Mac OS X" from the menu on the left hand side.
Click the "download here" link.
After the download has finished, open the downloaded disk image (.dmg file) and copy all application bundles to your Applications folder.
After installing gDEBugger, if you already have a license, install it following the instructions in the website.
If you don't, gDEBugger will prompt you to acquire a Trial License the first time you run it (requires internet connection).
When you are done installing the license, double-click the gDEBugger icon in the installation directory to start up gDEBugger.
When you start up gDEBugger, you will be presented with the startup dialog. In this dialog, choose "Create new project..." to bring up the Create New Workspace Wizard (If you wish to return to this wizard later, choose New from the gDEBugger File menu).
First, select your Project Type: Choose "OpenCL" if your application only uses OpenCL or "OpenGL and OpenCL" if your application uses both OpenCL and OpenGL.
 |
 |
After choosing the project type, press Next and choose the executable file you wish to debug using gDEBugger, by pressing the browse button. It is recommended to use an executable with debug information (a debug build), unless you want to make performance measurements, in which case you might wish to use a release build for more accurate results.
Next, input the working directory and any application arguments you wish to use in the next two text fields.
 |
In the final screen you may select functions that will be considered as computation frame terminators. A frame terminator function call notifies gDEBugger that a computation frame has ended, enabling it to clear logs, measure computation frames per second and more. You may also choose OpenCL function breakpoints by pressing "Select Breakpoints".
If you selected an OpenGL + OpenCL project, you will also be prompted to choose OpenGL render frame terminators and breakpoints. See "Getting Started with gDEBugger GL" for more details.
When you have completed inputting your choices, press the "Finish" button to create the gDEBugger project.
 |
All these settings may be later changed in the Debug Settings dialog (find it under the gDEBugger Debug menu, or by pressing Ctrl+D).
If your program is written using a scripting language (such as Java or Python), choose the runtime environment as the debugged application and add your program (script) as a program argument. Also note that if your application uses a launcher script, you should debug the application and not the launcher script.
gDEBugger's Execution Mode toolbar allows you to switch between gDEBugger's various execution modes. Changing the execution mode will also change the current GUI layout to contain the views and toolbars appropriate for the selected execution mode and project type.
The available execution modes are:
Debug Mode - Debug Mode enables most of gDEBugger's features, allowing a great range of tasks, from locating OpenCL related bugs to finding OpenCL related memory leaks and many other debugging tasks.
Profile Mode - Profile Mode removes CPU intensive logging operations performed by gDEBuggers OpenCL Server to provide a performance experience as close to running the application outside gDEBugger as possible. This mode is recommended for performance analysis tasks.
Analyze Mode - Analyze Mode enables in-depth analysis of the application's OpenCL usage. However, using this mode dramatically reduces performance. Therefore it is best to use this mode when analyzing the application OpenCL usage of a single computation frame.To load an existing project, select it from the startup dialog, or choose Open from the gDEBugger file menu.
If you wish to simply experiment with gDEBugger's capabilities, you can open the gDEBugger teapot example from the startup dialog.
To run the debugged application, press the 
Go button (F5). To suspend the execution, press the 
Break button (F6). To terminate the debugged application, press the 
Stop button (Shift+F5).
Please note that most of the information gDEBugger displays is only available when the debugged application execution is suspended.
Also note that when you break the execution, the debugged application will only be suspended at the next OpenCL call.
To advance the debugged process execution to a specific point, you should use the step buttons: Press the 
Step button (F11) to advance the debugged process to the next OpenCL call. Press the 
Frame Step button (Ctrl+F11) to advance to the next frame terminator call.
To break at a specific OpenCL function, you should add it as a breakpoint in the breakpoints dialog (Add/Remove Breakpoints in the Breakpoints menu or Ctrl+B). After adding the function as a breakpoint, press the Go button (F5) and the debugged process execution will break before the next call to the specific function.
The next pages contain information about performing various debugging and profiling tasks. The tasks are organized by their recomended execution mode.