Debugging with Intel® Distribution for GDB*#

Numba-dpex allows you to debug SYCL* kernels with Intel® Distribution for GDB*. To enable the emission of debug information, set the debug environment variable NUMBA_DPEX_DEBUGINFO, for example: export NUMBA_DPEX_DEBUGINFO=1 To disable debugging, unset the variable: unset NUMBA_DPEX_DEBUGINFO

Note

Enabling debug information significantly increases the memory consumption for each compiled kernel. For a large application, this may cause out-of-memory error.

Not all debugging features supported by Numba on CPUs are yet supported by numba-dpex. See Features and Limitations.

Requirements#

Intel® Distribution for GDB* is required for numba-dpex debugging features to work. Intel® Distribution for GDB* is part of Intel oneAPI. For relevant documentation, refer to the Intel® Distribution for GDB* product page.

Example of Intel® Distribution for GDB* usage#

You can use a sample kernel code, simple_sum.py, for basic debugging:

 5import dpctl
 6import dpnp as np
 7
 8import numba_dpex as ndpx
 9
10
11@ndpx.kernel(debug=True)
12def data_parallel_sum(a, b, c):
13    i = ndpx.get_global_id(0)
14    c[i] = a[i] + b[i]  # Condition breakpoint location
15
16
17global_size = 10
18N = global_size
19
20a = np.array(np.random.random(N), dtype=np.float32)
21b = np.array(np.random.random(N), dtype=np.float32)
22c = np.ones_like(a)
23
24data_parallel_sum[ndpx.Range(global_size)](a, b, c)
25
26print("Done...")

Use the following commands to create a breakpoint inside the kernel and run the debugger:

$ NUMBA_OPT=0 gdb-oneapi -q python
(gdb) set breakpoint pending on
(gdb) break simple_sum.py:22
(gdb) run simple_sum.py
...
Thread 2.2 hit Breakpoint 1, with SIMD lanes [0-7], __main__::data_parallel_sum () at simple_sum.py:22
22           i = dpex.get_global_id(0)
(gdb) next
Thread 2.3 hit Breakpoint 1, with SIMD lanes [0-1], __main__::data_parallel_sum () at simple_sum.py:22
22           i = dpex.get_global_id(0)
(gdb) next
23           c[i] = a[i] + b[i]
(gdb) continue
...
Done...

Features and Limitations#