Re: [PATCH 21/24] media: vb2-core: fix descriptions for VB2-only functions
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
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