Kernel/linux-stable
1
0
Fork 0
mirror of https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git synced 2025-01-17 02:36:21 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Documentation/gpu: use recommended order of heading markers

Browse Source 
While splitting the document up, the headings "shifted" from what pandoc
generated. Use the following order for headings for consistency:

==============
Document title
==============

First
=====

Second
------

Third
~~~~~

Leave the lower level headings as they are; I think those are less
important. Although RST doesn't mandate a specific order ("Rather than
imposing a fixed number and order of section title adornment styles, the
order enforced will be the order as encountered."), having the higher
levels the same overall makes it easier to follow the documents.

[I'm sort of kind of writing the recommendation for docs-next in the
mean time, but this order seems sensible, and is what I'm proposing.]

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/126f42734defac6cbb8496a481d58db7b38461dd.1466506505.git.jani.nikula@intel.com
This commit is contained in:
Jani Nikula 2016-06-21 14:49:00 +03:00 committed by Daniel Vetter
parent 621c547474
commit 2255402040
4 changed files with 110 additions and 106 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

127
Documentation/gpu/drm-internals.rst
View File

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

5
Documentation/gpu/drm-uapi.rst
View File

@ -1,3 +1,4 @@
===================
Userland interfaces Userland interfaces
=================== ===================
@ -14,7 +15,7 @@ Cover generic ioctls and sysfs layout here. We only need high-level
info, since man pages should cover the rest. info, since man pages should cover the rest.
Render nodes Render nodes
------------ ============
DRM core provides multiple character-devices for user-space to use. DRM core provides multiple character-devices for user-space to use.
Depending on which device is opened, user-space can perform a different Depending on which device is opened, user-space can perform a different
@ -67,7 +68,7 @@ visible to user-space and accessible beyond open-file boundaries, they
cannot support render nodes. cannot support render nodes.
VBlank event handling VBlank event handling
--------------------- =====================
The DRM core exposes two vertical blank related ioctls: The DRM core exposes two vertical blank related ioctls:

81
Documentation/gpu/i915.rst
View File

@ -1,5 +1,6 @@
drm/i915 Intel GFX Driver ===========================
========================= drm/i915 Intel GFX Driver
===========================
The drm/i915 driver supports all (with the exception of some very early The drm/i915 driver supports all (with the exception of some very early
models) integrated GFX chipsets with both Intel display and rendering models) integrated GFX chipsets with both Intel display and rendering
@ -7,13 +8,13 @@ blocks. This excludes a set of SoC platforms with an SGX rendering unit,
those have basic support through the gma500 drm driver. those have basic support through the gma500 drm driver.
Core Driver Infrastructure Core Driver Infrastructure
-------------------------- ==========================
This section covers core driver infrastructure used by both the display This section covers core driver infrastructure used by both the display
and the GEM parts of the driver. and the GEM parts of the driver.
Runtime Power Management Runtime Power Management
~~~~~~~~~~~~~~~~~~~~~~~~ ------------------------
.. kernel-doc:: drivers/gpu/drm/i915/intel_runtime_pm.c .. kernel-doc:: drivers/gpu/drm/i915/intel_runtime_pm.c
:doc: runtime pm :doc: runtime pm
@ -25,7 +26,7 @@ Runtime Power Management
:internal: :internal:
Interrupt Handling Interrupt Handling
~~~~~~~~~~~~~~~~~~ ------------------
.. kernel-doc:: drivers/gpu/drm/i915/i915_irq.c .. kernel-doc:: drivers/gpu/drm/i915/i915_irq.c
:doc: interrupt handling :doc: interrupt handling
@ -40,7 +41,7 @@ Interrupt Handling
:functions: intel_runtime_pm_enable_interrupts :functions: intel_runtime_pm_enable_interrupts
Intel GVT-g Guest Support(vGPU) Intel GVT-g Guest Support(vGPU)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -------------------------------
.. kernel-doc:: drivers/gpu/drm/i915/i915_vgpu.c .. kernel-doc:: drivers/gpu/drm/i915/i915_vgpu.c
:doc: Intel GVT-g guest support :doc: Intel GVT-g guest support
@ -49,14 +50,14 @@ Intel GVT-g Guest Support(vGPU)
:internal: :internal:
Display Hardware Handling Display Hardware Handling
------------------------- =========================
This section covers everything related to the display hardware including This section covers everything related to the display hardware including
the mode setting infrastructure, plane, sprite and cursor handling and the mode setting infrastructure, plane, sprite and cursor handling and
display, output probing and related topics. display, output probing and related topics.
Mode Setting Infrastructure Mode Setting Infrastructure
~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---------------------------
The i915 driver is thus far the only DRM driver which doesn't use the 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 common DRM helper code to implement mode setting sequences. Thus it has
@ -64,7 +65,7 @@ its own tailor-made infrastructure for executing a display configuration
change. change.
Frontbuffer Tracking Frontbuffer Tracking
~~~~~~~~~~~~~~~~~~~~ --------------------
.. kernel-doc:: drivers/gpu/drm/i915/intel_frontbuffer.c .. kernel-doc:: drivers/gpu/drm/i915/intel_frontbuffer.c
:doc: frontbuffer tracking :doc: frontbuffer tracking
@ -76,7 +77,7 @@ Frontbuffer Tracking
:functions: i915_gem_track_fb :functions: i915_gem_track_fb
Display FIFO Underrun Reporting Display FIFO Underrun Reporting
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -------------------------------
.. kernel-doc:: drivers/gpu/drm/i915/intel_fifo_underrun.c .. kernel-doc:: drivers/gpu/drm/i915/intel_fifo_underrun.c
:doc: fifo underrun handling :doc: fifo underrun handling
@ -85,7 +86,7 @@ Display FIFO Underrun Reporting
:internal: :internal:
Plane Configuration Plane Configuration
~~~~~~~~~~~~~~~~~~~ -------------------
This section covers plane configuration and composition with the primary This section covers plane configuration and composition with the primary
plane, sprites, cursors and overlays. This includes the infrastructure plane, sprites, cursors and overlays. This includes the infrastructure
@ -94,7 +95,7 @@ topics like watermark setup and computation, framebuffer compression and
panel self refresh. panel self refresh.
Atomic Plane Helpers Atomic Plane Helpers
~~~~~~~~~~~~~~~~~~~~ --------------------
.. kernel-doc:: drivers/gpu/drm/i915/intel_atomic_plane.c .. kernel-doc:: drivers/gpu/drm/i915/intel_atomic_plane.c
:doc: atomic plane helpers :doc: atomic plane helpers
@ -103,7 +104,7 @@ Atomic Plane Helpers
:internal: :internal:
Output Probing Output Probing
~~~~~~~~~~~~~~ --------------
This section covers output probing and related infrastructure like the This section covers output probing and related infrastructure like the
hotplug interrupt storm detection and mitigation code. Note that the hotplug interrupt storm detection and mitigation code. Note that the
@ -111,7 +112,7 @@ i915 driver still uses most of the common DRM helper code for output
probing, so those sections fully apply. probing, so those sections fully apply.
Hotplug Hotplug
~~~~~~~ -------
.. kernel-doc:: drivers/gpu/drm/i915/intel_hotplug.c .. kernel-doc:: drivers/gpu/drm/i915/intel_hotplug.c
:doc: Hotplug :doc: Hotplug
@ -120,7 +121,7 @@ Hotplug
:internal: :internal:
High Definition Audio High Definition Audio
~~~~~~~~~~~~~~~~~~~~~ ---------------------
.. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
:doc: High Definition Audio over HDMI and Display Port :doc: High Definition Audio over HDMI and Display Port
@ -132,7 +133,7 @@ High Definition Audio
:internal: :internal:
Panel Self Refresh PSR (PSR/SRD) Panel Self Refresh PSR (PSR/SRD)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --------------------------------
.. kernel-doc:: drivers/gpu/drm/i915/intel_psr.c .. kernel-doc:: drivers/gpu/drm/i915/intel_psr.c
:doc: Panel Self Refresh (PSR/SRD) :doc: Panel Self Refresh (PSR/SRD)
@ -141,7 +142,7 @@ Panel Self Refresh PSR (PSR/SRD)
:internal: :internal:
Frame Buffer Compression (FBC) Frame Buffer Compression (FBC)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ------------------------------
.. kernel-doc:: drivers/gpu/drm/i915/intel_fbc.c .. kernel-doc:: drivers/gpu/drm/i915/intel_fbc.c
:doc: Frame Buffer Compression (FBC) :doc: Frame Buffer Compression (FBC)
@ -150,7 +151,7 @@ Frame Buffer Compression (FBC)
:internal: :internal:
Display Refresh Rate Switching (DRRS) Display Refresh Rate Switching (DRRS)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -------------------------------------
.. kernel-doc:: drivers/gpu/drm/i915/intel_dp.c .. kernel-doc:: drivers/gpu/drm/i915/intel_dp.c
:doc: Display Refresh Rate Switching (DRRS) :doc: Display Refresh Rate Switching (DRRS)
@ -174,13 +175,13 @@ Display Refresh Rate Switching (DRRS)
:functions: intel_dp_drrs_init :functions: intel_dp_drrs_init
DPIO DPIO
~~~~ ----
.. kernel-doc:: drivers/gpu/drm/i915/i915_reg.h .. kernel-doc:: drivers/gpu/drm/i915/i915_reg.h
:doc: DPIO :doc: DPIO
CSR firmware support for DMC CSR firmware support for DMC
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ----------------------------
.. kernel-doc:: drivers/gpu/drm/i915/intel_csr.c .. kernel-doc:: drivers/gpu/drm/i915/intel_csr.c
:doc: csr support for dmc :doc: csr support for dmc
@ -189,7 +190,7 @@ CSR firmware support for DMC
:internal: :internal:
Video BIOS Table (VBT) Video BIOS Table (VBT)
~~~~~~~~~~~~~~~~~~~~~~ ----------------------
.. kernel-doc:: drivers/gpu/drm/i915/intel_bios.c .. kernel-doc:: drivers/gpu/drm/i915/intel_bios.c
:doc: Video BIOS Table (VBT) :doc: Video BIOS Table (VBT)
@ -201,13 +202,13 @@ Video BIOS Table (VBT)
:internal: :internal:
Memory Management and Command Submission Memory Management and Command Submission
---------------------------------------- ========================================
This sections covers all things related to the GEM implementation in the This sections covers all things related to the GEM implementation in the
i915 driver. i915 driver.
Batchbuffer Parsing Batchbuffer Parsing
~~~~~~~~~~~~~~~~~~~ -------------------
.. kernel-doc:: drivers/gpu/drm/i915/i915_cmd_parser.c .. kernel-doc:: drivers/gpu/drm/i915/i915_cmd_parser.c
:doc: batch buffer command parser :doc: batch buffer command parser
@ -216,7 +217,7 @@ Batchbuffer Parsing
:internal: :internal:
Batchbuffer Pools Batchbuffer Pools
~~~~~~~~~~~~~~~~~ -----------------
.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_batch_pool.c .. kernel-doc:: drivers/gpu/drm/i915/i915_gem_batch_pool.c
:doc: batch pool :doc: batch pool
@ -225,7 +226,7 @@ Batchbuffer Pools
:internal: :internal:
Logical Rings, Logical Ring Contexts and Execlists Logical Rings, Logical Ring Contexts and Execlists
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --------------------------------------------------
.. kernel-doc:: drivers/gpu/drm/i915/intel_lrc.c .. kernel-doc:: drivers/gpu/drm/i915/intel_lrc.c
:doc: Logical Rings, Logical Ring Contexts and Execlists :doc: Logical Rings, Logical Ring Contexts and Execlists
@ -234,7 +235,7 @@ Logical Rings, Logical Ring Contexts and Execlists
:internal: :internal:
Global GTT views Global GTT views
~~~~~~~~~~~~~~~~ ----------------
.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_gtt.c .. kernel-doc:: drivers/gpu/drm/i915/i915_gem_gtt.c
:doc: Global GTT views :doc: Global GTT views
@ -243,25 +244,25 @@ Global GTT views
:internal: :internal:
GTT Fences and Swizzling GTT Fences and Swizzling
~~~~~~~~~~~~~~~~~~~~~~~~ ------------------------
.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_fence.c .. kernel-doc:: drivers/gpu/drm/i915/i915_gem_fence.c
:internal: :internal:
Global GTT Fence Handling Global GTT Fence Handling
^^^^^^^^^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~~~~~~~~~
.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_fence.c .. kernel-doc:: drivers/gpu/drm/i915/i915_gem_fence.c
:doc: fence register handling :doc: fence register handling
Hardware Tiling and Swizzling Details Hardware Tiling and Swizzling Details
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_fence.c .. kernel-doc:: drivers/gpu/drm/i915/i915_gem_fence.c
:doc: tiling swizzling details :doc: tiling swizzling details
Object Tiling IOCTLs Object Tiling IOCTLs
~~~~~~~~~~~~~~~~~~~~ --------------------
.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_tiling.c .. kernel-doc:: drivers/gpu/drm/i915/i915_gem_tiling.c
:internal: :internal:
@ -270,7 +271,7 @@ Object Tiling IOCTLs
:doc: buffer object tiling :doc: buffer object tiling
Buffer Object Eviction Buffer Object Eviction
~~~~~~~~~~~~~~~~~~~~~~ ----------------------
This section documents the interface functions for evicting buffer This section documents the interface functions for evicting buffer
objects to make space available in the virtual gpu address spaces. Note objects to make space available in the virtual gpu address spaces. Note
@ -282,7 +283,7 @@ unified memory architecture) available.
:internal: :internal:
Buffer Object Memory Shrinking Buffer Object Memory Shrinking
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ------------------------------
This section documents the interface function for shrinking memory usage This section documents the interface function for shrinking memory usage
of buffer object caches. Shrinking is used to make main memory of buffer object caches. Shrinking is used to make main memory
@ -293,10 +294,10 @@ objects, which has the goal to make space in gpu virtual address spaces.
:internal: :internal:
GuC GuC
--- ===
GuC-specific firmware loader GuC-specific firmware loader
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ----------------------------
.. kernel-doc:: drivers/gpu/drm/i915/intel_guc_loader.c .. kernel-doc:: drivers/gpu/drm/i915/intel_guc_loader.c
:doc: GuC-specific firmware loader :doc: GuC-specific firmware loader
@ -305,7 +306,7 @@ GuC-specific firmware loader
:internal: :internal:
GuC-based command submission GuC-based command submission
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ----------------------------
.. kernel-doc:: drivers/gpu/drm/i915/i915_guc_submission.c .. kernel-doc:: drivers/gpu/drm/i915/i915_guc_submission.c
:doc: GuC-based command submission :doc: GuC-based command submission
@ -314,31 +315,31 @@ GuC-based command submission
:internal: :internal:
GuC Firmware Layout GuC Firmware Layout
~~~~~~~~~~~~~~~~~~~ -------------------
.. kernel-doc:: drivers/gpu/drm/i915/intel_guc_fwif.h .. kernel-doc:: drivers/gpu/drm/i915/intel_guc_fwif.h
:doc: GuC Firmware Layout :doc: GuC Firmware Layout
Tracing Tracing
------- =======
This sections covers all things related to the tracepoints implemented This sections covers all things related to the tracepoints implemented
in the i915 driver. in the i915 driver.
i915_ppgtt_create and i915_ppgtt_release i915_ppgtt_create and i915_ppgtt_release
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ----------------------------------------
.. kernel-doc:: drivers/gpu/drm/i915/i915_trace.h .. kernel-doc:: drivers/gpu/drm/i915/i915_trace.h
:doc: i915_ppgtt_create and i915_ppgtt_release tracepoints :doc: i915_ppgtt_create and i915_ppgtt_release tracepoints
i915_context_create and i915_context_free i915_context_create and i915_context_free
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -----------------------------------------
.. kernel-doc:: drivers/gpu/drm/i915/i915_trace.h .. kernel-doc:: drivers/gpu/drm/i915/i915_trace.h
:doc: i915_context_create and i915_context_free tracepoints :doc: i915_context_create and i915_context_free tracepoints
switch_mm switch_mm
~~~~~~~~~~ ---------
.. kernel-doc:: drivers/gpu/drm/i915/i915_trace.h .. kernel-doc:: drivers/gpu/drm/i915/i915_trace.h
:doc: switch_mm tracepoint :doc: switch_mm tracepoint

3
Documentation/gpu/introduction.rst
View File

@ -1,3 +1,4 @@
============
Introduction Introduction
============ ============
@ -16,7 +17,7 @@ found in current kernels.
[Insert diagram of typical DRM stack here] [Insert diagram of typical DRM stack here]
Style Guidelines Style Guidelines
---------------- ================
For consistency this documentation uses American English. Abbreviations For consistency this documentation uses American English. Abbreviations
are written as all-uppercase, for example: DRM, KMS, IOCTL, CRTC, and so are written as all-uppercase, for example: DRM, KMS, IOCTL, CRTC, and so