<!DOCTYPE html>
<html lang="en" data-content_root="../../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>GPU Debugging — The Linux Kernel documentation</title>
<link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="../../_static/alabaster.css?v=3918102e" />
<script src="../../_static/documentation_options.js?v=5929fcd5"></script>
<script src="../../_static/doctools.js?v=9bcbadda"></script>
<script src="../../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="index" title="Index" href="../../genindex.html" />
<link rel="search" title="Search" href="../../search.html" />
<link rel="next" title="AMDGPU DebugFS" href="debugfs.html" />
<link rel="prev" title="Misc AMDGPU driver information" href="driver-misc.html" />
<link rel="stylesheet" href="../../_static/custom.css" type="text/css" />
</head><body>
<div class="document">
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../../index.html">
<img class="logo" src="../../_static/logo.svg" alt="Logo of The Linux Kernel"/>
</a></p>
<h1 class="logo"><a href="../../index.html">The Linux Kernel</a></h1>
<p class="blurb">6.18.50</p>
<search id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script>
<p>
<h3 class="kernel-toc-contents">Contents</h3>
<input type="checkbox" class="kernel-toc-toggle" id = "kernel-toc-toggle" checked>
<label class="kernel-toc-title" for="kernel-toc-toggle"></label>
<div class="kerneltoc" id="kerneltoc">
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../process/development-process.html">Development process</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../process/submitting-patches.html">Submitting patches</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../process/code-of-conduct.html">Code of conduct</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../maintainer/index.html">Maintainer handbook</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../process/index.html">All development-process docs</a></li>
</ul>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../core-api/index.html">Core API</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../driver-api/index.html">Driver APIs</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../../subsystem-apis.html">Subsystems</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../../subsystem-apis.html#core-subsystems">Core subsystems</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="../../subsystem-apis.html#human-interfaces">Human interfaces</a><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="../../input/index.html">Input Documentation</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../hid/index.html">Human Interface Devices (HID)</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../sound/index.html">Sound Subsystem Documentation</a></li>
<li class="toctree-l3 current"><a class="reference internal" href="../index.html">GPU Driver Developer’s Guide</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../fb/index.html">Frame Buffer</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../leds/index.html">LEDs</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../../subsystem-apis.html#networking-interfaces">Networking interfaces</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../subsystem-apis.html#storage-interfaces">Storage interfaces</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../subsystem-apis.html#other-subsystems">Other subsystems</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../locking/index.html">Locking</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../process/license-rules.html">Licensing rules</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../doc-guide/index.html">Writing documentation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../dev-tools/index.html">Development tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../dev-tools/testing-overview.html">Testing guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../kernel-hacking/index.html">Hacking guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../trace/index.html">Tracing</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../fault-injection/index.html">Fault injection</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../livepatch/index.html">Livepatching</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../rust/index.html">Rust</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../admin-guide/index.html">Administration</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../kbuild/index.html">Build system</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../admin-guide/reporting-issues.html">Reporting issues</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../tools/index.html">Userspace tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../userspace-api/index.html">Userspace API</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../firmware-guide/index.html">Firmware</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../devicetree/index.html">Firmware and Devicetree</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../arch/index.html">CPU architectures</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../staging/index.html">Unsorted documentation</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../translations/index.html">Translations</a></li>
</ul>
</div>
<script type="text/javascript"> <!--
var sbar = document.getElementsByClassName("sphinxsidebar")[0];
let currents = document.getElementsByClassName("current")
if (currents.length) {
sbar.scrollTop = currents[currents.length - 1].offsetTop;
}
--> </script>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../../_sources/gpu/amdgpu/debugging.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
</div>
</div>
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="gpu-debugging">
<h1>GPU Debugging<a class="headerlink" href="#gpu-debugging" title="Link to this heading">¶</a></h1>
<section id="general-debugging-options">
<h2>General Debugging Options<a class="headerlink" href="#general-debugging-options" title="Link to this heading">¶</a></h2>
<p>The DebugFS section provides documentation on a number files to aid in debugging
issues on the GPU.</p>
</section>
<section id="gpuvm-debugging">
<h2>GPUVM Debugging<a class="headerlink" href="#gpuvm-debugging" title="Link to this heading">¶</a></h2>
<p>To aid in debugging GPU virtual memory related problems, the driver supports a
number of options module parameters:</p>
<p><cite>vm_fault_stop</cite> - If non-0, halt the GPU memory controller on a GPU page fault.</p>
<p><cite>vm_update_mode</cite> - If non-0, use the CPU to update GPU page tables rather than
the GPU.</p>
</section>
<section id="decoding-a-gpuvm-page-fault">
<h2>Decoding a GPUVM Page Fault<a class="headerlink" href="#decoding-a-gpuvm-page-fault" title="Link to this heading">¶</a></h2>
<p>If you see a GPU page fault in the kernel log, you can decode it to figure
out what is going wrong in your application. A page fault in your kernel
log may look something like this:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>[gfxhub0] no-retry page fault (src_id:0 ring:24 vmid:3 pasid:32777, for process glxinfo pid 2424 thread glxinfo:cs0 pid 2425)
in page starting at address 0x0000800102800000 from IH client 0x1b (UTCL2)
VM_L2_PROTECTION_FAULT_STATUS:0x00301030
Faulty UTCL2 client ID: TCP (0x8)
MORE_FAULTS: 0x0
WALKER_ERROR: 0x0
PERMISSION_FAULTS: 0x3
MAPPING_ERROR: 0x0
RW: 0x0
</pre></div>
</div>
<p>First you have the memory hub, gfxhub and mmhub. gfxhub is the memory
hub used for graphics, compute, and sdma on some chips. mmhub is the
memory hub used for multi-media and sdma on some chips.</p>
<p>Next you have the vmid and pasid. If the vmid is 0, this fault was likely
caused by the kernel driver or firmware. If the vmid is non-0, it is generally
a fault in a user application. The pasid is used to link a vmid to a system
process id. If the process is active when the fault happens, the process
information will be printed.</p>
<p>The GPU virtual address that caused the fault comes next.</p>
<p>The client ID indicates the GPU block that caused the fault.
Some common client IDs:</p>
<ul class="simple">
<li><p>CB/DB: The color/depth backend of the graphics pipe</p></li>
<li><p>CPF: Command Processor Frontend</p></li>
<li><p>CPC: Command Processor Compute</p></li>
<li><p>CPG: Command Processor Graphics</p></li>
<li><p>TCP/SQC/SQG: Shaders</p></li>
<li><p>SDMA: SDMA engines</p></li>
<li><p>VCN: Video encode/decode engines</p></li>
<li><p>JPEG: JPEG engines</p></li>
</ul>
<p>PERMISSION_FAULTS describe what faults were encountered:</p>
<ul class="simple">
<li><p>bit 0: the PTE was not valid</p></li>
<li><p>bit 1: the PTE read bit was not set</p></li>
<li><p>bit 2: the PTE write bit was not set</p></li>
<li><p>bit 3: the PTE execute bit was not set</p></li>
</ul>
<p>Finally, RW, indicates whether the access was a read (0) or a write (1).</p>
<p>In the example above, a shader (cliend id = TCP) generated a read (RW = 0x0) to
an invalid page (PERMISSION_FAULTS = 0x3) at GPU virtual address
0x0000800102800000. The user can then inspect their shader code and resource
descriptor state to determine what caused the GPU page fault.</p>
</section>
<section id="umr">
<h2>UMR<a class="headerlink" href="#umr" title="Link to this heading">¶</a></h2>
<p><a class="reference external" href="https://gitlab.freedesktop.org/tomstdenis/umr">umr</a> is a general purpose
GPU debugging and diagnostics tool. Please see the umr
<a class="reference external" href="https://umr.readthedocs.io/en/main/">documentation</a> for more information
about its capabilities.</p>
</section>
<section id="debugging-backlight-brightness">
<h2>Debugging backlight brightness<a class="headerlink" href="#debugging-backlight-brightness" title="Link to this heading">¶</a></h2>
<p>Default backlight brightness is intended to be set via the policy advertised
by the firmware. Firmware will often provide different defaults for AC or DC.
Furthermore, some userspace software will save backlight brightness during
the previous boot and attempt to restore it.</p>
<p>Some firmware also has support for a feature called “Custom Backlight Curves”
where an input value for brightness is mapped along a linearly interpolated
curve of brightness values that better match display characteristics.</p>
<p>In the event of problems happening with backlight, there is a trace event
that can be enabled at bootup to log every brightness change request.
This can help isolate where the problem is. To enable the trace event add
the following to the kernel command line:</p>
<blockquote>
<div><p>tp_printk trace_event=amdgpu_dm:amdgpu_dm_brightness:mod:amdgpu trace_buf_size=1M</p>
</div></blockquote>
</section>
</section>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
©The kernel development community.
|
Powered by <a href="https://www.sphinx-doc.org/">Sphinx 8.1.3</a>
& <a href="https://alabaster.readthedocs.io">Alabaster 0.7.16</a>
|
<a href="../../_sources/gpu/amdgpu/debugging.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>