Skip to contentSkip to conversation

drm: Atomic modesetting doc and comment improvements

PATCH Applied Geert Uytterhoeven 2 participants 7 messages Jul 19, 2023 – Jul 29, 2023

Subsystems (6)
lore
Share & tools
lore

Geert Uytterhoeven

author maintainer
#0 lore raw

v3 cover drm: Atomic modesetting doc and comment improvements

Hi all,

This patch series contains various improvements to the documentation and comments related to atomic modesetting. Hopefully, it will ease the job of DRM novice who want to tackle the daunting task of converting a legacy DRM driver to atomic modesetting.

Changes compared to v2[1]:
- Make main text read correctly when ignoring the footnotes,
- Add Reviewed-by.

Changes compared to v1[2]:
- Add Reviewed-by,
- Drop double space after full stop,
- Use footnotes for references,
- Remore reference to unconverted virtual HW drivers,
- New patch [2/4],
- Drop "first part" in drivers/gpu/drm/drm_plane_helper.c.

Thanks for applying!

[1] https://lore.kernel.org/r/[email protected]
[2] https://lore.kernel.org/r/[email protected]

Geert Uytterhoeven (4):
drm/todo: Add atomic modesetting references drm/todo: Convert list of fbconv links to footnotes
drm: Remove references to removed transitional helpers
drm: Fix references to drm_plane_helper_check_state()

 Documentation/gpu/todo.rst                    | 22 +++++----
 drivers/gpu/drm/drm_plane_helper.c            | 12 +----
 .../gpu/drm/renesas/rcar-du/rcar_du_plane.c   |  3 +-
 drivers/gpu/drm/tidss/tidss_plane.c           |  3 +-
 include/drm/drm_crtc.h                        |  5 --
 include/drm/drm_modeset_helper_vtables.h      | 48 ++++++++-----------
 6 files changed, 40 insertions(+), 53 deletions(-)
Signature · 12 lines
2.34.1

Gr{oetje,eeting}s,

						Geert

--
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- [email protected]

In personal conversations with technical people, I call myself a hacker. But
when I'm talking to journalists I just say "programmer" or something like that.
							    -- Linus Torvalds
author maintainer
#1 lore raw

PATCH v3 1/4 drm/todo: Add atomic modesetting references

The section about converting existing KMS drivers to atomic modesetting mentions the existence of a conversion guide, but does not reference it. While the guide is old and rusty, it still contains useful information, so add a link to it. Also link to the LWN.net articles that give an overview about the atomic mode setting design.

While at it, remove the reference to unconverted virtual HW drivers, as they've been converted.

---
v3:
- No changes,

v2:
- Add Reviewed-by,
- Drop double space after full stop,
- Use footnotes for references,
- Remore reference to unconverted virtual HW drivers.

---
 Documentation/gpu/todo.rst | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)
Documentation/gpu/todo.rst +7 -3
index b05b32c12975559b..b93059e384128904 100644
@@ -49,14 +49,18 @@ converted over. Modern compositors like Wayland or Surfaceflinger on Android
 really want an atomic modeset interface, so this is all about the bright
 future.
 
-There is a conversion guide for atomic and all you need is a GPU for a
-non-converted driver (again virtual HW drivers for KVM are still all
-suitable).
+There is a conversion guide for atomic [1]_ and all you need is a GPU for a
+non-converted driver.  The "Atomic mode setting design overview" series [2]_
+[3]_ at LWN.net can also be helpful.
 
 As part of this drivers also need to convert to universal plane (which means
 exposing primary & cursor as proper plane objects). But that's much easier to
 do by directly using the new atomic helper driver callbacks.
 
+  .. [1] https://blog.ffwll.ch/2014/11/atomic-modeset-support-for-kms-drivers.html
+  .. [2] https://lwn.net/Articles/653071/
+  .. [3] https://lwn.net/Articles/653466/
+
 Contact: Daniel Vetter, respective driver maintainers
 
 Level: Advanced
Signature · 1 line
2.34.1
author maintainer
#2 lore raw

PATCH v3 2/4 drm/todo: Convert list of fbconv links to footnotes

In reply to Geert Uytterhoeven

Convert the references to fbconv links to footnotes, so they can be navigated.

---
v3:
- Make main text read correctly when ignoring the footnotes,

v2:
- New.

---
 Documentation/gpu/todo.rst | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)
Documentation/gpu/todo.rst +6 -6
index b93059e384128904..f2a4f6f90c54eefe 100644
@@ -756,16 +756,16 @@ existing hardware. The new driver's call-back functions are filled from
 existing fbdev code.
 
 More complex fbdev drivers can be refactored step-by-step into a DRM
-driver with the help of the DRM fbconv helpers. [1] These helpers provide
+driver with the help of the DRM fbconv helpers [4]_. These helpers provide
 the transition layer between the DRM core infrastructure and the fbdev
 driver interface. Create a new DRM driver on top of the fbconv helpers,
 copy over the fbdev driver, and hook it up to the DRM code. Examples for
-several fbdev drivers are available at [1] and a tutorial of this process
-available at [2]. The result is a primitive DRM driver that can run X11
-and Weston.
+several fbdev drivers are available in Thomas Zimmermann's fbconv tree
+[4]_, as well as a tutorial of this process [5]_. The result is a primitive
+DRM driver that can run X11 and Weston.
 
- - [1] https://gitlab.freedesktop.org/tzimmermann/linux/tree/fbconv
- - [2] https://gitlab.freedesktop.org/tzimmermann/linux/blob/fbconv/drivers/gpu/drm/drm_fbconv_helper.c
+ .. [4] https://gitlab.freedesktop.org/tzimmermann/linux/tree/fbconv
+ .. [5] https://gitlab.freedesktop.org/tzimmermann/linux/blob/fbconv/drivers/gpu/drm/drm_fbconv_helper.c
 
 Contact: Thomas Zimmermann <[email protected]>
 
Signature · 1 line
2.34.1
Acked-by on v3 2/4
#3 lore raw

Re: [PATCH v3 2/4] drm/todo: Convert list of fbconv links to footnotes

Geert Uytterhoeven <[email protected]> writes:

Hello Geert,

Quoted 11 lines

Convert the references to fbconv links to footnotes, so they can be navigated.

---
v3:
- Make main text read correctly when ignoring the footnotes,

v2:
- New.
---

Signature · 5 lines
Best regards,

Javier Martinez Canillas
Core Platforms
Red Hat
author maintainer
#4 lore raw

PATCH v3 3/4 drm: Remove references to removed transitional helpers

In reply to Geert Uytterhoeven

The transitional helpers were removed a long time ago, but some references stuck. Remove them.

Fixes 21ebe615c16994f3 ("drm: Remove transitional helpers")

---
v3:
- Add Reviewed-by,

v2:
- Drop "first part" in drivers/gpu/drm/drm_plane_helper.c.

---
 drivers/gpu/drm/drm_plane_helper.c       | 12 +-----
 include/drm/drm_crtc.h                   |  5 ---
 include/drm/drm_modeset_helper_vtables.h | 48 +++++++++++-------------
 3 files changed, 23 insertions(+), 42 deletions(-)
drivers/gpu/drm/drm_plane_helper.c +2 -10
index c91e454eba097942..5e95089676ff81ed 100644
@@ -40,8 +40,8 @@
 /**
  * DOC: overview
  *
- * This helper library has two parts. The first part has support to implement
- * primary plane support on top of the normal CRTC configuration interface.
+ * This helper library contains helpers to implement primary plane support on
+ * top of the normal CRTC configuration interface.
  * Since the legacy &drm_mode_config_funcs.set_config interface ties the primary
  * plane together with the CRTC state this does not allow userspace to disable
  * the primary plane itself. The default primary plane only expose XRBG8888 and
@@ -51,14 +51,6 @@
  * planes, and newly merged drivers must not rely upon these transitional
  * helpers.
  *
- * The second part also implements transitional helpers which allow drivers to
- * gradually switch to the atomic helper infrastructure for plane updates. Once
- * that switch is complete drivers shouldn't use these any longer, instead using
- * the proper legacy implementations for update and disable plane hooks provided
- * by the atomic helpers.
- *
- * Again drivers are strongly urged to switch to the new interfaces.
- *
  * The plane helpers share the function table structures with other helpers,
  * specifically also the atomic helpers. See &struct drm_plane_helper_funcs for
  * the details.
include/drm/drm_crtc.h +0 -5
index 8e1cbc75143ef216..8b48a1974da3143c 100644
@@ -77,11 +77,6 @@ struct drm_plane_helper_funcs;
  * intended to indicate whether a full modeset is needed, rather than strictly
  * describing what has changed in a commit. See also:
  * drm_atomic_crtc_needs_modeset()
- *
- * WARNING: Transitional helpers (like drm_helper_crtc_mode_set() or
- * drm_helper_crtc_mode_set_base()) do not maintain many of the derived control
- * state like @plane_mask so drivers not converted over to atomic helpers should
- * not rely on these being accurate!
  */
 struct drm_crtc_state {
 	/** @crtc: backpointer to the CRTC */
include/drm/drm_modeset_helper_vtables.h +21 -27

120 lines not on this page · raw message

Signature · 1 line
2.34.1
author maintainer
#5 lore raw

PATCH v3 4/4 drm: Fix references to drm_plane_helper_check_state()

In reply to Geert Uytterhoeven

As of commit a01cb8ba3f628293 ("drm: Move drm_plane_helper_check_state() into drm_atomic_helper.c"), drm_plane_helper_check_state() no longer exists, but is part of drm_atomic_helper_check_plane_state().

---
v3:
- No changes,

v2:
- Add Reviewed-by.

---
 drivers/gpu/drm/renesas/rcar-du/rcar_du_plane.c | 3 ++-
 drivers/gpu/drm/tidss/tidss_plane.c             | 3 ++-
 2 files changed, 4 insertions(+), 2 deletions(-)
drivers/gpu/drm/renesas/rcar-du/rcar_du_plane.c +2 -1
index d759e019218181ce..e445fac8e0b46c21 100644
@@ -600,7 +600,8 @@ int __rcar_du_plane_atomic_check(struct drm_plane *plane,
 	if (!state->crtc) {
 		/*
 		 * The visible field is not reset by the DRM core but only
-		 * updated by drm_plane_helper_check_state(), set it manually.
+		 * updated by drm_atomic_helper_check_plane_state(), set it
+		 * manually.
 		 */
 		state->visible = false;
 		*format = NULL;
drivers/gpu/drm/tidss/tidss_plane.c +2 -1
index 6bdd6e4a955ab3cc..e1c0ef0c3894c855 100644
@@ -38,7 +38,8 @@ static int tidss_plane_atomic_check(struct drm_plane *plane,
 	if (!new_plane_state->crtc) {
 		/*
 		 * The visible field is not reset by the DRM core but only
-		 * updated by drm_plane_helper_check_state(), set it manually.
+		 * updated by drm_atomic_helper_check_plane_state(), set it
+		 * manually.
 		 */
 		new_plane_state->visible = false;
 		return 0;
Signature · 1 line
2.34.1
#6 lore raw
In reply to Geert Uytterhoeven

Geert Uytterhoeven <[email protected]> writes:

Hello Geert,

Quoted 21 lines

Hi all,

This patch series contains various improvements to the documentation and comments related to atomic modesetting. Hopefully, it will ease the job of DRM novice who want to tackle the daunting task of converting a legacy DRM driver to atomic modesetting.

Changes compared to v2[1]:
- Make main text read correctly when ignoring the footnotes,
- Add Reviewed-by.

Changes compared to v1[2]:
- Add Reviewed-by,
- Drop double space after full stop,
- Use footnotes for references,
- Remore reference to unconverted virtual HW drivers,
- New patch [2/4],
- Drop "first part" in drivers/gpu/drm/drm_plane_helper.c.

Thanks for applying!

Quoted 9 lines

[1] https://lore.kernel.org/r/[email protected]
[2] https://lore.kernel.org/r/[email protected]

Geert Uytterhoeven (4):
drm/todo: Add atomic modesetting references drm/todo: Convert list of fbconv links to footnotes
drm: Remove references to removed transitional helpers
drm: Fix references to drm_plane_helper_check_state()

Pushed to drm-misc (drm-misc-next). Thanks!

Signature · 5 lines
Best regards,

Javier Martinez Canillas
Core Platforms
Red Hat