summaryrefslogtreecommitdiffstats
path: root/Documentation/gpu/drm-internals.rst
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/gpu/drm-internals.rst')
-rw-r--r--Documentation/gpu/drm-internals.rst127
1 files changed, 64 insertions, 63 deletions
diff --git a/Documentation/gpu/drm-internals.rst b/Documentation/gpu/drm-internals.rst
index 8b8257891396..ee01a4fbd657 100644
--- a/Documentation/gpu/drm-internals.rst
+++ b/Documentation/gpu/drm-internals.rst
@@ -1,3 +1,4 @@
+=============
DRM Internals
=============
@@ -18,7 +19,7 @@ management, command submission & fencing, suspend/resume support, and
DMA services.
Driver Initialization
----------------------
+=====================
At the core of every DRM driver is a :c:type:`struct drm_driver
<drm_driver>` structure. Drivers typically statically initialize
@@ -36,7 +37,7 @@ then describe individual operations in details as they get used in later
sections.
Driver Information
-~~~~~~~~~~~~~~~~~~
+------------------
Driver Features
^^^^^^^^^^^^^^^
@@ -131,7 +132,7 @@ kernel log at initialization time and passes it to userspace through the
DRM_IOCTL_VERSION ioctl.
Device Instance and Driver Handling
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------------
.. kernel-doc:: drivers/gpu/drm/drm_drv.c
:doc: driver instance overview
@@ -140,7 +141,7 @@ Device Instance and Driver Handling
:export:
Driver Load
-~~~~~~~~~~~
+-----------
IRQ Registration
^^^^^^^^^^^^^^^^
@@ -221,7 +222,7 @@ other BARs, so leaving it mapped could cause undesired behaviour like
hangs or memory corruption.
Bus-specific Device Registration and PCI Support
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------------------------
A number of functions are provided to help with device registration. The
functions deal with PCI and platform devices respectively and are only
@@ -236,7 +237,7 @@ drivers.
:export:
Memory management
------------------
+=================
Modern Linux systems require large amount of graphics memory to store
frame buffers, textures, vertices and other graphics-related data. Given
@@ -262,7 +263,7 @@ TTM, but has no video RAM management capabilities and is thus limited to
UMA devices.
The Translation Table Manager (TTM)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------------
TTM design background and information belongs here.
@@ -313,7 +314,7 @@ object, ttm_global_item_ref() is used to create an initial reference
count for the TTM, which will call your initialization function.
The Graphics Execution Manager (GEM)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------------
The GEM design approach has resulted in a memory manager that doesn't
provide full coverage of all (or even all common) use cases in its
@@ -576,7 +577,7 @@ available to the client. Such resource management should be abstracted
from the client in libdrm.
GEM Function Reference
-~~~~~~~~~~~~~~~~~~~~~~
+----------------------
.. kernel-doc:: drivers/gpu/drm/drm_gem.c
:export:
@@ -585,7 +586,7 @@ GEM Function Reference
:internal:
VMA Offset Manager
-~~~~~~~~~~~~~~~~~~
+------------------
.. kernel-doc:: drivers/gpu/drm/drm_vma_manager.c
:doc: vma offset manager
@@ -597,7 +598,7 @@ VMA Offset Manager
:internal:
PRIME Buffer Sharing
-~~~~~~~~~~~~~~~~~~~~
+--------------------
PRIME is the cross device buffer sharing framework in drm, originally
created for the OPTIMUS range of multi-gpu platforms. To userspace PRIME
@@ -648,13 +649,13 @@ PRIME Helper Functions
:doc: PRIME Helpers
PRIME Function References
-~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------
.. kernel-doc:: drivers/gpu/drm/drm_prime.c
:export:
DRM MM Range Allocator
-~~~~~~~~~~~~~~~~~~~~~~
+----------------------
Overview
^^^^^^^^
@@ -669,7 +670,7 @@ LRU Scan/Eviction Support
:doc: lru scan roaster
DRM MM Range Allocator Function References
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------------------
.. kernel-doc:: drivers/gpu/drm/drm_mm.c
:export:
@@ -678,7 +679,7 @@ DRM MM Range Allocator Function References
:internal:
CMA Helper Functions Reference
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------
.. kernel-doc:: drivers/gpu/drm/drm_gem_cma_helper.c
:doc: cma helpers
@@ -690,7 +691,7 @@ CMA Helper Functions Reference
:internal:
Mode Setting
-------------
+============
Drivers must initialize the mode setting core by calling
:c:func:`drm_mode_config_init()` on the DRM device. The function
@@ -706,7 +707,7 @@ be setup by initializing the following fields.
Mode setting functions.
Display Modes Function Reference
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------------
.. kernel-doc:: include/drm/drm_modes.h
:internal:
@@ -715,7 +716,7 @@ Display Modes Function Reference
:export:
Atomic Mode Setting Function Reference
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------------------
.. kernel-doc:: drivers/gpu/drm/drm_atomic.c
:export:
@@ -724,7 +725,7 @@ Atomic Mode Setting Function Reference
:internal:
Frame Buffer Abstraction
-~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------
Frame buffers are abstract memory objects that provide a source of
pixels to scanout to a CRTC. Applications explicitly request the
@@ -752,7 +753,7 @@ drivers can manually clean up a framebuffer at module unload time with
:c:func:`drm_framebuffer_unregister_private()`.
DRM Format Handling
-~~~~~~~~~~~~~~~~~~~
+-------------------
.. kernel-doc:: include/drm/drm_fourcc.h
:internal:
@@ -761,7 +762,7 @@ DRM Format Handling
:export:
Dumb Buffer Objects
-~~~~~~~~~~~~~~~~~~~
+-------------------
The KMS API doesn't standardize backing storage object creation and
leaves it to driver-specific ioctls. Furthermore actually creating a
@@ -805,7 +806,7 @@ attempted on some ARM embedded platforms. Such drivers really must have
a hardware-specific ioctl to allocate suitable buffer objects.
Output Polling
-~~~~~~~~~~~~~~
+--------------
void (\*output_poll_changed)(struct drm_device \*dev);
This operation notifies the driver that the status of one or more
@@ -814,14 +815,14 @@ connectors has changed. Drivers that use the fb helper can just call the
operation.
KMS Initialization and Cleanup
-------------------------------
+==============================
A KMS device is abstracted and exposed as a set of planes, CRTCs,
encoders and connectors. KMS drivers must thus create and initialize all
those objects at load time after initializing mode setting.
CRTCs (:c:type:`struct drm_crtc <drm_crtc>`)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------------------------
A CRTC is an abstraction representing a part of the chip that contains a
pointer to a scanout buffer. Therefore, the number of CRTCs available
@@ -842,7 +843,7 @@ structure, and registered with a call to :c:func:`drm_crtc_init()`
with a pointer to CRTC functions.
Planes (:c:type:`struct drm_plane <drm_plane>`)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------------------------
A plane represents an image source that can be blended with or overlayed
on top of a CRTC during the scanout process. Planes are associated with
@@ -887,7 +888,7 @@ primary planes may make use of the helper functions described in ? to
create and register a primary plane with standard capabilities.
Encoders (:c:type:`struct drm_encoder <drm_encoder>`)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------------------------------
An encoder takes pixel data from a CRTC and converts it to a format
suitable for any attached connectors. On some devices, it may be
@@ -927,7 +928,7 @@ compatibility layer when implemented) are responsible for attaching the
encoders they want to use to a CRTC.
Connectors (:c:type:`struct drm_connector <drm_connector>`)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------------------------------------
A connector is the final destination for pixel data on a device, and
usually connects directly to an external display device like a monitor
@@ -1087,7 +1088,7 @@ can't detect the connection status, or failed connection status probes,
should return connector_status_unknown.
Cleanup
-~~~~~~~
+-------
The DRM core manages its objects' lifetime. When an object is not needed
anymore the core calls its destroy function, which must clean up and
@@ -1106,7 +1107,7 @@ Connectors state change detection must be cleanup up with a call to
:c:func:`drm_kms_helper_poll_fini()`.
Output discovery and initialization example
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------------
::
@@ -1154,19 +1155,19 @@ the process is complete, the new connector is registered with sysfs to
make its properties available to applications.
KMS API Functions
-~~~~~~~~~~~~~~~~~
+-----------------
.. kernel-doc:: drivers/gpu/drm/drm_crtc.c
:export:
KMS Data Structures
-~~~~~~~~~~~~~~~~~~~
+-------------------
.. kernel-doc:: include/drm/drm_crtc.h
:internal:
KMS Locking
-~~~~~~~~~~~
+-----------
.. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
:doc: kms locking
@@ -1178,7 +1179,7 @@ KMS Locking
:export:
Mode Setting Helper Functions
------------------------------
+=============================
The plane, CRTC, encoder and connector functions provided by the drivers
implement the DRM API. They're called by the DRM core and ioctl handlers
@@ -1214,7 +1215,7 @@ operations. To use it, a driver must provide bottom functions for all of
the three KMS entities.
Atomic Modeset Helper Functions Reference
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------------------
Overview
^^^^^^^^
@@ -1241,7 +1242,7 @@ Atomic State Reset and Initialization
:export:
Modeset Helper Reference for Common Vtables
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------------
.. kernel-doc:: include/drm/drm_modeset_helper_vtables.h
:internal:
@@ -1250,7 +1251,7 @@ Modeset Helper Reference for Common Vtables
:doc: overview
Legacy CRTC/Modeset Helper Functions Reference
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------------------------
.. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c
:export:
@@ -1259,7 +1260,7 @@ Legacy CRTC/Modeset Helper Functions Reference
:doc: overview
Output Probing Helper Functions Reference
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------------------
.. kernel-doc:: drivers/gpu/drm/drm_probe_helper.c
:doc: output probing helper overview
@@ -1268,7 +1269,7 @@ Output Probing Helper Functions Reference
:export:
fbdev Helper Functions Reference
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------------
.. kernel-doc:: drivers/gpu/drm/drm_fb_helper.c
:doc: fbdev helpers
@@ -1280,7 +1281,7 @@ fbdev Helper Functions Reference
:internal:
Framebuffer CMA Helper Functions Reference
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------------------
.. kernel-doc:: drivers/gpu/drm/drm_fb_cma_helper.c
:doc: framebuffer cma helper functions
@@ -1289,7 +1290,7 @@ Framebuffer CMA Helper Functions Reference
:export:
Display Port Helper Functions Reference
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------------------
.. kernel-doc:: drivers/gpu/drm/drm_dp_helper.c
:doc: dp helpers
@@ -1301,7 +1302,7 @@ Display Port Helper Functions Reference
:export:
Display Port Dual Mode Adaptor Helper Functions Reference
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------------------------------------
.. kernel-doc:: drivers/gpu/drm/drm_dp_dual_mode_helper.c
:doc: dp dual mode helpers
@@ -1313,7 +1314,7 @@ Display Port Dual Mode Adaptor Helper Functions Reference
:export:
Display Port MST Helper Functions Reference
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------------
.. kernel-doc:: drivers/gpu/drm/drm_dp_mst_topology.c
:doc: dp mst helper
@@ -1325,7 +1326,7 @@ Display Port MST Helper Functions Reference
:export:
MIPI DSI Helper Functions Reference
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------------
.. kernel-doc:: drivers/gpu/drm/drm_mipi_dsi.c
:doc: dsi helpers
@@ -1337,13 +1338,13 @@ MIPI DSI Helper Functions Reference
:export:
EDID Helper Functions Reference
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------
.. kernel-doc:: drivers/gpu/drm/drm_edid.c
:export:
Rectangle Utilities Reference
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------
.. kernel-doc:: include/drm/drm_rect.h
:doc: rect utils
@@ -1355,7 +1356,7 @@ Rectangle Utilities Reference
:export:
Flip-work Helper Reference
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------
.. kernel-doc:: include/drm/drm_flip_work.h
:doc: flip utils
@@ -1367,7 +1368,7 @@ Flip-work Helper Reference
:export:
HDMI Infoframes Helper Reference
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------------
Strictly speaking this is not a DRM helper library but generally useable
by any driver interfacing with HDMI outputs like v4l or alsa drivers.
@@ -1381,7 +1382,7 @@ libraries and hence is also included here.
:export:
Plane Helper Reference
-~~~~~~~~~~~~~~~~~~~~~~
+----------------------
.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c
:export:
@@ -1390,13 +1391,13 @@ Plane Helper Reference
:doc: overview
Tile group
-~~~~~~~~~~
+----------
.. kernel-doc:: drivers/gpu/drm/drm_crtc.c
:doc: Tile group
Bridges
-~~~~~~~
+-------
Overview
^^^^^^^^
@@ -1414,7 +1415,7 @@ Default bridge callback sequence
:export:
Panel Helper Reference
-~~~~~~~~~~~~~~~~~~~~~~
+----------------------
.. kernel-doc:: include/drm/drm_panel.h
:internal:
@@ -1426,7 +1427,7 @@ Panel Helper Reference
:doc: drm panel
Simple KMS Helper Reference
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------
.. kernel-doc:: include/drm/drm_simple_kms_helper.h
:internal:
@@ -1438,7 +1439,7 @@ Simple KMS Helper Reference
:doc: overview
KMS Properties
---------------
+==============
Drivers may need to expose additional parameters to applications than
those described in the previous sections. KMS supports attaching
@@ -1526,7 +1527,7 @@ pointer to the target object, a pointer to the previously created
property and an initial instance value.
Existing KMS Properties
-~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------
The following table gives description of drm properties exposed by
various modules/drivers.
@@ -1790,7 +1791,7 @@ various modules/drivers.
+-------------------------------+----------------------+--------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Vertical Blanking
------------------
+=================
Vertical blanking plays a major role in graphics rendering. To achieve
tear-free display, users must synchronize page flips and/or rendering to
@@ -1848,7 +1849,7 @@ with a call to :c:func:`drm_vblank_cleanup()` in the driver unload
operation handler.
Vertical Blanking and Interrupt Handling Functions Reference
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------------------------------------
.. kernel-doc:: drivers/gpu/drm/drm_irq.c
:export:
@@ -1857,10 +1858,10 @@ Vertical Blanking and Interrupt Handling Functions Reference
:functions: drm_crtc_vblank_waitqueue
Open/Close, File Operations and IOCTLs
---------------------------------------
+======================================
Open and Close
-~~~~~~~~~~~~~~
+--------------
int (\*firstopen) (struct drm_device \*); void (\*lastclose) (struct
drm_device \*); int (\*open) (struct drm_device \*, struct drm_file
@@ -1907,7 +1908,7 @@ state so that the vga console or an independent fbdev driver could take
over.
File Operations
-~~~~~~~~~~~~~~~
+---------------
.. kernel-doc:: drivers/gpu/drm/drm_fops.c
:doc: file operations
@@ -1916,7 +1917,7 @@ File Operations
:export:
IOCTLs
-~~~~~~
+------
struct drm_ioctl_desc \*ioctls; int num_ioctls;
Driver-specific ioctls descriptors table.
@@ -1965,7 +1966,7 @@ how the ioctl is allowed to be called.
:export:
Legacy Support Code
--------------------
+===================
The section very briefly covers some of the old legacy support code
which is only used by old DRM drivers which have done a so-called
@@ -1975,7 +1976,7 @@ command submission code. Do not use any of this in new and modern
drivers.
Legacy Suspend/Resume
-~~~~~~~~~~~~~~~~~~~~~
+---------------------
The DRM core provides some suspend/resume code, but drivers wanting full
suspend/resume support should provide save() and restore() functions.
@@ -1992,7 +1993,7 @@ through the :c:type:`struct device_driver <device_driver>`
dev_pm_ops) and set these methods to NULL.
Legacy DMA Services
-~~~~~~~~~~~~~~~~~~~
+-------------------
This should cover how DMA mapping etc. is supported by the core. These
functions are deprecated and should not be used.