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 --- include/drm/drm_mode_config.h | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'include/drm/drm_mode_config.h') diff --git a/include/drm/drm_mode_config.h b/include/drm/drm_mode_config.h index a0afeb591dcb..e5f3b43014e1 100644 --- a/include/drm/drm_mode_config.h +++ b/include/drm/drm_mode_config.h @@ -268,6 +268,9 @@ struct drm_mode_config_funcs { * state easily. If this hook is implemented, drivers must also * implement @atomic_state_clear and @atomic_state_free. * + * Subclassing of &drm_atomic_state is deprecated in favour of using + * &drm_private_state and &drm_private_obj. + * * RETURNS: * * A new &drm_atomic_state on success or NULL on failure. @@ -289,6 +292,9 @@ struct drm_mode_config_funcs { * * Drivers that implement this must call drm_atomic_state_default_clear() * to clear common state. + * + * Subclassing of &drm_atomic_state is deprecated in favour of using + * &drm_private_state and &drm_private_obj. */ void (*atomic_state_clear)(struct drm_atomic_state *state); @@ -301,6 +307,9 @@ struct drm_mode_config_funcs { * * Drivers that implement this must call * drm_atomic_state_default_release() to release common resources. + * + * Subclassing of &drm_atomic_state is deprecated in favour of using + * &drm_private_state and &drm_private_obj. */ void (*atomic_state_free)(struct drm_atomic_state *state); }; -- cgit v1.2.3