From da6c05969785a0f4108a089ef33c55f46ae21775 Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Thu, 14 Dec 2017 21:30:53 +0100 Subject: drm/atomic: document how to handle driver private objects MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit DK put some nice docs into the commit introducing driver private state, but in the git history alone it'll be lost. Also, since Ville remove the void* usage it's a good opportunity to give the driver private stuff some tlc on the doc front. Finally try to explain why the "let's just subclass drm_atomic_state" approach wasn't the greatest, and annotate all those functions as deprecated in favour of more standardized driver private states. Also note where we could/should extend driver private states going forward (atm neither locking nor synchronization is handled in core/helpers, which isn't really all that great). v2: Spelling and phrasing improvements (Alex, DK). Cc: Harry Wentland Cc: Dhinakaran Pandiyan Cc: Maarten Lankhorst Cc: Ville Syrjälä Cc: Laurent Pinchart Cc: Rob Clark Cc: Alex Deucher Cc: Ben Skeggs Reviewed-by: Dhinakaran Pandiyan Reviewed-by: Alex Deucher Signed-off-by: Daniel Vetter Link: https://patchwork.freedesktop.org/patch/msgid/20171214203054.20141-5-daniel.vetter@ffwll.ch --- Documentation/gpu/drm-kms.rst | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'Documentation') diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst index 307284125d7a..420025bd6a9b 100644 --- a/Documentation/gpu/drm-kms.rst +++ b/Documentation/gpu/drm-kms.rst @@ -271,6 +271,12 @@ Taken all together there's two consequences for the atomic design: Read on in this chapter, and also in :ref:`drm_atomic_helper` for more detailed coverage of specific topics. +Handling Driver Private State +----------------------------- + +.. kernel-doc:: drivers/gpu/drm/drm_atomic.c + :doc: handling driver private state + Atomic Mode Setting Function Reference -------------------------------------- -- cgit v1.2.3 From 5fca5ece6af8dd507c0459262766369e057e6d60 Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Thu, 14 Dec 2017 21:30:54 +0100 Subject: drm/doc: Move legacy kms helpers to the very end We don't want people to accidentally stumble over there. Also rename the plane helpers to legacy plane helpers. After Ville's patch to make the clipping helper atomic and move it to drm_atomic_helper.c there's nothing left in there that should be useful for modern drivers. v2: Laurent had a few questions around how state is added to drm_atomic_state, tried to clarify that. And spotted another sentence where the docs suggested subclassing. v3: Small polish (Alex). Reviewed-by: Alex Deucher Signed-off-by: Daniel Vetter Link: https://patchwork.freedesktop.org/patch/msgid/20171214203054.20141-6-daniel.vetter@ffwll.ch --- Documentation/gpu/drm-kms-helpers.rst | 36 +++++++++++++++++------------------ Documentation/gpu/drm-kms.rst | 8 ++++---- 2 files changed, 22 insertions(+), 22 deletions(-) (limited to 'Documentation') diff --git a/Documentation/gpu/drm-kms-helpers.rst b/Documentation/gpu/drm-kms-helpers.rst index 3ea622876b67..e37557b30f62 100644 --- a/Documentation/gpu/drm-kms-helpers.rst +++ b/Documentation/gpu/drm-kms-helpers.rst @@ -74,15 +74,6 @@ Helper Functions Reference .. kernel-doc:: drivers/gpu/drm/drm_atomic_helper.c :export: -Legacy CRTC/Modeset Helper Functions Reference -============================================== - -.. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c - :doc: overview - -.. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c - :export: - Simple KMS Helper Reference =========================== @@ -282,15 +273,6 @@ Flip-work Helper Reference .. kernel-doc:: drivers/gpu/drm/drm_flip_work.c :export: -Plane Helper Reference -====================== - -.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c - :doc: overview - -.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c - :export: - Auxiliary Modeset Helpers ========================= @@ -308,3 +290,21 @@ Framebuffer GEM Helper Reference .. kernel-doc:: drivers/gpu/drm/drm_gem_framebuffer_helper.c :export: + +Legacy Plane Helper Reference +============================= + +.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c + :doc: overview + +.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c + :export: + +Legacy CRTC/Modeset Helper Functions Reference +============================================== + +.. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c + :doc: overview + +.. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c + :export: diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst index 420025bd6a9b..2dcf5b42015d 100644 --- a/Documentation/gpu/drm-kms.rst +++ b/Documentation/gpu/drm-kms.rst @@ -263,10 +263,10 @@ Taken all together there's two consequences for the atomic design: - An atomic update is assembled and validated as an entirely free-standing pile of structures within the :c:type:`drm_atomic_state ` - container. Again drivers can subclass that container for their own state - structure tracking needs. Only when a state is committed is it applied to the - driver and modeset objects. This way rolling back an update boils down to - releasing memory and unreferencing objects like framebuffers. + container. Driver private state structures are also tracked in the same + structure; see the next chapter. Only when a state is committed is it applied + to the driver and modeset objects. This way rolling back an update boils down + to releasing memory and unreferencing objects like framebuffers. Read on in this chapter, and also in :ref:`drm_atomic_helper` for more detailed coverage of specific topics. -- cgit v1.2.3 From ee05baa0bfe634f747b51c44e1f9355c5ff2e64e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Noralf=20Tr=C3=B8nnes?= Date: Fri, 15 Dec 2017 18:51:15 +0100 Subject: drm/docs: Add todo entry for drm_fb_helper_fbdev_setup() MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add entry for conversion of drivers to new helpers. Signed-off-by: Noralf Trønnes Reviewed-by: Daniel Vetter Link: https://patchwork.freedesktop.org/patch/msgid/20171215175119.36181-4-noralf@tronnes.org --- Documentation/gpu/todo.rst | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) (limited to 'Documentation') diff --git a/Documentation/gpu/todo.rst b/Documentation/gpu/todo.rst index f421a54527d2..1e593370f64f 100644 --- a/Documentation/gpu/todo.rst +++ b/Documentation/gpu/todo.rst @@ -194,6 +194,24 @@ drm_mode_config_helper_suspend/resume(). Contact: Maintainer of the driver you plan to convert +Convert drivers to use drm_fb_helper_fbdev_setup/teardown() +----------------------------------------------------------- + +Most drivers can use drm_fb_helper_fbdev_setup() except maybe: + +- amdgpu which has special logic to decide whether to call + drm_helper_disable_unused_functions() + +- armada which isn't atomic and doesn't call + drm_helper_disable_unused_functions() + +- i915 which calls drm_fb_helper_initial_config() in a worker + +Drivers that use drm_framebuffer_remove() to clean up the fbdev framebuffer can +probably use drm_fb_helper_fbdev_teardown(). + +Contact: Maintainer of the driver you plan to convert + Core refactorings ================= -- cgit v1.2.3