summaryrefslogtreecommitdiffstats
path: root/include/drm
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 /include/drm
parent43968d7b806d7a7e021261294c583a216fddf0e5 (diff)
downloadlinux-532b36712ddfdca90f4db9a5365039cc08a3ff84.tar.gz
linux-532b36712ddfdca90f4db9a5365039cc08a3ff84.tar.bz2
linux-532b36712ddfdca90f4db9a5365039cc08a3ff84.zip
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 'include/drm')
-rw-r--r--include/drm/drm_plane.h57
1 files changed, 55 insertions, 2 deletions
diff --git a/include/drm/drm_plane.h b/include/drm/drm_plane.h
index 1407715736a5..256219bfd07b 100644
--- a/include/drm/drm_plane.h
+++ b/include/drm/drm_plane.h
@@ -319,10 +319,48 @@ struct drm_plane_funcs {
void (*early_unregister)(struct drm_plane *plane);
};
+/**
+ * enum drm_plane_type - uapi plane type enumeration
+ *
+ * For historical reasons not all planes are made the same. This enumeration is
+ * used to tell the different types of planes apart to implement the different
+ * uapi semantics for them. For userspace which is universal plane aware and
+ * which is using that atomic IOCTL there's no difference between these planes
+ * (beyong what the driver and hardware can support of course).
+ *
+ * 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. See also
+ * drm_for_each_legacy_plane().
+ */
enum drm_plane_type {
- DRM_PLANE_TYPE_OVERLAY,
+ /**
+ * @DRM_PLANE_TYPE_PRIMARY:
+ *
+ * Primary planes represent a "main" plane for a CRTC. Primary planes
+ * are the planes operated upon by CRTC modesetting and flipping
+ * operations described in the page_flip and set_config hooks in struct
+ * &drm_crtc_funcs.
+ */
DRM_PLANE_TYPE_PRIMARY,
+
+ /**
+ * @DRM_PLANE_TYPE_CURSOR:
+ *
+ * Cursor planes represent 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_CURSOR,
+
+ /**
+ * @DRM_PLANE_TYPE_OVERLAY:
+ *
+ * Overlay planes represent all non-primary, non-cursor planes. Some
+ * drivers refer to these types of planes as "sprites" internally.
+ */
+ DRM_PLANE_TYPE_OVERLAY,
};
@@ -458,11 +496,26 @@ static inline struct drm_plane *drm_plane_find(struct drm_device *dev,
list_for_each_entry((plane), &(dev)->mode_config.plane_list, head) \
for_each_if ((plane_mask) & (1 << drm_plane_index(plane)))
-/* Plane list iterator for legacy (overlay only) planes. */
+/**
+ * drm_for_each_legacy_plane - iterate over all planes for legacy userspace
+ * @plane: the loop cursor
+ * @dev: the DRM device
+ *
+ * Iterate over all legacy planes of @dev, excluding primary and cursor planes.
+ * This is useful for implementing userspace apis when userspace is not
+ * universal plane aware. See also enum &drm_plane_type.
+ */
#define drm_for_each_legacy_plane(plane, dev) \
list_for_each_entry(plane, &(dev)->mode_config.plane_list, head) \
for_each_if (plane->type == DRM_PLANE_TYPE_OVERLAY)
+/**
+ * drm_for_each_plane - iterate over all planes
+ * @plane: the loop cursor
+ * @dev: the DRM device
+ *
+ * Iterate over all planes of @dev, include primary and cursor planes.
+ */
#define drm_for_each_plane(plane, dev) \
list_for_each_entry(plane, &(dev)->mode_config.plane_list, head)