drm/doc: Remove atomic_state_helper.h from drm-kms-helpers.rst
Subsystems (3)
PATCH 1/2 drm/doc: Remove atomic_state_helper.h from drm-kms-helpers.rst
From: Sean Paul <[email protected]>
There are no structured comments in the file, so it generates this warning on compilation:
include/drm/drm_atomic_state_helper.h:1: warning: no structured comments found
--- Documentation/gpu/drm-kms-helpers.rst | 3 --- 1 file changed, 3 deletions(-)
Documentation/gpu/drm-kms-helpers.rst +0 -3
@@ -77,9 +77,6 @@ Atomic State Reset and Initialization Atomic State Helper Reference ----------------------------- -.. kernel-doc:: include/drm/drm_atomic_state_helper.h - :internal: - .. kernel-doc:: drivers/gpu/drm/drm_atomic_state_helper.c :export:
Signature · 6 lines
Sean Paul, Software Engineer, Google / Chromium OS _______________________________________________ dri-devel mailing list [email protected] https://lists.freedesktop.org/mailman/listinfo/dri-devel
PATCH 2/2 drm/doc: Document the writeback prepare/cleanup jobs
From: Sean Paul <[email protected]>
These functions were missing documentation.
Fixes the warning:../include/drm/drm_modeset_helper_vtables.h:1000: warning: Function parameter or member 'prepare_writeback_job' not described in 'drm_connector_helper_funcs' ../include/drm/drm_modeset_helper_vtables.h:1000: warning: Function parameter or member 'cleanup_writeback_job' not described in 'drm_connector_helper_funcs'
--- drivers/gpu/drm/drm_writeback.c | 20 ++++++++++++++++++++ include/drm/drm_modeset_helper_vtables.h | 20 ++++++++++++++++++++ 2 files changed, 40 insertions(+)
drivers/gpu/drm/drm_writeback.c +20 -0
@@ -258,6 +258,15 @@ int drm_writeback_set_fb(struct drm_connector_state *conn_state,return 0 ; } +/** +* drm_writeback_prepare_job - Gives driver a chance to prepare for writeback +* @job: The writeback job to be prepared +* +* This function is called from &drm_atomic_helper_prepare_planes(), and allows +* the driver to setup the upcoming writeback job. The job will be +* destroyed/cleaned up in &drm_writeback_cleanup_job when the connector state +* is destroyed. +*/ int drm_writeback_prepare_job (struct drm_writeback_job *job) {struct drm_writeback_connector *connector = job->connector;
@@ -310,6 +319,17 @@ void drm_writeback_queue_job(struct drm_writeback_connector *wb_connector, }EXPORT_SYMBOL (drm_writeback_queue_job); +/** +* drm_writeback_cleanup_job - Gives driver a chance to cleanup a writeback job +* @job: The writeback job to be cleaned up +* +* This function is called from &atomic_helper_connector_destroy_state() and +* allows the driver to clean up the now finished writeback job. +* +* Notice the asymmetry from prepare, this is called on destroy to +* ensure the job is not destroyed before than the writeback operation +* has completed. +*/ void drm_writeback_cleanup_job (struct drm_writeback_job *job) {struct drm_writeback_connector *connector = job->connector;
include/drm/drm_modeset_helper_vtables.h +20 -0
@@ -992,8 +992,28 @@ struct drm_connector_helper_funcs {void (*atomic_commit)(struct drm_connector *connector,struct drm_connector_state *state); +/** +* @prepare_writeback_job: +* +* Called from &drm_atomic_helper_prepare_planes(), provides the driver +* a chance to setup things in preparation for a writeback job. +* +* This hook is optional. +*/ int (*prepare_writeback_job)(struct drm_writeback_connector *connector,struct drm_writeback_job *job); + +/** +* @cleanup_writeback_job: +* +* Called from &drm_atomic_helper_connector_destroy_state(), and +* provides the driver an opportunity to cleanup the writeback job. +* Notice the asymmetry from prepare, this is called on destroy to +* ensure the job is not destroyed before than the writeback operation +* has completed. +* +* This hook is optional. +*/ void (*cleanup_writeback_job)(struct drm_writeback_connector *connector,struct drm_writeback_job *job); };
Signature · 6 lines
Sean Paul, Software Engineer, Google / Chromium OS _______________________________________________ dri-devel mailing list [email protected] https://lists.freedesktop.org/mailman/listinfo/dri-devel
Re: [PATCH 2/2] drm/doc: Document the writeback prepare/cleanup jobs
Quoted 10 lines · Sean Paul
From: Sean Paul <[email protected]>
These functions were missing documentation.
Fixes the warning:
../include/drm/drm_modeset_helper_vtables.h:1000: warning: Function parameter or member 'prepare_writeback_job' not described in 'drm_connector_helper_funcs'../include/drm/drm_modeset_helper_vtables.h:1000: warning: Function parameter or member 'cleanup_writeback_job' not described in 'drm_connector_helper_funcs'Fixes 9d2230dc1351 ("drm: writeback: Add job prepare and cleanup operations")Cc Laurent Pinchart <[email protected]>
Oh Laurent didn't type documentation, I'll remember that one :-)
Quoted 19 lines
Cc Liviu Dudau <[email protected]>Cc Maarten Lankhorst <[email protected]>Cc Maxime Ripard <[email protected]>Cc Sean Paul <[email protected]>Cc David Airlie <[email protected]>Cc Daniel Vetter <[email protected]>Signed-off-by Sean Paul <[email protected]>--- drivers/gpu/drm/drm_writeback.c | 20 ++++++++++++++++++++ include/drm/drm_modeset_helper_vtables.h | 20 ++++++++++++++++++++ 2 files changed, 40 insertions(+)drivers/gpu/drm/drm_writeback.c +0
-0@@ -258,6 +258,15 @@ int drm_writeback_set_fb(struct drm_connector_state *conn_state,return 0 ;
drivers/gpu/drm/drm_writeback.c int drm_writeback_set_fb(struct drm_connector_state *conn_state, · line 268
Quoted 10 lines
drivers/gpu/drm/drm_writeback.c +8
-0} +/** +* drm_writeback_prepare_job - Gives driver a chance to prepare for writeback +* @job: The writeback job to be prepared +* +* This function is called from &drm_atomic_helper_prepare_planes(), and allows +* the driver to setup the upcoming writeback job. The job will be +* destroyed/cleaned up in &drm_writeback_cleanup_job when the connector state +* is destroyed.
This is missing the standard "Returns 0 on success, negative error codes on failures."
Quoted 7 lines
drivers/gpu/drm/drm_writeback.c +1
-0+*/ int drm_writeback_prepare_job (struct drm_writeback_job *job) {struct drm_writeback_connector *connector = job->connector;@@ -310,6 +319,17 @@ void drm_writeback_queue_job(struct drm_writeback_connector *wb_connector, }EXPORT_SYMBOL (drm_writeback_queue_job);
drivers/gpu/drm/drm_writeback.c void drm_writeback_queue_job(struct drm_writeback_connector *wb_connector, · line 330
Quoted 10 lines
drivers/gpu/drm/drm_writeback.c +9
-0+/** +* drm_writeback_cleanup_job - Gives driver a chance to cleanup a writeback job +* @job: The writeback job to be cleaned up +* +* This function is called from &atomic_helper_connector_destroy_state() and +* allows the driver to clean up the now finished writeback job. +* +* Notice the asymmetry from prepare, this is called on destroy to +* ensure the job is not destroyed before than the writeback operation
s/than// I think.
But I'm not really clear on what exactly the asymmetry is.
Plus it's not only called from destry_state, but also through a worker that's launched by drm_writeback_signal_completion.
I think you're docs here don't reflect reality. But yeah I think there's some asymmetry, as in cleanup_job is always called, even if prepare_job wasn't. Not the greatest interface I think, probably should rename cleanup to release/free. Since that's what it's supposed to do I think.
Quoted 10 lines
drivers/gpu/drm/drm_writeback.c +2
-0+* has completed. +*/ void drm_writeback_cleanup_job (struct drm_writeback_job *job) {struct drm_writeback_connector *connector = job->connector;include/drm/drm_modeset_helper_vtables.h +0
-0
include/drm/drm_modeset_helper_vtables.h struct drm_connector_helper_funcs { · line 1000
Quoted 9 lines
include/drm/drm_modeset_helper_vtables.h +6
-0@@ -992,8 +992,28 @@ struct drm_connector_helper_funcs {void (*atomic_commit)(struct drm_connector *connector,struct drm_connector_state *state); +/** +* @prepare_writeback_job: +* +* Called from &drm_atomic_helper_prepare_planes(), provides the driver +* a chance to setup things in preparation for a writeback job. +*
Missing standard boilerplate about return values.
Quoted 9 lines
include/drm/drm_modeset_helper_vtables.h +7
-0+* This hook is optional. +*/ int (*prepare_writeback_job)(struct drm_writeback_connector *connector,struct drm_writeback_job *job); + +/** +* @cleanup_writeback_job: +* +* Called from &drm_atomic_helper_connector_destroy_state(), and
include/drm/drm_modeset_helper_vtables.h struct drm_connector_helper_funcs { · line 1019
Quoted 10 lines
include/drm/drm_modeset_helper_vtables.h +7
-0+* provides the driver an opportunity to cleanup the writeback job. +* Notice the asymmetry from prepare, this is called on destroy to +* ensure the job is not destroyed before than the writeback operation +* has completed. +* +* This hook is optional. +*/ void (*cleanup_writeback_job)(struct drm_writeback_connector *connector,struct drm_writeback_job *job); };
So I looked through the writeback code some more, and realized that this here is probably more helper code (it's mostly called from helpers, the vfuncs are in helpers), but it's in core code.
I think before we document the details of this we also need to rethink the layering here, atm it looks like someone smashed a penne vertically into our very nice kms core/helper lasagna ... Would be really nice to clean this up too and either make it all core (which feels wrong) or move into helpers (probably needs a writeback_helper.c for this, or we stuff it into drm_atomic_helper.c).
Cheers, Daniel
Signature · 7 lines
Daniel Vetter Software Engineer, Intel Corporation http://blog.ffwll.ch _______________________________________________ dri-devel mailing list [email protected] https://lists.freedesktop.org/mailman/listinfo/dri-devel
Quoted 7 lines · Sean Paul
From: Sean Paul <[email protected]>
There are no structured comments in the file, so it generates this warning on compilation:
include/drm/drm_atomic_state_helper.h:1: warning: no structured comments found
Quoted 10 lines
Fixes 9ef8a9dc4b21 ("drm: Extract drm_atomic_state_helper.[hc]")Cc Ville Syrjälä <[email protected]>Cc Daniel Vetter <[email protected]>Cc David Airlie <[email protected]>Cc Daniel Vetter <[email protected]>Cc Maarten Lankhorst <[email protected]>Cc Maxime Ripard <[email protected]>Cc Sean Paul <[email protected]>Signed-off-by Sean Paul <[email protected]>
Quoted 21 lines
--- Documentation/gpu/drm-kms-helpers.rst | 3 --- 1 file changed, 3 deletions(-)Documentation/gpu/drm-kms-helpers.rst +0
-3@@ -77,9 +77,6 @@ Atomic State Reset and Initialization Atomic State Helper Reference ----------------------------- -.. kernel-doc:: include/drm/drm_atomic_state_helper.h - :internal: - .. kernel-doc:: drivers/gpu/drm/drm_atomic_state_helper.c :export:Signature · 1 line
Sean Paul, Software Engineer, Google / Chromium OS
Signature · 7 lines
Daniel Vetter Software Engineer, Intel Corporation http://blog.ffwll.ch _______________________________________________ dri-devel mailing list [email protected] https://lists.freedesktop.org/mailman/listinfo/dri-devel