Re: [PATCH, RFC] Document the videobuf layer
On Mon, 14 Dec 2009 15:36:08 -0200 Mauro Carvalho Chehab wrote: > It is probably better to have it as a separate document like what you've > proposed, > so, could you please drop the duplicated information that is there and move > any > missing info that might not be on your new doc? Yes, I can certainly do that. Will prepare a new patch, but it might take a day or two. jon -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH, RFC] Document the videobuf layer
Hi Jon,
You probably lost my feedback.
I've added some time ago a videobuf description at
Documentation/video4linux/v4l2-framework.txt.
It is probably better to have it as a separate document like what you've
proposed,
so, could you please drop the duplicated information that is there and move any
missing info that might not be on your new doc?
Thanks,
Mauro.
Jonathan Corbet wrote:
> I've taken the liberty of dropping this into my docs-next tree, and
> will send it upward unless there are objections. Hopefully it's
> useful...
>
> jon
> ---
> V4L2: Add a document describing the videobuf layer
>
> Videobuf is a moderately complex API which most V4L2 drivers should use,
> but its documentation is...sparse. This document attempts to improve the
> situation.
>
> Signed-off-by: Jonathan Corbet
>
> diff --git a/Documentation/video4linux/videobuf
> b/Documentation/video4linux/videobuf
> new file mode 100644
> index 000..4e21ea7
> --- /dev/null
> +++ b/Documentation/video4linux/videobuf
> @@ -0,0 +1,341 @@
> +An introduction to the videobuf layer
> +Jonathan Corbet
> +Current as of 2.6.32
> +
> +The videobuf layer functions as a sort of glue layer between a V4L2 driver
> +and user space. It handles the allocation and management of buffers for
> +the storage of video frames. There is a set of functions which can be used
> +to implement many of the standard POSIX I/O system calls, including read(),
> +poll(), and, happily, mmap(). Another set of functions can be used to
> +implement the bulk of the V4L2 ioctl() calls related to streaming I/O,
> +including buffer allocation, queueing and dequeueing, and streaming
> +control. Using videobuf imposes a few design decisions on the driver
> +author, but the payback comes in the form of reduced code in the driver and
> +a consistent implementation of the V4L2 user-space API.
> +
> +Buffer types
> +
> +Not all video devices use the same kind of buffers. In fact, there are (at
> +least) three common variations:
> +
> + - Buffers which are scattered in both the physical and (kernel) virtual
> + address spaces. All user-space buffers are like this, but it makes
> + great sense to allocate kernel-space buffers this way as well when it is
> + possible. Unfortunately, it is not always possible; working with this
> + kind of buffer normally requires hardware which can do scatter/gather
> + DMA operations.
> +
> + - Buffers which are physically scattered, but which are virtually
> + contiguous; buffers allocated with vmalloc(), in other words. These
> + buffers are just as hard to use for DMA operations, but they can be
> + useful in situations where DMA is not available but virtually-contiguous
> + buffers are convenient.
> +
> + - Buffers which are physically contiguous. Allocation of this kind of
> + buffer can be unreliable on fragmented systems, but simpler DMA
> + controllers cannot deal with anything else.
> +
> +Videobuf can work with all three types of buffers, but the driver author
> +must pick one at the outset and design the driver around that decision.
> +
> +Data structures, callbacks, and initialization
> +
> +Depending on which type of buffers are being used, the driver should
> +include one of the following files:
> +
> +/* Physically scattered */
> + /* vmalloc() buffers*/
> +/* Physically contiguous */
> +
> +The driver's data structure describing a V4L2 device should include a
> +struct videobuf_queue instance for the management of the buffer queue,
> +along with a list_head for the queue of available buffers. There will also
> +need to be an interrupt-safe spinlock which is used to protect (at least)
> +the queue.
> +
> +The next step is to write four simple callbacks to help videobuf deal with
> +the management of buffers:
> +
> +struct videobuf_queue_ops {
> + int (*buf_setup)(struct videobuf_queue *q,
> + unsigned int *count, unsigned int *size);
> + int (*buf_prepare)(struct videobuf_queue *q,
> +struct videobuf_buffer *vb,
> +enum v4l2_field field);
> + void (*buf_queue)(struct videobuf_queue *q,
> + struct videobuf_buffer *vb);
> + void (*buf_release)(struct videobuf_queue *q,
> + struct videobuf_buffer *vb);
> +};
> +
> +buf_setup() is called early in the I/O process, when streaming is being
> +initiated; its purpose is to tell videobuf about the I/O stream. The count
> +parameter will be a suggested number of buffers to use; the driver should
> +check it for rationality and adjust it if need be. As a practical rule, a
> +minimum of two buffers are needed for proper streaming, and there is
> +usually a maximum (which cannot exceed 32) which makes sense for each
> +device. The size parameter should be set to the expected (maximum) size
> +for each frame of data.
> +
> +Each buffer (in the form of a struct videobuf_b
Re: [PATCH, RFC] Document the videobuf layer
Jonathan Corbet wrote:
> I've taken the liberty of dropping this into my docs-next tree, and
> will send it upward unless there are objections. Hopefully it's
> useful...
Hi Jon,
Thanks for the doc!
I'll take a more detailed review, but I've added already some bits about
videobuf at:
Documentation/video4linux/v4l2-framework.txt
Your documentation seems more complete on a very quick view, but it also
seemed to have some duplicated info.
Cheers,
Mauro
>
> jon
> ---
> V4L2: Add a document describing the videobuf layer
>
> Videobuf is a moderately complex API which most V4L2 drivers should use,
> but its documentation is...sparse. This document attempts to improve the
> situation.
>
> Signed-off-by: Jonathan Corbet
>
> diff --git a/Documentation/video4linux/videobuf
> b/Documentation/video4linux/videobuf
> new file mode 100644
> index 000..4e21ea7
> --- /dev/null
> +++ b/Documentation/video4linux/videobuf
> @@ -0,0 +1,341 @@
> +An introduction to the videobuf layer
> +Jonathan Corbet
> +Current as of 2.6.32
> +
> +The videobuf layer functions as a sort of glue layer between a V4L2 driver
> +and user space. It handles the allocation and management of buffers for
> +the storage of video frames. There is a set of functions which can be used
> +to implement many of the standard POSIX I/O system calls, including read(),
> +poll(), and, happily, mmap(). Another set of functions can be used to
> +implement the bulk of the V4L2 ioctl() calls related to streaming I/O,
> +including buffer allocation, queueing and dequeueing, and streaming
> +control. Using videobuf imposes a few design decisions on the driver
> +author, but the payback comes in the form of reduced code in the driver and
> +a consistent implementation of the V4L2 user-space API.
> +
> +Buffer types
> +
> +Not all video devices use the same kind of buffers. In fact, there are (at
> +least) three common variations:
> +
> + - Buffers which are scattered in both the physical and (kernel) virtual
> + address spaces. All user-space buffers are like this, but it makes
> + great sense to allocate kernel-space buffers this way as well when it is
> + possible. Unfortunately, it is not always possible; working with this
> + kind of buffer normally requires hardware which can do scatter/gather
> + DMA operations.
> +
> + - Buffers which are physically scattered, but which are virtually
> + contiguous; buffers allocated with vmalloc(), in other words. These
> + buffers are just as hard to use for DMA operations, but they can be
> + useful in situations where DMA is not available but virtually-contiguous
> + buffers are convenient.
> +
> + - Buffers which are physically contiguous. Allocation of this kind of
> + buffer can be unreliable on fragmented systems, but simpler DMA
> + controllers cannot deal with anything else.
> +
> +Videobuf can work with all three types of buffers, but the driver author
> +must pick one at the outset and design the driver around that decision.
> +
> +Data structures, callbacks, and initialization
> +
> +Depending on which type of buffers are being used, the driver should
> +include one of the following files:
> +
> +/* Physically scattered */
> + /* vmalloc() buffers*/
> +/* Physically contiguous */
> +
> +The driver's data structure describing a V4L2 device should include a
> +struct videobuf_queue instance for the management of the buffer queue,
> +along with a list_head for the queue of available buffers. There will also
> +need to be an interrupt-safe spinlock which is used to protect (at least)
> +the queue.
> +
> +The next step is to write four simple callbacks to help videobuf deal with
> +the management of buffers:
> +
> +struct videobuf_queue_ops {
> + int (*buf_setup)(struct videobuf_queue *q,
> + unsigned int *count, unsigned int *size);
> + int (*buf_prepare)(struct videobuf_queue *q,
> +struct videobuf_buffer *vb,
> +enum v4l2_field field);
> + void (*buf_queue)(struct videobuf_queue *q,
> + struct videobuf_buffer *vb);
> + void (*buf_release)(struct videobuf_queue *q,
> + struct videobuf_buffer *vb);
> +};
> +
> +buf_setup() is called early in the I/O process, when streaming is being
> +initiated; its purpose is to tell videobuf about the I/O stream. The count
> +parameter will be a suggested number of buffers to use; the driver should
> +check it for rationality and adjust it if need be. As a practical rule, a
> +minimum of two buffers are needed for proper streaming, and there is
> +usually a maximum (which cannot exceed 32) which makes sense for each
> +device. The size parameter should be set to the expected (maximum) size
> +for each frame of data.
> +
> +Each buffer (in the form of a struct videobuf_buffer pointer) will be
> +passed to buf_prepare(), which should set the buffer'
[PATCH, RFC] Document the videobuf layer
I've taken the liberty of dropping this into my docs-next tree, and
will send it upward unless there are objections. Hopefully it's
useful...
jon
---
V4L2: Add a document describing the videobuf layer
Videobuf is a moderately complex API which most V4L2 drivers should use,
but its documentation is...sparse. This document attempts to improve the
situation.
Signed-off-by: Jonathan Corbet
diff --git a/Documentation/video4linux/videobuf
b/Documentation/video4linux/videobuf
new file mode 100644
index 000..4e21ea7
--- /dev/null
+++ b/Documentation/video4linux/videobuf
@@ -0,0 +1,341 @@
+An introduction to the videobuf layer
+Jonathan Corbet
+Current as of 2.6.32
+
+The videobuf layer functions as a sort of glue layer between a V4L2 driver
+and user space. It handles the allocation and management of buffers for
+the storage of video frames. There is a set of functions which can be used
+to implement many of the standard POSIX I/O system calls, including read(),
+poll(), and, happily, mmap(). Another set of functions can be used to
+implement the bulk of the V4L2 ioctl() calls related to streaming I/O,
+including buffer allocation, queueing and dequeueing, and streaming
+control. Using videobuf imposes a few design decisions on the driver
+author, but the payback comes in the form of reduced code in the driver and
+a consistent implementation of the V4L2 user-space API.
+
+Buffer types
+
+Not all video devices use the same kind of buffers. In fact, there are (at
+least) three common variations:
+
+ - Buffers which are scattered in both the physical and (kernel) virtual
+ address spaces. All user-space buffers are like this, but it makes
+ great sense to allocate kernel-space buffers this way as well when it is
+ possible. Unfortunately, it is not always possible; working with this
+ kind of buffer normally requires hardware which can do scatter/gather
+ DMA operations.
+
+ - Buffers which are physically scattered, but which are virtually
+ contiguous; buffers allocated with vmalloc(), in other words. These
+ buffers are just as hard to use for DMA operations, but they can be
+ useful in situations where DMA is not available but virtually-contiguous
+ buffers are convenient.
+
+ - Buffers which are physically contiguous. Allocation of this kind of
+ buffer can be unreliable on fragmented systems, but simpler DMA
+ controllers cannot deal with anything else.
+
+Videobuf can work with all three types of buffers, but the driver author
+must pick one at the outset and design the driver around that decision.
+
+Data structures, callbacks, and initialization
+
+Depending on which type of buffers are being used, the driver should
+include one of the following files:
+
+ /* Physically scattered */
+ /* vmalloc() buffers*/
+ /* Physically contiguous */
+
+The driver's data structure describing a V4L2 device should include a
+struct videobuf_queue instance for the management of the buffer queue,
+along with a list_head for the queue of available buffers. There will also
+need to be an interrupt-safe spinlock which is used to protect (at least)
+the queue.
+
+The next step is to write four simple callbacks to help videobuf deal with
+the management of buffers:
+
+struct videobuf_queue_ops {
+ int (*buf_setup)(struct videobuf_queue *q,
+unsigned int *count, unsigned int *size);
+ int (*buf_prepare)(struct videobuf_queue *q,
+ struct videobuf_buffer *vb,
+ enum v4l2_field field);
+ void (*buf_queue)(struct videobuf_queue *q,
+ struct videobuf_buffer *vb);
+ void (*buf_release)(struct videobuf_queue *q,
+ struct videobuf_buffer *vb);
+};
+
+buf_setup() is called early in the I/O process, when streaming is being
+initiated; its purpose is to tell videobuf about the I/O stream. The count
+parameter will be a suggested number of buffers to use; the driver should
+check it for rationality and adjust it if need be. As a practical rule, a
+minimum of two buffers are needed for proper streaming, and there is
+usually a maximum (which cannot exceed 32) which makes sense for each
+device. The size parameter should be set to the expected (maximum) size
+for each frame of data.
+
+Each buffer (in the form of a struct videobuf_buffer pointer) will be
+passed to buf_prepare(), which should set the buffer's size, width, height,
+and field fields properly. If the buffer's state field is
+VIDEOBUF_NEEDS_INIT, the driver should pass it to:
+
+int videobuf_iolock(struct videobuf_queue* q, struct videobuf_buffer *vb,
+ struct v4l2_framebuffer *fbuf);
+
+Among other things, this call will usually allocate memory for the buffer.
+Finally, the buf_setup() function should set the buffer's state to
+VIDEOBUF_PREPARED.
+
+When a buffer is queued for I/O, it is passed to buf_queue(), which
