Linux GPU Driver Developer’s Guide

• Introduction
  • Style Guidelines
    • Documentation Requirements for kAPI
  • Getting Started
  • Contribution Process
    • Feature Merge Deadlines
    • Code of Conduct
• DRM Internals
  • Driver Initialization
    • Driver Information
      • Major, Minor and Patchlevel
      • Name, Description and Date
    • Managing Ownership of the Framebuffer Aperture
    • Device Instance and Driver Handling
      • Display driver example
    • Driver Load
      • Component Helper Usage
      • Memory Manager Initialization
      • Miscellaneous Device Configuration
    • Managed Resources
    • Bus-specific Device Registration and PCI Support
  • Open/Close, File Operations and IOCTLs
    • File Operations
  • Misc Utilities
    • Printer
    • Utilities
  • Legacy Support Code
    • Legacy Suspend/Resume
    • Legacy DMA Services
• DRM Memory Management
  • The Translation Table Manager (TTM)
    • TTM device object reference
    • TTM resource placement reference
    • TTM resource object reference
    • TTM TT object reference
    • TTM page pool reference
  • The Graphics Execution Manager (GEM)
    • GEM Initialization
    • GEM Objects Creation
    • GEM Objects Lifetime
    • GEM Objects Naming
    • GEM Objects Mapping
    • Memory Coherency
    • Command Execution
    • GEM Function Reference
    • GEM CMA Helper Functions Reference
    • GEM SHMEM Helper Function Reference
    • GEM VRAM Helper Functions Reference
    • GEM TTM Helper Functions Reference
  • VMA Offset Manager
  • PRIME Buffer Sharing
    • Overview and Lifetime Rules
      • Reference Counting for GEM Drivers
    • PRIME Helper Functions
      • Exporting buffers
      • Importing buffers
    • PRIME Function References
  • DRM MM Range Allocator
    • Overview
    • LRU Scan/Eviction Support
    • DRM MM Range Allocator Function References
  • DRM Cache Handling and Fast WC memcpy()
  • DRM Sync Objects
    • Host-side wait on syncobjs
    • Import/export of syncobjs
    • Import/export of timeline points in timeline syncobjs
  • GPU Scheduler
    • Overview
    • Scheduler Function References
• Kernel Mode Setting (KMS)
  • Overview
  • KMS Core Structures and Functions
  • Modeset Base Object Abstraction
  • Atomic Mode Setting
    • Handling Driver Private State
    • Atomic Mode Setting Function Reference
    • Atomic Mode Setting IOCTL and UAPI Functions
  • CRTC Abstraction
    • CRTC Functions Reference
    • Color Management Functions Reference
  • Frame Buffer Abstraction
    • Frame Buffer Functions Reference
  • DRM Format Handling
    • Format Modifiers
    • Format Functions Reference
  • Dumb Buffer Objects
  • Plane Abstraction
    • Plane Functions Reference
    • Plane Composition Functions Reference
    • Plane Damage Tracking Functions Reference
  • Display Modes Function Reference
  • Connector Abstraction
    • Connector Functions Reference
    • Writeback Connectors
  • Encoder Abstraction
    • Encoder Functions Reference
  • KMS Locking
  • KMS Properties
    • Requirements
    • Property Types and Blob Property Support
    • Standard Connector Properties
    • HDMI Specific Connector Properties
    • Standard CRTC Properties
    • Standard Plane Properties
    • Plane Composition Properties
    • Damage Tracking Properties
    • Color Management Properties
    • Tile Group Property
    • Explicit Fencing Properties
    • Variable Refresh Properties
    • Existing KMS Properties
  • Vertical Blanking
    • Vertical Blanking and Interrupt Handling Functions Reference
  • Vertical Blank Work
    • Vertical Blank Work Functions Reference
• Mode Setting Helper Functions
  • Modeset Helper Reference for Common Vtables
  • Atomic Modeset Helper Functions Reference
    • Overview
    • Implementing Asynchronous Atomic Commit
    • Helper Functions Reference
    • Atomic State Reset and Initialization
    • Atomic State Helper Reference
    • GEM Atomic Helper Reference
  • Simple KMS Helper Reference
  • fbdev Helper Functions Reference
  • format Helper Functions Reference
  • Framebuffer CMA Helper Functions Reference
  • Framebuffer GEM Helper Reference
  • Bridges
    • Overview
    • Display Driver Integration
    • Special Care with MIPI-DSI bridges
    • Bridge Operations
    • Bridge Connector Helper
    • Bridge Helper Reference
    • Bridge Connector Helper Reference
    • Panel-Bridge Helper Reference
  • Panel Helper Reference
  • Panel Self Refresh Helper Reference
  • HDCP Helper Functions Reference
  • Display Port Helper Functions Reference
  • Display Port CEC Helper Functions Reference
  • Display Port Dual Mode Adaptor Helper Functions Reference
  • Display Port MST Helpers
    • Overview
      • Topology refcount overview
      • Malloc refcount overview
      • Refcount relationships in a topology
    • Functions Reference
    • Topology Lifetime Internals
  • MIPI DBI Helper Functions Reference
  • MIPI DSI Helper Functions Reference
  • Display Stream Compression Helper Functions Reference
  • Output Probing Helper Functions Reference
  • EDID Helper Functions Reference
  • SCDC Helper Functions Reference
  • HDMI Infoframes Helper Reference
  • Rectangle Utilities Reference
  • Flip-work Helper Reference
  • Auxiliary Modeset Helpers
  • OF/DT Helpers
  • Legacy Plane Helper Reference
  • Legacy CRTC/Modeset Helper Functions Reference
• Userland interfaces
  • libdrm Device Lookup
  • Primary Nodes, DRM Master and Authentication
  • DRM Display Resource Leasing
  • Open-Source Userspace Requirements
  • Render nodes
  • Device Hot-Unplug
    • Requirements for KMS UAPI
    • Requirements for Render and Cross-Device UAPI
    • Requirements for Memory Maps
  • IOCTL Support on Device Nodes
    • Recommended IOCTL Return Values
  • Testing and validation
    • Testing Requirements for userspace API
    • Validating changes with IGT
    • Using VKMS to test DRM API
    • Display CRC Support
    • Debugfs Support
  • Sysfs Support
  • VBlank event handling
  • Userspace API Structures
    • CRTC index
• DRM Driver uAPI
  • drm/i915 uAPI
• Kernel clients
• GPU Driver Documentation
  • drm/amdgpu AMDgpu driver
    • Module Parameters
    • Core Driver Infrastructure
      • Memory Domains
      • Buffer Objects
      • PRIME Buffer Sharing
      • MMU Notifier
      • AMDGPU Virtual Memory
      • Interrupt Handling
      • IP Blocks
    • AMDGPU XGMI Support
    • AMDGPU RAS Support
      • RAS debugfs/sysfs Control and Error Injection Interfaces
      • RAS Reboot Behavior for Unrecoverable Errors
      • RAS Error Count sysfs Interface
      • RAS EEPROM debugfs Interface
      • RAS VRAM Bad Pages sysfs Interface
      • Sample Code
    • GPU Power/Thermal Controls and Monitoring
      • HWMON Interfaces
      • GPU sysfs Power State Interfaces
        • power_dpm_state
        • power_dpm_force_performance_level
        • pp_table
        • pp_od_clk_voltage
        • pp_dpm_*
        • pp_power_profile_mode
        • *_busy_percent
        • gpu_metrics
    • GPU Product Information
      • product_name
      • product_number
      • serial_number
      • unique_id
    • GPU Memory Usage Information
      • mem_info_vram_total
      • mem_info_vram_used
      • mem_info_vis_vram_total
      • mem_info_vis_vram_used
      • mem_info_gtt_total
      • mem_info_gtt_used
    • PCIe Accounting Information
      • pcie_bw
      • pcie_replay_count
    • GPU SmartShift Information
      • smartshift_apu_power
      • smartshift_dgpu_power
      • smartshift_bias
  • drm/amd/display - Display Core (DC)
    • AMDgpu Display Manager
      • Lifecycle
      • Interrupts
      • Atomic Implementation
    • Display Core
      • FreeSync Video
  • drm/i915 Intel GFX Driver
    • Core Driver Infrastructure
      • Runtime Power Management
      • Interrupt Handling
      • Intel GVT-g Guest Support(vGPU)
      • Intel GVT-g Host Support(vGPU device model)
      • Workarounds
        • Layout
    • Display Hardware Handling
      • Mode Setting Infrastructure
      • Frontbuffer Tracking
      • Display FIFO Underrun Reporting
      • Plane Configuration
      • Atomic Plane Helpers
      • Asynchronous Page Flip
      • Output Probing
      • Hotplug
      • High Definition Audio
      • Intel HDMI LPE Audio Support
      • Panel Self Refresh PSR (PSR/SRD)
      • Frame Buffer Compression (FBC)
      • Display Refresh Rate Switching (DRRS)
      • DPIO
      • DMC Firmware Support
      • Video BIOS Table (VBT)
      • Display clocks
      • Display PLLs
      • Display State Buffer
    • Memory Management and Command Submission
      • Intel GPU Basics
      • Locking Guidelines
      • GEM BO Management Implementation Details
      • Buffer Object Eviction
      • Buffer Object Memory Shrinking
      • Batchbuffer Parsing
      • User Batchbuffer Execution
      • Scheduling
      • Logical Rings, Logical Ring Contexts and Execlists
      • Global GTT views
      • GTT Fences and Swizzling
        • Global GTT Fence Handling
        • Hardware Tiling and Swizzling Details
      • Object Tiling IOCTLs
      • Protected Objects
    • Microcontrollers
      • WOPCM
        • WOPCM Layout
      • GuC
        • GuC Firmware Layout
        • GuC Memory Management
        • GuC-specific firmware loader
        • GuC-based command submission
        • GuC ABI
      • HuC
        • HuC Memory Management
        • HuC Firmware Layout
      • DMC
    • Tracing
      • i915_ppgtt_create and i915_ppgtt_release
      • i915_context_create and i915_context_free
    • Perf
      • Overview
      • Comparison with Core Perf
        • Issues hit with first prototype based on Core Perf
      • i915 Driver Entry Points
      • i915 Perf Stream
      • i915 Perf Observation Architecture Stream
      • Other i915 Perf Internals
    • Style
      • Register macro definition style
        • File Layout
        • Naming
        • Examples
  • drm/mcde ST-Ericsson MCDE Multi-channel display engine
  • drm/meson AmLogic Meson Video Processing Unit
    • Video Processing Unit
    • Video Input Unit
    • Video Post Processing
    • Video Encoder
    • Video Clocks
    • HDMI Video Output
  • drm/pl111 ARM PrimeCell PL110 and PL111 CLCD Driver
  • drm/tegra NVIDIA Tegra GPU and display driver
    • Driver Infrastructure
      • Host1x Infrastructure Reference
      • Host1x Syncpoint Reference
    • KMS driver
      • Display Controllers
        • Windows
      • Outputs
        • RGB/LVDS
        • HDMI
        • DSI
        • eDP/DP
    • Userspace Interface
      • GEM Buffers
      • Syncpoints
      • Command Stream Submission
  • drm/tve200 Faraday TV Encoder 200
  • drm/v3d Broadcom V3D Graphics Driver
    • GPU buffer object (BO) management
      • Address space management
      • GPU Scheduling
    • Interrupts
  • drm/vc4 Broadcom VC4 Graphics Driver
    • Display Hardware Handling
      • Pixel Valve (DRM CRTC)
      • HVS
      • HVS planes
      • HDMI encoder
      • DSI encoder
      • DPI encoder
      • VEC (Composite TV out) encoder
    • Memory Management and 3D Command Submission
      • GPU buffer object (BO) management
      • V3D binner command list (BCL) validation
      • V3D render command list (RCL) generation
      • Shader validator for VC4
      • V3D Interrupts
  • drm/vkms Virtual Kernel Modesetting
    • Setup
    • Testing With IGT
    • TODO
      • IGT better support
      • Add Plane Features
      • Runtime Configuration
      • Writeback support
      • Output Features
      • CRC API Improvements
      • Atomic Check using eBPF
  • drm/bridge/dw-hdmi Synopsys DesignWare HDMI Controller
    • Synopsys DesignWare HDMI Controller
      • Supported Input Formats and Encodings
  • drm/xen-front Xen para-virtualized frontend driver
    • Driver modes of operation in terms of display buffers used
      • Buffers allocated by the frontend driver
      • Buffers allocated by the backend
    • Driver limitations
  • Arm Framebuffer Compression (AFBC)
    • Components and Ordering
    • Number of Planes
    • Cross-device interoperability
  • drm/komeda Arm display driver
    • Overview of D71 like display IPs
      • Layer
      • Scaler
      • Compositor (compiz)
      • Writeback Layer (wb_layer)
      • Post image processor (improc)
      • Timing controller (timing_ctrlr)
      • Merger
      • Splitter
    • Possible D71 Pipeline usage
      • Single pipeline data flow
      • Dual pipeline with Slave enabled
      • Sub-pipelines for input and output
        • Layer(input) pipeline
        • Writeback(output) pipeline
        • Display output pipeline
    • Komeda Resource abstraction
      • struct komeda_pipeline/component
    • Resource discovery and initialization
    • Format handling
    • Attach komeda_dev to DRM-KMS
      • How to map plane to Layer(input) pipeline
      • Make component/pipeline to be drm_private_obj
      • Tracking component_state/pipeline_state by drm_atomic_state
      • komeda component validation
      • komeda_kms Abstraction
      • komde_kms Functions
    • Build komeda to be a Linux module driver
• Backlight support
• VGA Switcheroo
  • Modes of Use
    • Manual switching and manual power control
    • Driver power control
  • API
    • Public functions
    • Public structures
    • Public constants
    • Private structures
  • Handlers
    • apple-gmux Handler
      • Graphics mux
      • Power control
      • Backlight control
      • Public functions
• VGA Arbiter
  • vgaarb kernel/userspace ABI
  • In-kernel interface
  • libpciaccess
  • xf86VGAArbiter (X server implementation)
  • References
• TODO list
  • Difficulty
    • Subsystem-wide refactorings
  • Remove custom dumb_map_offset implementations
  • Convert existing KMS drivers to atomic modesetting
  • Clean up the clipped coordination confusion around planes
  • Improve plane atomic_check helpers
  • Convert early atomic drivers to async commit helpers
  • Fallout from atomic KMS
  • Get rid of dev->struct_mutex from GEM drivers
  • Move Buffer Object Locking to dma_resv_lock()
  • Convert logging to drm_* functions with drm_device paramater
  • Convert drivers to use simple modeset suspend/resume
  • Convert drivers to use drm_fbdev_generic_setup()
  • Reimplement functions in drm_fbdev_fb_ops without fbdev
  • drm_framebuffer_funcs and drm_mode_config_funcs.fb_create cleanup
  • Clean up mmap forwarding
  • Generic fbdev defio support
  • Garbage collect fbdev scrolling acceleration
  • idr_init_base()
  • struct drm_gem_object_funcs
  • Rename CMA helpers to DMA helpers
  • connector register/unregister fixes
  • Remove load/unload callbacks from all non-DRIVER_LEGACY drivers
  • Replace drm_detect_hdmi_monitor() with drm_display_info.is_hdmi
  • Consolidate custom driver modeset properties
  • Use struct dma_buf_map throughout codebase
    • Core refactorings
  • Make panic handling work
  • Clean up the debugfs support
  • Object lifetime fixes
  • Remove automatic page mapping from dma-buf importing
    • Better Testing
  • Enable trinity for DRM
  • Make KMS tests in i-g-t generic
  • Extend virtual test driver (VKMS)
  • Backlight Refactoring
    • Driver Specific
  • AMD DC Display Driver
    • Bootsplash
    • Outside DRM
  • Convert fbdev drivers to DRM
• GPU RFC Section
  • I915 DG1/LMEM RFC Section
    • Upstream plan
  • I915 GuC Submission/DRM Scheduler Section
    • Upstream plan
    • TODOs for GuC submission upstream
    • New uAPI for basic GuC submission
      • Spec references:
    • New parallel submission uAPI
      • Export engines logical mapping
      • A ‘set_parallel’ extension to configure contexts for parallel submission
      • Extend execbuf2 IOCTL to support submitting N BBs in a single IOCTL