Debugging OpenCL Program with gdb

Debugging one complex application manually without any help of debugger is realy tiresome job. On the other hand debuggers make it a simple and enjoyable experiences. The GNU Project Debugger( gdb ) is one of the best debugger available for developers. Programmers like it because of its simplicity and easy-to-use features.

gdb helps us in following things.

  1. breakpoints : gdb allow you to pause at any point of execution and see the state of any variable currently in the scope.
  2. next : using next command we can do line by line execution. Also can do dry-run of our application. Which makes debugging a very easy job. The complete flow of execution come alive while we do dry-run. It is very reliable way to identify logical errors of an application.
  3. display : using display command developers can constantly monitor, state of one variable and can find the bug.
  4. backtrace : if any code gives core dump, with help of backtrace features , developer can exactly pinpoint , from which location of code , problem started.

There are many other useful features provided by gdb. One can certainly explore by referring to official gdb documentation here

OpenCL(Open Computing Language) is open standard for General Purpose Parallel Programming Across GPU, CPU , DSP and Cell/BE Processor. OpenCL Program mainly having two part. The main program part, which is also called host code, is simple C or CPP Code with some API provided by OpenCL Library. The second part of the program is called OpenCL Kernel Code, which needs to be written in a different file. OpenCL Kernel code is having different syntax, though it is quite similar to C syntax.

While compiling any normal C or CPP Program , we can pass many flag to compiler which give instruction to compiler to do certain task ,like generating binary executable with optimized instruction set. Similarly one very important compiler flag is “-g”. This flag tells compiler like gcc or icc, to generate binary executable of an application with debugging information.

Ex. gcc -g HelloWorld.c

But developer face difficulties while compiling OpenCL Program . After compilation of OpenCL host code, binary executable will be generated for host code only because OpenCL kernel code gets loaded, linked, compiled and get executed on the fly at runtime. So the compiler does not create any separate binary file for Kernel code. After execution of host code binary , there will be no executable of the kernel code as well, available on system.

While using GDB, to debug OpenCL Program main problem comes with the OpenCL kernel code section. Because no executable is generated for OpenCL kernel source, so we can not pass kernel executable’s directory path to gdb. That is why, we need to take different approach to debug OpenCL Program using gdb.

In the following section I will describe how to debug OpenCL Kernel and OpenCL host code using GDB.

Following picture shows generic structure of OpenCL host code.

OpenCL Program Structure

OpenCL Program Structure

If host program file name is HelloWorldOpenCL.c , then at the time of compilation , we can pass “-g” compiler flag to gcc compiler.

gcc -g -o run HelloWorldOpenCL.c

This will create one binary with debugging information. But how to pass -g flag while compiling OpenCL kernel code? If we look at above picture, we can notice that, at step 1.8. we are firing one API “ClBuildProgram()”. This is the API we use to build OpenCL Kernel code. The fourth parameter of this API allows us to pass compiler flag or options to OpenCL compiler on runtime.

So to enable gdb to debug your OpenCL program , This code section should be written something like bellow code snippet….

91 char *options = new char[10];

92 strcpy( options, “-g”);

93 status = clBuildProgram( *hProgram,1, *devices, options,NULL,NULL);

94 STATUSCHKMSG(“build”);

Compile your host code with -g flag. Now we can start debugging our program with following command

gdb ./<host-code-executable-name>

gdb will start and will wait for further user command. Find out the line number of the statement “status = clBuildProgram( *hProgram,1, *devices, options,NULL,NULL);” in host code. According to the above code snippet , in my program line number of this statement is 93. Then put one breakpoint at the very next statement , say “STATUSCHKMSG(“build”);”. gdb will halt its execution on this statement. Now we are all set to put break point in our OpenCL Kernel Code.

break 94

Because the kernel code is loaded , compiled and build with -g compiler flag so Kernel executable code will contain debugging information. But to put break point and debug Kernel code , we need any of the two thing. One : either kernel subroutine name , Two : The line number on which the statement is written. As the the code is compiled on runtime, there is no way that we can come to know, on which line which particular kernel code statement is placed. So there is one way to find the starting point of the code or subroutine. Use bellow command on gdb interactive shell to find out that , the kernel source code is successfully loaded.

info func __OpenCL_<your-kernel-subroutine-name>_kernel

say suppose my kernel name is “hello_world_OpenCL_kernel” then OpenCL compiler will mangle this soubroutine name as


now we can put break point at starting of kernel subroutine as follows

break __OpenCL_hello_world_OpenCL_kernel_kernel

Now as the break point is set at starting of OpenCL kernel subroutine , we can reach to that point with following gdb command.


With this command control will reach to line __OpenCL_hello_world_OpenCL_kernel_kernel (). Which is the starting line of OpenCL kernel subroutine. To check , if everything is going well, type following command to gdb


This command will display next ten line of your source code. As your current source code file will be kernel source code file , you should be able to see OpenCL kernel source code. So that it. You are ready to rock with gdb … to debug OpenCL program. Put as many break points , as you want on that kernel source. use display command to constantly monitor any variable value …debug line by line of the source code by next command. Good luck..

NOTE : with thanks to “brg” from AMD Developer forum.


Simple , Artistic , Meaningful

Tagged with: , , , , , ,
Posted in computer, Passion, Science
18 comments on “Debugging OpenCL Program with gdb
  1. viewon01 says:


    I have try the “-g” options … but my application crash, at least with the AMD implementation !

    • samritmaity says:

      I used same implementation while experimenting –
      AMD Beta Driver : ati-stream-sdk-v2.0-beta3-lnx32
      GCC : gcc-4.3.2
      on Fedora 8 System …

      let me know ,, if you need more information

  2. vpereira says:

    Are you sure it works for kernel code running on GPU? And all working items will halt in the breakpoint?

    Have you alredy tried it on NVIDIA Implementation?


    • samritmaity says:

      I have tried the explained process on CPU based OpenCL Driver ( ati-stream-sdk-v2.0-beta3-lnx32 ). Later I have not re-tested the whole process on GPU based driver.
      1) But I am sure they will work because of two reason first : the ” -g ” flag is supported through clBuildProgram(). Second the kernel compilation process is same. Also the kernel code is same.
      now, while debugging , can we run the code on REAL GPU or we have to use CPU mode , that is a issue I need to explore. ( means debugging OpenCL Program on nvidia GPU , need to be explored : AMD OpenCL Driver support both GPU and CPU Mode so i hope there will be no problem ).

      2) you are right , for all work Items ( I would prefer to say as ” for all global threads”) the execution will halt at breakpoint.
      I have modified all my CPU based driver code , to GPU based OpenCL code with minimum effort.

      But as you rise the question , I will try it with GPU Based driver – with gpu mode and confirm the same very soon.

  3. vpereira says:

    I’ve tried it on NVIDIA implementation and unfortunately it looks that its not working:(

    It returned: clang: Unknown command line argument ‘-g’. Try: ‘clang –help’
    :\ Any hint?

    • samritmaity says:

      hi vandopereira ,
      I checked my codes on nVidia Setup. Unfortunately I failed to do debugging on nVidia platform.
      I suspect , they are using an immature or backdated version o clang compiler for OpenCL kernel compilation . I can not confirm it , but as per ubuntu(lucid) ‘s clang man page , clang compiler should recognize the “-g” option but , with nVidia platform , clang compiler is not recognizing “-g” option.

      Another important issue is that , even on AMD platform , I succeeded to do debugging in CPU mode , but failed to debug in GPU mode. As nVidia is not supporting CPU mode OpenCL implementation for the time being, so there is no use of putting time on it. May be in future , this will be available. till then, we have to wait .

  4. Nadav says:

    Hi, my name is Nadav and I am a PhD student researching Parallel Compilers (such as OpenCL, OpenMP, etc). In the AMD runtime you can debug OpenCL code because it runs on the CPU and not on the device. It would be interesting to debug OpenCL code on the device.

    • samritmaity says:

      Thanks for your advice .. I will try it and confirm with in few days.

      • samritmaity says:

        hi Nadav, I tried to generate debugging information in GPU [ CL_DEVICE_TYPE_GPU ] mode. But the compilation process [ in particular “clBuildProgram()” API ] is failing.
        I suspect that , the compiler is not able to generate device specific debugging information [ failing to genrate symbol table which is required by GDB].
        bellow is the error I am getting while trying to run program , with CL_DEVICE_TYPE_GPU mode.
        let me know if you have any Idea regarding debugging on device itself.

        0 llc 0x087b4cc8
        1 llc 0x087b54da
        2 0x00a5b420 __kernel_sigreturn + 0
        3 llc 0x0873bb98
        4 llc 0x087883d3
        5 llc 0x083173f4
        6 llc 0x083183bc
        7 llc 0x08319079
        8 llc 0x08705921
        9 llc 0x0851c254
        10 llc 0x0851c54b
        11 llc 0x0851c762
        12 llc 0x08058e11
        13 0x00903e9c __libc_start_main + 220
        14 llc 0x08056a01 __gxx_personality_v0 + 573
        Stack dump:
        0. Program arguments: /usr/local/ati-stream-sdk-v2.01-rhel32/bin/x86/llc -mcpu=atir770 -mattr=mwgs-3-256-1-1 -regalloc=linearscan -mtriple=amdil-pc-amdopencl /tmp/OCLgxvBeS.bc -f -o /tmp/
        1. Running pass ‘AMDIL Assembly Printer’ on function ‘@__OpenCL_vectVectMult_kernel_kernel’

  5. josling says:

    have you ever tried to use eclipse or other IDEs to debug?

  6. […] Debugging OpenCL Program with gdb November 2009 11 comments 3 […]

  7. […] is a lot of choice, but mostly only if you have a paid version of Visual Studio. On Linux you have GDB, but that program is not really user-friendly for the […]

  8. […] is a lot of choice, but mostly only if you have a paid version of Visual Studio. On Linux you have GDB, but that program is not really user-friendly for the GUI-lovers.For AMD there is now gDEBugger […]

  9. chatsiri says:

    What another methods for debugging kernel? I try to “gdb>info function __OpenCL” in order to find subroutine of opencl, but it’s cannot represent after break point at clBuildProgram function name.

    • samritmaity says:

      info function __OpenCL_kernel should work ,, if you have passed “-g” flag during kernel compilation ( with in clBuildProgram function call). I haven’t tried any other method.

  10. […] Debugging OpenCL Program with gdb. (2009. Nov 20). Retrieved Jan. 06, 2014. […]

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: