Intel Distribution for GDB on Linux OS Host Guide User Guide

зміст приховувати

1 Розпочніть роботу з Intel® Distribution for GDB* на хості ОС Linux*

1.1 Передумови

1.2 Set Up the GPU Debugger

1.2.1 Compile the Program with Debug Information

1.2.2 Start a Debug Session

1.2.3 Детальніше

1.2.4 Повідомлення та застереження

2 Документи / Ресурси

2.1 посилання

3 схожі повідомлення

Розпочніть роботу з Intel® Distribution for GDB* на хості ОС Linux*

Start using the Intel® Distribution for GDB* for debugging applications. Follow the instructions below to set up the debugger to debug applications with kernels offloaded to CPU and GPU devices.

Intel® Distribution for GDB* is available as part of the Intel® oneAPI Base Toolkit. For more information on oneAPI toolkits, visit the Сторінка продукту.

Відвідати Примітки до випуску page for information about key capabilities, new features, and known issues.

You can use a SYCL* sample code, Array Transform, to get started with the Intel® Distribution for GDB*. The sample does not generate errors and simply illustrates debugger features. The code processes elements of the input array depending on whether they are even or odd and produces an output array. You can use the sample to debug on both the CPU or GPU, specifying the chosen device through a command line argument. Note though that GPU debugging may require two systems and additional configuration for remote debugging.

Передумови

If you aim to debug on GPU, install the latest GPU drivers and configure your system to use them. Refer to the Intel® oneAPI Toolkits Installation Guide for Linux* OS. Follow the instructions Install Intel GPU Drivers to install GPU drivers matching your system.

Additionally, you can install an extension for Visual Studio Code* for debugging GPU with Intel® Distribution for GDB*. Refer to the Using Visual Studio Code with Intel® oneAPI Toolkits Guide.

Set Up the GPU Debugger

To set up the GPU debugger, you must have root access.

ПРИМІТКА During kernel debugging, the GPU is halted and the video output is unavailable on your target machine. Because of this, you cannot debug the GPU from the target system if the GPU card of the system is also used for graphical output. In this case, connect to the machine via ssh.

1. If you aim to debug on GPU, a Linux Kernel that supports GPU debugging is needed.

a. Дотримуйтесь інструкцій на Intel® software for general purpose GPU capabilities to download and install the necessary drivers.
b. Enable i915 debug support in Kernel:

a. Відкрийте термінал.
b. Відкрийте grub file в /etc/default.
c. У харчі file, знайдіть рядок GRUB_CMDLINE_LINUX_DEFAULT=””.
d. Enter the following text between the quotes (“”):

i915.debug_eu=1

ПРИМІТКА By default, the GPU driver does not allow workloads to run on a GPU longer than a certain amount of time. The driver kills such long-running workloads by resetting the GPU to prevent hangs. The hangcheck mechanism of the driver is disabled if the application is running under the debugger. If you plan to run long compute workloads also without a debugger being attached, consider applying GPU: Вимкніть Hangcheck шляхом додавання

i915.enable_hangcheck=0

до того ж GRUB_CMDLINE_LINUX_DEFAULT line.

c. Update GRUB for these changes to take effect:

sudo update-grub

d. Reboot.

2. Set up your CLI environment by sourcing the setvars script located in the root of your toolkit installation.

Linux (sudo):

джерело /opt/intel/oneapi/setvars.sh

Linux (user):

джерело ~/intel/oneapi/setvars.sh

3. Середовище налаштування
Use the following environment variables to enable debugger support for Intel® oneAPI Level Zero:

export ZET_ENABLE_PROGRAM_DEBUGGING=1
export IGC_EnableGTLocationDebugging=1

4. Перевірка системи
When everything is ready, please run the following command to confirm that the system configuration is reliable:

python3 /path/to/intel/oneapi/diagnostics/latest/diagnostics.py –filter debugger_sys_check -force

A possible output of a well configured system is as follows:

...
Checks results:
================================================== ===============================
Check name: debugger_sys_check
Description: This check verifies if the environment is ready to use gdb (Intel(R) Distribution for GDB*).
Result status: PASS
Debugger found.
libipt found.
libiga found.
i915 debug is enabled.
Environmental variables correct. ==================================================================================

1 CHECK: 1 PASS, 0 FAIL, 0 WARNINGS, 0 ERRORS

Вихід консолі file: /path/to/logs/diagnostics_filter_debugger_sys_check_force.txt JSON output file: /path/to/diagnostics/logs/diagnostics_filter_debugger_sys_check_force.json …

Compile the Program with Debug Information

You can use the sample project, Array Transform, to quickly get started with the application debugger.

1. To get the sample, choose any of the following ways:

Use the oneAPI CLI Samples Browser to select Array Transform from the Getting Started category.
Скачати з GitHub*.

2. Navigate to the src of the sampпроект:

cd array-transform/src

3. Compile the application by enabling the debug info (-g flag) and turning off optimizations (-O0 flag).
Disabling optimization is recommended for a stable and accurate debug environment. This helps to avoid confusion caused by changes to the code after compiler optimizations.

ПРИМІТКА You can still compile the program with optimization enabled (-O2 flag), which can be helpful if you aim at GPU assembly debugging.

You can compile the program in several ways. Options 1 and 2 use just-in-time (JIT) compilation, which is recommended to debug the sample. Option 3 uses ahead-of-time (AOT) compilation.

Option 1. You can use the CMake file to configure and build the application. Refer to the README з sample for the instructions.

ПРИМІТКА The CMake file provided with the sample already passes the -g -O0 flags.

Option 2. To compile the array-transform.cpp sample application without the CMake file, issue the following commands:

icpx -fsycl -g -O0 array-transform.cpp -o array-transform

If compilation and linking is done separately, retain the -g -O0 flags at the link step. The link step is when icpx translates these flags to be passed to the device compiler at runtime. Exampле:

icpx -fsycl -g -O0 -c array-transform.cpp
icpx -fsycl -g -O0 array-transform.o -o array-transform

Option 3. You can use AOT compilation to avoid longer JIT compilation times at runtime. JIT compilation can take significantly longer for large kernels under the debugger. To use Ahead-of-Time compilation mode:

• For debugging on a GPU:
Specify the device that you will use for program execution. For example, -device dg2-g10 for Intel® Data Center GPU Flex 140 Graphics. For the list of supported options and more information on AOT compilation, refer to the Intel® oneAPI DPC++ Compiler Developer Guide and Reference.
Для exampле:

icpx -fsycl -g -O0 -fsycl-targets=spir64_gen -Xs “-device dg2-g10” array-transform.cpp -o arraytransform

Ahead-of-Time compilation requires the OpenCLTM Offline Compiler (OC Compiler LOC). For more information, refer the section “Install OpenCLTM Offline Compiler (OCLOC)” of the Керівництво по установці.

• For debugging on a CPU:

icpx -fsycl -g -O0 -fsycl-targets=spir64_x86_64 array-transform.cpp -o array-transform

Start a Debug Session

Start the debug session:

1. Start Intel® Distribution for GDB* as follows:

gdb-oneapi array-transform

You should see the (gdb) prompt.

2. To make sure that the kernel is offloaded to the right device, do the following steps. When you execute the run command from the (gdb) prompt, pass the центральний процесор, графічний процесор or прискорювач Аргумент:

For debugging on the CPU:

run cpu

Exampвихід файлу:

[SYCL] Using device: [Intel(R) Core(TM) i7-9750H CPU @ 2.60GHz] from [Intel(R) OpenCL]

For debugging on the GPU:

run gpu

Exampвихід файлу:

[SYCL] Using device: [Intel(R) Data Center GPU Flex Series 140 [0x56c1]] from [Intel(R) LevelZero]

For debugging on the FPGA-emulator:

run accelerator

Exampвихід файлу:

[SYCL] Using device: [Intel(R) FPGA Emulation Device] from [Intel(R) FPGA Emulation Platform for OpenCL(TM) software]

ПРИМІТКА The cpu, gpu, and accelerator parameters are specific to the Array Transform application.

3. To quit the Intel® Distribution for GDB*:

вихід

For your convenience, common Intel® Distribution for GDB* commands are provided in the Reference Sheet.

To debug the Array Transform sample and learn more about Intel® Distribution for GDB*, walk through basic debugging scenarios using the Підручник.

Детальніше

Документ	опис
Tutorial: Debugging with Intel® Distribution for GDB*	This document describes the basic scenarios to follow while debugging SYCL* and OpenCL with Intel® Distribution for GDB*.
Intel® Distribution for GDB* User Guide	This document describes all common tasks that you can complete with Intel® Distribution for GDB* and provides necessary technical details.
Intel® Distribution for GDB* Release Notes	The notes contain information about key capabilities, new features, and known issues of Intel® Distribution for GDB*.
oneAPI Product Page	This page contains brief introduction on oneAPI toolkits and links to useful resources.
Intel® Distribution for GDB* Reference Sheet	This one-page document briefly describes Intel® Distribution for GDB* prerequisites and useful commands.
Jacobi Sample	This small SYCL* application has two versions: bugged and fixed. Use the sample to exercise application debugging with Intel® Distribution for GDB*.

Повідомлення та застереження

Технології Intel можуть вимагати активації апаратного, програмного забезпечення або послуги.

Жоден продукт чи компонент не може бути абсолютно безпечним.

Ваші витрати та результати можуть відрізнятися.

Цей документ не надає жодної ліцензії (прямої чи неявної, estoppel чи іншим чином) на будь-які права інтелектуальної власності.

Описана продукція може містити дефекти конструкції або помилки, відомі як помилки, які можуть призвести до відхилення виробу від опублікованих специфікацій. Поточні характеристичні помилки доступні за запитом.

Intel відмовляється від усіх явних і непрямих гарантій, включаючи, без обмежень, непрямі гарантії придатності для продажу, придатності для певної мети та непорушення прав, а також будь-які гарантії, що випливають із ходу роботи, поведінки чи використання в торгівлі.

OpenCL і логотип OpenCL є товарними знаками Apple Inc., які використовуються з дозволу Khronos.

Документи / Ресурси

intel Distribution for GDB on Linux OS Host [pdf] Посібник користувача
Distribution for GDB on Linux OS Host, GDB on Linux OS Host, Linux OS Host, OS Host, Host