summaryrefslogtreecommitdiff
path: root/include/media/videobuf2-core.h
diff options
context:
space:
mode:
Diffstat (limited to 'include/media/videobuf2-core.h')
-rw-r--r--include/media/videobuf2-core.h74
1 files changed, 40 insertions, 34 deletions
diff --git a/include/media/videobuf2-core.h b/include/media/videobuf2-core.h
index bea81c9e3758..946340ce7701 100644
--- a/include/media/videobuf2-core.h
+++ b/include/media/videobuf2-core.h
@@ -85,11 +85,17 @@ struct vb2_threadio_data;
* @mmap: setup a userspace mapping for a given memory buffer under
* the provided virtual memory region.
*
- * Required ops for USERPTR types: get_userptr, put_userptr.
- * Required ops for MMAP types: alloc, put, num_users, mmap.
- * Required ops for read/write access types: alloc, put, num_users, vaddr.
- * Required ops for DMABUF types: attach_dmabuf, detach_dmabuf, map_dmabuf,
- * unmap_dmabuf.
+ * Those operations are used by the videobuf2 core to implement the memory
+ * handling/memory allocators for each type of supported streaming I/O method.
+ *
+ * .. note::
+ * #) Required ops for USERPTR types: get_userptr, put_userptr.
+ *
+ * #) Required ops for MMAP types: alloc, put, num_users, mmap.
+ *
+ * #) Required ops for read/write access types: alloc, put, num_users, vaddr.
+ *
+ * #) Required ops for DMABUF types: attach_dmabuf, detach_dmabuf, map_dmabuf, unmap_dmabuf.
*/
struct vb2_mem_ops {
void *(*alloc)(struct device *dev, const struct dma_attrs *attrs,
@@ -271,26 +277,26 @@ struct vb2_buffer {
/**
* struct vb2_ops - driver-specific callbacks
*
- * @queue_setup: called from VIDIOC_REQBUFS and VIDIOC_CREATE_BUFS
+ * @queue_setup: called from %VIDIOC_REQBUFS and %VIDIOC_CREATE_BUFS
* handlers before memory allocation. It can be called
* twice: if the original number of requested buffers
* could not be allocated, then it will be called a
* second time with the actually allocated number of
* buffers to verify if that is OK.
* The driver should return the required number of buffers
- * in *num_buffers, the required number of planes per
- * buffer in *num_planes, the size of each plane should be
- * set in the sizes[] array and optional per-plane
- * allocator specific device in the alloc_devs[] array.
- * When called from VIDIOC_REQBUFS, *num_planes == 0, the
+ * in \*num_buffers, the required number of planes per
+ * buffer in \*num_planes, the size of each plane should be
+ * set in the sizes\[\] array and optional per-plane
+ * allocator specific device in the alloc_devs\[\] array.
+ * When called from %VIDIOC_REQBUFS, \*num_planes == 0, the
* driver has to use the currently configured format to
- * determine the plane sizes and *num_buffers is the total
+ * determine the plane sizes and \*num_buffers is the total
* number of buffers that are being allocated. When called
- * from VIDIOC_CREATE_BUFS, *num_planes != 0 and it
- * describes the requested number of planes and sizes[]
+ * from %VIDIOC_CREATE_BUFS, \*num_planes != 0 and it
+ * describes the requested number of planes and sizes\[\]
* contains the requested plane sizes. If either
- * *num_planes or the requested sizes are invalid callback
- * must return -EINVAL. In this case *num_buffers are
+ * \*num_planes or the requested sizes are invalid callback
+ * must return %-EINVAL. In this case \*num_buffers are
* being allocated additionally to q->num_buffers.
* @wait_prepare: release any locks taken while calling vb2 functions;
* it is called before an ioctl needs to wait for a new
@@ -305,11 +311,11 @@ struct vb2_buffer {
* initialization failure (return != 0) will prevent
* queue setup from completing successfully; optional.
* @buf_prepare: called every time the buffer is queued from userspace
- * and from the VIDIOC_PREPARE_BUF ioctl; drivers may
+ * and from the %VIDIOC_PREPARE_BUF ioctl; drivers may
* perform any initialization required before each
* hardware operation in this callback; drivers can
* access/modify the buffer here as it is still synced for
- * the CPU; drivers that support VIDIOC_CREATE_BUFS must
+ * the CPU; drivers that support %VIDIOC_CREATE_BUFS must
* also validate the buffer size; if an error is returned,
* the buffer will not be queued in driver; optional.
* @buf_finish: called before every dequeue of the buffer back to
@@ -317,23 +323,23 @@ struct vb2_buffer {
* can access/modify the buffer contents; drivers may
* perform any operations required before userspace
* accesses the buffer; optional. The buffer state can be
- * one of the following: DONE and ERROR occur while
- * streaming is in progress, and the PREPARED state occurs
+ * one of the following: %DONE and %ERROR occur while
+ * streaming is in progress, and the %PREPARED state occurs
* when the queue has been canceled and all pending
- * buffers are being returned to their default DEQUEUED
+ * buffers are being returned to their default %DEQUEUED
* state. Typically you only have to do something if the
- * state is VB2_BUF_STATE_DONE, since in all other cases
+ * state is %VB2_BUF_STATE_DONE, since in all other cases
* the buffer contents will be ignored anyway.
* @buf_cleanup: called once before the buffer is freed; drivers may
* perform any additional cleanup; optional.
* @start_streaming: called once to enter 'streaming' state; the driver may
- * receive buffers with @buf_queue callback before
- * @start_streaming is called; the driver gets the number
- * of already queued buffers in count parameter; driver
- * can return an error if hardware fails, in that case all
- * buffers that have been already given by the @buf_queue
- * callback are to be returned by the driver by calling
- * @vb2_buffer_done(VB2_BUF_STATE_QUEUED).
+ * receive buffers with @buf_queue callback
+ * before @start_streaming is called; the driver gets the
+ * number of already queued buffers in count parameter;
+ * driver can return an error if hardware fails, in that
+ * case all buffers that have been already given by
+ * the @buf_queue callback are to be returned by the driver
+ * by calling @vb2_buffer_done\(%VB2_BUF_STATE_QUEUED\).
* If you need a minimum number of buffers before you can
* start streaming, then set @min_buffers_needed in the
* vb2_queue structure. If that is non-zero then
@@ -341,16 +347,16 @@ struct vb2_buffer {
* many buffers have been queued up by userspace.
* @stop_streaming: called when 'streaming' state must be disabled; driver
* should stop any DMA transactions or wait until they
- * finish and give back all buffers it got from buf_queue()
- * callback by calling @vb2_buffer_done() with either
- * VB2_BUF_STATE_DONE or VB2_BUF_STATE_ERROR; may use
+ * finish and give back all buffers it got from &buf_queue
+ * callback by calling @vb2_buffer_done\(\) with either
+ * %VB2_BUF_STATE_DONE or %VB2_BUF_STATE_ERROR; may use
* vb2_wait_for_all_buffers() function
* @buf_queue: passes buffer vb to the driver; driver may start
* hardware operation on this buffer; driver should give
* the buffer back by calling vb2_buffer_done() function;
- * it is allways called after calling STREAMON ioctl;
+ * it is allways called after calling %VIDIOC_STREAMON ioctl;
* might be called before start_streaming callback if user
- * pre-queued buffers before calling STREAMON.
+ * pre-queued buffers before calling %VIDIOC_STREAMON.
*/
struct vb2_ops {
int (*queue_setup)(struct vb2_queue *q,