This document describes how to use the Intercept Layer for OpenCL Applications to capture AUB files. An AUB file is an Intel GPU trace file format. It consists of HW commands, kernel ISA, and memory state, and can be used with various simulators for debugging and performance analysis.
The Intercept Layer for OpenCL Applications relies on the underlying GPU device drivers to actually perform AUB file capture. To reduce the size of an AUB file, the Intercept Layer for OpenCL Applications can be used to filter AUB file capture to a specific kernel and/or sub-section of an application.
This document describes the steps needed to enable AUB file capture. For details about specific AUB file controls, please refer to the AubCapture Controls section in the controls documentation.
The Intercept Layer for OpenCL Applications supports two methods of AUB file capture. The newest and default method relies on AUB capture functionality in the NEO OpenCL implementation. This method is described in detail in this document. The Intercept Layer for OpenCL Applications also supports the older KDC method for aub capture, however this method is deprecated, is not recommended, and is supported for internal use only.
IMPORTANT NOTE: NEO AUB file capture requires a Debug or Internal driver build. Most published drivers are Release driver builds, which do not support AUB file capture.
To initially enable NEO AUB file capture, please enable the NEO controls
AUBDumpSubcaptureMode
and SetCommandStreamReceiver
.
The mechanism to enable these controls is operating system dependent.
On Windows, enable NEO AUB file capture by setting two REG_DWORD
registry values
in the registry key:
HKEY_CURRENT_USER\SOFTWARE\INTEL\IGFX\OCL
The first registry value should be named AUBDumpSubCaptureMode
and should have the
value 2
, indicating Toggle
mode.
The second registry value should be named SetCommandStreamReceiver
and should have
the value 3
, indicating that commands should both be captured and sent to the GPU.
On Linux, enable NEO file AUB capture by setting the environment variable
AUBDumpSubCaptureMode
to the value 2
, indicating Toggle
mode, and by setting
the environment variable SetCommandStreamReceiver
to the value 3
, indicating that
commands should both be captured and sent to the GPU.
The AUBDumpSubCaptureMode
and SetCommandStreamReceiver
variables may also be set
via the config file igdrcl.config
, if preferred.
Suggested Intercept Layer for OpenCL Applications controls to test AUB file capture are:
AubCapture=1 // This is the "master" control for AUB Capture.
AubCaptureIndividualEnqueues=1 // One file per enqueue.
AubCaptureMaxEnqueue=10 // No more than 10 files.
Run your application with these controls, and you should see up to 10 AUB files
captured.
The exact number will depend on the number of kernel enqueues in the first 10 enqueues.
If the first 10 enqueues do not include any kernel enqueues, increase the
AubCaptureMaxEnqueue
value.
* Other names and brands may be claimed as the property of others.
Copyright (c) 2018-2020, Intel(R) Corporation