* [PATCH] drm: document drm_mode_get_connector
@ 2020-11-18 10:52 Simon Ser
2020-11-18 15:03 ` Daniel Vetter
2020-11-19 9:20 ` Pekka Paalanen
0 siblings, 2 replies; 5+ messages in thread
From: Simon Ser @ 2020-11-18 10:52 UTC (permalink / raw)
To: dri-devel
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 | 13 +++++++++++++
1 file changed, 13 insertions(+)
diff --git a/include/uapi/drm/drm_mode.h b/include/uapi/drm/drm_mode.h
index 5ad10ab2a577..09647b799f39 100644
--- a/include/uapi/drm/drm_mode.h
+++ b/include/uapi/drm/drm_mode.h
@@ -368,6 +368,19 @@ enum drm_mode_subconnector {
#define DRM_MODE_CONNECTOR_WRITEBACK 18
#define DRM_MODE_CONNECTOR_SPI 19
+/**
+ * struct drm_mode_get_connector - get connector metadata
+ *
+ * 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 {
__u64 encoders_ptr;
--
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] 5+ messages in thread
* Re: [PATCH] drm: document drm_mode_get_connector
2020-11-18 10:52 [PATCH] drm: document drm_mode_get_connector Simon Ser
@ 2020-11-18 15:03 ` Daniel Vetter
2020-11-18 15:09 ` Simon Ser
2020-11-19 9:20 ` Pekka Paalanen
1 sibling, 1 reply; 5+ messages in thread
From: Daniel Vetter @ 2020-11-18 15:03 UTC (permalink / raw)
To: Simon Ser; +Cc: dri-devel
On Wed, Nov 18, 2020 at 11:52 AM Simon Ser <contact@emersion.fr> wrote:
>
> 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 | 13 +++++++++++++
> 1 file changed, 13 insertions(+)
>
> diff --git a/include/uapi/drm/drm_mode.h b/include/uapi/drm/drm_mode.h
> index 5ad10ab2a577..09647b799f39 100644
> --- a/include/uapi/drm/drm_mode.h
> +++ b/include/uapi/drm/drm_mode.h
> @@ -368,6 +368,19 @@ enum drm_mode_subconnector {
> #define DRM_MODE_CONNECTOR_WRITEBACK 18
> #define DRM_MODE_CONNECTOR_SPI 19
>
> +/**
> + * struct drm_mode_get_connector - get connector metadata
> + *
> + * 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 this causes warnings, because now we have kerneldoc for this,
but not for all the members. Also the member-specific stuff should be
documented as inline comment, see
https://dri.freedesktop.org/docs/drm/doc-guide/kernel-doc.html#in-line-member-documentation-comments
I also noticed that this file has a ton of wrong kerneldoc comments,
but they seem to not cause warnings (anything starting with /** is
fishy).
Can I volunteer you for a bit more here?
Thanks, Daniel
> struct drm_mode_get_connector {
>
> __u64 encoders_ptr;
> --
> 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] 5+ messages in thread
* Re: [PATCH] drm: document drm_mode_get_connector
2020-11-18 15:03 ` Daniel Vetter
@ 2020-11-18 15:09 ` Simon Ser
2020-11-18 15:19 ` Daniel Vetter
0 siblings, 1 reply; 5+ messages in thread
From: Simon Ser @ 2020-11-18 15:09 UTC (permalink / raw)
To: Daniel Vetter; +Cc: dri-devel
On Wednesday, November 18, 2020 4:03 PM, Daniel Vetter <daniel@ffwll.ch> wrote:
> I think this causes warnings, because now we have kerneldoc for this,
> but not for all the members. Also the member-specific stuff should be
> documented as inline comment, see
>
> https://dri.freedesktop.org/docs/drm/doc-guide/kernel-doc.html#in-line-member-documentation-comments
Hm, right, will make sure the patch doesn't trigger warnings.
I still think the force-probe stuff shouldn't be documented in in-line
comments, because I'd never look at the in-line count_modes comment to know
whether the ioctl probes or not. Adding short in-line comments sounds fine
though.
> I also noticed that this file has a ton of wrong kerneldoc comments,
> but they seem to not cause warnings (anything starting with /** is
> fishy).
>
> Can I volunteer you for a bit more here?
Yeah, I've noticed this as well. Will have a look!
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH] drm: document drm_mode_get_connector
2020-11-18 15:09 ` Simon Ser
@ 2020-11-18 15:19 ` Daniel Vetter
0 siblings, 0 replies; 5+ messages in thread
From: Daniel Vetter @ 2020-11-18 15:19 UTC (permalink / raw)
To: Simon Ser; +Cc: dri-devel
On Wed, Nov 18, 2020 at 4:09 PM Simon Ser <contact@emersion.fr> wrote:
>
> On Wednesday, November 18, 2020 4:03 PM, Daniel Vetter <daniel@ffwll.ch> wrote:
>
> > I think this causes warnings, because now we have kerneldoc for this,
> > but not for all the members. Also the member-specific stuff should be
> > documented as inline comment, see
> >
> > https://dri.freedesktop.org/docs/drm/doc-guide/kernel-doc.html#in-line-member-documentation-comments
>
> Hm, right, will make sure the patch doesn't trigger warnings.
>
> I still think the force-probe stuff shouldn't be documented in in-line
> comments, because I'd never look at the in-line count_modes comment to know
> whether the ioctl probes or not. Adding short in-line comments sounds fine
> though.
Hm yeah, maybe give it a sub-title then like "Probe Modes" with the
two options. I think the detail that a small array/count (either 0 or
1 depending whether you want force probing) should be documented in
the inline comment though.
I think the inline comment for connection should also link to the
drm_connector_status enum. Maybe also have that link in the "Probe
Modes" section with an explanation that a forced probe can get rid of
some the unknown ones.
I also kinda wonder where we should up recommendations for autoconfiguration.
>
> > I also noticed that this file has a ton of wrong kerneldoc comments,
> > but they seem to not cause warnings (anything starting with /** is
> > fishy).
> >
> > Can I volunteer you for a bit more here?
>
> Yeah, I've noticed this as well. Will have a look!
Thanks!
-Daniel
--
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] 5+ messages in thread
* Re: [PATCH] drm: document drm_mode_get_connector
2020-11-18 10:52 [PATCH] drm: document drm_mode_get_connector Simon Ser
2020-11-18 15:03 ` Daniel Vetter
@ 2020-11-19 9:20 ` Pekka Paalanen
1 sibling, 0 replies; 5+ messages in thread
From: Pekka Paalanen @ 2020-11-19 9:20 UTC (permalink / raw)
To: Simon Ser; +Cc: dri-devel
[-- Attachment #1.1: Type: text/plain, Size: 1850 bytes --]
On Wed, 18 Nov 2020 10:52:12 +0000
Simon Ser <contact@emersion.fr> wrote:
> 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 | 13 +++++++++++++
> 1 file changed, 13 insertions(+)
>
> diff --git a/include/uapi/drm/drm_mode.h b/include/uapi/drm/drm_mode.h
> index 5ad10ab2a577..09647b799f39 100644
> --- a/include/uapi/drm/drm_mode.h
> +++ b/include/uapi/drm/drm_mode.h
> @@ -368,6 +368,19 @@ enum drm_mode_subconnector {
> #define DRM_MODE_CONNECTOR_WRITEBACK 18
> #define DRM_MODE_CONNECTOR_SPI 19
>
> +/**
> + * struct drm_mode_get_connector - get connector metadata
> + *
> + * 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.
> + *
Hi,
as I have no prior knowledge at all about how struct
drm_mode_get_connector works, the above paragraph only confuses me.
count_modes sounds totally unrelated to probing, and what does that
even do in this struct at all, how does one use this thing. I only know
the libdrm API for this. So I can't ack this bit.
> + * 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).
This paragraph is good and clear to me.
> + */
> struct drm_mode_get_connector {
>
> __u64 encoders_ptr;
Thanks,
pq
[-- Attachment #1.2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
[-- Attachment #2: Type: text/plain, Size: 160 bytes --]
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel
^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2020-11-19 9:20 UTC | newest]
Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-11-18 10:52 [PATCH] drm: document drm_mode_get_connector Simon Ser
2020-11-18 15:03 ` Daniel Vetter
2020-11-18 15:09 ` Simon Ser
2020-11-18 15:19 ` Daniel Vetter
2020-11-19 9:20 ` Pekka Paalanen
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).