summaryrefslogtreecommitdiff
path: root/Documentation/gpu/drm-kms.rst
diff options
context:
space:
mode:
authorDaniel Vetter <daniel.vetter@ffwll.ch>2016-09-21 10:59:25 +0200
committerSean Paul <seanpaul@chromium.org>2016-09-22 00:04:01 -0700
commit532b36712ddfdca90f4db9a5365039cc08a3ff84 (patch)
tree1570fbb736ce7964fcda7bcaf7eada3c3cdc0de5 /Documentation/gpu/drm-kms.rst
parent43968d7b806d7a7e021261294c583a216fddf0e5 (diff)
drm/doc: Polish for drm_plane.[hc]
Big thing is untangling and carefully documenting the different uapi types of planes. I also sprinkled a few more cross references around to make this easier to discover. As usual, remove the kerneldoc for internal functions which are not exported. Aside: We should probably go OCD on all the ioctl handlers and consistenly give them an _ioctl postfix. Acked-by: Archit Taneja <architt@codeaurora.org> Signed-off-by: Daniel Vetter <daniel.vetter@intel.com> Signed-off-by: Sean Paul <seanpaul@chromium.org> Link: http://patchwork.freedesktop.org/patch/msgid/1474448370-32227-2-git-send-email-daniel.vetter@ffwll.ch
Diffstat (limited to 'Documentation/gpu/drm-kms.rst')
-rw-r--r--Documentation/gpu/drm-kms.rst47
1 files changed, 3 insertions, 44 deletions
diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst
index 33181be97151..b1029e292e5c 100644
--- a/Documentation/gpu/drm-kms.rst
+++ b/Documentation/gpu/drm-kms.rst
@@ -113,6 +113,9 @@ a hardware-specific ioctl to allocate suitable buffer objects.
Plane Abstraction
=================
+.. kernel-doc:: drivers/gpu/drm/drm_plane.c
+ :doc: overview
+
Plane Functions Reference
-------------------------
@@ -189,50 +192,6 @@ allocated and zeroed by the driver, possibly as part of a larger
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
-a frame buffer to crop a portion of the image memory (source) and
-optionally scale it to a destination size. The result is then blended
-with or overlayed on top of a CRTC.
-
-The DRM core recognizes three types of planes:
-
-- DRM_PLANE_TYPE_PRIMARY represents a "main" plane for a CRTC.
- Primary planes are the planes operated upon by CRTC modesetting and
- flipping operations described in the page_flip hook in
- :c:type:`struct drm_crtc_funcs <drm_crtc_funcs>`.
-- DRM_PLANE_TYPE_CURSOR represents a "cursor" plane for a CRTC.
- Cursor planes are the planes operated upon by the
- DRM_IOCTL_MODE_CURSOR and DRM_IOCTL_MODE_CURSOR2 ioctls.
-- DRM_PLANE_TYPE_OVERLAY represents all non-primary, non-cursor
- planes. Some drivers refer to these types of planes as "sprites"
- internally.
-
-For compatibility with legacy userspace, only overlay planes are made
-available to userspace by default. Userspace clients may set the
-DRM_CLIENT_CAP_UNIVERSAL_PLANES client capability bit to indicate
-that they wish to receive a universal plane list containing all plane
-types.
-
-Plane Initialization
-~~~~~~~~~~~~~~~~~~~~
-
-To create a plane, a KMS drivers allocates and zeroes an instances of
-:c:type:`struct drm_plane <drm_plane>` (possibly as part of a
-larger structure) and registers it with a call to
-:c:func:`drm_universal_plane_init()`. The function takes a
-bitmask of the CRTCs that can be associated with the plane, a pointer to
-the plane functions, a list of format supported formats, and the type of
-plane (primary, cursor, or overlay) being initialized.
-
-Cursor and overlay planes are optional. All drivers should provide one
-primary plane per CRTC (although this requirement may change in the
-future); drivers that do not wish to provide special handling for
-primary planes may make use of the helper functions described in ? to
-create and register a primary plane with standard capabilities.
Cleanup
-------