.. _troubleshooting:

Troubleshooting
===============


Template Operators Cannot Be Found
----------------------------------

The compiler omits the code of a template class method if that method
is not used in the code. This is a C++ issue and may cause
inconvenience when you want to invoke the omitted function. This
issue is seen in SYCL\* because the basic classes (``range``, ``id``,
``nd_range``, ``accessor``, and others) are templates that have
several overloaded operators. Examples:


-  .. code-block:: bash


      p index


   Output:


   .. code-block:: bash


      $1 = cl::sycl::id<1> = {32}


-  .. code-block:: bash


      p index + 5


   Output:


   .. code-block:: bash


      Could not find operator +.


As a solution, you can explicitly instantiate a template class in
your source. Then the methods of the template instance are available
in the binary. The instantiations can be surrounded with
``#ifndef NDEBUG`` and ``#endif`` to avoid code bloat in release
builds. Example:


.. code-block:: bash


   #ifndef NDEBUG


   template class cl::sycl::id<1>;
   template class cl::sycl::id<2>;
   template class cl::sycl::id<3>;
   template class cl::sycl::range<1>;
   template class cl::sycl::nd_range<1>;


   #endif // #ifndef NDEBUG


Accessor Operator [] Cannot Be Resolved
---------------------------------------

Elements of an ``accessor`` object cannot be accessed using the
multi-dimensional access syntax during expression evaluation. See
example below:


.. code-block:: bash


   print anAccessor[5][3][4]


Example output:

.. code-block:: bash


   Cannot resolve function operator[] to any overloaded instance


Instead, use an ``id`` object:


-  .. code-block:: bash


      print workItemId


   Example output:


   .. code-block:: bash


      $1 = cl::sycl::id<3> = {5, 3, 4}


-  .. code-block:: bash


      print anAccessor[workItemId]


   Example output:


   .. code-block:: bash


      $2 = 1234


Kernel Stops Responding
-----------------------

If the kernel that is offloaded to a GPU stops responding:


#. Check whether there are any stray \`gdbserver-gt\` processes
   running in the background:


   .. code-block:: bash


      ps -u $USER | grep gdbserver-gt


#. Stop background \`gdbserver-gt\` processes, if there are any:


   .. code-block:: bash


      killall -9 gdbserver-gt


Breakpoint Is Not Hit
---------------------

-  If the breakpoints defined inside the kernel are not hit when
   running on a GPU, reset the GPU device (requires root access):


   #. Unload the \`igfxdcd\` driver


      .. code-block:: bash



         modprobe -r igfxdcd


   #. Reset the device


      .. code-block:: bash



         echo 0xffffffff | tee /sys/kernel/debug/dri/0/i915_wedged


   #. Load the \`igfxdcd\` driver again


      .. code-block:: bash



         modprobe igfxdcd


-  If the breakpoints defined inside the kernel are not hit when
   running on a GPU, and Virtualization technology for directed I/O
   (VT-d) is enabled, disable VT-d through the BIOS menu.


   Debug companion driver is not supported with VT-d enabled.