| Message ID | 1449218769-16577-17-git-send-email-daniel.vetter@ffwll.ch (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
On Fri, Dec 04, 2015 at 09:45:57AM +0100, Daniel Vetter wrote: > Yes these are internal functions and not exported and we generally > don't document them. But for symmetry with the _set_property functions > (which are exported for the atomic helpers) I'd like to document them. > Upcoming vtable kerneldoc will reference both the set and get_property > functions. > > Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch> > --- > Documentation/DocBook/gpu.tmpl | 1 + > drivers/gpu/drm/drm_atomic.c | 33 ++++++++++++++++++++++++++++++--- > 2 files changed, 31 insertions(+), 3 deletions(-) > > diff --git a/Documentation/DocBook/gpu.tmpl b/Documentation/DocBook/gpu.tmpl > index 23ad100c2bf5..02c7d44f517c 100644 > --- a/Documentation/DocBook/gpu.tmpl > +++ b/Documentation/DocBook/gpu.tmpl > @@ -946,6 +946,7 @@ int max_width, max_height;</synopsis> > <sect2> > <title>Atomic Mode Setting Function Reference</title> > !Edrivers/gpu/drm/drm_atomic.c > +!Idrivers/gpu/drm/drm_atomic.c > </sect2> > <sect2> > <title>Frame Buffer Creation</title> > diff --git a/drivers/gpu/drm/drm_atomic.c b/drivers/gpu/drm/drm_atomic.c > index ef5f7663a718..7426d40017a0 100644 > --- a/drivers/gpu/drm/drm_atomic.c > +++ b/drivers/gpu/drm/drm_atomic.c > @@ -429,11 +429,20 @@ int drm_atomic_crtc_set_property(struct drm_crtc *crtc, > } > EXPORT_SYMBOL(drm_atomic_crtc_set_property); > > -/* > +/** > + * drm_atomic_crtc_get_property - get property value from CRTC state > + * @crtc: the drm CRTC to set a property on > + * @state: the state object to get the property value from > + * @property: the property to set > + * @val: pointer to where the value should be written to Nit: I find this difficult to write and read, and I prefer the wording "return location for the property value". But either way: Reviewed-by: Thierry Reding <treding@nvidia.com>
On Mon, Dec 07, 2015 at 01:01:35PM +0100, Thierry Reding wrote: > On Fri, Dec 04, 2015 at 09:45:57AM +0100, Daniel Vetter wrote: > > Yes these are internal functions and not exported and we generally > > don't document them. But for symmetry with the _set_property functions > > (which are exported for the atomic helpers) I'd like to document them. > > Upcoming vtable kerneldoc will reference both the set and get_property > > functions. > > > > Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch> > > --- > > Documentation/DocBook/gpu.tmpl | 1 + > > drivers/gpu/drm/drm_atomic.c | 33 ++++++++++++++++++++++++++++++--- > > 2 files changed, 31 insertions(+), 3 deletions(-) > > > > diff --git a/Documentation/DocBook/gpu.tmpl b/Documentation/DocBook/gpu.tmpl > > index 23ad100c2bf5..02c7d44f517c 100644 > > --- a/Documentation/DocBook/gpu.tmpl > > +++ b/Documentation/DocBook/gpu.tmpl > > @@ -946,6 +946,7 @@ int max_width, max_height;</synopsis> > > <sect2> > > <title>Atomic Mode Setting Function Reference</title> > > !Edrivers/gpu/drm/drm_atomic.c > > +!Idrivers/gpu/drm/drm_atomic.c > > </sect2> > > <sect2> > > <title>Frame Buffer Creation</title> > > diff --git a/drivers/gpu/drm/drm_atomic.c b/drivers/gpu/drm/drm_atomic.c > > index ef5f7663a718..7426d40017a0 100644 > > --- a/drivers/gpu/drm/drm_atomic.c > > +++ b/drivers/gpu/drm/drm_atomic.c > > @@ -429,11 +429,20 @@ int drm_atomic_crtc_set_property(struct drm_crtc *crtc, > > } > > EXPORT_SYMBOL(drm_atomic_crtc_set_property); > > > > -/* > > +/** > > + * drm_atomic_crtc_get_property - get property value from CRTC state > > + * @crtc: the drm CRTC to set a property on > > + * @state: the state object to get the property value from > > + * @property: the property to set > > + * @val: pointer to where the value should be written to > > Nit: I find this difficult to write and read, and I prefer the wording > "return location for the property value". But either way: Yeah that reads much better. Changed all 3 places in drm_atomic. We might want to have a style guide for DRM docs for these things ... -Daniel > > Reviewed-by: Thierry Reding <treding@nvidia.com>
diff --git a/Documentation/DocBook/gpu.tmpl b/Documentation/DocBook/gpu.tmpl index 23ad100c2bf5..02c7d44f517c 100644 --- a/Documentation/DocBook/gpu.tmpl +++ b/Documentation/DocBook/gpu.tmpl @@ -946,6 +946,7 @@ int max_width, max_height;</synopsis> <sect2> <title>Atomic Mode Setting Function Reference</title> !Edrivers/gpu/drm/drm_atomic.c +!Idrivers/gpu/drm/drm_atomic.c </sect2> <sect2> <title>Frame Buffer Creation</title> diff --git a/drivers/gpu/drm/drm_atomic.c b/drivers/gpu/drm/drm_atomic.c index ef5f7663a718..7426d40017a0 100644 --- a/drivers/gpu/drm/drm_atomic.c +++ b/drivers/gpu/drm/drm_atomic.c @@ -429,11 +429,20 @@ int drm_atomic_crtc_set_property(struct drm_crtc *crtc, } EXPORT_SYMBOL(drm_atomic_crtc_set_property); -/* +/** + * drm_atomic_crtc_get_property - get property value from CRTC state + * @crtc: the drm CRTC to set a property on + * @state: the state object to get the property value from + * @property: the property to set + * @val: pointer to where the value should be written to + * * This function handles generic/core properties and calls out to * driver's ->atomic_get_property() for driver properties. To ensure * consistent behavior you must call this function rather than the * driver hook directly. + * + * RETURNS: + * Zero on success, error code on failure */ static int drm_atomic_crtc_get_property(struct drm_crtc *crtc, @@ -616,11 +625,20 @@ int drm_atomic_plane_set_property(struct drm_plane *plane, } EXPORT_SYMBOL(drm_atomic_plane_set_property); -/* +/** + * drm_atomic_plane_get_property - get property value from plane state + * @plane: the drm plane to set a property on + * @state: the state object to get the property value from + * @property: the property to set + * @val: pointer to where the value should be written to + * * This function handles generic/core properties and calls out to * driver's ->atomic_get_property() for driver properties. To ensure * consistent behavior you must call this function rather than the * driver hook directly. + * + * RETURNS: + * Zero on success, error code on failure */ static int drm_atomic_plane_get_property(struct drm_plane *plane, @@ -872,11 +890,20 @@ int drm_atomic_connector_set_property(struct drm_connector *connector, } EXPORT_SYMBOL(drm_atomic_connector_set_property); -/* +/** + * drm_atomic_connector_get_property - get property value from connector state + * @connector: the drm connector to set a property on + * @state: the state object to get the property value from + * @property: the property to set + * @val: pointer to where the value should be written to + * * This function handles generic/core properties and calls out to * driver's ->atomic_get_property() for driver properties. To ensure * consistent behavior you must call this function rather than the * driver hook directly. + * + * RETURNS: + * Zero on success, error code on failure */ static int drm_atomic_connector_get_property(struct drm_connector *connector,
Yes these are internal functions and not exported and we generally don't document them. But for symmetry with the _set_property functions (which are exported for the atomic helpers) I'd like to document them. Upcoming vtable kerneldoc will reference both the set and get_property functions. Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch> --- Documentation/DocBook/gpu.tmpl | 1 + drivers/gpu/drm/drm_atomic.c | 33 ++++++++++++++++++++++++++++++--- 2 files changed, 31 insertions(+), 3 deletions(-)