Re: [PATCH 21/24] media: vb2-core: fix descriptions for VB2-only functions

[Sakari Ailus]

Hi Mauro,

On Mon, Oct 09, 2017 at 07:19:27AM -0300, Mauro Carvalho Chehab wrote:
> When we split VB2 into an independent streaming module and
> a V4L2 one, some vb2-core functions started to have a wrong
> description: they're meant to be used only by the API-specific
> parts of VB2, like vb2-v4l2, as the functions that V4L2 drivers
> should use are all under videobuf2-v4l2.h.
> 
> Correct their descriptions.
> 
> Signed-off-by: Mauro Carvalho Chehab 
> ---
>  include/media/videobuf2-core.h | 86 
> ++
>  1 file changed, 46 insertions(+), 40 deletions(-)
> 
> diff --git a/include/media/videobuf2-core.h b/include/media/videobuf2-core.h
> index ce795cd0a7cc..3165f0f9a85f 100644
> --- a/include/media/videobuf2-core.h
> +++ b/include/media/videobuf2-core.h
> @@ -651,12 +651,14 @@ int vb2_wait_for_all_buffers(struct vb2_queue *q);
>   * @index:   id number of the buffer.
>   * @pb:  buffer struct passed from userspace.
>   *
> - * Should be called from _ioctl_ops->vidioc_querybuf ioctl handler
> - * in driver.
> + * Videbuf2 core helper to implement QUERYBUF operation. It is called

"Videobuf2" and "VIDIOC_" prefix for IOCTL commands. With this and the ones
below fixed,

Acked-by: Sakari Ailus 

> + * internally by VB2 by an API-specific handler, like ``videobuf2-v4l2.h``.
>   *
>   * The passed buffer should have been verified.
>   *
>   * This function fills the relevant information for the userspace.
> + *
> + * Return: returns zero on success; an error code otherwise.
>   */
>  void vb2_core_querybuf(struct vb2_queue *q, unsigned int index, void *pb);
>  
> @@ -666,27 +668,26 @@ void vb2_core_querybuf(struct vb2_queue *q, unsigned 
> int index, void *pb);
>   * @memory:  memory type, as defined by  vb2_memory.
>   * @count:   requested buffer count.
>   *
> - * Should be called from _ioctl_ops->vidioc_reqbufs ioctl
> - * handler of a driver.
> + * Videbuf2 core helper to implement REQBUF operation. It is called

Ditto.

> + * internally by VB2 by an API-specific handler, like ``videobuf2-v4l2.h``.
>   *
>   * This function:
>   *
> - * #) verifies streaming parameters passed from the userspace,
> - * #) sets up the queue,
> + * #) verifies streaming parameters passed from the userspace;
> + * #) sets up the queue;
>   * #) negotiates number of buffers and planes per buffer with the driver
> - *to be used during streaming,
> + *to be used during streaming;
>   * #) allocates internal buffer structures ( vb2_buffer), according to
> - *the agreed parameters,
> + *the agreed parameters;
>   * #) for MMAP memory type, allocates actual video memory, using the
> - *memory handling/allocation routines provided during queue 
> initialization
> + *memory handling/allocation routines provided during queue 
> initialization.
>   *
>   * If req->count is 0, all the memory will be freed instead.
>   *
>   * If the queue has been allocated previously by a previous 
> vb2_core_reqbufs()
>   * call and the queue is not busy, memory will be reallocated.
>   *
> - * The return values from this function are intended to be directly returned
> - * from _ioctl_ops->vidioc_reqbufs handler in driver.
> + * Return: returns zero on success; an error code otherwise.
>   */
>  int vb2_core_reqbufs(struct vb2_queue *q, enum vb2_memory memory,
>   unsigned int *count);
> @@ -699,17 +700,16 @@ int vb2_core_reqbufs(struct vb2_queue *q, enum 
> vb2_memory memory,
>   * @requested_planes: number of planes requested.
>   * @requested_sizes: array with the size of the planes.
>   *
> - * Should be called from _ioctl_ops->vidioc_create_bufs ioctl handler
> - * of a driver.
> + * Videbuf2 core helper to implement CREATE_BUFS operation. It is called

Ditto.

> + * internally by VB2 by an API-specific handler, like ``videobuf2-v4l2.h``.
>   *
>   * This function:
>   *
> - * #) verifies parameter sanity
> - * #) calls the _ops->queue_setup queue operation
> - * #) performs any necessary memory allocations
> + * #) verifies parameter sanity;
> + * #) calls the _ops->queue_setup queue operation;
> + * #) performs any necessary memory allocations.
>   *
> - * Return: the return values from this function are intended to be directly
> - * returned from _ioctl_ops->vidioc_create_bufs handler in driver.
> + * Return: returns zero on success; an error code otherwise.
>   */
>  int vb2_core_create_bufs(struct vb2_queue *q, enum vb2_memory memory,
>unsigned int *count, unsigned int requested_planes,
> @@ -723,16 +723,16 @@ int vb2_core_create_bufs(struct vb2_queue *q, enum 
> vb2_memory memory,
>   * @pb:  buffer structure passed from userspace to
>   *   _ioctl_ops->vidioc_prepare_buf handler in driver.
>   *
> - * Should be called from _ioctl_ops->vidioc_prepare_buf ioctl handler
> - * of a driver.
> + * Videbuf2 core helper to implement PREPARE_BUF operation. It is 

[PATCH 21/24] media: vb2-core: fix descriptions for VB2-only functions

[Mauro Carvalho Chehab]

When we split VB2 into an independent streaming module and
a V4L2 one, some vb2-core functions started to have a wrong
description: they're meant to be used only by the API-specific
parts of VB2, like vb2-v4l2, as the functions that V4L2 drivers
should use are all under videobuf2-v4l2.h.

Correct their descriptions.

Signed-off-by: Mauro Carvalho Chehab 
---
 include/media/videobuf2-core.h | 86 ++
 1 file changed, 46 insertions(+), 40 deletions(-)

diff --git a/include/media/videobuf2-core.h b/include/media/videobuf2-core.h
index ce795cd0a7cc..3165f0f9a85f 100644
--- a/include/media/videobuf2-core.h
+++ b/include/media/videobuf2-core.h
@@ -651,12 +651,14 @@ int vb2_wait_for_all_buffers(struct vb2_queue *q);
  * @index: id number of the buffer.
  * @pb:buffer struct passed from userspace.
  *
- * Should be called from _ioctl_ops->vidioc_querybuf ioctl handler
- * in driver.
+ * Videbuf2 core helper to implement QUERYBUF operation. It is called
+ * internally by VB2 by an API-specific handler, like ``videobuf2-v4l2.h``.
  *
  * The passed buffer should have been verified.
  *
  * This function fills the relevant information for the userspace.
+ *
+ * Return: returns zero on success; an error code otherwise.
  */
 void vb2_core_querybuf(struct vb2_queue *q, unsigned int index, void *pb);
 
@@ -666,27 +668,26 @@ void vb2_core_querybuf(struct vb2_queue *q, unsigned int 
index, void *pb);
  * @memory:memory type, as defined by  vb2_memory.
  * @count: requested buffer count.
  *
- * Should be called from _ioctl_ops->vidioc_reqbufs ioctl
- * handler of a driver.
+ * Videbuf2 core helper to implement REQBUF operation. It is called
+ * internally by VB2 by an API-specific handler, like ``videobuf2-v4l2.h``.
  *
  * This function:
  *
- * #) verifies streaming parameters passed from the userspace,
- * #) sets up the queue,
+ * #) verifies streaming parameters passed from the userspace;
+ * #) sets up the queue;
  * #) negotiates number of buffers and planes per buffer with the driver
- *to be used during streaming,
+ *to be used during streaming;
  * #) allocates internal buffer structures ( vb2_buffer), according to
- *the agreed parameters,
+ *the agreed parameters;
  * #) for MMAP memory type, allocates actual video memory, using the
- *memory handling/allocation routines provided during queue initialization
+ *memory handling/allocation routines provided during queue initialization.
  *
  * If req->count is 0, all the memory will be freed instead.
  *
  * If the queue has been allocated previously by a previous vb2_core_reqbufs()
  * call and the queue is not busy, memory will be reallocated.
  *
- * The return values from this function are intended to be directly returned
- * from _ioctl_ops->vidioc_reqbufs handler in driver.
+ * Return: returns zero on success; an error code otherwise.
  */
 int vb2_core_reqbufs(struct vb2_queue *q, enum vb2_memory memory,
unsigned int *count);
@@ -699,17 +700,16 @@ int vb2_core_reqbufs(struct vb2_queue *q, enum vb2_memory 
memory,
  * @requested_planes: number of planes requested.
  * @requested_sizes: array with the size of the planes.
  *
- * Should be called from _ioctl_ops->vidioc_create_bufs ioctl handler
- * of a driver.
+ * Videbuf2 core helper to implement CREATE_BUFS operation. It is called
+ * internally by VB2 by an API-specific handler, like ``videobuf2-v4l2.h``.
  *
  * This function:
  *
- * #) verifies parameter sanity
- * #) calls the _ops->queue_setup queue operation
- * #) performs any necessary memory allocations
+ * #) verifies parameter sanity;
+ * #) calls the _ops->queue_setup queue operation;
+ * #) performs any necessary memory allocations.
  *
- * Return: the return values from this function are intended to be directly
- * returned from _ioctl_ops->vidioc_create_bufs handler in driver.
+ * Return: returns zero on success; an error code otherwise.
  */
 int vb2_core_create_bufs(struct vb2_queue *q, enum vb2_memory memory,
 unsigned int *count, unsigned int requested_planes,
@@ -723,16 +723,16 @@ int vb2_core_create_bufs(struct vb2_queue *q, enum 
vb2_memory memory,
  * @pb:buffer structure passed from userspace to
  * _ioctl_ops->vidioc_prepare_buf handler in driver.
  *
- * Should be called from _ioctl_ops->vidioc_prepare_buf ioctl handler
- * of a driver.
+ * Videbuf2 core helper to implement PREPARE_BUF operation. It is called
+ * internally by VB2 by an API-specific handler, like ``videobuf2-v4l2.h``.
  *
  * The passed buffer should have been verified.
  *
- * This function calls buf_prepare callback in the driver (if provided),
- * in which driver-specific buffer initialization can be performed,
+ * This function calls vb2_ops->buf_prepare callback in the driver
+ * (if provided), in which driver-specific buffer initialization can
+ * be performed.
  *
- * The