Re: [PATCH, RFC] Document the videobuf layer

2009-12-14 Thread Mauro Carvalho Chehab
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 cor...@lwn.net
 
 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 cor...@lwn.net
 +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:
 +
 +media/videobuf-dma-sg.h/* Physically scattered */
 +media/videobuf-vmalloc.h   /* vmalloc() buffers*/
 +media/videobuf-dma-contig.h/* 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 

Re: [PATCH, RFC] Document the videobuf layer

2009-12-14 Thread Jonathan Corbet
On Mon, 14 Dec 2009 15:36:08 -0200
Mauro Carvalho Chehab mche...@infradead.org 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

2009-12-03 Thread Mauro Carvalho Chehab
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 cor...@lwn.net
 
 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 cor...@lwn.net
 +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:
 +
 +media/videobuf-dma-sg.h/* Physically scattered */
 +media/videobuf-vmalloc.h   /* vmalloc() buffers*/
 +media/videobuf-dma-contig.h/* 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