* [PATCH v2] drm: document drm_mode_get_connector
@ 2020-11-19 13:52 Simon Ser
2020-11-19 15:06 ` Daniel Vetter
0 siblings, 1 reply; 4+ messages in thread
From: Simon Ser @ 2020-11-19 13:52 UTC (permalink / raw)
To: dri-devel
Document how to perform a GETCONNECTOR ioctl. Document the various
struct fields. Also document how to perform a forced probe, and when
should user-space do it.
Signed-off-by: Simon Ser <contact@emersion.fr>
Cc: Daniel Vetter <daniel@ffwll.ch>
Cc: Pekka Paalanen <ppaalanen@gmail.com>
---
include/uapi/drm/drm_mode.h | 76 ++++++++++++++++++++++++++++++++++---
1 file changed, 71 insertions(+), 5 deletions(-)
diff --git a/include/uapi/drm/drm_mode.h b/include/uapi/drm/drm_mode.h
index 5ad10ab2a577..cd97c5671c75 100644
--- a/include/uapi/drm/drm_mode.h
+++ b/include/uapi/drm/drm_mode.h
@@ -368,27 +368,93 @@ enum drm_mode_subconnector {
#define DRM_MODE_CONNECTOR_WRITEBACK 18
#define DRM_MODE_CONNECTOR_SPI 19
+/**
+ * struct drm_mode_get_connector - Get connector metadata.
+ *
+ * User-space can perform a GETCONNECTOR ioctl to retrieve information about a
+ * connector. User-space is expected to retrieve encoders, modes and properties
+ * by performing this ioctl at least twice: the first time to retrieve the
+ * number of elements, the second time to retrieve the elements themselves.
+ *
+ * To retrieve the number of elements, set @count_props and @count_encoders to
+ * zero, set @count_modes to 1, and set @modes_ptr to a temporary struct
+ * drm_mode_modeinfo element.
+ *
+ * To retrieve the elements, allocate arrays for @encoders_ptr, @modes_ptr,
+ * @props_ptr and @prop_values_ptr, then set @count_modes, @count_props and
+ * @count_encoders to their capacity.
+ *
+ * Performing the ioctl only twice may be racy: the number of elements may have
+ * changed with a hotplug event in-between the two ioctls. User-space is
+ * expected to retry the last ioctl until the number of elements stabilizes.
+ * The kernel won't fill any array which doesn't have the expected length.
+ *
+ * **Force-probing a connector**
+ *
+ * If the @count_modes field is set to zero, the kernel will perform a forced
+ * probe on the connector to refresh the connector status, modes and EDID.
+ * A forced-probe can be slow and the ioctl will block.
+ *
+ * User-space shouldn't need to force-probe connectors in general: the kernel
+ * will automatically take care of probing connectors that don't support
+ * hot-plug detection when appropriate. However, user-space may force-probe
+ * connectors on user request (e.g. clicking a "Scan connectors" button, or
+ * opening a UI to manage screens).
+ */
struct drm_mode_get_connector {
-
+ /** @encoders_ptr: Pointer to ``__u32`` array of object IDs. */
__u64 encoders_ptr;
+ /** @modes_ptr: Pointer to struct drm_mode_modeinfo array. */
__u64 modes_ptr;
+ /** @props_ptr: Pointer to ``__u32`` array of property IDs. */
__u64 props_ptr;
+ /** @prop_values_ptr: Pointer to ``__u64`` array of property values. */
__u64 prop_values_ptr;
+ /** @count_modes: Number of modes. */
__u32 count_modes;
+ /** @count_props: Number of properties. */
__u32 count_props;
+ /** @count_encoders: Number of encoders. */
__u32 count_encoders;
- __u32 encoder_id; /**< Current Encoder */
- __u32 connector_id; /**< Id */
+ /** @encoder_id: Object ID of the current encoder. */
+ __u32 encoder_id;
+ /** @connector_id: Object ID of the connector. */
+ __u32 connector_id;
+ /**
+ * @connector_type: Type of the connector.
+ *
+ * See DRM_MODE_CONNECTOR_* defines.
+ */
__u32 connector_type;
+ /**
+ * @connector_type_id: Type-specific connector number.
+ *
+ * This is not an object ID. This is a per-type connector number. Each
+ * (type, type_id) combination is unique across all connectors of a DRM
+ * device.
+ */
__u32 connector_type_id;
+ /**
+ * @connection: Status of the connector.
+ *
+ * See enum drm_connector_status.
+ */
__u32 connection;
- __u32 mm_width; /**< width in millimeters */
- __u32 mm_height; /**< height in millimeters */
+ /** @mm_width: Width of the connected sink in millimeters. */
+ __u32 mm_width;
+ /** @mm_height: Height of the connected sink in millimeters. */
+ __u32 mm_height;
+ /**
+ * @subpixel: Subpixel order of the connected sink.
+ *
+ * See enum subpixel_order.
+ */
__u32 subpixel;
+ /** @pad: Padding. */
__u32 pad;
};
--
2.29.2
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel
^ permalink raw reply related [flat|nested] 4+ messages in thread
* Re: [PATCH v2] drm: document drm_mode_get_connector
2020-11-19 13:52 [PATCH v2] drm: document drm_mode_get_connector Simon Ser
@ 2020-11-19 15:06 ` Daniel Vetter
2020-11-20 8:46 ` Simon Ser
0 siblings, 1 reply; 4+ messages in thread
From: Daniel Vetter @ 2020-11-19 15:06 UTC (permalink / raw)
To: Simon Ser; +Cc: dri-devel
On Thu, Nov 19, 2020 at 2:52 PM Simon Ser <contact@emersion.fr> wrote:
>
> Document how to perform a GETCONNECTOR ioctl. Document the various
> struct fields. Also document how to perform a forced probe, and when
> should user-space do it.
>
> Signed-off-by: Simon Ser <contact@emersion.fr>
> Cc: Daniel Vetter <daniel@ffwll.ch>
> Cc: Pekka Paalanen <ppaalanen@gmail.com>
> ---
> include/uapi/drm/drm_mode.h | 76 ++++++++++++++++++++++++++++++++++---
> 1 file changed, 71 insertions(+), 5 deletions(-)
>
> diff --git a/include/uapi/drm/drm_mode.h b/include/uapi/drm/drm_mode.h
> index 5ad10ab2a577..cd97c5671c75 100644
> --- a/include/uapi/drm/drm_mode.h
> +++ b/include/uapi/drm/drm_mode.h
> @@ -368,27 +368,93 @@ enum drm_mode_subconnector {
> #define DRM_MODE_CONNECTOR_WRITEBACK 18
> #define DRM_MODE_CONNECTOR_SPI 19
>
> +/**
> + * struct drm_mode_get_connector - Get connector metadata.
> + *
> + * User-space can perform a GETCONNECTOR ioctl to retrieve information about a
> + * connector. User-space is expected to retrieve encoders, modes and properties
> + * by performing this ioctl at least twice: the first time to retrieve the
> + * number of elements, the second time to retrieve the elements themselves.
> + *
> + * To retrieve the number of elements, set @count_props and @count_encoders to
> + * zero, set @count_modes to 1, and set @modes_ptr to a temporary struct
> + * drm_mode_modeinfo element.
> + *
> + * To retrieve the elements, allocate arrays for @encoders_ptr, @modes_ptr,
> + * @props_ptr and @prop_values_ptr, then set @count_modes, @count_props and
> + * @count_encoders to their capacity.
> + *
> + * Performing the ioctl only twice may be racy: the number of elements may have
> + * changed with a hotplug event in-between the two ioctls. User-space is
> + * expected to retry the last ioctl until the number of elements stabilizes.
> + * The kernel won't fill any array which doesn't have the expected length.
> + *
> + * **Force-probing a connector**
> + *
> + * If the @count_modes field is set to zero, the kernel will perform a forced
> + * probe on the connector to refresh the connector status, modes and EDID.
> + * A forced-probe can be slow and the ioctl will block.
> + *
> + * User-space shouldn't need to force-probe connectors in general: the kernel
> + * will automatically take care of probing connectors that don't support
> + * hot-plug detection when appropriate. However, user-space may force-probe
> + * connectors on user request (e.g. clicking a "Scan connectors" button, or
> + * opening a UI to manage screens).
I think we should warn here that force probe can disrupt the UI, hence
why it should only be done on user request and not automatically.
> + */
> struct drm_mode_get_connector {
> -
> + /** @encoders_ptr: Pointer to ``__u32`` array of object IDs. */
> __u64 encoders_ptr;
> + /** @modes_ptr: Pointer to struct drm_mode_modeinfo array. */
> __u64 modes_ptr;
> + /** @props_ptr: Pointer to ``__u32`` array of property IDs. */
> __u64 props_ptr;
> + /** @prop_values_ptr: Pointer to ``__u64`` array of property values. */
> __u64 prop_values_ptr;
>
> + /** @count_modes: Number of modes. */
> __u32 count_modes;
> + /** @count_props: Number of properties. */
> __u32 count_props;
> + /** @count_encoders: Number of encoders. */
> __u32 count_encoders;
>
> - __u32 encoder_id; /**< Current Encoder */
> - __u32 connector_id; /**< Id */
> + /** @encoder_id: Object ID of the current encoder. */
> + __u32 encoder_id;
> + /** @connector_id: Object ID of the connector. */
> + __u32 connector_id;
> + /**
> + * @connector_type: Type of the connector.
> + *
> + * See DRM_MODE_CONNECTOR_* defines.
> + */
> __u32 connector_type;
> + /**
> + * @connector_type_id: Type-specific connector number.
> + *
> + * This is not an object ID. This is a per-type connector number. Each
> + * (type, type_id) combination is unique across all connectors of a DRM
> + * device.
> + */
> __u32 connector_type_id;
>
> + /**
> + * @connection: Status of the connector.
> + *
> + * See enum drm_connector_status.
Please add & so it becomes a link in the generated docs (and pls check
the link goes to the right place).
> + */
> __u32 connection;
> - __u32 mm_width; /**< width in millimeters */
> - __u32 mm_height; /**< height in millimeters */
> + /** @mm_width: Width of the connected sink in millimeters. */
> + __u32 mm_width;
> + /** @mm_height: Height of the connected sink in millimeters. */
> + __u32 mm_height;
> + /**
> + * @subpixel: Subpixel order of the connected sink.
> + *
> + * See enum subpixel_order.
Same here.
> + */
> __u32 subpixel;
>
> + /** @pad: Padding. */
I think this should have a "Must be zero"?
With the nits addressed: Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Thanks a lot for doing this!
> __u32 pad;
> };
>
> --
> 2.29.2
>
>
--
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [PATCH v2] drm: document drm_mode_get_connector
2020-11-19 15:06 ` Daniel Vetter
@ 2020-11-20 8:46 ` Simon Ser
2020-11-20 9:19 ` Daniel Vetter
0 siblings, 1 reply; 4+ messages in thread
From: Simon Ser @ 2020-11-20 8:46 UTC (permalink / raw)
To: Daniel Vetter; +Cc: dri-devel
On Thursday, November 19, 2020 4:06 PM, Daniel Vetter <daniel@ffwll.ch> wrote:
> > + /**
> > + * @connection: Status of the connector.
> > + *
> > + * See enum drm_connector_status.
>
> Please add & so it becomes a link in the generated docs (and pls check
> the link goes to the right place).
Per [1], just prefixing the enum name with "enum" is enough to generate a link.
I prefer this style over the ampersand because it makes the raw text easier to
read. The result looks like this [2].
[1]: https://dri.freedesktop.org/docs/drm/doc-guide/kernel-doc.html#cross-referencing-from-restructuredtext
[2]: https://l.sr.ht/o7Kb.png
> > + */
> > __u32 connection;
> > - __u32 mm_width; /**< width in millimeters */
> > - __u32 mm_height; /**< height in millimeters */
> > + /** @mm_width: Width of the connected sink in millimeters. */
> > + __u32 mm_width;
> > + /** @mm_height: Height of the connected sink in millimeters. */
> > + __u32 mm_height;
> > + /**
> > + * @subpixel: Subpixel order of the connected sink.
> > + *
> > + * See enum subpixel_order.
>
> Same here.
This one doesn't generate a link, because enum subpixel_order is undocumented.
As soon as it's documented, the link will be created.
The enum is weird in the first place: it has CamelCase members and no drm_
prefix.
> With the nits addressed: Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch>
I'll fix the other issues you've raised, thanks for the review!
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [PATCH v2] drm: document drm_mode_get_connector
2020-11-20 8:46 ` Simon Ser
@ 2020-11-20 9:19 ` Daniel Vetter
0 siblings, 0 replies; 4+ messages in thread
From: Daniel Vetter @ 2020-11-20 9:19 UTC (permalink / raw)
To: Simon Ser; +Cc: dri-devel
On Fri, Nov 20, 2020 at 9:46 AM Simon Ser <contact@emersion.fr> wrote:
>
> On Thursday, November 19, 2020 4:06 PM, Daniel Vetter <daniel@ffwll.ch> wrote:
>
> > > + /**
> > > + * @connection: Status of the connector.
> > > + *
> > > + * See enum drm_connector_status.
> >
> > Please add & so it becomes a link in the generated docs (and pls check
> > the link goes to the right place).
>
> Per [1], just prefixing the enum name with "enum" is enough to generate a link.
> I prefer this style over the ampersand because it makes the raw text easier to
> read. The result looks like this [2].
>
> [1]: https://dri.freedesktop.org/docs/drm/doc-guide/kernel-doc.html#cross-referencing-from-restructuredtext
> [2]: https://l.sr.ht/o7Kb.png
Ah nice, I missed that this was updated. We have a ton of & in our
kerneldoc that probably could be dropped ...
-Daniel
>
> > > + */
> > > __u32 connection;
> > > - __u32 mm_width; /**< width in millimeters */
> > > - __u32 mm_height; /**< height in millimeters */
> > > + /** @mm_width: Width of the connected sink in millimeters. */
> > > + __u32 mm_width;
> > > + /** @mm_height: Height of the connected sink in millimeters. */
> > > + __u32 mm_height;
> > > + /**
> > > + * @subpixel: Subpixel order of the connected sink.
> > > + *
> > > + * See enum subpixel_order.
> >
> > Same here.
>
> This one doesn't generate a link, because enum subpixel_order is undocumented.
> As soon as it's documented, the link will be created.
>
> The enum is weird in the first place: it has CamelCase members and no drm_
> prefix.
>
> > With the nits addressed: Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch>
>
> I'll fix the other issues you've raised, thanks for the review!
--
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel
^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2020-11-20 9:19 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-11-19 13:52 [PATCH v2] drm: document drm_mode_get_connector Simon Ser
2020-11-19 15:06 ` Daniel Vetter
2020-11-20 8:46 ` Simon Ser
2020-11-20 9:19 ` Daniel Vetter
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.