Skip to contentSkip to conversation

Document drm_mode_get_plane

PATCH Superseded Leandro Ribeiro 2 participants 10 messages Apr 28, 2021 – May 20, 2021

Subsystems (3)

v3 of 6 Superseded Latest is v6 →

lore
Share & tools
lore
#0 lore raw

v3 cover Document drm_mode_get_plane

v2: possible_crtcs field is a bitmask, not a pointer. Suggested by Ville Syrjälä <[email protected]>

v3: document how userspace should find out CRTC index. Also, document that field 'gamma_size' represents the number of entries in the lookup table. Suggested by Pekka Paalanen <[email protected]> and Daniel Vetter <[email protected]>

Leandro Ribeiro (2):
drm/doc: document how userspace should find out CRTC index drm/doc: document drm_mode_get_plane

 Documentation/gpu/drm-uapi.rst    | 14 ++++++++++++++
 drivers/gpu/drm/drm_debugfs_crc.c |  9 +++++----
 include/uapi/drm/drm.h            |  3 ++-
 include/uapi/drm/drm_mode.h       | 22 ++++++++++++++++++++++
 4 files changed, 43 insertions(+), 5 deletions(-)

--
2.31.1

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

#1 lore raw

PATCH v3 1/2 drm/doc: document how userspace should find out CRTC index

In this patch we add a section to document what userspace should do to find out the CRTC index. This is important as there are multiple places in the documentation that need this, so it's better to just point to this section and avoid repetition.

---
 Documentation/gpu/drm-uapi.rst    | 14 ++++++++++++++
 drivers/gpu/drm/drm_debugfs_crc.c |  9 +++++----
 include/uapi/drm/drm.h            |  3 ++-
 3 files changed, 21 insertions(+), 5 deletions(-)
Documentation/gpu/drm-uapi.rst +14 -0
index 04bdc7a91d53..1aa52a6ac567 100644
@@ -457,6 +457,20 @@ Userspace API Structures
 .. kernel-doc:: include/uapi/drm/drm_mode.h
    :doc: overview
 
+.. _crtc_index:
+
+CRTC index
+----------
+
+In some situations, it is important for userspace to find out the index of a
+CRTC. The CRTC index should not be confused with its object id.
+
+In order to do this, userspace should first query the resources object
+from the device that owns the CRTC (using the DRM_IOCTL_MODE_GETRESOURCES
+ioctl). The resources object contains a pointer to an array of CRTC's, and also
+the number of entries of the array. The index of the CRTC is the same as its
+position in this array.
+
 .. kernel-doc:: include/uapi/drm/drm.h
    :internal:
 
drivers/gpu/drm/drm_debugfs_crc.c +5 -4
index 3dd70d813f69..9575188d97ee 100644
@@ -46,10 +46,11 @@
  * it reached a given hardware component (a CRC sampling "source").
  *
  * Userspace can control generation of CRCs in a given CRTC by writing to the
- * file dri/0/crtc-N/crc/control in debugfs, with N being the index of the CRTC.
- * Accepted values are source names (which are driver-specific) and the "auto"
- * keyword, which will let the driver select a default source of frame CRCs
- * for this CRTC.
+ * file dri/0/crtc-N/crc/control in debugfs, with N being the index of the
+ * CRTC. To learn how to find out the index of a certain CRTC, please see
+ * :ref:`crtc_index`. Accepted values are source names (which are
+ * driver-specific) and the "auto" keyword, which will let the driver select a
+ * default source of frame CRCs for this CRTC.
  *
  * Once frame CRC generation is enabled, userspace can capture them by reading
  * the dri/0/crtc-N/crc/data file. Each line in that file contains the frame
include/uapi/drm/drm.h +2 -1
index 67b94bc3c885..6944f08ab1a6 100644
@@ -636,7 +636,8 @@ struct drm_gem_open {
  * DRM_CAP_VBLANK_HIGH_CRTC
  *
  * If set to 1, the kernel supports specifying a CRTC index in the high bits of
- * &drm_wait_vblank_request.type.
+ * &drm_wait_vblank_request.type. To learn how to find out the index of a
+ * certain CRTC, please see :ref:`crtc_index`.
  *
  * Starting kernel version 2.6.39, this capability is always set to 1.
  */

--
2.31.1

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

#2 lore raw

Re: [PATCH 1/2] drm/doc: document how userspace should find out CRTC index

Quoted 17 lines · On Wed, 28 Apr 2021 18:36:50 -0300 Leandro Ribeiro…

In this patch we add a section to document what userspace should do to find out the CRTC index. This is important as there are multiple places in the documentation that need this, so it's better to just point to this section and avoid repetition.

---
 Documentation/gpu/drm-uapi.rst    | 14 ++++++++++++++
 drivers/gpu/drm/drm_debugfs_crc.c |  9 +++++----
 include/uapi/drm/drm.h            |  3 ++-
 3 files changed, 21 insertions(+), 5 deletions(-)
Documentation/gpu/drm-uapi.rst +0 -0
index 04bdc7a91d53..1aa52a6ac567 100644

Documentation/gpu/drm-uapi.rst Userspace API Structures · line 465

Quoted 9 lines
Documentation/gpu/drm-uapi.rst +6 -0
@@ -457,6 +457,20 @@ Userspace API Structures
 .. kernel-doc:: include/uapi/drm/drm_mode.h
    :doc: overview
 
+.. _crtc_index:
+
+CRTC index
+----------
+
+In some situations, it is important for userspace to find out the index of a

That could be said about everything, so this sentence has no information value. Instead, you could start by stating that CRTCs have both an object ID and an index, and they are not the same thing. CRTC index is used in cases where a densely packed identifier for a CRTC is needed, e.g. in bit-for-crtc masks, where using the object ID would not work.

Documentation/gpu/drm-uapi.rst Userspace API Structures · line 468

Quoted 3 lines
Documentation/gpu/drm-uapi.rst +3 -0
+CRTC. The CRTC index should not be confused with its object id.
+
+In order to do this, userspace should first query the resources object

Instead of saying what userspace must do, you could just explain where it can be observed.

Documentation/gpu/drm-uapi.rst Userspace API Structures · line 469

Quoted 1 line
Documentation/gpu/drm-uapi.rst +1 -0
+from the device that owns the CRTC (using the DRM_IOCTL_MODE_GETRESOURCES

So here you might start with: DRM_IOCTL_MODE_GETRESOURCES populates a structure with an array of CRTC IDs. CRTC's index is its index in that array.

Documentation/gpu/drm-uapi.rst Userspace API Structures · line 472

Quoted 3 lines
Documentation/gpu/drm-uapi.rst +3 -0
+ioctl). The resources object contains a pointer to an array of CRTC's, and also
+the number of entries of the array. The index of the CRTC is the same as its
+position in this array.

Anyway, the idea here is right.

Quoted 9 lines
Documentation/gpu/drm-uapi.rst +1 -0
+
 .. kernel-doc:: include/uapi/drm/drm.h
    :internal:
 
drivers/gpu/drm/drm_debugfs_crc.c +0 -0
index 3dd70d813f69..9575188d97ee 100644

drivers/gpu/drm/drm_debugfs_crc.c line 51

Quoted 10 lines
drivers/gpu/drm/drm_debugfs_crc.c +3 -4
@@ -46,10 +46,11 @@
  * it reached a given hardware component (a CRC sampling "source").
  *
  * Userspace can control generation of CRCs in a given CRTC by writing to the
- * file dri/0/crtc-N/crc/control in debugfs, with N being the index of the CRTC.
- * Accepted values are source names (which are driver-specific) and the "auto"
- * keyword, which will let the driver select a default source of frame CRCs
- * for this CRTC.
+ * file dri/0/crtc-N/crc/control in debugfs, with N being the index of the
+ * CRTC. To learn how to find out the index of a certain CRTC, please see
+ * :ref:`crtc_index`. Accepted values are source names (which are

This a bit verbose: "To learn..." It could be more concise, like making the words "the index" a hyperlink instead of adding a whole sentence.

Quoted 10 lines
drivers/gpu/drm/drm_debugfs_crc.c +2 -0
+ * driver-specific) and the "auto" keyword, which will let the driver select a
+ * default source of frame CRCs for this CRTC.
  *
  * Once frame CRC generation is enabled, userspace can capture them by reading
  * the dri/0/crtc-N/crc/data file. Each line in that file contains the frame
include/uapi/drm/drm.h +0 -0
index 67b94bc3c885..6944f08ab1a6 100644

include/uapi/drm/drm.h struct drm_gem_open { · line 640

Quoted 6 lines
include/uapi/drm/drm.h +2 -1
@@ -636,7 +636,8 @@ struct drm_gem_open {
  * DRM_CAP_VBLANK_HIGH_CRTC
  *
  * If set to 1, the kernel supports specifying a CRTC index in the high bits of
- * &drm_wait_vblank_request.type.
+ * &drm_wait_vblank_request.type. To learn how to find out the index of a
+ * certain CRTC, please see :ref:`crtc_index`.

The same here with "a CRTC index" turned into a hyperlink.

Thanks,
pq

Quoted 10 lines
include/uapi/drm/drm.h +0 -1
  *
  * Starting kernel version 2.6.39, this capability is always set to 1.
  */
--

2.31.1

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

#3 lore raw

Re: [PATCH 1/2] drm/doc: document how userspace should find out CRTC index

Quoted 50 lines · Pekka Paalanen
Quoted 17 lines · On Wed, 28 Apr 2021 18:36:50 -0300 Leandro Ribeiro…

In this patch we add a section to document what userspace should do to find out the CRTC index. This is important as there are multiple places in the documentation that need this, so it's better to just point to this section and avoid repetition.

---
 Documentation/gpu/drm-uapi.rst    | 14 ++++++++++++++
 drivers/gpu/drm/drm_debugfs_crc.c |  9 +++++----
 include/uapi/drm/drm.h            |  3 ++-
 3 files changed, 21 insertions(+), 5 deletions(-)
Documentation/gpu/drm-uapi.rst +0 -0
index 04bdc7a91d53..1aa52a6ac567 100644

Documentation/gpu/drm-uapi.rst Userspace API Structures · line 465

Quoted 9 lines
Documentation/gpu/drm-uapi.rst +6 -0
@@ -457,6 +457,20 @@ Userspace API Structures
 .. kernel-doc:: include/uapi/drm/drm_mode.h
    :doc: overview
 
+.. _crtc_index:
+
+CRTC index
+----------
+
+In some situations, it is important for userspace to find out the index of a

That could be said about everything, so this sentence has no information value. Instead, you could start by stating that CRTCs have both an object ID and an index, and they are not the same thing. CRTC index is used in cases where a densely packed identifier for a CRTC is needed, e.g. in bit-for-crtc masks, where using the object ID would not work.

Documentation/gpu/drm-uapi.rst Userspace API Structures · line 468

Quoted 3 lines
Documentation/gpu/drm-uapi.rst +3 -0
+CRTC. The CRTC index should not be confused with its object id.
+
+In order to do this, userspace should first query the resources object

Instead of saying what userspace must do, you could just explain where it can be observed.

Documentation/gpu/drm-uapi.rst Userspace API Structures · line 469

Quoted 1 line
Documentation/gpu/drm-uapi.rst +1 -0
+from the device that owns the CRTC (using the DRM_IOCTL_MODE_GETRESOURCES

So here you might start with: DRM_IOCTL_MODE_GETRESOURCES populates a structure with an array of CRTC IDs. CRTC's index is its index in that array.

Quoted 6 lines

Documentation/gpu/drm-uapi.rst Userspace API Structures · line 472

Quoted 3 lines
Documentation/gpu/drm-uapi.rst +3 -0
+ioctl). The resources object contains a pointer to an array of CRTC's, and also
+the number of entries of the array. The index of the CRTC is the same as its
+position in this array.

Anyway, the idea here is right.

So what about:

CRTC's have both an object ID and an index, and they should not be confused. The index is used in cases where a densely packed identifier for a CRTC is needed, for instance in a bitmask of CRTC's. (maybe a link to the possible_crtcs field of struct drm_mode_get_plane? as example)

DRM_IOCTL_MODE_GETRESOURCES populates a structure with an array of CRTC id's, and the CRTC index is its position in this array.

Quoted 15 lines
Quoted 15 lines
Documentation/gpu/drm-uapi.rst +1 -0
+
 .. kernel-doc:: include/uapi/drm/drm.h
    :internal:
 
drivers/gpu/drm/drm_debugfs_crc.c +0 -3
index 3dd70d813f69..9575188d97ee 100644
@@ -46,10 +46,11 @@
  * it reached a given hardware component (a CRC sampling "source").
  *
  * Userspace can control generation of CRCs in a given CRTC by writing to the
- * file dri/0/crtc-N/crc/control in debugfs, with N being the index of the CRTC.
- * Accepted values are source names (which are driver-specific) and the "auto"
- * keyword, which will let the driver select a default source of frame CRCs
Quoted 9 lines

drivers/gpu/drm/drm_debugfs_crc.c line 51

Quoted 4 lines
drivers/gpu/drm/drm_debugfs_crc.c +3 -1
- * for this CRTC.
+ * file dri/0/crtc-N/crc/control in debugfs, with N being the index of the
+ * CRTC. To learn how to find out the index of a certain CRTC, please see
+ * :ref:`crtc_index`. Accepted values are source names (which are

This a bit verbose: "To learn..." It could be more concise, like making the words "the index" a hyperlink instead of adding a whole sentence.

Nice, I'll apply this change.

Quoted 10 lines
Quoted 10 lines
drivers/gpu/drm/drm_debugfs_crc.c +2 -0
+ * driver-specific) and the "auto" keyword, which will let the driver select a
+ * default source of frame CRCs for this CRTC.
  *
  * Once frame CRC generation is enabled, userspace can capture them by reading
  * the dri/0/crtc-N/crc/data file. Each line in that file contains the frame
include/uapi/drm/drm.h +0 -0
index 67b94bc3c885..6944f08ab1a6 100644
@@ -636,7 +636,8 @@ struct drm_gem_open {
Quoted 9 lines

include/uapi/drm/drm.h struct drm_gem_open { · line 640

Quoted 6 lines
include/uapi/drm/drm.h +2 -1
  * DRM_CAP_VBLANK_HIGH_CRTC
  *
  * If set to 1, the kernel supports specifying a CRTC index in the high bits of
- * &drm_wait_vblank_request.type.
+ * &drm_wait_vblank_request.type. To learn how to find out the index of a
+ * certain CRTC, please see :ref:`crtc_index`.

The same here with "a CRTC index" turned into a hyperlink.

I'll change this as well.

Thanks,
Leandro

Quoted 15 lines

Thanks,
pq

Quoted 10 lines
include/uapi/drm/drm.h +0 -1
  *
  * Starting kernel version 2.6.39, this capability is always set to 1.
  */
--

2.31.1

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

#4 lore raw

Re: [PATCH 1/2] drm/doc: document how userspace should find out CRTC index

Quoted 60 lines · On Wed, 12 May 2021 09:50:14 -0300 Leandro Ribeiro…
Quoted 50 lines · Pekka Paalanen
Quoted 17 lines · On Wed, 28 Apr 2021 18:36:50 -0300 Leandro Ribeiro…

In this patch we add a section to document what userspace should do to find out the CRTC index. This is important as there are multiple places in the documentation that need this, so it's better to just point to this section and avoid repetition.

---
 Documentation/gpu/drm-uapi.rst    | 14 ++++++++++++++
 drivers/gpu/drm/drm_debugfs_crc.c |  9 +++++----
 include/uapi/drm/drm.h            |  3 ++-
 3 files changed, 21 insertions(+), 5 deletions(-)
Documentation/gpu/drm-uapi.rst +0 -0
index 04bdc7a91d53..1aa52a6ac567 100644

Documentation/gpu/drm-uapi.rst Userspace API Structures · line 465

Quoted 9 lines
Documentation/gpu/drm-uapi.rst +6 -0
@@ -457,6 +457,20 @@ Userspace API Structures
 .. kernel-doc:: include/uapi/drm/drm_mode.h
    :doc: overview
 
+.. _crtc_index:
+
+CRTC index
+----------
+
+In some situations, it is important for userspace to find out the index of a  

That could be said about everything, so this sentence has no information value. Instead, you could start by stating that CRTCs have both an object ID and an index, and they are not the same thing. CRTC index is used in cases where a densely packed identifier for a CRTC is needed, e.g. in bit-for-crtc masks, where using the object ID would not work.

Documentation/gpu/drm-uapi.rst Userspace API Structures · line 468

Quoted 3 lines
Documentation/gpu/drm-uapi.rst +3 -0
+CRTC. The CRTC index should not be confused with its object id.
+
+In order to do this, userspace should first query the resources object  

Instead of saying what userspace must do, you could just explain where it can be observed.

Documentation/gpu/drm-uapi.rst Userspace API Structures · line 469

Quoted 1 line
Documentation/gpu/drm-uapi.rst +1 -0
+from the device that owns the CRTC (using the DRM_IOCTL_MODE_GETRESOURCES  

So here you might start with: DRM_IOCTL_MODE_GETRESOURCES populates a structure with an array of CRTC IDs. CRTC's index is its index in that array.

Quoted 6 lines

Documentation/gpu/drm-uapi.rst Userspace API Structures · line 472

Quoted 3 lines
Documentation/gpu/drm-uapi.rst +3 -0
+ioctl). The resources object contains a pointer to an array of CRTC's, and also
+the number of entries of the array. The index of the CRTC is the same as its
+position in this array.  

Anyway, the idea here is right.

So what about:

Quoted 7 lines

CRTC's have both an object ID and an index, and they should not be confused. The index is used in cases where a densely packed identifier for a CRTC is needed, for instance in a bitmask of CRTC's. (maybe a link to the possible_crtcs field of struct drm_mode_get_plane? as example)

DRM_IOCTL_MODE_GETRESOURCES populates a structure with an array of CRTC id's, and the CRTC index is its position in this array.

Sure, sounds good.

Capitalized 'ID'?

Thanks,
pq

#5 lore raw

Re: [PATCH 1/2] drm/doc: document how userspace should find out CRTC index

Quoted 68 lines · Pekka Paalanen
Quoted 65 lines · On Wed, 12 May 2021 09:50:14 -0300 Leandro Ribeiro…
Quoted 50 lines · Pekka Paalanen
Quoted 17 lines · On Wed, 28 Apr 2021 18:36:50 -0300 Leandro Ribeiro…

In this patch we add a section to document what userspace should do to find out the CRTC index. This is important as there are multiple places in the documentation that need this, so it's better to just point to this section and avoid repetition.

---
 Documentation/gpu/drm-uapi.rst    | 14 ++++++++++++++
 drivers/gpu/drm/drm_debugfs_crc.c |  9 +++++----
 include/uapi/drm/drm.h            |  3 ++-
 3 files changed, 21 insertions(+), 5 deletions(-)
Documentation/gpu/drm-uapi.rst +0 -0
index 04bdc7a91d53..1aa52a6ac567 100644

Documentation/gpu/drm-uapi.rst Userspace API Structures · line 465

Quoted 9 lines
Documentation/gpu/drm-uapi.rst +6 -0
@@ -457,6 +457,20 @@ Userspace API Structures
 .. kernel-doc:: include/uapi/drm/drm_mode.h
    :doc: overview
 
+.. _crtc_index:
+
+CRTC index
+----------
+
+In some situations, it is important for userspace to find out the index of a  

That could be said about everything, so this sentence has no information value. Instead, you could start by stating that CRTCs have both an object ID and an index, and they are not the same thing. CRTC index is used in cases where a densely packed identifier for a CRTC is needed, e.g. in bit-for-crtc masks, where using the object ID would not work.

Documentation/gpu/drm-uapi.rst Userspace API Structures · line 468

Quoted 3 lines
Documentation/gpu/drm-uapi.rst +3 -0
+CRTC. The CRTC index should not be confused with its object id.
+
+In order to do this, userspace should first query the resources object  

Instead of saying what userspace must do, you could just explain where it can be observed.

Documentation/gpu/drm-uapi.rst Userspace API Structures · line 469

Quoted 1 line
Documentation/gpu/drm-uapi.rst +1 -0
+from the device that owns the CRTC (using the DRM_IOCTL_MODE_GETRESOURCES  

So here you might start with: DRM_IOCTL_MODE_GETRESOURCES populates a structure with an array of CRTC IDs. CRTC's index is its index in that array.

Quoted 6 lines

Documentation/gpu/drm-uapi.rst Userspace API Structures · line 472

Quoted 3 lines
Documentation/gpu/drm-uapi.rst +3 -0
+ioctl). The resources object contains a pointer to an array of CRTC's, and also
+the number of entries of the array. The index of the CRTC is the same as its
+position in this array.  

Anyway, the idea here is right.

So what about:

CRTC's have both an object ID and an index, and they should not be confused. The index is used in cases where a densely packed identifier for a CRTC is needed, for instance in a bitmask of CRTC's. (maybe a link to the possible_crtcs field of struct drm_mode_get_plane? as example)

Quoted 7 lines
Quoted 2 lines

DRM_IOCTL_MODE_GETRESOURCES populates a structure with an array of CRTC id's, and the CRTC index is its position in this array.

Sure, sounds good.

Capitalized 'ID'?

Sure, I'll add this change.

Thanks,
Leandro

#6 lore raw

PATCH v3 2/2 drm/doc: document drm_mode_get_plane

In reply to Leandro Ribeiro

Add a small description and document struct fields of drm_mode_get_plane.

---
 include/uapi/drm/drm_mode.h | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)
include/uapi/drm/drm_mode.h +22 -0
index a5e76aa06ad5..8fa6495cd948 100644
@@ -312,16 +312,38 @@ struct drm_mode_set_plane {
 	__u32 src_w;
 };
 
+/**
+ * struct drm_mode_get_plane - Get plane metadata.
+ *
+ * Userspace can perform a GETPLANE ioctl to retrieve information about a
+ * plane.
+ */
 struct drm_mode_get_plane {
+	/** @plane_id: Object ID of the plane. */
 	__u32 plane_id;
 
+	/** @crtc_id: Object ID of the current CRTC. */
 	__u32 crtc_id;
+	/** @fb_id: Object ID of the current fb. */
 	__u32 fb_id;
 
+	/**
+	 * @possible_crtcs: Bitmask of CRTC's compatible with the plane. CRTC's
+	 * are created and they receive an index, which corresponds to their
+	 * position in the bitmask. CRTC with index 0 will be in bit 0, and so
+	 * on. To learn how to find out the index of a certain CRTC, please see
+	 * :ref:`crtc_index`.
+	 */
 	__u32 possible_crtcs;
+	/** @gamma_size: Number of entries of the legacy gamma lookup table. */
 	__u32 gamma_size;
 
+	/** @count_format_types: Number of formats. */
 	__u32 count_format_types;
+	/**
+	 * @format_type_ptr: Pointer to ``__u32`` array of formats that are
+	 * supported by the plane. These formats do not require modifiers.
+	 */
 	__u64 format_type_ptr;
 };
 

--
2.31.1

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

#7 lore raw

Re: [PATCH 2/2] drm/doc: document drm_mode_get_plane

Quoted 4 lines · On Wed, 28 Apr 2021 18:36:51 -0300 Leandro Ribeiro…

Add a small description and document struct fields of drm_mode_get_plane.

Hi,

thanks a lot for revising these.

Quoted 10 lines
---
 include/uapi/drm/drm_mode.h | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)
include/uapi/drm/drm_mode.h +0 -0
index a5e76aa06ad5..8fa6495cd948 100644
@@ -312,16 +312,38 @@ struct drm_mode_set_plane {
 	__u32 src_w;

include/uapi/drm/drm_mode.h struct drm_mode_set_plane { · line 322

Quoted 10 lines
include/uapi/drm/drm_mode.h +7 -0
 };
 
+/**
+ * struct drm_mode_get_plane - Get plane metadata.
+ *
+ * Userspace can perform a GETPLANE ioctl to retrieve information about a
+ * plane.
+ */
 struct drm_mode_get_plane {
+	/** @plane_id: Object ID of the plane. */

This is an "in" field, right?

"in" meaning that userspace sets it to the ID of the plane it wants information on.

"out" field is a field written by the kernel as a response.

I'm not sure if the kernel has a habit of documenting these, because we use libdrm to abstract this so users do not need to care, but I think it would be nice.

include/uapi/drm/drm_mode.h struct drm_mode_set_plane { · line 335

Quoted 13 lines
include/uapi/drm/drm_mode.h +8 -0
 	__u32 plane_id;
 
+	/** @crtc_id: Object ID of the current CRTC. */
 	__u32 crtc_id;
+	/** @fb_id: Object ID of the current fb. */
 	__u32 fb_id;
 
+	/**
+	 * @possible_crtcs: Bitmask of CRTC's compatible with the plane. CRTC's
+	 * are created and they receive an index, which corresponds to their
+	 * position in the bitmask. CRTC with index 0 will be in bit 0, and so
+	 * on. To learn how to find out the index of a certain CRTC, please see
+	 * :ref:`crtc_index`.

This could be shortened to something like bit N corresponds to CRTC index N, and make "CRTC index N" a hyperlink.

include/uapi/drm/drm_mode.h struct drm_mode_set_plane { · line 347

Quoted 12 lines
include/uapi/drm/drm_mode.h +7 -0
+	 */
 	__u32 possible_crtcs;
+	/** @gamma_size: Number of entries of the legacy gamma lookup table. */
 	__u32 gamma_size;
 
+	/** @count_format_types: Number of formats. */
 	__u32 count_format_types;
+	/**
+	 * @format_type_ptr: Pointer to ``__u32`` array of formats that are
+	 * supported by the plane. These formats do not require modifiers.
+	 */
 	__u64 format_type_ptr;

The count/ptr fields have an interesting usage pattern, which I suppose is common for all DRM ioctls. Makes me wonder if it should be documented.

AFAIU, count is in+out field: when set to 0, the kernel uses it to return the count needed. Then userspace allocates space and calls the ioctl again with the right count and ptr set to point to the allocated array of count elements. This is so that kernel never allocates memory on behalf of userspace for the return data, making things much simpler at the cost of maybe needing to call the ioctl twice to first figure out long the array should be.

This can be seen in libdrm code for drmModeGetPlane().

There is certainly no point in explaining all that here, that is too much. But if there was a way to annotate the count member as in+out, that would be nice. And the ptr member as "in".

Thanks,
pq

Quoted 9 lines
include/uapi/drm/drm_mode.h +0 -1
 };
 
--

2.31.1

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

#8 lore raw

Re: [PATCH 2/2] drm/doc: document drm_mode_get_plane

Quoted 35 lines · Pekka Paalanen
Quoted 4 lines · On Wed, 28 Apr 2021 18:36:51 -0300 Leandro Ribeiro…

Add a small description and document struct fields of drm_mode_get_plane.

Hi,

thanks a lot for revising these.

Quoted 10 lines
---
 include/uapi/drm/drm_mode.h | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)
include/uapi/drm/drm_mode.h +0 -0
index a5e76aa06ad5..8fa6495cd948 100644
@@ -312,16 +312,38 @@ struct drm_mode_set_plane {
 	__u32 src_w;

include/uapi/drm/drm_mode.h struct drm_mode_set_plane { · line 322

Quoted 10 lines
include/uapi/drm/drm_mode.h +7 -0
 };
 
+/**
+ * struct drm_mode_get_plane - Get plane metadata.
+ *
+ * Userspace can perform a GETPLANE ioctl to retrieve information about a
+ * plane.
+ */
 struct drm_mode_get_plane {
+	/** @plane_id: Object ID of the plane. */

This is an "in" field, right?

Quoted 9 lines

"in" meaning that userspace sets it to the ID of the plane it wants information on.

"out" field is a field written by the kernel as a response.

I'm not sure if the kernel has a habit of documenting these, because we use libdrm to abstract this so users do not need to care, but I think it would be nice.

In a quick look, I couldn't find anything. But I can change the phrasing to the following:

"@plane_id: Object ID of the plane whose information should be retrieved. IN field, set by userspace."

Quoted 7 lines
Quoted 7 lines
include/uapi/drm/drm_mode.h +2 -0
 	__u32 plane_id;
 
+	/** @crtc_id: Object ID of the current CRTC. */
 	__u32 crtc_id;
+	/** @fb_id: Object ID of the current fb. */
 	__u32 fb_id;
 
Quoted 10 lines

include/uapi/drm/drm_mode.h struct drm_mode_set_plane { · line 335

Quoted 6 lines
include/uapi/drm/drm_mode.h +6 -0
+	/**
+	 * @possible_crtcs: Bitmask of CRTC's compatible with the plane. CRTC's
+	 * are created and they receive an index, which corresponds to their
+	 * position in the bitmask. CRTC with index 0 will be in bit 0, and so
+	 * on. To learn how to find out the index of a certain CRTC, please see
+	 * :ref:`crtc_index`.

This could be shortened to something like bit N corresponds to CRTC index N, and make "CRTC index N" a hyperlink.

Nice, I'll apply this change.

Quoted 24 lines

include/uapi/drm/drm_mode.h struct drm_mode_set_plane { · line 347

Quoted 12 lines
include/uapi/drm/drm_mode.h +7 -0
+	 */
 	__u32 possible_crtcs;
+	/** @gamma_size: Number of entries of the legacy gamma lookup table. */
 	__u32 gamma_size;
 
+	/** @count_format_types: Number of formats. */
 	__u32 count_format_types;
+	/**
+	 * @format_type_ptr: Pointer to ``__u32`` array of formats that are
+	 * supported by the plane. These formats do not require modifiers.
+	 */
 	__u64 format_type_ptr;

The count/ptr fields have an interesting usage pattern, which I suppose is common for all DRM ioctls. Makes me wonder if it should be documented.

AFAIU, count is in+out field: when set to 0, the kernel uses it to return the count needed. Then userspace allocates space and calls the ioctl again with the right count and ptr set to point to the allocated array of count elements. This is so that kernel never allocates memory on behalf of userspace for the return data, making things much simpler at the cost of maybe needing to call the ioctl twice to first figure out long the array should be.

Quoted 6 lines

This can be seen in libdrm code for drmModeGetPlane().

There is certainly no point in explaining all that here, that is too much. But if there was a way to annotate the count member as in+out, that would be nice. And the ptr member as "in".

This is documented in the description of struct drm_mode_get_connector:

https://www.kernel.org/doc/html/latest/gpu/drm-uapi.html#c.drm_mode_get_connector

Would be enough to have something similar in struct drm_mode_get_plane?

Quoted 14 lines

Thanks,
pq

Quoted 9 lines
include/uapi/drm/drm_mode.h +0 -1
 };
 
--

2.31.1

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

#9 lore raw

Re: [PATCH 2/2] drm/doc: document drm_mode_get_plane

Quoted 46 lines · On Wed, 19 May 2021 10:30:40 -0300 Leandro Ribeiro…
Quoted 35 lines · Pekka Paalanen
Quoted 4 lines · On Wed, 28 Apr 2021 18:36:51 -0300 Leandro Ribeiro…

Add a small description and document struct fields of drm_mode_get_plane.

Hi,

thanks a lot for revising these.

Quoted 10 lines
---
 include/uapi/drm/drm_mode.h | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)
include/uapi/drm/drm_mode.h +0 -0
index a5e76aa06ad5..8fa6495cd948 100644
@@ -312,16 +312,38 @@ struct drm_mode_set_plane {
 	__u32 src_w;

include/uapi/drm/drm_mode.h struct drm_mode_set_plane { · line 322

Quoted 10 lines
include/uapi/drm/drm_mode.h +7 -0
 };
 
+/**
+ * struct drm_mode_get_plane - Get plane metadata.
+ *
+ * Userspace can perform a GETPLANE ioctl to retrieve information about a
+ * plane.
+ */
 struct drm_mode_get_plane {
+	/** @plane_id: Object ID of the plane. */  

This is an "in" field, right?

Quoted 9 lines

"in" meaning that userspace sets it to the ID of the plane it wants information on.

"out" field is a field written by the kernel as a response.

I'm not sure if the kernel has a habit of documenting these, because we use libdrm to abstract this so users do not need to care, but I think it would be nice.

Quoted 5 lines

In a quick look, I couldn't find anything. But I can change the phrasing to the following:

"@plane_id: Object ID of the plane whose information should be retrieved. IN field, set by userspace."

I think "set by userspace" or "set by caller" would be enough.

Quoted 51 lines
Quoted 7 lines
Quoted 7 lines
include/uapi/drm/drm_mode.h +2 -0
 	__u32 plane_id;
 
+	/** @crtc_id: Object ID of the current CRTC. */
 	__u32 crtc_id;
+	/** @fb_id: Object ID of the current fb. */
 	__u32 fb_id;
 
Quoted 10 lines

include/uapi/drm/drm_mode.h struct drm_mode_set_plane { · line 335

Quoted 6 lines
include/uapi/drm/drm_mode.h +6 -0
+	/**
+	 * @possible_crtcs: Bitmask of CRTC's compatible with the plane. CRTC's
+	 * are created and they receive an index, which corresponds to their
+	 * position in the bitmask. CRTC with index 0 will be in bit 0, and so
+	 * on. To learn how to find out the index of a certain CRTC, please see
+	 * :ref:`crtc_index`.  

This could be shortened to something like bit N corresponds to CRTC index N, and make "CRTC index N" a hyperlink.

Nice, I'll apply this change.

Quoted 24 lines

include/uapi/drm/drm_mode.h struct drm_mode_set_plane { · line 347

Quoted 12 lines
include/uapi/drm/drm_mode.h +7 -0
+	 */
 	__u32 possible_crtcs;
+	/** @gamma_size: Number of entries of the legacy gamma lookup table. */
 	__u32 gamma_size;
 
+	/** @count_format_types: Number of formats. */
 	__u32 count_format_types;
+	/**
+	 * @format_type_ptr: Pointer to ``__u32`` array of formats that are
+	 * supported by the plane. These formats do not require modifiers.
+	 */
 	__u64 format_type_ptr;  

The count/ptr fields have an interesting usage pattern, which I suppose is common for all DRM ioctls. Makes me wonder if it should be documented.

AFAIU, count is in+out field: when set to 0, the kernel uses it to return the count needed. Then userspace allocates space and calls the ioctl again with the right count and ptr set to point to the allocated array of count elements. This is so that kernel never allocates memory on behalf of userspace for the return data, making things much simpler at the cost of maybe needing to call the ioctl twice to first figure out long the array should be.

Quoted 6 lines

This can be seen in libdrm code for drmModeGetPlane().

There is certainly no point in explaining all that here, that is too much. But if there was a way to annotate the count member as in+out, that would be nice. And the ptr member as "in".

Quoted 5 lines

This is documented in the description of struct drm_mode_get_connector:

https://www.kernel.org/doc/html/latest/gpu/drm-uapi.html#c.drm_mode_get_connector

Would be enough to have something similar in struct drm_mode_get_plane?

That would be really nice!

Thanks,
pq