IntelPython · PokhodenkoSA · Dec 27, 2021 · Dec 22, 2021 · Dec 22, 2021 · Dec 22, 2021
diff --git a/docs/user_guides/debugging/altering.rst b/docs/user_guides/debugging/altering.rst
@@ -0,0 +1,51 @@
+Altering Execution
+==================
+
+See `GDB* documentation <https://sourceware.org/gdb/onlinedocs/gdb/Altering.html>`_.
+
+.. _assignment-to-variables:
+
+Assignment to Variables
+-----------------------
+
+To alter the value of a variable, evaluate an assignment expression.
+This also works for function arguments.
+
+.. note::
+
+   Altering arguments has limitation. For it to work correctly
+   arguments should not be modified in code.
+   See `Numba issue <https://github.com/numba/numba/pull/7196>`_.
+
+Example
+```````
+
+Source code :file:`numba_dppy/examples/debug/side-by-side-2.py`:
+
+.. literalinclude:: ../../../numba_dppy/examples/debug/side-by-side-2.py
+   :pyobject: common_loop_body
+   :linenos:
+   :lineno-match:
+   :emphasize-lines: 6
+
+Debug session:
+
+.. code-block:: shell-session
+   :emphasize-lines: 11-
+
+   $ gdb-oneapi -q python
+   ...
+   (gdb) set environment NUMBA_OPT 0
+   (gdb) set environment NUMBA_EXTEND_VARIABLE_LIFETIMES 1
+   (gdb) break side-by-side-2.py:29 if param_a == 5
+   ...
+   (gdb) run numba_dppy/examples/debug/side-by-side-2.py --api=numba-dppy-kernel
+   ...
+   Thread 2.1 hit Breakpoint 1, with SIMD lane 5, __main__::common_loop_body (i=5, a=..., b=...) at side-by-side-2.py:29
+   29          result = param_c + param_d
+   (gdb) print param_c
+   $1 = 15
+   (gdb) print param_c=200
+   $2 = 200
+   (gdb) print param_c
+   $3 = 200
diff --git a/docs/user_guides/debugging/data.rst b/docs/user_guides/debugging/data.rst
@@ -0,0 +1,58 @@
+Examining Data
+==============
+
+See `GDB* documentation <https://www.sourceware.org/gdb/onlinedocs/gdb/Data.html>`_.
+
+.. _print:
+
+``print expr``
+--------------
+
+To print the value of a variable, run the ``print <variable>`` command.
+
+.. literalinclude:: ../../../numba_dppy/examples/debug/commands/docs/local_variables_0
+    :language: shell-session
+    :lines: 67-72
+    :emphasize-lines: 1-6
+
+.. note::
+
+    Displaying complex data types requires Numba 0.55 or higher.
+
+Example - Complex Data Types
+````````````````````````````
+
+Source code :file:`numba_dppy/examples/debug/side-by-side-2.py`:
+
+.. literalinclude:: ../../../numba_dppy/examples/debug/side-by-side-2.py
+   :pyobject: common_loop_body
+   :linenos:
+   :lineno-match:
+   :emphasize-lines: 6
+
+Debug session:
+
+.. code-block:: shell-session
+   :emphasize-lines: 9-
+
+   $ gdb-oneapi -q python
+   ...
+   (gdb) set environment NUMBA_OPT 0
+   (gdb) set environment NUMBA_EXTEND_VARIABLE_LIFETIMES 1
+   (gdb) break side-by-side-2.py:29 if param_a == 5
+   ...
+   (gdb) run numba_dppy/examples/debug/side-by-side-2.py --api=numba-dppy-kernel
+   ...
+   Thread 2.1 hit Breakpoint 1, with SIMD lane 5, __main__::common_loop_body (i=5, a=..., b=...) at side-by-side-2.py:29
+   29          result = param_c + param_d
+   (gdb) print a
+   $1 = {meminfo = 0x0, parent = 0x0, nitems = 10, itemsize = 4,
+     data = 0x555558461000, shape = {10}, strides = {4}}
+   (gdb) x/10f a.data
+   0x555558461000: 0       1       2       3
+   0x555558461010: 4       5       6       7
+   0x555558461020: 8       9
+   (gdb) print a.data[5]
+   $2 = 5
+
+This example prints array and its element.
diff --git a/docs/user_guides/debugging/features.rst b/docs/user_guides/debugging/features.rst
@@ -1,19 +1,24 @@
 Supported Features
-====================
+==================
 
-The following debugging features are available:
-
-- Source location (filename and line number).
-- Setting breakpoints by the line number.
-- Stepping over breakpoints.
-
-Numba-dppy supports the following Intel® Distribution for GDB* commands:
+Numba-dppy and Intel® Distribution for GDB* provide at least
+following debugging features:
 
 .. toctree::
     :maxdepth: 2
 
     breakpoints
     stepping
-    local_variables
+    frame_info
     backtrace
-    info
+    data
+    symbols
+    altering
+
+Other topics:
+
+.. toctree::
+    :maxdepth: 2
+
+    local_variables
+    numba-0.55
diff --git a/docs/user_guides/debugging/frame_info.rst b/docs/user_guides/debugging/frame_info.rst
@@ -0,0 +1,79 @@
+Information About a Frame
+=========================
+
+See `GDB* documentation <https://www.sourceware.org/gdb/onlinedocs/gdb/Frame-Info.html>`_.
+
+.. _info-args:
+
+``info args``
+-------------
+
+Test :file:`numba_dppy/tests/debugging/test_info.py:test_info_args`.
+
+.. note::
+
+   Requires Numba 0.55 or higher.
+   In previous versions ``info args`` always returns ``No arguments.``.
+
+Example
+```````
+
+Source code :file:`numba_dppy/examples/debug/side-by-side.py`:
+
+.. literalinclude:: ../../../numba_dppy/examples/debug/side-by-side.py
+   :pyobject: common_loop_body
+   :linenos:
+   :lineno-match:
+   :emphasize-lines: 2
+
+Debug session:
+
+.. code-block:: shell-session
+   :emphasize-lines: 9-11
+
+   $ NUMBA_OPT=0 gdb-oneapi -q python
+   ...
+   (gdb) break side-by-side.py:25
+   ...
+   (gdb) run numba_dppy/examples/debug/side-by-side.py --api=numba-dppy-kernel
+   ...
+   Thread 2.1 hit Breakpoint 1, with SIMD lanes [0-7], __main__::common_loop_body (param_a=0, param_b=0) at side-by-side.py:25
+   25          param_c = param_a + 10  # Set breakpoint here
+   (gdb) info args
+   param_a = 0
+   param_b = 0
+
+.. _info-locals:
+
+``info locals``
+---------------
+
+Test :file:`numba_dppy/tests/debugging/test_info.py:test_info_locals`.
+
+.. note::
+
+   Requires Numba 0.55 or higher.
+
+Example
+```````
+
+Source code :file:`sum_local_vars.py`:
+
+.. literalinclude:: ../../../numba_dppy/examples/debug/sum_local_vars.py
+    :lines: 15-
+    :linenos:
+    :lineno-match:
+
+Run the debugger with ``NUMBA_OPT=0``:
+
+.. literalinclude:: ../../../numba_dppy/examples/debug/commands/docs/local_variables_0
+    :language: shell-session
+    :lines: 1-6
+
+Use ``info locals``.
+Note that uninitialized variables are zeros:
+
+.. literalinclude:: ../../../numba_dppy/examples/debug/commands/docs/local_variables_0
+    :language: shell-session
+    :lines: 8-48
+    :emphasize-lines: 1-16, 24-39
diff --git a/docs/user_guides/debugging/info.rst b/docs/user_guides/debugging/info.rst
diff --git a/docs/user_guides/debugging/limitations.rst b/docs/user_guides/debugging/limitations.rst
@@ -1,11 +1,21 @@
 Limitations
 ===========
 
-Currently Numba-dppy provides only initial support of debugging SYCL* kernels.
-The following functionality is **limited** or **not supported**:
-
-  - Information about variable values may not match the actual values while debugging.
-  - Information about variable types is limited.
-  - Printing kernel arguments is not supported.
-  - Overwriting the value of a variable is not supported.
-  - Accessing elements of a complex variable type is not supported.
+The following functionality is **limited** or **not supported**.
+
+Altering arguments modified in code
+-----------------------------------
+
+Altering arguments has limitation. For it to work correctly
+arguments should not be modified in code.
+See `Numba issue <https://github.com/numba/numba/pull/7196>`_.
+
+See :ref:`assignment-to-variables`.
+
+Using Numba’s direct ``gdb`` bindings in ``nopython`` mode
+----------------------------------------------------------
+
+Using Numba’s direct ``gdb`` bindings in ``nopython`` mode is not supported in
+Numba DPPY.
+
+See `Numba documentation <https://numba.pydata.org/numba-doc/latest/user/troubleshoot.html#using-numba-s-direct-gdb-bindings-in-nopython-mode>`_.