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
Daniel Vetter
parent
cb597fcea5
commit
ca00c2b986
File diff suppressed because it is too large
Load Diff
|
|
@ -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.
|
||||||
|
|
@ -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
|
|
@ -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.
|
||||||
|
|
@ -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
|
||||||
Loading…
Reference in New Issue