Documentation/gpu: split up the gpu documentation

Make the gpu documentation easier to manage by splitting to separate
files. Again, this is just the split, no real edits.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Link: http://patchwork.freedesktop.org/patch/msgid/bd2b599b5105c28c8f05923005e6cc9b7efa7fc1.1466506505.git.jani.nikula@intel.com
This commit is contained in:
Jani Nikula 2016-06-21 14:48:58 +03:00 committed by Daniel Vetter
parent cb597fcea5
commit ca00c2b986
6 changed files with 2593 additions and 2596 deletions

File diff suppressed because it is too large Load Diff

View File

@ -0,0 +1,91 @@
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.

346
Documentation/gpu/i915.rst Normal file
View File

@ -0,0 +1,346 @@
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

File diff suppressed because it is too large Load Diff

View File

@ -0,0 +1,50 @@
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.

View File

@ -0,0 +1,102 @@
==============
VGA Switcheroo
==============
.. kernel-doc:: drivers/gpu/vga/vga_switcheroo.c
:doc: Overview
Modes of Use
============
Manual switching and manual power control
-----------------------------------------
.. kernel-doc:: drivers/gpu/vga/vga_switcheroo.c
:doc: Manual switching and manual power control
Driver power control
--------------------
.. kernel-doc:: drivers/gpu/vga/vga_switcheroo.c
:doc: Driver power control
API
===
Public functions
----------------
.. kernel-doc:: drivers/gpu/vga/vga_switcheroo.c
:export:
Public structures
-----------------
.. kernel-doc:: include/linux/vga_switcheroo.h
:functions: vga_switcheroo_handler
.. kernel-doc:: include/linux/vga_switcheroo.h
:functions: vga_switcheroo_client_ops
Public constants
----------------
.. kernel-doc:: include/linux/vga_switcheroo.h
:functions: vga_switcheroo_handler_flags_t
.. kernel-doc:: include/linux/vga_switcheroo.h
:functions: vga_switcheroo_client_id
.. kernel-doc:: include/linux/vga_switcheroo.h
:functions: vga_switcheroo_state
Private structures
------------------
.. kernel-doc:: drivers/gpu/vga/vga_switcheroo.c
:functions: vgasr_priv
.. kernel-doc:: drivers/gpu/vga/vga_switcheroo.c
:functions: vga_switcheroo_client
Handlers
========
apple-gmux Handler
------------------
.. kernel-doc:: drivers/platform/x86/apple-gmux.c
:doc: Overview
.. kernel-doc:: drivers/platform/x86/apple-gmux.c
:doc: Interrupt
Graphics mux
~~~~~~~~~~~~
.. kernel-doc:: drivers/platform/x86/apple-gmux.c
:doc: Graphics mux
Power control
~~~~~~~~~~~~~
.. kernel-doc:: drivers/platform/x86/apple-gmux.c
:doc: Power control
Backlight control
~~~~~~~~~~~~~~~~~
.. kernel-doc:: drivers/platform/x86/apple-gmux.c
:doc: Backlight control
Public functions
~~~~~~~~~~~~~~~~
.. kernel-doc:: include/linux/apple-gmux.h
:internal:
.. WARNING: DOCPROC directive not supported: !Cdrivers/gpu/vga/vga_switcheroo.c
.. WARNING: DOCPROC directive not supported: !Cinclude/linux/vga_switcheroo.h
.. WARNING: DOCPROC directive not supported: !Cdrivers/platform/x86/apple-gmux.c