Documentation/gpu: split up the gpu documentation

Userland interfaces

===================

The DRM core exports several interfaces to applications, generally

intended to be used through corresponding libdrm wrapper functions. In

addition, drivers export device-specific interfaces for use by userspace

drivers & device-aware applications through ioctls and sysfs files.

External interfaces include: memory mapping, context management, DMA

operations, AGP management, vblank control, fence management, memory

management, and output management.

Cover generic ioctls and sysfs layout here. We only need high-level

info, since man pages should cover the rest.

Render nodes

------------

DRM core provides multiple character-devices for user-space to use.

Depending on which device is opened, user-space can perform a different

set of operations (mainly ioctls). The primary node is always created

and called card<num>. Additionally, a currently unused control node,

called controlD<num> is also created. The primary node provides all

legacy operations and historically was the only interface used by

userspace. With KMS, the control node was introduced. However, the

planned KMS control interface has never been written and so the control

node stays unused to date.

With the increased use of offscreen renderers and GPGPU applications,

clients no longer require running compositors or graphics servers to

make use of a GPU. But the DRM API required unprivileged clients to

authenticate to a DRM-Master prior to getting GPU access. To avoid this

step and to grant clients GPU access without authenticating, render

nodes were introduced. Render nodes solely serve render clients, that

is, no modesetting or privileged ioctls can be issued on render nodes.

Only non-global rendering commands are allowed. If a driver supports

render nodes, it must advertise it via the DRIVER_RENDER DRM driver

capability. If not supported, the primary node must be used for render

clients together with the legacy drmAuth authentication procedure.

If a driver advertises render node support, DRM core will create a

separate render node called renderD<num>. There will be one render node

per device. No ioctls except PRIME-related ioctls will be allowed on

this node. Especially GEM_OPEN will be explicitly prohibited. Render

nodes are designed to avoid the buffer-leaks, which occur if clients

guess the flink names or mmap offsets on the legacy interface.

Additionally to this basic interface, drivers must mark their

driver-dependent render-only ioctls as DRM_RENDER_ALLOW so render

clients can use them. Driver authors must be careful not to allow any

privileged ioctls on render nodes.

With render nodes, user-space can now control access to the render node

via basic file-system access-modes. A running graphics server which

authenticates clients on the privileged primary/legacy node is no longer

required. Instead, a client can open the render node and is immediately

granted GPU access. Communication between clients (or servers) is done

via PRIME. FLINK from render node to legacy node is not supported. New

clients must not use the insecure FLINK interface.

Besides dropping all modeset/global ioctls, render nodes also drop the

DRM-Master concept. There is no reason to associate render clients with

a DRM-Master as they are independent of any graphics server. Besides,

they must work without any running master, anyway. Drivers must be able

to run without a master object if they support render nodes. If, on the

other hand, a driver requires shared state between clients which is

visible to user-space and accessible beyond open-file boundaries, they

cannot support render nodes.

VBlank event handling

---------------------

The DRM core exposes two vertical blank related ioctls:

DRM_IOCTL_WAIT_VBLANK

    This takes a struct drm_wait_vblank structure as its argument, and

    it is used to block or request a signal when a specified vblank

    event occurs.

DRM_IOCTL_MODESET_CTL

    This was only used for user-mode-settind drivers around modesetting

    changes to allow the kernel to update the vblank interrupt after

    mode setting, since on many devices the vertical blank counter is

    reset to 0 at some point during modeset. Modern drivers should not

    call this any more since with kernel mode setting it is a no-op.

This second part of the GPU Driver Developer's Guide documents driver

code, implementation details and also all the driver-specific userspace

interfaces. Especially since all hardware-acceleration interfaces to

userspace are driver specific for efficiency and other reasons these

interfaces can be rather substantial. Hence every driver has its own

chapter.

drm/i915 Intel GFX Driver

=========================

The drm/i915 driver supports all (with the exception of some very early

models) integrated GFX chipsets with both Intel display and rendering

blocks. This excludes a set of SoC platforms with an SGX rendering unit,

those have basic support through the gma500 drm driver.

Core Driver Infrastructure

--------------------------

This section covers core driver infrastructure used by both the display

and the GEM parts of the driver.

Runtime Power Management

~~~~~~~~~~~~~~~~~~~~~~~~

.. kernel-doc:: drivers/gpu/drm/i915/intel_runtime_pm.c

   :doc: runtime pm

.. kernel-doc:: drivers/gpu/drm/i915/intel_runtime_pm.c

   :internal:

.. kernel-doc:: drivers/gpu/drm/i915/intel_uncore.c

   :internal:

Interrupt Handling

~~~~~~~~~~~~~~~~~~

.. kernel-doc:: drivers/gpu/drm/i915/i915_irq.c

   :doc: interrupt handling

.. kernel-doc:: drivers/gpu/drm/i915/i915_irq.c

   :functions: intel_irq_init intel_irq_init_hw intel_hpd_init

.. kernel-doc:: drivers/gpu/drm/i915/i915_irq.c

   :functions: intel_runtime_pm_disable_interrupts

.. kernel-doc:: drivers/gpu/drm/i915/i915_irq.c

   :functions: intel_runtime_pm_enable_interrupts

Intel GVT-g Guest Support(vGPU)

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. kernel-doc:: drivers/gpu/drm/i915/i915_vgpu.c

   :doc: Intel GVT-g guest support

.. kernel-doc:: drivers/gpu/drm/i915/i915_vgpu.c

   :internal:

Display Hardware Handling

-------------------------

This section covers everything related to the display hardware including

the mode setting infrastructure, plane, sprite and cursor handling and

display, output probing and related topics.

Mode Setting Infrastructure

~~~~~~~~~~~~~~~~~~~~~~~~~~~

The i915 driver is thus far the only DRM driver which doesn't use the

common DRM helper code to implement mode setting sequences. Thus it has

its own tailor-made infrastructure for executing a display configuration

change.

Frontbuffer Tracking

~~~~~~~~~~~~~~~~~~~~

.. kernel-doc:: drivers/gpu/drm/i915/intel_frontbuffer.c

   :doc: frontbuffer tracking

.. kernel-doc:: drivers/gpu/drm/i915/intel_frontbuffer.c

   :internal:

.. kernel-doc:: drivers/gpu/drm/i915/i915_gem.c

   :functions: i915_gem_track_fb

Display FIFO Underrun Reporting

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. kernel-doc:: drivers/gpu/drm/i915/intel_fifo_underrun.c

   :doc: fifo underrun handling

.. kernel-doc:: drivers/gpu/drm/i915/intel_fifo_underrun.c

   :internal:

Plane Configuration

~~~~~~~~~~~~~~~~~~~

This section covers plane configuration and composition with the primary

plane, sprites, cursors and overlays. This includes the infrastructure

to do atomic vsync'ed updates of all this state and also tightly coupled

topics like watermark setup and computation, framebuffer compression and

panel self refresh.

Atomic Plane Helpers

~~~~~~~~~~~~~~~~~~~~

.. kernel-doc:: drivers/gpu/drm/i915/intel_atomic_plane.c

   :doc: atomic plane helpers

.. kernel-doc:: drivers/gpu/drm/i915/intel_atomic_plane.c

   :internal:

Output Probing

~~~~~~~~~~~~~~

This section covers output probing and related infrastructure like the

hotplug interrupt storm detection and mitigation code. Note that the

i915 driver still uses most of the common DRM helper code for output

probing, so those sections fully apply.

Hotplug

~~~~~~~

.. kernel-doc:: drivers/gpu/drm/i915/intel_hotplug.c

   :doc: Hotplug

.. kernel-doc:: drivers/gpu/drm/i915/intel_hotplug.c

   :internal:

High Definition Audio

~~~~~~~~~~~~~~~~~~~~~

.. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c

   :doc: High Definition Audio over HDMI and Display Port

.. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c

   :internal:

.. kernel-doc:: include/drm/i915_component.h

   :internal:

Panel Self Refresh PSR (PSR/SRD)

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. kernel-doc:: drivers/gpu/drm/i915/intel_psr.c

   :doc: Panel Self Refresh (PSR/SRD)

.. kernel-doc:: drivers/gpu/drm/i915/intel_psr.c

   :internal:

Frame Buffer Compression (FBC)

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. kernel-doc:: drivers/gpu/drm/i915/intel_fbc.c

   :doc: Frame Buffer Compression (FBC)

.. kernel-doc:: drivers/gpu/drm/i915/intel_fbc.c

   :internal:

Display Refresh Rate Switching (DRRS)

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. kernel-doc:: drivers/gpu/drm/i915/intel_dp.c

   :doc: Display Refresh Rate Switching (DRRS)

.. kernel-doc:: drivers/gpu/drm/i915/intel_dp.c

   :functions: intel_dp_set_drrs_state

.. kernel-doc:: drivers/gpu/drm/i915/intel_dp.c

   :functions: intel_edp_drrs_enable

.. kernel-doc:: drivers/gpu/drm/i915/intel_dp.c

   :functions: intel_edp_drrs_disable

.. kernel-doc:: drivers/gpu/drm/i915/intel_dp.c

   :functions: intel_edp_drrs_invalidate

.. kernel-doc:: drivers/gpu/drm/i915/intel_dp.c

   :functions: intel_edp_drrs_flush

.. kernel-doc:: drivers/gpu/drm/i915/intel_dp.c

   :functions: intel_dp_drrs_init

DPIO

~~~~

.. kernel-doc:: drivers/gpu/drm/i915/i915_reg.h

   :doc: DPIO

CSR firmware support for DMC

~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. kernel-doc:: drivers/gpu/drm/i915/intel_csr.c

   :doc: csr support for dmc

.. kernel-doc:: drivers/gpu/drm/i915/intel_csr.c

   :internal:

Video BIOS Table (VBT)

~~~~~~~~~~~~~~~~~~~~~~

.. kernel-doc:: drivers/gpu/drm/i915/intel_bios.c

   :doc: Video BIOS Table (VBT)

.. kernel-doc:: drivers/gpu/drm/i915/intel_bios.c

   :internal:

.. kernel-doc:: drivers/gpu/drm/i915/intel_vbt_defs.h

   :internal:

Memory Management and Command Submission

----------------------------------------

This sections covers all things related to the GEM implementation in the

i915 driver.

Batchbuffer Parsing

~~~~~~~~~~~~~~~~~~~

.. kernel-doc:: drivers/gpu/drm/i915/i915_cmd_parser.c

   :doc: batch buffer command parser

.. kernel-doc:: drivers/gpu/drm/i915/i915_cmd_parser.c

   :internal:

Batchbuffer Pools

~~~~~~~~~~~~~~~~~

.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_batch_pool.c

   :doc: batch pool

.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_batch_pool.c

   :internal:

Logical Rings, Logical Ring Contexts and Execlists

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. kernel-doc:: drivers/gpu/drm/i915/intel_lrc.c

   :doc: Logical Rings, Logical Ring Contexts and Execlists

.. kernel-doc:: drivers/gpu/drm/i915/intel_lrc.c

   :internal:

Global GTT views

~~~~~~~~~~~~~~~~

.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_gtt.c

   :doc: Global GTT views

.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_gtt.c

   :internal:

GTT Fences and Swizzling

~~~~~~~~~~~~~~~~~~~~~~~~

.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_fence.c

   :internal:

Global GTT Fence Handling

^^^^^^^^^^^^^^^^^^^^^^^^^

.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_fence.c

   :doc: fence register handling

Hardware Tiling and Swizzling Details

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_fence.c

   :doc: tiling swizzling details

Object Tiling IOCTLs

~~~~~~~~~~~~~~~~~~~~

.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_tiling.c

   :internal:

.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_tiling.c

   :doc: buffer object tiling

Buffer Object Eviction

~~~~~~~~~~~~~~~~~~~~~~

This section documents the interface functions for evicting buffer

objects to make space available in the virtual gpu address spaces. Note

that this is mostly orthogonal to shrinking buffer objects caches, which

has the goal to make main memory (shared with the gpu through the

unified memory architecture) available.

.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_evict.c

   :internal:

Buffer Object Memory Shrinking

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This section documents the interface function for shrinking memory usage

of buffer object caches. Shrinking is used to make main memory

available. Note that this is mostly orthogonal to evicting buffer

objects, which has the goal to make space in gpu virtual address spaces.

.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_shrinker.c

   :internal:

GuC

---

GuC-specific firmware loader

~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. kernel-doc:: drivers/gpu/drm/i915/intel_guc_loader.c

   :doc: GuC-specific firmware loader

.. kernel-doc:: drivers/gpu/drm/i915/intel_guc_loader.c

   :internal:

GuC-based command submission

~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. kernel-doc:: drivers/gpu/drm/i915/i915_guc_submission.c

   :doc: GuC-based command submission

.. kernel-doc:: drivers/gpu/drm/i915/i915_guc_submission.c

   :internal:

GuC Firmware Layout

~~~~~~~~~~~~~~~~~~~

.. kernel-doc:: drivers/gpu/drm/i915/intel_guc_fwif.h

   :doc: GuC Firmware Layout

Tracing

-------

This sections covers all things related to the tracepoints implemented

in the i915 driver.

i915_ppgtt_create and i915_ppgtt_release

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. kernel-doc:: drivers/gpu/drm/i915/i915_trace.h

   :doc: i915_ppgtt_create and i915_ppgtt_release tracepoints

i915_context_create and i915_context_free

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. kernel-doc:: drivers/gpu/drm/i915/i915_trace.h

   :doc: i915_context_create and i915_context_free tracepoints

switch_mm

~~~~~~~~~~

.. kernel-doc:: drivers/gpu/drm/i915/i915_trace.h

   :doc: switch_mm tracepoint

.. WARNING: DOCPROC directive not supported: !Cdrivers/gpu/drm/i915/i915_irq.c

Introduction

============

The Linux DRM layer contains code intended to support the needs of

complex graphics devices, usually containing programmable pipelines well

suited to 3D graphics acceleration. Graphics drivers in the kernel may

make use of DRM functions to make tasks like memory management,

interrupt handling and DMA easier, and provide a uniform interface to

applications.

A note on versions: this guide covers features found in the DRM tree,

including the TTM memory manager, output configuration and mode setting,

and the new vblank internals, in addition to all the regular features

found in current kernels.

[Insert diagram of typical DRM stack here]

Style Guidelines

----------------

For consistency this documentation uses American English. Abbreviations

are written as all-uppercase, for example: DRM, KMS, IOCTL, CRTC, and so

on. To aid in reading, documentations make full use of the markup

characters kerneldoc provides: @parameter for function parameters,

@member for structure members, &structure to reference structures and

function() for functions. These all get automatically hyperlinked if

kerneldoc for the referenced objects exists. When referencing entries in

function vtables please use ->vfunc(). Note that kerneldoc does not

support referencing struct members directly, so please add a reference

to the vtable struct somewhere in the same paragraph or at least

section.

Except in special situations (to separate locked from unlocked variants)

locking requirements for functions aren't documented in the kerneldoc.

Instead locking should be check at runtime using e.g.

``WARN_ON(!mutex_is_locked(...));``. Since it's much easier to ignore

documentation than runtime noise this provides more value. And on top of

that runtime checks do need to be updated when the locking rules change,

increasing the chances that they're correct. Within the documentation

the locking rules should be explained in the relevant structures: Either

in the comment for the lock explaining what it protects, or data fields

need a note about which lock protects them, or both.

Functions which have a non-\ ``void`` return value should have a section

called "Returns" explaining the expected return values in different

cases and their meanings. Currently there's no consensus whether that

section name should be all upper-case or not, and whether it should end

in a colon or not. Go with the file-local style. Other common section

names are "Notes" with information for dangerous or tricky corner cases,

and "FIXME" where the interface could be cleaned up.