1<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Linux GPU Driver Developer's Guide</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="index.html" title="Linux GPU Driver Developer's Guide"><link rel="next" href="drmCore.html" title="Part I. DRM Core"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Linux GPU Driver Developer's Guide</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="drmCore.html">Next</a></td></tr></table><hr></div><div class="book"><div class="titlepage"><div><div><h1 class="title"><a name="gpuDevelopersGuide"></a>Linux GPU Driver Developer's Guide</h1></div><div><div class="authorgroup"><div class="author"><h3 class="author"><span class="firstname">Jesse</span> <span class="surname">Barnes</span></h3><span class="contrib">Initial version</span> <div class="affiliation"><span class="orgname">Intel Corporation<br></span><div class="address"><p><br> 2 <code class="email"><<a class="email" href="mailto:jesse.barnes@intel.com">jesse.barnes@intel.com</a>></code><br> 3 </p></div></div></div><div class="author"><h3 class="author"><span class="firstname">Laurent</span> <span class="surname">Pinchart</span></h3><span class="contrib">Driver internals</span> <div class="affiliation"><span class="orgname">Ideas on board SPRL<br></span><div class="address"><p><br> 4 <code class="email"><<a class="email" href="mailto:laurent.pinchart@ideasonboard.com">laurent.pinchart@ideasonboard.com</a>></code><br> 5 </p></div></div></div><div class="author"><h3 class="author"><span class="firstname">Daniel</span> <span class="surname">Vetter</span></h3><span class="contrib">Contributions all over the place</span> <div class="affiliation"><span class="orgname">Intel Corporation<br></span><div class="address"><p><br> 6 <code class="email"><<a class="email" href="mailto:daniel.vetter@ffwll.ch">daniel.vetter@ffwll.ch</a>></code><br> 7 </p></div></div></div><div class="author"><h3 class="author"><span class="firstname">Lukas</span> <span class="surname">Wunner</span></h3><span class="contrib">vga_switcheroo documentation</span> <div class="affiliation"><div class="address"><p><br> 8 <code class="email"><<a class="email" href="mailto:lukas@wunner.de">lukas@wunner.de</a>></code><br> 9 </p></div></div></div></div></div><div><p class="copyright">Copyright © 2008-2009, 2013-2014 Intel Corporation</p></div><div><p class="copyright">Copyright © 2012 Laurent Pinchart</p></div><div><p class="copyright">Copyright © 2015 Lukas Wunner</p></div><div><div class="legalnotice"><a name="id-1.1.6"></a><p> 10 The contents of this file may be used under the terms of the GNU 11 General Public License version 2 (the "GPL") as distributed in 12 the kernel source COPYING file. 13 </p></div></div><div><div class="revhistory"><table style="border-style:solid; width:100%;" summary="Revision History"><tr><th align="left" valign="top" colspan="3"><b>Revision History</b></th></tr><tr><td align="left">Revision 1.0</td><td align="left">2012-07-13</td><td align="left">LP</td></tr><tr><td align="left" colspan="3">Added extensive documentation about driver internals. 14 </td></tr><tr><td align="left">Revision 1.1</td><td align="left">2015-10-11</td><td align="left">LW</td></tr><tr><td align="left" colspan="3">Added vga_switcheroo documentation. 15 </td></tr></table></div></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="part"><a href="drmCore.html">I. DRM Core</a></span></dt><dd><dl><dt><span class="chapter"><a href="drmIntroduction.html">1. Introduction</a></span></dt><dt><span class="chapter"><a href="drmInternals.html">2. DRM Internals</a></span></dt><dd><dl><dt><span class="sect1"><a href="drmInternals.html#id-1.3.4.5">Driver Initialization</a></span></dt><dd><dl><dt><span class="sect2"><a href="drmInternals.html#id-1.3.4.5.4">Driver Information</a></span></dt><dt><span class="sect2"><a href="drmInternals.html#id-1.3.4.5.5">Device Instance and Driver Handling</a></span></dt><dt><span class="sect2"><a href="drmInternals.html#id-1.3.4.5.6">Driver Load</a></span></dt><dt><span class="sect2"><a href="drmInternals.html#id-1.3.4.5.7">Bus-specific Device Registration and PCI Support</a></span></dt></dl></dd><dt><span class="sect1"><a href="drm-memory-management.html">Memory management</a></span></dt><dd><dl><dt><span class="sect2"><a href="drm-memory-management.html#id-1.3.4.6.5">The Translation Table Manager (TTM)</a></span></dt><dt><span class="sect2"><a href="drm-memory-management.html#drm-gem">The Graphics Execution Manager (GEM)</a></span></dt><dt><span class="sect2"><a href="drm-memory-management.html#id-1.3.4.6.7">VMA Offset Manager</a></span></dt><dt><span class="sect2"><a href="drm-memory-management.html#drm-prime-support">PRIME Buffer Sharing</a></span></dt><dt><span class="sect2"><a href="drm-memory-management.html#id-1.3.4.6.9">PRIME Function References</a></span></dt><dt><span class="sect2"><a href="drm-memory-management.html#id-1.3.4.6.10">DRM MM Range Allocator</a></span></dt><dt><span class="sect2"><a href="drm-memory-management.html#id-1.3.4.6.11">DRM MM Range Allocator Function References</a></span></dt><dt><span class="sect2"><a href="drm-memory-management.html#id-1.3.4.6.12">CMA Helper Functions Reference</a></span></dt></dl></dd><dt><span class="sect1"><a href="drm-mode-setting.html">Mode Setting</a></span></dt><dd><dl><dt><span class="sect2"><a href="drm-mode-setting.html#id-1.3.4.7.4">Display Modes Function Reference</a></span></dt><dt><span class="sect2"><a href="drm-mode-setting.html#id-1.3.4.7.5">Atomic Mode Setting Function Reference</a></span></dt><dt><span class="sect2"><a href="drm-mode-setting.html#id-1.3.4.7.6">Frame Buffer Creation</a></span></dt><dt><span class="sect2"><a href="drm-mode-setting.html#id-1.3.4.7.7">Dumb Buffer Objects</a></span></dt><dt><span class="sect2"><a href="drm-mode-setting.html#id-1.3.4.7.8">Output Polling</a></span></dt><dt><span class="sect2"><a href="drm-mode-setting.html#id-1.3.4.7.9">Locking</a></span></dt></dl></dd><dt><span class="sect1"><a href="drm-kms-init.html">KMS Initialization and Cleanup</a></span></dt><dd><dl><dt><span class="sect2"><a href="drm-kms-init.html#id-1.3.4.8.3">CRTCs (struct drm_crtc)</a></span></dt><dt><span class="sect2"><a href="drm-kms-init.html#id-1.3.4.8.4">Planes (struct drm_plane)</a></span></dt><dt><span class="sect2"><a href="drm-kms-init.html#id-1.3.4.8.5">Encoders (struct drm_encoder)</a></span></dt><dt><span class="sect2"><a href="drm-kms-init.html#id-1.3.4.8.6">Connectors (struct drm_connector)</a></span></dt><dt><span class="sect2"><a href="drm-kms-init.html#id-1.3.4.8.7">Cleanup</a></span></dt><dt><span class="sect2"><a href="drm-kms-init.html#id-1.3.4.8.8">Output discovery and initialization example</a></span></dt><dt><span class="sect2"><a href="drm-kms-init.html#id-1.3.4.8.9">KMS API Functions</a></span></dt><dt><span class="sect2"><a href="drm-kms-init.html#id-1.3.4.8.10">KMS Data Structures</a></span></dt><dt><span class="sect2"><a href="drm-kms-init.html#id-1.3.4.8.11">KMS Locking</a></span></dt></dl></dd><dt><span class="sect1"><a href="ch02s05.html">Mode Setting Helper Functions</a></span></dt><dd><dl><dt><span class="sect2"><a href="ch02s05.html#id-1.3.4.9.6">Helper Functions</a></span></dt><dt><span class="sect2"><a href="ch02s05.html#id-1.3.4.9.7">CRTC Helper Operations</a></span></dt><dt><span class="sect2"><a href="ch02s05.html#id-1.3.4.9.8">Encoder Helper Operations</a></span></dt><dt><span class="sect2"><a href="ch02s05.html#id-1.3.4.9.9">Connector Helper Operations</a></span></dt><dt><span class="sect2"><a href="ch02s05.html#id-1.3.4.9.10">Atomic Modeset Helper Functions Reference</a></span></dt><dt><span class="sect2"><a href="ch02s05.html#id-1.3.4.9.11">Modeset Helper Functions Reference</a></span></dt><dt><span class="sect2"><a href="ch02s05.html#id-1.3.4.9.12">Output Probing Helper Functions Reference</a></span></dt><dt><span class="sect2"><a href="ch02s05.html#id-1.3.4.9.13">fbdev Helper Functions Reference</a></span></dt><dt><span class="sect2"><a href="ch02s05.html#id-1.3.4.9.14">Display Port Helper Functions Reference</a></span></dt><dt><span class="sect2"><a href="ch02s05.html#id-1.3.4.9.15">Display Port MST Helper Functions Reference</a></span></dt><dt><span class="sect2"><a href="ch02s05.html#id-1.3.4.9.16">MIPI DSI Helper Functions Reference</a></span></dt><dt><span class="sect2"><a href="ch02s05.html#id-1.3.4.9.17">EDID Helper Functions Reference</a></span></dt><dt><span class="sect2"><a href="ch02s05.html#id-1.3.4.9.18">Rectangle Utilities Reference</a></span></dt><dt><span class="sect2"><a href="ch02s05.html#id-1.3.4.9.19">Flip-work Helper Reference</a></span></dt><dt><span class="sect2"><a href="ch02s05.html#id-1.3.4.9.20">HDMI Infoframes Helper Reference</a></span></dt><dt><span class="sect2"><a href="ch02s05.html#id-1.3.4.9.21">Plane Helper Reference</a></span></dt><dt><span class="sect2"><a href="ch02s05.html#id-1.3.4.9.22">Tile group</a></span></dt><dt><span class="sect2"><a href="ch02s05.html#id-1.3.4.9.23">Bridges</a></span></dt></dl></dd><dt><span class="sect1"><a href="drm-kms-properties.html">KMS Properties</a></span></dt><dd><dl><dt><span class="sect2"><a href="drm-kms-properties.html#id-1.3.4.10.10">Existing KMS Properties</a></span></dt></dl></dd><dt><span class="sect1"><a href="drm-vertical-blank.html">Vertical Blanking</a></span></dt><dd><dl><dt><span class="sect2"><a href="drm-vertical-blank.html#id-1.3.4.11.10">Vertical Blanking and Interrupt Handling Functions Reference</a></span></dt></dl></dd><dt><span class="sect1"><a href="ch02s08.html">Open/Close, File Operations and IOCTLs</a></span></dt><dd><dl><dt><span class="sect2"><a href="ch02s08.html#id-1.3.4.12.2">Open and Close</a></span></dt><dt><span class="sect2"><a href="ch02s08.html#id-1.3.4.12.3">File Operations</a></span></dt><dt><span class="sect2"><a href="ch02s08.html#id-1.3.4.12.4">IOCTLs</a></span></dt></dl></dd><dt><span class="sect1"><a href="ch02s09.html">Legacy Support Code</a></span></dt><dd><dl><dt><span class="sect2"><a href="ch02s09.html#id-1.3.4.13.3">Legacy Suspend/Resume</a></span></dt><dt><span class="sect2"><a href="ch02s09.html#id-1.3.4.13.4">Legacy DMA Services</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="drmExternals.html">3. Userland interfaces</a></span></dt><dd><dl><dt><span class="sect1"><a href="drmExternals.html#id-1.3.5.5">Render nodes</a></span></dt><dt><span class="sect1"><a href="ch03s02.html">VBlank event handling</a></span></dt></dl></dd></dl></dd><dt><span class="part"><a href="drmDrivers.html">II. DRM Drivers</a></span></dt><dd><dl><dt><span class="chapter"><a href="drmI915.html">4. drm/i915 Intel GFX Driver</a></span></dt><dd><dl><dt><span class="sect1"><a href="drmI915.html#id-1.4.3.3">Core Driver Infrastructure</a></span></dt><dd><dl><dt><span class="sect2"><a href="drmI915.html#id-1.4.3.3.3">Runtime Power Management</a></span></dt><dt><span class="sect2"><a href="drmI915.html#id-1.4.3.3.4">Interrupt Handling</a></span></dt><dt><span class="sect2"><a href="drmI915.html#id-1.4.3.3.5">Intel GVT-g Guest Support(vGPU)</a></span></dt></dl></dd><dt><span class="sect1"><a href="ch04s02.html">Display Hardware Handling</a></span></dt><dd><dl><dt><span class="sect2"><a href="ch04s02.html#id-1.4.3.4.3">Mode Setting Infrastructure</a></span></dt><dt><span class="sect2"><a href="ch04s02.html#id-1.4.3.4.4">Frontbuffer Tracking</a></span></dt><dt><span class="sect2"><a href="ch04s02.html#id-1.4.3.4.5">Display FIFO Underrun Reporting</a></span></dt><dt><span class="sect2"><a href="ch04s02.html#id-1.4.3.4.6">Plane Configuration</a></span></dt><dt><span class="sect2"><a href="ch04s02.html#id-1.4.3.4.7">Atomic Plane Helpers</a></span></dt><dt><span class="sect2"><a href="ch04s02.html#id-1.4.3.4.8">Output Probing</a></span></dt><dt><span class="sect2"><a href="ch04s02.html#id-1.4.3.4.9">Hotplug</a></span></dt><dt><span class="sect2"><a href="ch04s02.html#id-1.4.3.4.10">High Definition Audio</a></span></dt><dt><span class="sect2"><a href="ch04s02.html#id-1.4.3.4.11">Panel Self Refresh PSR (PSR/SRD)</a></span></dt><dt><span class="sect2"><a href="ch04s02.html#id-1.4.3.4.12">Frame Buffer Compression (FBC)</a></span></dt><dt><span class="sect2"><a href="ch04s02.html#id-1.4.3.4.13">Display Refresh Rate Switching (DRRS)</a></span></dt><dt><span class="sect2"><a href="ch04s02.html#id-1.4.3.4.14">DPIO</a></span></dt><dt><span class="sect2"><a href="ch04s02.html#id-1.4.3.4.15">CSR firmware support for DMC</a></span></dt></dl></dd><dt><span class="sect1"><a href="ch04s03.html">Memory Management and Command Submission</a></span></dt><dd><dl><dt><span class="sect2"><a href="ch04s03.html#id-1.4.3.5.3">Batchbuffer Parsing</a></span></dt><dt><span class="sect2"><a href="ch04s03.html#id-1.4.3.5.4">Batchbuffer Pools</a></span></dt><dt><span class="sect2"><a href="ch04s03.html#id-1.4.3.5.5">Logical Rings, Logical Ring Contexts and Execlists</a></span></dt><dt><span class="sect2"><a href="ch04s03.html#id-1.4.3.5.6">Global GTT views</a></span></dt><dt><span class="sect2"><a href="ch04s03.html#id-1.4.3.5.7">GTT Fences and Swizzling</a></span></dt><dt><span class="sect2"><a href="ch04s03.html#id-1.4.3.5.8">Object Tiling IOCTLs</a></span></dt><dt><span class="sect2"><a href="ch04s03.html#id-1.4.3.5.9">Buffer Object Eviction</a></span></dt><dt><span class="sect2"><a href="ch04s03.html#id-1.4.3.5.10">Buffer Object Memory Shrinking</a></span></dt></dl></dd><dt><span class="sect1"><a href="ch04s04.html">GuC-based Command Submission</a></span></dt><dd><dl><dt><span class="sect2"><a href="ch04s04.html#id-1.4.3.6.2">GuC</a></span></dt><dt><span class="sect2"><a href="ch04s04.html#id-1.4.3.6.3">GuC Client</a></span></dt></dl></dd><dt><span class="sect1"><a href="ch04s05.html"> Tracing </a></span></dt><dd><dl><dt><span class="sect2"><a href="ch04s05.html#id-1.4.3.7.3"> i915_ppgtt_create and i915_ppgtt_release </a></span></dt><dt><span class="sect2"><a href="ch04s05.html#id-1.4.3.7.4"> i915_context_create and i915_context_free </a></span></dt><dt><span class="sect2"><a href="ch04s05.html#id-1.4.3.7.5"> switch_mm </a></span></dt></dl></dd></dl></dd></dl></dd><dt><span class="part"><a href="vga_switcheroo.html">III. vga_switcheroo</a></span></dt><dd><dl><dt><span class="chapter"><a href="modes_of_use.html">5. Modes of Use</a></span></dt><dd><dl><dt><span class="sect1"><a href="modes_of_use.html#id-1.5.3.2">Manual switching and manual power control</a></span></dt><dt><span class="sect1"><a href="ch05s02.html">Driver power control</a></span></dt></dl></dd><dt><span class="chapter"><a href="pubfunctions.html">6. Public functions</a></span></dt><dd><dl><dt><span class="refentrytitle"><a href="API-vga-switcheroo-register-handler.html"><span class="phrase">vga_switcheroo_register_handler</span></a></span><span class="refpurpose"> — 16 register handler 17 </span></dt><dt><span class="refentrytitle"><a href="API-vga-switcheroo-unregister-handler.html"><span class="phrase">vga_switcheroo_unregister_handler</span></a></span><span class="refpurpose"> — 18 unregister handler 19 </span></dt><dt><span class="refentrytitle"><a href="API-vga-switcheroo-register-client.html"><span class="phrase">vga_switcheroo_register_client</span></a></span><span class="refpurpose"> — 20 register vga client 21 </span></dt><dt><span class="refentrytitle"><a href="API-vga-switcheroo-register-audio-client.html"><span class="phrase">vga_switcheroo_register_audio_client</span></a></span><span class="refpurpose"> — 22 register audio client 23 </span></dt><dt><span class="refentrytitle"><a href="API-vga-switcheroo-get-client-state.html"><span class="phrase">vga_switcheroo_get_client_state</span></a></span><span class="refpurpose"> — 24 obtain power state of a given client 25 </span></dt><dt><span class="refentrytitle"><a href="API-vga-switcheroo-unregister-client.html"><span class="phrase">vga_switcheroo_unregister_client</span></a></span><span class="refpurpose"> — 26 unregister client 27 </span></dt><dt><span class="refentrytitle"><a href="API-vga-switcheroo-client-fb-set.html"><span class="phrase">vga_switcheroo_client_fb_set</span></a></span><span class="refpurpose"> — 28 set framebuffer of a given client 29 </span></dt><dt><span class="refentrytitle"><a href="API-vga-switcheroo-process-delayed-switch.html"><span class="phrase">vga_switcheroo_process_delayed_switch</span></a></span><span class="refpurpose"> — 30 helper for delayed switching 31 </span></dt><dt><span class="refentrytitle"><a href="API-vga-switcheroo-set-dynamic-switch.html"><span class="phrase">vga_switcheroo_set_dynamic_switch</span></a></span><span class="refpurpose"> — 32 helper for driver power control 33 </span></dt><dt><span class="refentrytitle"><a href="API-vga-switcheroo-init-domain-pm-ops.html"><span class="phrase">vga_switcheroo_init_domain_pm_ops</span></a></span><span class="refpurpose"> — 34 helper for driver power control 35 </span></dt><dt><span class="refentrytitle"><a href="API-vga-switcheroo-init-domain-pm-optimus-hdmi-audio.html"><span class="phrase">vga_switcheroo_init_domain_pm_optimus_hdmi_audio</span></a></span><span class="refpurpose"> — 36 helper for driver power control 37 </span></dt></dl></dd><dt><span class="chapter"><a href="pubstructures.html">7. Public structures</a></span></dt><dd><dl><dt><span class="refentrytitle"><a href="API-struct-vga-switcheroo-handler.html"><span class="phrase">struct vga_switcheroo_handler</span></a></span><span class="refpurpose"> — 38 handler callbacks 39 </span></dt><dt><span class="refentrytitle"><a href="API-struct-vga-switcheroo-client-ops.html"><span class="phrase">struct vga_switcheroo_client_ops</span></a></span><span class="refpurpose"> — 40 client callbacks 41 </span></dt></dl></dd><dt><span class="chapter"><a href="pubconstants.html">8. Public constants</a></span></dt><dd><dl><dt><span class="refentrytitle"><a href="API-enum-vga-switcheroo-client-id.html"><span class="phrase">enum vga_switcheroo_client_id</span></a></span><span class="refpurpose"> — 42 client identifier 43 </span></dt><dt><span class="refentrytitle"><a href="API-enum-vga-switcheroo-state.html"><span class="phrase">enum vga_switcheroo_state</span></a></span><span class="refpurpose"> — 44 client power state 45 </span></dt></dl></dd><dt><span class="chapter"><a href="privstructures.html">9. Private structures</a></span></dt><dd><dl><dt><span class="refentrytitle"><a href="API-struct-vgasr-priv.html"><span class="phrase">struct vgasr_priv</span></a></span><span class="refpurpose"> — 46 vga_switcheroo private data 47 </span></dt><dt><span class="refentrytitle"><a href="API-struct-vga-switcheroo-client.html"><span class="phrase">struct vga_switcheroo_client</span></a></span><span class="refpurpose"> — 48 registered client 49 </span></dt></dl></dd></dl></dd></dl></div><div class="list-of-tables"><p><b>List of Tables</b></p><dl><dt>2.1. <a href="drm-kms-properties.html#id-1.3.4.10.10.3"></a></dt><dt>4.1. <a href="ch04s02.html#dpiox2">Dual channel PHY (VLV/CHV/BXT)</a></dt><dt>4.2. <a href="ch04s02.html#dpiox1">Single channel PHY (CHV/BXT)</a></dt></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="drmCore.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"> </td><td width="40%" align="right" valign="top"> Part I. DRM Core</td></tr></table></div></body></html> 50