Skip to contentSkip to conversation

drm/doc: improve plane property docs

PATCH In review Simon Ser 2 participants 20 messages Dec 16, 2020 – Dec 17, 2020

Subsystems (3)
lore
Share & tools
lore

Simon Ser

author
#0 lore raw

cover drm/doc: improve plane property docs

Re-organize and improve plane property docs.

Simon Ser (8):
drm/doc: rename FB_DAMAGE_CLIPS section
drm/doc: move composition function docs to new section drm/doc: move damage tracking functions to new section drm/doc: move color management functions under CRTC section drm/doc: the KMS properties section is for user-space devs drm/doc: introduce new section for standard plane properties drm/doc: fix drm_plane_type docs
drm/doc: document the type plane property

 Documentation/gpu/drm-kms.rst | 52 +++++++++++++++++++++++------------
 drivers/gpu/drm/drm_blend.c   |  6 ----
 drivers/gpu/drm/drm_plane.c   | 51 +++++++++++++++++++++++++++++++---
 include/drm/drm_plane.h       | 21 ++++++++------
 4 files changed, 95 insertions(+), 35 deletions(-)
Signature · 6 lines
2.29.2

_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
author
#1 lore raw

PATCH 1/8 drm/doc: rename FB_DAMAGE_CLIPS section

Make it more human-readable.

Cc Daniel Vetter <[email protected]>
Cc Pekka Paalanen <[email protected]>
---
 Documentation/gpu/drm-kms.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
Documentation/gpu/drm-kms.rst +2 -2
index 3c5ae4f6dfd2..76cf6acc23a5 100644
@@ -475,8 +475,8 @@ Plane Composition Properties
 .. kernel-doc:: drivers/gpu/drm/drm_blend.c
    :export:
 
-FB_DAMAGE_CLIPS
-~~~~~~~~~~~~~~~
+Damage Tracking Properties
+--------------------------
 
 .. kernel-doc:: drivers/gpu/drm/drm_damage_helper.c
    :doc: overview
Signature · 6 lines
2.29.2

_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
author
#2 lore raw

PATCH 2/8 drm/doc: move composition function docs to new section

In reply to Simon Ser

Move drm_blend.c function reference from the KMS properties section to the plane abstraction section. This makes the KMS properties section more readable for user-space developers.

Cc Daniel Vetter <[email protected]>
Cc Pekka Paalanen <[email protected]>
---
 Documentation/gpu/drm-kms.rst | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)
Documentation/gpu/drm-kms.rst +6 -3
index 76cf6acc23a5..3f92d4eb224b 100644
@@ -370,6 +370,12 @@ Plane Functions Reference
 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
    :export:
 
+Plane Composition Functions Reference
+-------------------------------------
+
+.. kernel-doc:: drivers/gpu/drm/drm_blend.c
+   :export:
+
 Display Modes Function Reference
 ================================
 
@@ -472,9 +478,6 @@ Plane Composition Properties
 .. kernel-doc:: drivers/gpu/drm/drm_blend.c
    :doc: overview
 
-.. kernel-doc:: drivers/gpu/drm/drm_blend.c
-   :export:
-
 Damage Tracking Properties
 --------------------------
 
Signature · 6 lines
2.29.2

_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
author
#3 lore raw

PATCH 3/8 drm/doc: move damage tracking functions to new section

In reply to Simon Ser

Move drm_damage_helper function reference from the KMS properties section to the plane abstraction section. This makes the KMS properties section more readable for user-space developers.

Cc Daniel Vetter <[email protected]>
Cc Pekka Paalanen <[email protected]>
---
 Documentation/gpu/drm-kms.rst | 15 +++++++++------
 1 file changed, 9 insertions(+), 6 deletions(-)
Documentation/gpu/drm-kms.rst +9 -6
index 3f92d4eb224b..e6329e7e638e 100644
@@ -376,6 +376,15 @@ Plane Composition Functions Reference
 .. kernel-doc:: drivers/gpu/drm/drm_blend.c
    :export:
 
+Plane Damage Tracking Functions Reference
+-----------------------------------------
+
+.. kernel-doc:: drivers/gpu/drm/drm_damage_helper.c
+   :export:
+
+.. kernel-doc:: include/drm/drm_damage_helper.h
+   :internal:
+
 Display Modes Function Reference
 ================================
 
@@ -484,12 +493,6 @@ Damage Tracking Properties
 .. kernel-doc:: drivers/gpu/drm/drm_damage_helper.c
    :doc: overview
 
-.. kernel-doc:: drivers/gpu/drm/drm_damage_helper.c
-   :export:
-
-.. kernel-doc:: include/drm/drm_damage_helper.h
-   :internal:
-
 Color Management Properties
 ---------------------------
 
Signature · 6 lines
2.29.2

_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
author
#4 lore raw

PATCH 4/8 drm/doc: move color management functions under CRTC section

In reply to Simon Ser

Move drm_color_mgmt function reference from the KMS properties section to the CRTC abstraction section. This makes the KMS properties section more readable for user-space developers.

Cc Daniel Vetter <[email protected]>
Cc Pekka Paalanen <[email protected]>
---
 Documentation/gpu/drm-kms.rst | 15 +++++++++------
 1 file changed, 9 insertions(+), 6 deletions(-)
Documentation/gpu/drm-kms.rst +9 -6
index e6329e7e638e..2f3efb63e5ba 100644
@@ -319,6 +319,15 @@ CRTC Functions Reference
 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c
    :export:
 
+Color Management Functions Reference
+------------------------------------
+
+.. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
+   :export:
+
+.. kernel-doc:: include/drm/drm_color_mgmt.h
+   :internal:
+
 Frame Buffer Abstraction
 ========================
 
@@ -499,12 +508,6 @@ Color Management Properties
 .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
    :doc: overview
 
-.. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
-   :export:
-
-.. kernel-doc:: include/drm/drm_color_mgmt.h
-   :internal:
-
 Tile Group Property
 -------------------
 
Signature · 6 lines
2.29.2

_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
#5 lore raw

Re: [PATCH 4/8] drm/doc: move color management functions under CRTC section

Quoted 7 lines · Simon Ser

Move drm_color_mgmt function reference from the KMS properties section to the CRTC abstraction section. This makes the KMS properties section more readable for user-space developers.

Cc Daniel Vetter <[email protected]>
Cc Pekka Paalanen <[email protected]>

For patches 1-4: Reviewed-by: Daniel Vetter <[email protected]>

Quoted 40 lines
---
 Documentation/gpu/drm-kms.rst | 15 +++++++++------
 1 file changed, 9 insertions(+), 6 deletions(-)
Documentation/gpu/drm-kms.rst +9 -6
index e6329e7e638e..2f3efb63e5ba 100644
@@ -319,6 +319,15 @@ CRTC Functions Reference
 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c
    :export:
 
+Color Management Functions Reference
+------------------------------------
+
+.. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
+   :export:
+
+.. kernel-doc:: include/drm/drm_color_mgmt.h
+   :internal:
+
 Frame Buffer Abstraction
 ========================
 
@@ -499,12 +508,6 @@ Color Management Properties
 .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
    :doc: overview
 
-.. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
-   :export:
-
-.. kernel-doc:: include/drm/drm_color_mgmt.h
-   :internal:
-
 Tile Group Property
 -------------------
 
Signature · 1 line
2.29.2
Signature · 7 lines
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
author
#6 lore raw

PATCH 5/8 drm/doc: the KMS properties section is for user-space devs

In reply to Simon Ser

State that the "KMS Properties" section is mainly for user-space developers.

Cc Daniel Vetter <[email protected]>
Cc Pekka Paalanen <[email protected]>
---
 Documentation/gpu/drm-kms.rst | 3 +++
 1 file changed, 3 insertions(+)
Documentation/gpu/drm-kms.rst +3 -0
index 2f3efb63e5ba..fcd4e15379b0 100644
@@ -460,6 +460,9 @@ KMS Locking
 KMS Properties
 ==============
 
+This section of the documentation is primarily aimed at user-space developers.
+For the driver APIs, so the other sections.
+
 Property Types and Blob Property Support
 ----------------------------------------
 
Signature · 6 lines
2.29.2

_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
#7 lore raw

Re: [PATCH 5/8] drm/doc: the KMS properties section is for user-space devs

Quoted 15 lines · Simon Ser

State that the "KMS Properties" section is mainly for user-space developers.

Cc Daniel Vetter <[email protected]>
Cc Pekka Paalanen <[email protected]>
---
 Documentation/gpu/drm-kms.rst | 3 +++
 1 file changed, 3 insertions(+)
Documentation/gpu/drm-kms.rst +0 -0
index 2f3efb63e5ba..fcd4e15379b0 100644

Documentation/gpu/drm-kms.rst KMS Locking · line 464

Quoted 5 lines
Documentation/gpu/drm-kms.rst +2 -0
@@ -460,6 +460,9 @@ KMS Locking
 KMS Properties
 ==============
 
+This section of the documentation is primarily aimed at user-space developers.
+For the driver APIs, so the other sections.

s/so/consult/ ? 2nd sentence doesn't parse here.
-Daniel

Quoted 7 lines
Documentation/gpu/drm-kms.rst +1 -0
+
 Property Types and Blob Property Support
 ----------------------------------------
 
Signature · 1 line
2.29.2
Signature · 7 lines
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
author
#8 lore raw

PATCH 6/8 drm/doc: introduce new section for standard plane properties

In reply to Simon Ser

Introduce a new "Standard Plane Properties" section for properties defined in drm_plane.c. Move the mis-placed IN_FORMATS docs there.

Cc Daniel Vetter <[email protected]>
Cc Pekka Paalanen <[email protected]>
---
 Documentation/gpu/drm-kms.rst |  6 ++++++
 drivers/gpu/drm/drm_blend.c   |  6 ------
 drivers/gpu/drm/drm_plane.c   | 12 ++++++++++++
 3 files changed, 18 insertions(+), 6 deletions(-)
Documentation/gpu/drm-kms.rst +6 -0
index fcd4e15379b0..9cfaab4df21a 100644
@@ -493,6 +493,12 @@ Standard CRTC Properties
 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c
    :doc: standard CRTC properties
 
+Standard Plane Properties
+-------------------------
+
+.. kernel-doc:: drivers/gpu/drm/drm_plane.c
+   :doc: standard plane properties
+
 Plane Composition Properties
 ----------------------------
 
drivers/gpu/drm/drm_blend.c +0 -6
index 5c2141e9a9f4..26e2f2ffd255 100644
@@ -185,12 +185,6 @@
  *		 plane does not expose the "alpha" property, then this is
  *		 assumed to be 1.0
  *
- * IN_FORMATS:
- *	Blob property which contains the set of buffer format and modifier
- *	pairs supported by this plane. The blob is a drm_format_modifier_blob
- *	struct. Without this property the plane doesn't support buffers with
- *	modifiers. Userspace cannot change this property.
- *
  * Note that all the property extensions described here apply either to the
  * plane or the CRTC (e.g. for the background color, which currently is not
  * exposed and assumed to be black).
drivers/gpu/drm/drm_plane.c +12 -0
index 49b0a8b9ac02..4c1a45ac18e6 100644
@@ -61,6 +61,18 @@
  * userspace too much.
  */
 
+/**
+ * DOC: standard plane properties
+ *
+ * DRM planes have a few standardized properties:
+ *
+ * IN_FORMATS:
+ *     Blob property which contains the set of buffer format and modifier
+ *     pairs supported by this plane. The blob is a drm_format_modifier_blob
+ *     struct. Without this property the plane doesn't support buffers with
+ *     modifiers. Userspace cannot change this property.
+ */
+
 static unsigned int drm_num_planes(struct drm_device *dev)
 {
 	unsigned int num = 0;
Signature · 6 lines
2.29.2

_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
Reviewed-by on v1 6/8
#9 lore raw

Re: [PATCH 6/8] drm/doc: introduce new section for standard plane properties

Quoted 2 lines · Simon Ser

Introduce a new "Standard Plane Properties" section for properties defined in drm_plane.c. Move the mis-placed IN_FORMATS docs there.

Yeah that's misplaced.

Quoted 70 lines
Cc Daniel Vetter <[email protected]>
Cc Pekka Paalanen <[email protected]>
---
 Documentation/gpu/drm-kms.rst |  6 ++++++
 drivers/gpu/drm/drm_blend.c   |  6 ------
 drivers/gpu/drm/drm_plane.c   | 12 ++++++++++++
 3 files changed, 18 insertions(+), 6 deletions(-)
Documentation/gpu/drm-kms.rst +6 -0
index fcd4e15379b0..9cfaab4df21a 100644
@@ -493,6 +493,12 @@ Standard CRTC Properties
 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c
    :doc: standard CRTC properties
 
+Standard Plane Properties
+-------------------------
+
+.. kernel-doc:: drivers/gpu/drm/drm_plane.c
+   :doc: standard plane properties
+
 Plane Composition Properties
 ----------------------------
 
drivers/gpu/drm/drm_blend.c +0 -6
index 5c2141e9a9f4..26e2f2ffd255 100644
@@ -185,12 +185,6 @@
  *		 plane does not expose the "alpha" property, then this is
  *		 assumed to be 1.0
  *
- * IN_FORMATS:
- *	Blob property which contains the set of buffer format and modifier
- *	pairs supported by this plane. The blob is a drm_format_modifier_blob
- *	struct. Without this property the plane doesn't support buffers with
- *	modifiers. Userspace cannot change this property.
- *
  * Note that all the property extensions described here apply either to the
  * plane or the CRTC (e.g. for the background color, which currently is not
  * exposed and assumed to be black).
drivers/gpu/drm/drm_plane.c +12 -0
index 49b0a8b9ac02..4c1a45ac18e6 100644
@@ -61,6 +61,18 @@
  * userspace too much.
  */
 
+/**
+ * DOC: standard plane properties
+ *
+ * DRM planes have a few standardized properties:
+ *
+ * IN_FORMATS:
+ *     Blob property which contains the set of buffer format and modifier
+ *     pairs supported by this plane. The blob is a drm_format_modifier_blob
+ *     struct. Without this property the plane doesn't support buffers with
+ *     modifiers. Userspace cannot change this property.
+ */
+
 static unsigned int drm_num_planes(struct drm_device *dev)
 {
 	unsigned int num = 0;
Signature · 1 line
2.29.2
Signature · 7 lines
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
author
#10 lore raw

PATCH 7/8 drm/doc: fix drm_plane_type docs

In reply to Simon Ser

The docs for enum drm_plane_type mention legacy IOCTLs, however the plane type is not tied to legacy IOCTLs, the drm_cursor.primary and cursor fields are. Add a small paragraph to reference these.

Instead, document expectations for primary and cursor planes for non-legacy userspace. Note that these docs are for driver developers, not userspace developers, so internal kernel APIs are mentionned.

Cc Daniel Vetter <[email protected]>
Cc Pekka Paalanen <[email protected]>
---
 include/drm/drm_plane.h | 21 +++++++++++++--------
 1 file changed, 13 insertions(+), 8 deletions(-)
include/drm/drm_plane.h +13 -8
index 1d82b264e5e4..94fdd0c68450 100644
@@ -538,10 +538,14 @@ struct drm_plane_funcs {
  *
  * 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
+ * &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().
  *
+ * In addition to setting each plane's type, drivers need to setup the
+ * &drm_crtc.primary and optionally &drm_crtc.cursor for legacy IOCTLs. See
+ * drm_crtc_init_with_planes().
+ *
  * WARNING: The values of this enum is UABI since they're exposed in the "type"
  * property.
  */
@@ -557,19 +561,20 @@ enum drm_plane_type {
 	/**
 	 * @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 &drm_crtc_funcs.page_flip and
-	 * &drm_crtc_funcs.set_config hooks.
+	 * A primary plane attached to a CRTC is the most likely to be able to
+	 * light up the CRTC when no scaling/cropping is used and the plane
+	 * covers the whole CRTC.
 	 */
 	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.
+	 * A cursor plane attached to a CRTC is more likely to be able to be
+	 * enabled when no scaling/cropping is used and the framebuffer has the
+	 * size indicated by &drm_mode_config.cursor_width and
+	 * &drm_mode_config.cursor_height. Additionally, if the driver doesn't
+	 * support modifiers, the framebuffer should have a linear layout.
 	 */
 	DRM_PLANE_TYPE_CURSOR,
 };
Signature · 6 lines
2.29.2

_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
#11 lore raw

Re: [PATCH 7/8] drm/doc: fix drm_plane_type docs

Quoted 20 lines · Simon Ser

The docs for enum drm_plane_type mention legacy IOCTLs, however the plane type is not tied to legacy IOCTLs, the drm_cursor.primary and cursor fields are. Add a small paragraph to reference these.

Instead, document expectations for primary and cursor planes for non-legacy userspace. Note that these docs are for driver developers, not userspace developers, so internal kernel APIs are mentionned.

Cc Daniel Vetter <[email protected]>
Cc Pekka Paalanen <[email protected]>
---
 include/drm/drm_plane.h | 21 +++++++++++++--------
 1 file changed, 13 insertions(+), 8 deletions(-)
include/drm/drm_plane.h +0 -0
index 1d82b264e5e4..94fdd0c68450 100644

include/drm/drm_plane.h struct drm_plane_funcs { · line 546

Quoted 10 lines
include/drm/drm_plane.h +3 -1
@@ -538,10 +538,14 @@ struct drm_plane_funcs {
  *
  * 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
+ * &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().
  *
+ * In addition to setting each plane's type, drivers need to setup the
+ * &drm_crtc.primary and optionally &drm_crtc.cursor for legacy IOCTLs. See

insert "pointers" here ^ for readability.

include/drm/drm_plane.h enum drm_plane_type { · line 563

Quoted 13 lines
include/drm/drm_plane.h +2 -4
+ * drm_crtc_init_with_planes().
+ *
  * WARNING: The values of this enum is UABI since they're exposed in the "type"
  * property.
  */
@@ -557,19 +561,20 @@ enum drm_plane_type {
 	/**
 	 * @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 &drm_crtc_funcs.page_flip and
-	 * &drm_crtc_funcs.set_config hooks.

I think we should keep the notice which legacy entry hooks implicitly operate on the primary plane. Not sure why you're removing the above sentence. Maybe improve it by adding "See also &drm_crtc.primary." for more context?

include/drm/drm_plane.h enum drm_plane_type { · line 572

Quoted 12 lines
include/drm/drm_plane.h +3 -3
+	 * A primary plane attached to a CRTC is the most likely to be able to
+	 * light up the CRTC when no scaling/cropping is used and the plane
+	 * covers the whole CRTC.
 	 */
 	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.

Same here, I think it matters that this is used by legacy cursor ioctls. Again perhaps a pointer to drm_crtc.cursor can help.
-Daniel

Quoted 11 lines
include/drm/drm_plane.h +5 -0
+	 * A cursor plane attached to a CRTC is more likely to be able to be
+	 * enabled when no scaling/cropping is used and the framebuffer has the
+	 * size indicated by &drm_mode_config.cursor_width and
+	 * &drm_mode_config.cursor_height. Additionally, if the driver doesn't
+	 * support modifiers, the framebuffer should have a linear layout.
 	 */
 	DRM_PLANE_TYPE_CURSOR,
 };
Signature · 1 line
2.29.2
Signature · 7 lines
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
author
#12 lore raw

Re: [PATCH 7/8] drm/doc: fix drm_plane_type docs

Quoted 44 lines · Daniel Vetter
Quoted 20 lines · Simon Ser

The docs for enum drm_plane_type mention legacy IOCTLs, however the plane type is not tied to legacy IOCTLs, the drm_cursor.primary and cursor fields are. Add a small paragraph to reference these.

Instead, document expectations for primary and cursor planes for non-legacy userspace. Note that these docs are for driver developers, not userspace developers, so internal kernel APIs are mentionned.

Cc Daniel Vetter <[email protected]>
Cc Pekka Paalanen <[email protected]>
---
 include/drm/drm_plane.h | 21 +++++++++++++--------
 1 file changed, 13 insertions(+), 8 deletions(-)
include/drm/drm_plane.h +0 -0
index 1d82b264e5e4..94fdd0c68450 100644

include/drm/drm_plane.h struct drm_plane_funcs { · line 546

Quoted 10 lines
include/drm/drm_plane.h +3 -1
@@ -538,10 +538,14 @@ struct drm_plane_funcs {
  *
  * 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
+ * &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().
  *
+ * In addition to setting each plane's type, drivers need to setup the
+ * &drm_crtc.primary and optionally &drm_crtc.cursor for legacy IOCTLs. See

insert "pointers" here ^ for readability.

Quoted 10 lines
include/drm/drm_plane.h +2 -1
+ * drm_crtc_init_with_planes().
+ *
  * WARNING: The values of this enum is UABI since they're exposed in the "type"
  * property.
  */
@@ -557,19 +561,20 @@ enum drm_plane_type {
 	/**
 	 * @DRM_PLANE_TYPE_PRIMARY:
 	 *
-	 * Primary planes represent a "main" plane for a CRTC.  Primary planes
Quoted 8 lines

include/drm/drm_plane.h enum drm_plane_type { · line 563

Quoted 3 lines
include/drm/drm_plane.h +0 -3
-	 * are the planes operated upon by CRTC modesetting and flipping
-	 * operations described in the &drm_crtc_funcs.page_flip and
-	 * &drm_crtc_funcs.set_config hooks.

I think we should keep the notice which legacy entry hooks implicitly operate on the primary plane. Not sure why you're removing the above sentence. Maybe improve it by adding "See also &drm_crtc.primary." for more context?

I intentionally removed it, because setting the plane type will not magically make it used for legacy IOCTLs. The previous version documented the legacy IOCTLs behaviour in the primary and cursor type docs. That was misleading because only the drm_crtc.{primary,cursor} pointers make it so a plane is used for legacy IOCTLs, not the type.

This patch does keep a reference to drm_crtc.{primary,cursor}, in the paragraph right above. Clicking on the reference will explain in detail which legacy IOCTLs are affected. I don't think repeating the paragraph again in the primary and cursor type docs is necessary.
_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Reviewed-by
#13 lore raw

Re: [PATCH 7/8] drm/doc: fix drm_plane_type docs

Quoted 62 lines · Simon Ser
Quoted 44 lines · Daniel Vetter
Quoted 20 lines · Simon Ser

The docs for enum drm_plane_type mention legacy IOCTLs, however the plane type is not tied to legacy IOCTLs, the drm_cursor.primary and cursor fields are. Add a small paragraph to reference these.

Instead, document expectations for primary and cursor planes for non-legacy userspace. Note that these docs are for driver developers, not userspace developers, so internal kernel APIs are mentionned.

Cc Daniel Vetter <[email protected]>
Cc Pekka Paalanen <[email protected]>
---
 include/drm/drm_plane.h | 21 +++++++++++++--------
 1 file changed, 13 insertions(+), 8 deletions(-)
include/drm/drm_plane.h +0 -0
index 1d82b264e5e4..94fdd0c68450 100644

include/drm/drm_plane.h struct drm_plane_funcs { · line 546

Quoted 10 lines
include/drm/drm_plane.h +3 -1
@@ -538,10 +538,14 @@ struct drm_plane_funcs {
  *
  * 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
+ * &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().
  *
+ * In addition to setting each plane's type, drivers need to setup the
+ * &drm_crtc.primary and optionally &drm_crtc.cursor for legacy IOCTLs. See

insert "pointers" here ^ for readability.

Quoted 10 lines
include/drm/drm_plane.h +2 -1
+ * drm_crtc_init_with_planes().
+ *
  * WARNING: The values of this enum is UABI since they're exposed in the "type"
  * property.
  */
@@ -557,19 +561,20 @@ enum drm_plane_type {
    /**
     * @DRM_PLANE_TYPE_PRIMARY:
     *
-    * Primary planes represent a "main" plane for a CRTC.  Primary planes
Quoted 8 lines

include/drm/drm_plane.h enum drm_plane_type { · line 563

Quoted 3 lines
include/drm/drm_plane.h +0 -3
-    * are the planes operated upon by CRTC modesetting and flipping
-    * operations described in the &drm_crtc_funcs.page_flip and
-    * &drm_crtc_funcs.set_config hooks.

I think we should keep the notice which legacy entry hooks implicitly operate on the primary plane. Not sure why you're removing the above sentence. Maybe improve it by adding "See also &drm_crtc.primary." for more context?

I intentionally removed it, because setting the plane type will not magically make it used for legacy IOCTLs. The previous version documented the legacy IOCTLs behaviour in the primary and cursor type docs. That was misleading because only the drm_crtc.{primary,cursor} pointers make it so a plane is used for legacy IOCTLs, not the type.

Quoted 4 lines

This patch does keep a reference to drm_crtc.{primary,cursor}, in the paragraph right above. Clicking on the reference will explain in detail which legacy IOCTLs are affected. I don't think repeating the paragraph again in the primary and cursor type docs is necessary.

Hm I guess works too, I'm not sure documentations must avoid repetitions at all costs (since it generally makes stuff harder to find, despite all the links). So without that change:

Signature · 7 lines
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
author
#14 lore raw

Re: [PATCH 7/8] drm/doc: fix drm_plane_type docs

Quoted 20 lines · Daniel Vetter
Quoted 20 lines
Quoted 5 lines
Quoted 5 lines
include/drm/drm_plane.h +0 -1
@@ -557,19 +561,20 @@ enum drm_plane_type {
    /**
     * @DRM_PLANE_TYPE_PRIMARY:
     *
-    * Primary planes represent a "main" plane for a CRTC.  Primary planes
Quoted 8 lines

include/drm/drm_plane.h enum drm_plane_type { · line 563

Quoted 3 lines
include/drm/drm_plane.h +0 -3
-    * are the planes operated upon by CRTC modesetting and flipping
-    * operations described in the &drm_crtc_funcs.page_flip and
-    * &drm_crtc_funcs.set_config hooks.

I think we should keep the notice which legacy entry hooks implicitly operate on the primary plane. Not sure why you're removing the above sentence. Maybe improve it by adding "See also &drm_crtc.primary." for more context?

I intentionally removed it, because setting the plane type will not magically make it used for legacy IOCTLs. The previous version documented the legacy IOCTLs behaviour in the primary and cursor type docs. That was misleading because only the drm_crtc.{primary,cursor} pointers make it so a plane is used for legacy IOCTLs, not the type.

Quoted 8 lines
Quoted 4 lines

This patch does keep a reference to drm_crtc.{primary,cursor}, in the paragraph right above. Clicking on the reference will explain in detail which legacy IOCTLs are affected. I don't think repeating the paragraph again in the primary and cursor type docs is necessary.

Hm I guess works too, I'm not sure documentations must avoid repetitions at all costs (since it generally makes stuff harder to find, despite all the links).

I didn't find the repetition necessary because the paragraph referencing drm_crtc.{primary,cursor} is literally just a few lines of text away. But I guess as long as it's clear that setting the type doesn't set drm_crtc.{primary,cursor} I'm fine with duplicating the references.

_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel

author
#15 lore raw

PATCH 8/8 drm/doc: document the type plane property

In reply to Simon Ser

Add a new entry for "type" in the section for standard plane properties.

Cc Daniel Vetter <[email protected]>
Cc Pekka Paalanen <[email protected]>
---
 drivers/gpu/drm/drm_plane.c | 39 +++++++++++++++++++++++++++++++++----
 1 file changed, 35 insertions(+), 4 deletions(-)
drivers/gpu/drm/drm_plane.c +35 -4
index 4c1a45ac18e6..e21e0caaca0f 100644
@@ -49,10 +49,8 @@
  * &struct drm_plane (possibly as part of a larger structure) and registers it
  * with a call to drm_universal_plane_init().
  *
- * The type of a plane is exposed in the immutable "type" enumeration property,
- * which has one of the following values: "Overlay", "Primary", "Cursor" (see
- * enum drm_plane_type). A plane can be compatible with multiple CRTCs, see
- * &drm_plane.possible_crtcs.
+ * Each plane has a type, see enum drm_plane_type. A plane can be compatible
+ * with multiple CRTCs, see &drm_plane.possible_crtcs.
  *
  * Legacy uAPI doesn't expose the primary and cursor planes directly. DRM core
  * relies on the driver to set the primary and optionally the cursor plane used
@@ -66,6 +64,39 @@
  *
  * DRM planes have a few standardized properties:
  *
+ * type:
+ *     Immutable property describing the type of the plane.
+ *
+ *     For user-space which has enabled the &DRM_CLIENT_CAP_UNIVERSAL_PLANES
+ *     capability, the plane type is just a hint and is mostly superseded by
+ *     atomic test-only commits. The type hint can still be used to come up
+ *     more easily with a plane configuration accepted by the driver.
+ *
+ *     The value of this property can be one of the following:
+ *
+ *     "Primary":
+ *         To light up a CRTC, attaching a primary plane is the most likely to
+ *         work if it covers the whole CRTC and doesn't have scaling or
+ *         cropping set up.
+ *
+ *         Drivers may support more features for the primary plane, user-space
+ *         can find out with test-only atomic commits.
+ *     "Cursor":
+ *         To enable this plane, using a framebuffer configured without scaling
+ *         or cropping and with the following properties is the most likely to
+ *         work:
+ *
+ *         - If the driver provides the capabilities &DRM_CAP_CURSOR_WIDTH and
+ *           &DRM_CAP_CURSOR_HEIGHT, create the framebuffer with this size.
+ *           Otherwise, create a framebuffer with the size 64x64.
+ *         - If the driver doesn't support modifiers, create a framebuffer with
+ *           a linear layout. Otherwise, use the IN_FORMATS plane property.
+ *
+ *         Drivers may support more features for the cursor plane, user-space
+ *         can find out with test-only atomic commits.
+ *     "Overlay":
+ *         Neither primary nor cursor.
+ *
  * IN_FORMATS:
  *     Blob property which contains the set of buffer format and modifier
  *     pairs supported by this plane. The blob is a drm_format_modifier_blob
Signature · 6 lines
2.29.2

_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
#16 lore raw

Re: [PATCH 8/8] drm/doc: document the type plane property

Quoted 5 lines · Simon Ser

Add a new entry for "type" in the section for standard plane properties.

Cc Daniel Vetter <[email protected]>
Cc Pekka Paalanen <[email protected]>

Looks solid, bunch of comments for extensions and more clarity below. -Daniel

Quoted 22 lines
---
 drivers/gpu/drm/drm_plane.c | 39 +++++++++++++++++++++++++++++++++----
 1 file changed, 35 insertions(+), 4 deletions(-)
drivers/gpu/drm/drm_plane.c +2 -4
index 4c1a45ac18e6..e21e0caaca0f 100644
@@ -49,10 +49,8 @@
  * &struct drm_plane (possibly as part of a larger structure) and registers it
  * with a call to drm_universal_plane_init().
  *
- * The type of a plane is exposed in the immutable "type" enumeration property,
- * which has one of the following values: "Overlay", "Primary", "Cursor" (see
- * enum drm_plane_type). A plane can be compatible with multiple CRTCs, see
- * &drm_plane.possible_crtcs.
+ * Each plane has a type, see enum drm_plane_type. A plane can be compatible
+ * with multiple CRTCs, see &drm_plane.possible_crtcs.
  *
  * Legacy uAPI doesn't expose the primary and cursor planes directly. DRM core
  * relies on the driver to set the primary and optionally the cursor plane used

drivers/gpu/drm/drm_plane.c line 70

Quoted 7 lines
drivers/gpu/drm/drm_plane.c +4 -0
@@ -66,6 +64,39 @@
  *
  * DRM planes have a few standardized properties:
  *
+ * type:
+ *     Immutable property describing the type of the plane.
+ *
+ *     For user-space which has enabled the &DRM_CLIENT_CAP_UNIVERSAL_PLANES

While we're at this: Does the kerneldoc for this cap mention that it's implicitly enabled when you're enabling atomic?

Maybe worth repeating here too.

drivers/gpu/drm/drm_plane.c line 83

Quoted 13 lines
drivers/gpu/drm/drm_plane.c +13 -0
+ *     capability, the plane type is just a hint and is mostly superseded by
+ *     atomic test-only commits. The type hint can still be used to come up
+ *     more easily with a plane configuration accepted by the driver.
+ *
+ *     The value of this property can be one of the following:
+ *
+ *     "Primary":
+ *         To light up a CRTC, attaching a primary plane is the most likely to
+ *         work if it covers the whole CRTC and doesn't have scaling or
+ *         cropping set up.
+ *
+ *         Drivers may support more features for the primary plane, user-space
+ *         can find out with test-only atomic commits.

We need to mention here that this is the implicit plane used by the PAGE_FLIP and SETCRTC ioctl (maybe spell them out in full since these are userspace docs).

drivers/gpu/drm/drm_plane.c line 93

Quoted 10 lines
drivers/gpu/drm/drm_plane.c +10 -0
+ *     "Cursor":
+ *         To enable this plane, using a framebuffer configured without scaling
+ *         or cropping and with the following properties is the most likely to
+ *         work:
+ *
+ *         - If the driver provides the capabilities &DRM_CAP_CURSOR_WIDTH and
+ *           &DRM_CAP_CURSOR_HEIGHT, create the framebuffer with this size.
+ *           Otherwise, create a framebuffer with the size 64x64.
+ *         - If the driver doesn't support modifiers, create a framebuffer with
+ *           a linear layout. Otherwise, use the IN_FORMATS plane property.

Same here, I think we should mention this is used implicitly (but only on some drivers, there atomic drivers which do _not_ expose their cursor as a cursor plane).

drivers/gpu/drm/drm_plane.c line 98

Quoted 5 lines
drivers/gpu/drm/drm_plane.c +5 -0
+ *
+ *         Drivers may support more features for the cursor plane, user-space
+ *         can find out with test-only atomic commits.
+ *     "Overlay":
+ *         Neither primary nor cursor.

This should mention that these are the only planes exposed when universal planes isnt set.

Quoted 7 lines
drivers/gpu/drm/drm_plane.c +1 -0
+ *
  * IN_FORMATS:
  *     Blob property which contains the set of buffer format and modifier
  *     pairs supported by this plane. The blob is a drm_format_modifier_blob
Signature · 1 line
2.29.2
Signature · 7 lines
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
author
#17 lore raw

Re: [PATCH 8/8] drm/doc: document the type plane property

Quoted 9 lines · Daniel Vetter
Quoted 4 lines

+ * type:
+ * Immutable property describing the type of the plane.
+ *
+ * For user-space which has enabled the &DRM_CLIENT_CAP_UNIVERSAL_PLANES

While we're at this: Does the kerneldoc for this cap mention that it's implicitly enabled when you're enabling atomic?

Maybe worth repeating here too.

Good point. v2 will do both.

Quoted 14 lines
Quoted 7 lines
+ *     capability, the plane type is just a hint and is mostly superseded by
+ *     atomic test-only commits. The type hint can still be used to come up
+ *     more easily with a plane configuration accepted by the driver.

+ *
+ * The value of this property can be one of the following:
+ *
+ * "Primary":

Quoted 6 lines
+ *         To light up a CRTC, attaching a primary plane is the most likely to
+ *         work if it covers the whole CRTC and doesn't have scaling or
+ *         cropping set up.

+ *
+ * Drivers may support more features for the primary plane, user-space
+ * can find out with test-only atomic commits.

Quoted 3 lines

We need to mention here that this is the implicit plane used by the PAGE_FLIP and SETCRTC ioctl (maybe spell them out in full since these are userspace docs).

I intentionally didn't write that down here, because as previously discussed, user-space has no way to guess the drm_crtc.{primary,cursor} pointers, so user-space cannot guess which planes will be used for legacy IOCTLs. Adding any hint that user-space _could_ do it will result in broken user-space.
_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel

#18 lore raw

Re: [PATCH 8/8] drm/doc: document the type plane property

Quoted 29 lines · Simon Ser
Quoted 9 lines · Daniel Vetter
Quoted 4 lines

+ * type:
+ * Immutable property describing the type of the plane.
+ *
+ * For user-space which has enabled the &DRM_CLIENT_CAP_UNIVERSAL_PLANES

While we're at this: Does the kerneldoc for this cap mention that it's implicitly enabled when you're enabling atomic?

Maybe worth repeating here too.

Good point. v2 will do both.

Quoted 14 lines
Quoted 13 lines
+ *     capability, the plane type is just a hint and is mostly superseded by
+ *     atomic test-only commits. The type hint can still be used to come up
+ *     more easily with a plane configuration accepted by the driver.

+ *
+ * The value of this property can be one of the following:
+ *
+ * "Primary":

+ *         To light up a CRTC, attaching a primary plane is the most likely to
+ *         work if it covers the whole CRTC and doesn't have scaling or
+ *         cropping set up.

+ *
+ * Drivers may support more features for the primary plane, user-space
+ * can find out with test-only atomic commits.

Quoted 8 lines
Quoted 3 lines

We need to mention here that this is the implicit plane used by the PAGE_FLIP and SETCRTC ioctl (maybe spell them out in full since these are userspace docs).

I intentionally didn't write that down here, because as previously discussed, user-space has no way to guess the drm_crtc.{primary,cursor} pointers, so user-space cannot guess which planes will be used for legacy IOCTLs. Adding any hint that user-space _could_ do it will result in broken user-space.

Hm then at least a warning that userspace must not mix legacy ioctls with using primary planes explicitly, since havoc will ensue? More relevant for cursor planes, since some compositors do use atomic + legacy cursor planes, but imo good to have the same blurb with the list of relevant ioctls for each.
-Daniel

Signature · 7 lines
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
author
#19 lore raw

Re: [PATCH 8/8] drm/doc: document the type plane property

Quoted 23 lines · Daniel Vetter
Quoted 14 lines
Quoted 14 lines
Quoted 13 lines
+ *     capability, the plane type is just a hint and is mostly superseded by
+ *     atomic test-only commits. The type hint can still be used to come up
+ *     more easily with a plane configuration accepted by the driver.

+ *
+ * The value of this property can be one of the following:
+ *
+ * "Primary":

+ *         To light up a CRTC, attaching a primary plane is the most likely to
+ *         work if it covers the whole CRTC and doesn't have scaling or
+ *         cropping set up.

+ *
+ * Drivers may support more features for the primary plane, user-space
+ * can find out with test-only atomic commits.

Quoted 8 lines
Quoted 3 lines

We need to mention here that this is the implicit plane used by the PAGE_FLIP and SETCRTC ioctl (maybe spell them out in full since these are userspace docs).

I intentionally didn't write that down here, because as previously discussed, user-space has no way to guess the drm_crtc.{primary,cursor} pointers, so user-space cannot guess which planes will be used for legacy IOCTLs. Adding any hint that user-space _could_ do it will result in broken user-space.

Quoted 5 lines

Hm then at least a warning that userspace must not mix legacy ioctls with using primary planes explicitly, since havoc will ensue? More relevant for cursor planes, since some compositors do use atomic + legacy cursor planes, but imo good to have the same blurb with the list of relevant ioctls for each.

Oh, right, good idea, this sounds important. Will add in v2.
_______________________________________________
dri-devel mailing list [email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel