Re: [PATCH 16/24] media: v4l2-subdev: document remaining undocumented functions

[Sakari Ailus]

On Mon, Oct 09, 2017 at 07:19:22AM -0300, Mauro Carvalho Chehab wrote:
> There are several undocumented v4l2-subdev functions that are
> part of kAPI. Document them.
> 
> Signed-off-by: Mauro Carvalho Chehab 
> ---
>  include/media/v4l2-subdev.h | 70 
> +
>  1 file changed, 65 insertions(+), 5 deletions(-)
> 
> diff --git a/include/media/v4l2-subdev.h b/include/media/v4l2-subdev.h
> index 35c4476c56ee..e215732eed45 100644
> --- a/include/media/v4l2-subdev.h
> +++ b/include/media/v4l2-subdev.h
> @@ -868,6 +868,13 @@ struct v4l2_subdev {
>   struct v4l2_subdev_platform_data *pdata;
>  };
>  
> +
> +/**
> + * media_entity_to_v4l2_subdev - Returns a  v4l2_subdev from
> + * the  media_entity embedded on it.

I'd add that "calling this macro with NULL argument safely returns NULL".

> + *
> + * @ent: pointer to  media_entity.
> + */
>  #define media_entity_to_v4l2_subdev(ent) \
>  ({   \
>   typeof(ent) __me_sd_ent = (ent);\
> @@ -877,14 +884,20 @@ struct v4l2_subdev {
>   NULL;   \
>  })
>  
> +/**
> + * vdev_to_v4l2_subdev - Returns a  v4l2_subdev from
> + * the  video_device embedded on it.
> + *
> + * @vdev: pointer to  video_device
> + */
>  #define vdev_to_v4l2_subdev(vdev) \
>   ((struct v4l2_subdev *)video_get_drvdata(vdev))
>  
>  /**
>   * struct v4l2_subdev_fh - Used for storing subdev information per file 
> handle
>   *
> - * @vfh: pointer to struct v4l2_fh
> - * @pad: pointer to v4l2_subdev_pad_config
> + * @vfh: pointer to  v4l2_fh
> + * @pad: pointer to  v4l2_subdev_pad_config
>   */
>  struct v4l2_subdev_fh {
>   struct v4l2_fh vfh;
> @@ -893,10 +906,25 @@ struct v4l2_subdev_fh {
>  #endif
>  };
>  
> +/**
> + * to_v4l2_subdev_fh - Returns a  v4l2_subdev_fh from
> + * the  v4l2_fh embedded on it.

s/on/in/

> + *
> + * @fh: pointer to  v4l2_fh
> + */
>  #define to_v4l2_subdev_fh(fh)\
>   container_of(fh, struct v4l2_subdev_fh, vfh)
>  
>  #if defined(CONFIG_VIDEO_V4L2_SUBDEV_API)
> +
> +/**
> + * v4l2_subdev_get_try_format - ancillary routine to call
> + *v4l2_subdev_pad_config->try_fmt
> + *
> + * @sd: pointer to  v4l2_subdev
> + * @cfg: pointer to  v4l2_subdev_pad_config array.
> + * @pad: index of the pad a the @cfg array.

s/a /in /

The same for the other instances.

> + */
>  static inline struct v4l2_mbus_framefmt
>  *v4l2_subdev_get_try_format(struct v4l2_subdev *sd,
>   struct v4l2_subdev_pad_config *cfg,
> @@ -906,6 +934,14 @@ static inline struct v4l2_mbus_framefmt
>   return [pad].try_fmt;
>  }
>  
> +/**
> + * v4l2_subdev_get_try_crop - ancillary routine to call
> + *v4l2_subdev_pad_config->try_crop
> + *
> + * @sd: pointer to  v4l2_subdev
> + * @cfg: pointer to  v4l2_subdev_pad_config array.
> + * @pad: index of the pad a the @cfg array.
> + */
>  static inline struct v4l2_rect
>  *v4l2_subdev_get_try_crop(struct v4l2_subdev *sd,
> struct v4l2_subdev_pad_config *cfg,
> @@ -915,6 +951,14 @@ static inline struct v4l2_rect
>   return [pad].try_crop;
>  }
>  
> +/**
> + * v4l2_subdev_get_try_crop - ancillary routine to call
> + *v4l2_subdev_pad_config->try_compose
> + *
> + * @sd: pointer to  v4l2_subdev
> + * @cfg: pointer to  v4l2_subdev_pad_config array.
> + * @pad: index of the pad a the @cfg array.
> + */
>  static inline struct v4l2_rect
>  *v4l2_subdev_get_try_compose(struct v4l2_subdev *sd,
>struct v4l2_subdev_pad_config *cfg,
> @@ -1030,9 +1074,17 @@ void v4l2_subdev_free_pad_config(struct 
> v4l2_subdev_pad_config *cfg);
>  void v4l2_subdev_init(struct v4l2_subdev *sd,
> const struct v4l2_subdev_ops *ops);
>  
> -/*
> - * Call an ops of a v4l2_subdev, doing the right checks against
> - * NULL pointers.
> +/**
> + * v4l2_subdev_call - call an ops of a v4l2_subdev, doing the right checks

s/ops/operation/ ?

> + *   against NULL pointers.

We already say in struct v4l2_subdev_ops documentation that the individual
ops may be NULL. I think that should be enough.

> + *
> + * @sd: pointer to the  v4l2_subdev
> + * @o: name of the element at  v4l2_subdev_ops that contains @f.
> + * Each element there groups a set of callbacks functions.
> + * @f: callback function that will be called if @cond matches.
> + * The callback functions are defined in groups, according to
> + * each element at  v4l2_subdev_ops.
> + * @args...: arguments for @f.
>   *
>   * Example: err = v4l2_subdev_call(sd, video, s_std, norm);
>   */
> @@ -1048,6 +1100,14 @@ void v4l2_subdev_init(struct v4l2_subdev *sd,
>   __result;   \
>   })
>  
> +/**
> + * v4l2_subdev_has_op - Checks if a subdev defines a certain ops.

s/ops/operation/ (or 

[PATCH 16/24] media: v4l2-subdev: document remaining undocumented functions

[Mauro Carvalho Chehab]

There are several undocumented v4l2-subdev functions that are
part of kAPI. Document them.

Signed-off-by: Mauro Carvalho Chehab 
---
 include/media/v4l2-subdev.h | 70 +
 1 file changed, 65 insertions(+), 5 deletions(-)

diff --git a/include/media/v4l2-subdev.h b/include/media/v4l2-subdev.h
index 35c4476c56ee..e215732eed45 100644
--- a/include/media/v4l2-subdev.h
+++ b/include/media/v4l2-subdev.h
@@ -868,6 +868,13 @@ struct v4l2_subdev {
struct v4l2_subdev_platform_data *pdata;
 };
 
+
+/**
+ * media_entity_to_v4l2_subdev - Returns a  v4l2_subdev from
+ * the  media_entity embedded on it.
+ *
+ * @ent: pointer to  media_entity.
+ */
 #define media_entity_to_v4l2_subdev(ent)   \
 ({ \
typeof(ent) __me_sd_ent = (ent);\
@@ -877,14 +884,20 @@ struct v4l2_subdev {
NULL;   \
 })
 
+/**
+ * vdev_to_v4l2_subdev - Returns a  v4l2_subdev from
+ * the  video_device embedded on it.
+ *
+ * @vdev: pointer to  video_device
+ */
 #define vdev_to_v4l2_subdev(vdev) \
((struct v4l2_subdev *)video_get_drvdata(vdev))
 
 /**
  * struct v4l2_subdev_fh - Used for storing subdev information per file handle
  *
- * @vfh: pointer to struct v4l2_fh
- * @pad: pointer to v4l2_subdev_pad_config
+ * @vfh: pointer to  v4l2_fh
+ * @pad: pointer to  v4l2_subdev_pad_config
  */
 struct v4l2_subdev_fh {
struct v4l2_fh vfh;
@@ -893,10 +906,25 @@ struct v4l2_subdev_fh {
 #endif
 };
 
+/**
+ * to_v4l2_subdev_fh - Returns a  v4l2_subdev_fh from
+ * the  v4l2_fh embedded on it.
+ *
+ * @fh: pointer to  v4l2_fh
+ */
 #define to_v4l2_subdev_fh(fh)  \
container_of(fh, struct v4l2_subdev_fh, vfh)
 
 #if defined(CONFIG_VIDEO_V4L2_SUBDEV_API)
+
+/**
+ * v4l2_subdev_get_try_format - ancillary routine to call
+ *  v4l2_subdev_pad_config->try_fmt
+ *
+ * @sd: pointer to  v4l2_subdev
+ * @cfg: pointer to  v4l2_subdev_pad_config array.
+ * @pad: index of the pad a the @cfg array.
+ */
 static inline struct v4l2_mbus_framefmt
 *v4l2_subdev_get_try_format(struct v4l2_subdev *sd,
struct v4l2_subdev_pad_config *cfg,
@@ -906,6 +934,14 @@ static inline struct v4l2_mbus_framefmt
return [pad].try_fmt;
 }
 
+/**
+ * v4l2_subdev_get_try_crop - ancillary routine to call
+ *  v4l2_subdev_pad_config->try_crop
+ *
+ * @sd: pointer to  v4l2_subdev
+ * @cfg: pointer to  v4l2_subdev_pad_config array.
+ * @pad: index of the pad a the @cfg array.
+ */
 static inline struct v4l2_rect
 *v4l2_subdev_get_try_crop(struct v4l2_subdev *sd,
  struct v4l2_subdev_pad_config *cfg,
@@ -915,6 +951,14 @@ static inline struct v4l2_rect
return [pad].try_crop;
 }
 
+/**
+ * v4l2_subdev_get_try_crop - ancillary routine to call
+ *  v4l2_subdev_pad_config->try_compose
+ *
+ * @sd: pointer to  v4l2_subdev
+ * @cfg: pointer to  v4l2_subdev_pad_config array.
+ * @pad: index of the pad a the @cfg array.
+ */
 static inline struct v4l2_rect
 *v4l2_subdev_get_try_compose(struct v4l2_subdev *sd,
 struct v4l2_subdev_pad_config *cfg,
@@ -1030,9 +1074,17 @@ void v4l2_subdev_free_pad_config(struct 
v4l2_subdev_pad_config *cfg);
 void v4l2_subdev_init(struct v4l2_subdev *sd,
  const struct v4l2_subdev_ops *ops);
 
-/*
- * Call an ops of a v4l2_subdev, doing the right checks against
- * NULL pointers.
+/**
+ * v4l2_subdev_call - call an ops of a v4l2_subdev, doing the right checks
+ * against NULL pointers.
+ *
+ * @sd: pointer to the  v4l2_subdev
+ * @o: name of the element at  v4l2_subdev_ops that contains @f.
+ * Each element there groups a set of callbacks functions.
+ * @f: callback function that will be called if @cond matches.
+ * The callback functions are defined in groups, according to
+ * each element at  v4l2_subdev_ops.
+ * @args...: arguments for @f.
  *
  * Example: err = v4l2_subdev_call(sd, video, s_std, norm);
  */
@@ -1048,6 +1100,14 @@ void v4l2_subdev_init(struct v4l2_subdev *sd,
__result;   \
})
 
+/**
+ * v4l2_subdev_has_op - Checks if a subdev defines a certain ops.
+ *
+ * @sd: pointer to the  v4l2_subdev
+ * @o: name of the element at  v4l2_subdev_ops that contains @f.
+ * Each element there groups a set of callbacks functions.
+ * @f: callback function to be checked for its existence.
+ */
 #define v4l2_subdev_has_op(sd, o, f) \
((sd)->ops->o && (sd)->ops->o->f)
 
-- 
2.13.6

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html