[16/28] drm: Document drm_atomic_*_get_property
diff mbox

Message ID 1449218769-16577-17-git-send-email-daniel.vetter@ffwll.ch
State New
Headers show

Commit Message

Daniel Vetter Dec. 4, 2015, 8:45 a.m. UTC
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(-)

Comments

Thierry Reding Dec. 7, 2015, 12:01 p.m. UTC | #1
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>
Daniel Vetter Dec. 7, 2015, 12:51 p.m. UTC | #2
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>

Patch
diff mbox

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,