Documentation/gpu: use recommended order of heading markers

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

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.