Improving User Guide section on Debugging with GDB

[PokhodenkoSA]

From Matti:

PAGE : https://intelpython.github.io/numba-dppy/latest/user_guides/debugging/index.html
In the example code, perhaps we could add an output text (e.g. print(“SUCCESS”)) immediately after the kernel returns. And after hitting the breakpoint in the kernel, let the application run to the end (“continue”).
This could help to understand, how debugger stops in the kernel, and how execution then can come back to the host.

• Add print("Done...") Improving User Guide section on Debugging with GDB #448
• Add continue Improving User Guide section on Debugging with GDB #448
• See 6c1677d

PAGE : https://intelpython.github.io/numba-dppy/latest/user_guides/debugging/set_up_machine.html

Follow the link below to download the drivers.
There is no link below this text. Instead, the link is in the text. Perhaps reformulate this sentence?

• Reformulate the sentence about link to NEO driver Improving User Guide section on Debugging with GDB #448

export OCL_ICD_VENDORS=
The example code shows this env.variable, but the text doesn’t state anything about it. Perhaps add some text explaining what to do with it?

• Add explanation (@1e-to) Fix docs #451

If you are installing DCD for the first time, you need to create keys.
Perhaps some more explanatory text is needed. Below there is a link to the page, where the kex generation is explained. But for an average user, it may not be obvious. Perhaps add text like “For more details, see the link at the end of this page.”?

• Add guiding text (@1e-to) Fix docs #451

PAGE : https://intelpython.github.io/numba-dppy/latest/user_guides/debugging/debugging_environment.html

You will also need to create and acrivate conda environment with installed numba-dppy
Typo (activate -> activate)

• Fix typo for activate Improving User Guide section on Debugging with GDB #448

Further, if you want to use local NEO driver, you need to activate the variables for it.
This text seems to miss explanation on what variables needs to be activated, and how to activate them?

• Add missing explanation (@1e-to) Fix docs #451

Checking debugging environment
Again, perhaps we should continue running to the end of the program. That is, after hitting the breakpoint and stepping in the kernel, use “continue” and add an output string (like print(“SUCCESS”)) after the kernel.

• Add print("Done...") Improving User Guide section on Debugging with GDB #448
• Add continue Improving User Guide section on Debugging with GDB #448

In the output you can see that the breakpoint was set successfully:
Perhaps we should say “hit” rather than “set”? That is, user sets a breakpoint, but debugger hits the breakpoint.

• Use hit instead of set (@1e-to) Fix docs #451

PAGE : https://intelpython.github.io/numba-dppy/latest/user_guides/debugging/features.html

Perhaps some examples could help to understand these features?

• “Source location (filename and line number)”
  o I am not sure what this means and how the user could use such feature?
• “Setting break point by the line number”
  o This is clear, but an example would make it even more clear.
• “Stepping over breakpoint
  o Again, I am not sure what this means? I would rather talk about stepping, and show an example.

• Add example for source location (@vlad-perevezentsev) Add docs for breakpoints #459
• Add example for setting break point by the line number (@vlad-perevezentsev) Add docs for breakpoints #459
• Add example for stepping over breakpoint (@vlad-perevezentsev)

Also note the command “stepi”. It steps individual assembly lines, and can be useful to investigate how an individual Python code line was compiled to assembly. A brief example could be useful? (use “disassemble” to get the assembly code, and then use “stepi” to step line-by-line)

• Add example for stepi (@1e-to) Docs step/stepi/next #450

On listing the “subset” of supported commands: I would be careful on setting restrictive boundaries on what commands are supported. Perhaps we should say something like “... supports at least following GDB commands ... “

• Reformulate sentence about supported commands Improving User Guide section on Debugging with GDB #448

PAGE https://intelpython.github.io/numba-dppy/latest/user_guides/debugging/local_variables.html

some variables can be optimized out.
Perhaps we should say “some variable may be optimized out.”?

• Replace can with may (@akharche) Update docs about debugger local vars #452

“no optimization” level may not work due to llvm issues.
Should we give a little more explanation or examples? E.g. explain what the user may experience / see, if NUMBA_OPT is set to zero?

• Add example for NUMBA_OPT (@akharche) Update docs about debugger local vars #452

PAGE : https://intelpython.github.io/numba-dppy/latest/user_guides/debugging/limitations.html

This page states that “info locals” is not supported, but an earlier page stated that it is supported?

• Update text with latest status (@akharche) Update docs about debugger local vars #452

Also, what does mean “stepping over several offloaded functions is not supported”?

• Update text with latest status (@1e-to) Docs step/stepi/next #450

Text also states that variable values are not show while debugging. But I think this is not strictly true. Instead, in my understanding (which may or may not be wrong):

• Debugger can show the variable values, but the show values may not be representing the actual value of the referred variable

• Update text with latest status (@akharche)

• To access the “real” value of a variable, user would have to stepi in the assembly level, and find the location where the actual value is copied into the location referred from DWARF.

• Update text with latest status (@1e-to can you help with stepi?)

Obviously my above explanation is far too complicated, and cannot be used on any user documentation. But perhaps we could add an example, which would show how the user could get access to the “real” value of a local variable? Or at least, change the first bulleting in that page (currently it seems to state that the variable values could be accessed, but not during the time of debugging).

• Add example for access "real" value
• Update text with latest status for accessing variable values

[PokhodenkoSA]

Most of remarks are fixed. I will close it. If some updates are important, please, reopen.