* [PATCH 01/15] [media] mc-core.rst: fix a warning about an internal routine
2016-09-08 21:37 [PATCH 00/15] Fix another set of nitpick warnings Mauro Carvalho Chehab
@ 2016-09-08 21:37 ` Mauro Carvalho Chehab
2016-09-08 21:37 ` [PATCH 02/15] [media] v4l2-mem2mem.h: move descriptions from .c file Mauro Carvalho Chehab
` (13 subsequent siblings)
14 siblings, 0 replies; 16+ messages in thread
From: Mauro Carvalho Chehab @ 2016-09-08 21:37 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Mauro Carvalho Chehab
Fix this warning:
Documentation/media/kapi/mc-core.rst:97: WARNING: c:func reference target not found: media_devnode_release
The media_device_release() is a function internal to media-devnode.c,
and not exported elsewhere. So, we can't cross-reference it here.
Make it explicit at the documentation.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
include/media/media-devnode.h | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/include/media/media-devnode.h b/include/media/media-devnode.h
index 972168e90413..cd23e915764c 100644
--- a/include/media/media-devnode.h
+++ b/include/media/media-devnode.h
@@ -76,7 +76,8 @@ struct media_file_operations {
* @parent: parent device
* @minor: device node minor number
* @flags: flags, combination of the ``MEDIA_FLAG_*`` constants
- * @release: release callback called at the end of media_devnode_release()
+ * @release: release callback called at the end of ``media_devnode_release()``
+ * routine at media-device.c.
*
* This structure represents a media-related device node.
*
--
2.7.4
^ permalink raw reply related [flat|nested] 16+ messages in thread* [PATCH 02/15] [media] v4l2-mem2mem.h: move descriptions from .c file
2016-09-08 21:37 [PATCH 00/15] Fix another set of nitpick warnings Mauro Carvalho Chehab
2016-09-08 21:37 ` [PATCH 01/15] [media] mc-core.rst: fix a warning about an internal routine Mauro Carvalho Chehab
@ 2016-09-08 21:37 ` Mauro Carvalho Chehab
2016-09-08 21:37 ` [PATCH 03/15] [media] v4l2-mem2mem.h: document function arguments Mauro Carvalho Chehab
` (12 subsequent siblings)
14 siblings, 0 replies; 16+ messages in thread
From: Mauro Carvalho Chehab @ 2016-09-08 21:37 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab,
Mauro Carvalho Chehab, Hans Verkuil, Inki Dae, Seung-Woo Kim,
Junghak Sung, Zahari Doychev
Several routines are somewhat documented at v4l2-mem2mem.c
file. Move what's there to the header file.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
drivers/media/v4l2-core/v4l2-mem2mem.c | 128 +-------------------------------
include/media/v4l2-mem2mem.h | 132 +++++++++++++++++++++++++++++++++
2 files changed, 133 insertions(+), 127 deletions(-)
diff --git a/drivers/media/v4l2-core/v4l2-mem2mem.c b/drivers/media/v4l2-core/v4l2-mem2mem.c
index 61d56c940f80..6bc27e7b2a33 100644
--- a/drivers/media/v4l2-core/v4l2-mem2mem.c
+++ b/drivers/media/v4l2-core/v4l2-mem2mem.c
@@ -76,9 +76,6 @@ static struct v4l2_m2m_queue_ctx *get_queue_ctx(struct v4l2_m2m_ctx *m2m_ctx,
return &m2m_ctx->cap_q_ctx;
}
-/**
- * v4l2_m2m_get_vq() - return vb2_queue for the given type
- */
struct vb2_queue *v4l2_m2m_get_vq(struct v4l2_m2m_ctx *m2m_ctx,
enum v4l2_buf_type type)
{
@@ -92,9 +89,6 @@ struct vb2_queue *v4l2_m2m_get_vq(struct v4l2_m2m_ctx *m2m_ctx,
}
EXPORT_SYMBOL(v4l2_m2m_get_vq);
-/**
- * v4l2_m2m_next_buf() - return next buffer from the list of ready buffers
- */
void *v4l2_m2m_next_buf(struct v4l2_m2m_queue_ctx *q_ctx)
{
struct v4l2_m2m_buffer *b;
@@ -113,10 +107,6 @@ void *v4l2_m2m_next_buf(struct v4l2_m2m_queue_ctx *q_ctx)
}
EXPORT_SYMBOL_GPL(v4l2_m2m_next_buf);
-/**
- * v4l2_m2m_buf_remove() - take off a buffer from the list of ready buffers and
- * return it
- */
void *v4l2_m2m_buf_remove(struct v4l2_m2m_queue_ctx *q_ctx)
{
struct v4l2_m2m_buffer *b;
@@ -140,10 +130,6 @@ EXPORT_SYMBOL_GPL(v4l2_m2m_buf_remove);
* Scheduling handlers
*/
-/**
- * v4l2_m2m_get_curr_priv() - return driver private data for the currently
- * running instance or NULL if no instance is running
- */
void *v4l2_m2m_get_curr_priv(struct v4l2_m2m_dev *m2m_dev)
{
unsigned long flags;
@@ -188,26 +174,6 @@ static void v4l2_m2m_try_run(struct v4l2_m2m_dev *m2m_dev)
m2m_dev->m2m_ops->device_run(m2m_dev->curr_ctx->priv);
}
-/**
- * v4l2_m2m_try_schedule() - check whether an instance is ready to be added to
- * the pending job queue and add it if so.
- * @m2m_ctx: m2m context assigned to the instance to be checked
- *
- * There are three basic requirements an instance has to meet to be able to run:
- * 1) at least one source buffer has to be queued,
- * 2) at least one destination buffer has to be queued,
- * 3) streaming has to be on.
- *
- * If a queue is buffered (for example a decoder hardware ringbuffer that has
- * to be drained before doing streamoff), allow scheduling without v4l2 buffers
- * on that queue.
- *
- * There may also be additional, custom requirements. In such case the driver
- * should supply a custom callback (job_ready in v4l2_m2m_ops) that should
- * return 1 if the instance is ready.
- * An example of the above could be an instance that requires more than one
- * src/dst buffer per transaction.
- */
void v4l2_m2m_try_schedule(struct v4l2_m2m_ctx *m2m_ctx)
{
struct v4l2_m2m_dev *m2m_dev;
@@ -311,18 +277,6 @@ static void v4l2_m2m_cancel_job(struct v4l2_m2m_ctx *m2m_ctx)
}
}
-/**
- * v4l2_m2m_job_finish() - inform the framework that a job has been finished
- * and have it clean up
- *
- * Called by a driver to yield back the device after it has finished with it.
- * Should be called as soon as possible after reaching a state which allows
- * other instances to take control of the device.
- *
- * This function has to be called only after device_run() callback has been
- * called on the driver. To prevent recursion, it should not be called directly
- * from the device_run() callback though.
- */
void v4l2_m2m_job_finish(struct v4l2_m2m_dev *m2m_dev,
struct v4l2_m2m_ctx *m2m_ctx)
{
@@ -350,9 +304,6 @@ void v4l2_m2m_job_finish(struct v4l2_m2m_dev *m2m_dev,
}
EXPORT_SYMBOL(v4l2_m2m_job_finish);
-/**
- * v4l2_m2m_reqbufs() - multi-queue-aware REQBUFS multiplexer
- */
int v4l2_m2m_reqbufs(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
struct v4l2_requestbuffers *reqbufs)
{
@@ -370,11 +321,6 @@ int v4l2_m2m_reqbufs(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
}
EXPORT_SYMBOL_GPL(v4l2_m2m_reqbufs);
-/**
- * v4l2_m2m_querybuf() - multi-queue-aware QUERYBUF multiplexer
- *
- * See v4l2_m2m_mmap() documentation for details.
- */
int v4l2_m2m_querybuf(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
struct v4l2_buffer *buf)
{
@@ -400,10 +346,6 @@ int v4l2_m2m_querybuf(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
}
EXPORT_SYMBOL_GPL(v4l2_m2m_querybuf);
-/**
- * v4l2_m2m_qbuf() - enqueue a source or destination buffer, depending on
- * the type
- */
int v4l2_m2m_qbuf(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
struct v4l2_buffer *buf)
{
@@ -419,10 +361,6 @@ int v4l2_m2m_qbuf(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
}
EXPORT_SYMBOL_GPL(v4l2_m2m_qbuf);
-/**
- * v4l2_m2m_dqbuf() - dequeue a source or destination buffer, depending on
- * the type
- */
int v4l2_m2m_dqbuf(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
struct v4l2_buffer *buf)
{
@@ -433,10 +371,6 @@ int v4l2_m2m_dqbuf(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
}
EXPORT_SYMBOL_GPL(v4l2_m2m_dqbuf);
-/**
- * v4l2_m2m_prepare_buf() - prepare a source or destination buffer, depending on
- * the type
- */
int v4l2_m2m_prepare_buf(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
struct v4l2_buffer *buf)
{
@@ -452,10 +386,6 @@ int v4l2_m2m_prepare_buf(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
}
EXPORT_SYMBOL_GPL(v4l2_m2m_prepare_buf);
-/**
- * v4l2_m2m_create_bufs() - create a source or destination buffer, depending
- * on the type
- */
int v4l2_m2m_create_bufs(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
struct v4l2_create_buffers *create)
{
@@ -466,10 +396,6 @@ int v4l2_m2m_create_bufs(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
}
EXPORT_SYMBOL_GPL(v4l2_m2m_create_bufs);
-/**
- * v4l2_m2m_expbuf() - export a source or destination buffer, depending on
- * the type
- */
int v4l2_m2m_expbuf(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
struct v4l2_exportbuffer *eb)
{
@@ -479,9 +405,7 @@ int v4l2_m2m_expbuf(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
return vb2_expbuf(vq, eb);
}
EXPORT_SYMBOL_GPL(v4l2_m2m_expbuf);
-/**
- * v4l2_m2m_streamon() - turn on streaming for a video queue
- */
+
int v4l2_m2m_streamon(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
enum v4l2_buf_type type)
{
@@ -497,9 +421,6 @@ int v4l2_m2m_streamon(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
}
EXPORT_SYMBOL_GPL(v4l2_m2m_streamon);
-/**
- * v4l2_m2m_streamoff() - turn off streaming for a video queue
- */
int v4l2_m2m_streamoff(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
enum v4l2_buf_type type)
{
@@ -540,14 +461,6 @@ int v4l2_m2m_streamoff(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
}
EXPORT_SYMBOL_GPL(v4l2_m2m_streamoff);
-/**
- * v4l2_m2m_poll() - poll replacement, for destination buffers only
- *
- * Call from the driver's poll() function. Will poll both queues. If a buffer
- * is available to dequeue (with dqbuf) from the source queue, this will
- * indicate that a non-blocking write can be performed, while read will be
- * returned in case of the destination queue.
- */
unsigned int v4l2_m2m_poll(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
struct poll_table_struct *wait)
{
@@ -626,16 +539,6 @@ end:
}
EXPORT_SYMBOL_GPL(v4l2_m2m_poll);
-/**
- * v4l2_m2m_mmap() - source and destination queues-aware mmap multiplexer
- *
- * Call from driver's mmap() function. Will handle mmap() for both queues
- * seamlessly for videobuffer, which will receive normal per-queue offsets and
- * proper videobuf queue pointers. The differentiation is made outside videobuf
- * by adding a predefined offset to buffers from one of the queues and
- * subtracting it before passing it back to videobuf. Only drivers (and
- * thus applications) receive modified offsets.
- */
int v4l2_m2m_mmap(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
struct vm_area_struct *vma)
{
@@ -653,11 +556,6 @@ int v4l2_m2m_mmap(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
}
EXPORT_SYMBOL(v4l2_m2m_mmap);
-/**
- * v4l2_m2m_init() - initialize per-driver m2m data
- *
- * Usually called from driver's probe() function.
- */
struct v4l2_m2m_dev *v4l2_m2m_init(const struct v4l2_m2m_ops *m2m_ops)
{
struct v4l2_m2m_dev *m2m_dev;
@@ -679,26 +577,12 @@ struct v4l2_m2m_dev *v4l2_m2m_init(const struct v4l2_m2m_ops *m2m_ops)
}
EXPORT_SYMBOL_GPL(v4l2_m2m_init);
-/**
- * v4l2_m2m_release() - cleans up and frees a m2m_dev structure
- *
- * Usually called from driver's remove() function.
- */
void v4l2_m2m_release(struct v4l2_m2m_dev *m2m_dev)
{
kfree(m2m_dev);
}
EXPORT_SYMBOL_GPL(v4l2_m2m_release);
-/**
- * v4l2_m2m_ctx_init() - allocate and initialize a m2m context
- * @priv - driver's instance private data
- * @m2m_dev - a previously initialized m2m_dev struct
- * @vq_init - a callback for queue type-specific initialization function to be
- * used for initializing videobuf_queues
- *
- * Usually called from driver's open() function.
- */
struct v4l2_m2m_ctx *v4l2_m2m_ctx_init(struct v4l2_m2m_dev *m2m_dev,
void *drv_priv,
int (*queue_init)(void *priv, struct vb2_queue *src_vq, struct vb2_queue *dst_vq))
@@ -744,11 +628,6 @@ err:
}
EXPORT_SYMBOL_GPL(v4l2_m2m_ctx_init);
-/**
- * v4l2_m2m_ctx_release() - release m2m context
- *
- * Usually called from driver's release() function.
- */
void v4l2_m2m_ctx_release(struct v4l2_m2m_ctx *m2m_ctx)
{
/* wait until the current context is dequeued from job_queue */
@@ -761,11 +640,6 @@ void v4l2_m2m_ctx_release(struct v4l2_m2m_ctx *m2m_ctx)
}
EXPORT_SYMBOL_GPL(v4l2_m2m_ctx_release);
-/**
- * v4l2_m2m_buf_queue() - add a buffer to the proper ready buffers list.
- *
- * Call from buf_queue(), videobuf_queue_ops callback.
- */
void v4l2_m2m_buf_queue(struct v4l2_m2m_ctx *m2m_ctx,
struct vb2_v4l2_buffer *vbuf)
{
diff --git a/include/media/v4l2-mem2mem.h b/include/media/v4l2-mem2mem.h
index 5a9597dd1ee0..e5449a2c8475 100644
--- a/include/media/v4l2-mem2mem.h
+++ b/include/media/v4l2-mem2mem.h
@@ -94,13 +94,52 @@ struct v4l2_m2m_buffer {
struct list_head list;
};
+/**
+ * v4l2_m2m_get_curr_priv() - return driver private data for the currently
+ * running instance or NULL if no instance is running
+ */
void *v4l2_m2m_get_curr_priv(struct v4l2_m2m_dev *m2m_dev);
+/**
+ * v4l2_m2m_get_vq() - return vb2_queue for the given type
+ */
struct vb2_queue *v4l2_m2m_get_vq(struct v4l2_m2m_ctx *m2m_ctx,
enum v4l2_buf_type type);
+/**
+ * v4l2_m2m_try_schedule() - check whether an instance is ready to be added to
+ * the pending job queue and add it if so.
+ * @m2m_ctx: m2m context assigned to the instance to be checked
+ *
+ * There are three basic requirements an instance has to meet to be able to run:
+ * 1) at least one source buffer has to be queued,
+ * 2) at least one destination buffer has to be queued,
+ * 3) streaming has to be on.
+ *
+ * If a queue is buffered (for example a decoder hardware ringbuffer that has
+ * to be drained before doing streamoff), allow scheduling without v4l2 buffers
+ * on that queue.
+ *
+ * There may also be additional, custom requirements. In such case the driver
+ * should supply a custom callback (job_ready in v4l2_m2m_ops) that should
+ * return 1 if the instance is ready.
+ * An example of the above could be an instance that requires more than one
+ * src/dst buffer per transaction.
+ */
void v4l2_m2m_try_schedule(struct v4l2_m2m_ctx *m2m_ctx);
+/**
+ * v4l2_m2m_job_finish() - inform the framework that a job has been finished
+ * and have it clean up
+ *
+ * Called by a driver to yield back the device after it has finished with it.
+ * Should be called as soon as possible after reaching a state which allows
+ * other instances to take control of the device.
+ *
+ * This function has to be called only after device_run() callback has been
+ * called on the driver. To prevent recursion, it should not be called directly
+ * from the device_run() callback though.
+ */
void v4l2_m2m_job_finish(struct v4l2_m2m_dev *m2m_dev,
struct v4l2_m2m_ctx *m2m_ctx);
@@ -110,38 +149,114 @@ v4l2_m2m_buf_done(struct vb2_v4l2_buffer *buf, enum vb2_buffer_state state)
vb2_buffer_done(&buf->vb2_buf, state);
}
+/**
+ * v4l2_m2m_reqbufs() - multi-queue-aware REQBUFS multiplexer
+ */
int v4l2_m2m_reqbufs(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
struct v4l2_requestbuffers *reqbufs);
+/**
+ * v4l2_m2m_querybuf() - multi-queue-aware QUERYBUF multiplexer
+ *
+ * See v4l2_m2m_mmap() documentation for details.
+ */
int v4l2_m2m_querybuf(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
struct v4l2_buffer *buf);
+/**
+ * v4l2_m2m_qbuf() - enqueue a source or destination buffer, depending on
+ * the type
+ */
int v4l2_m2m_qbuf(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
struct v4l2_buffer *buf);
+
+/**
+ * v4l2_m2m_dqbuf() - dequeue a source or destination buffer, depending on
+ * the type
+ */
int v4l2_m2m_dqbuf(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
struct v4l2_buffer *buf);
+
+/**
+ * v4l2_m2m_prepare_buf() - prepare a source or destination buffer, depending on
+ * the type
+ */
int v4l2_m2m_prepare_buf(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
struct v4l2_buffer *buf);
+
+/**
+ * v4l2_m2m_create_bufs() - create a source or destination buffer, depending
+ * on the type
+ */
int v4l2_m2m_create_bufs(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
struct v4l2_create_buffers *create);
+/**
+ * v4l2_m2m_expbuf() - export a source or destination buffer, depending on
+ * the type
+ */
int v4l2_m2m_expbuf(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
struct v4l2_exportbuffer *eb);
+/**
+ * v4l2_m2m_streamon() - turn on streaming for a video queue
+ */
int v4l2_m2m_streamon(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
enum v4l2_buf_type type);
+
+/**
+ * v4l2_m2m_streamoff() - turn off streaming for a video queue
+ */
int v4l2_m2m_streamoff(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
enum v4l2_buf_type type);
+/**
+ * v4l2_m2m_poll() - poll replacement, for destination buffers only
+ *
+ * Call from the driver's poll() function. Will poll both queues. If a buffer
+ * is available to dequeue (with dqbuf) from the source queue, this will
+ * indicate that a non-blocking write can be performed, while read will be
+ * returned in case of the destination queue.
+ */
unsigned int v4l2_m2m_poll(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
struct poll_table_struct *wait);
+/**
+ * v4l2_m2m_mmap() - source and destination queues-aware mmap multiplexer
+ *
+ * Call from driver's mmap() function. Will handle mmap() for both queues
+ * seamlessly for videobuffer, which will receive normal per-queue offsets and
+ * proper videobuf queue pointers. The differentiation is made outside videobuf
+ * by adding a predefined offset to buffers from one of the queues and
+ * subtracting it before passing it back to videobuf. Only drivers (and
+ * thus applications) receive modified offsets.
+ */
int v4l2_m2m_mmap(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
struct vm_area_struct *vma);
+/**
+ * v4l2_m2m_init() - initialize per-driver m2m data
+ *
+ * Usually called from driver's probe() function.
+ */
struct v4l2_m2m_dev *v4l2_m2m_init(const struct v4l2_m2m_ops *m2m_ops);
+
+/**
+ * v4l2_m2m_release() - cleans up and frees a m2m_dev structure
+ *
+ * Usually called from driver's remove() function.
+ */
void v4l2_m2m_release(struct v4l2_m2m_dev *m2m_dev);
+/**
+ * v4l2_m2m_ctx_init() - allocate and initialize a m2m context
+ * @priv - driver's instance private data
+ * @m2m_dev - a previously initialized m2m_dev struct
+ * @vq_init - a callback for queue type-specific initialization function to be
+ * used for initializing videobuf_queues
+ *
+ * Usually called from driver's open() function.
+ */
struct v4l2_m2m_ctx *v4l2_m2m_ctx_init(struct v4l2_m2m_dev *m2m_dev,
void *drv_priv,
int (*queue_init)(void *priv, struct vb2_queue *src_vq, struct vb2_queue *dst_vq));
@@ -158,8 +273,18 @@ static inline void v4l2_m2m_set_dst_buffered(struct v4l2_m2m_ctx *m2m_ctx,
m2m_ctx->cap_q_ctx.buffered = buffered;
}
+/**
+ * v4l2_m2m_ctx_release() - release m2m context
+ *
+ * Usually called from driver's release() function.
+ */
void v4l2_m2m_ctx_release(struct v4l2_m2m_ctx *m2m_ctx);
+/**
+ * v4l2_m2m_buf_queue() - add a buffer to the proper ready buffers list.
+ *
+ * Call from buf_queue(), videobuf_queue_ops callback.
+ */
void v4l2_m2m_buf_queue(struct v4l2_m2m_ctx *m2m_ctx,
struct vb2_v4l2_buffer *vbuf);
@@ -187,6 +312,9 @@ unsigned int v4l2_m2m_num_dst_bufs_ready(struct v4l2_m2m_ctx *m2m_ctx)
return m2m_ctx->cap_q_ctx.num_rdy;
}
+/**
+ * v4l2_m2m_next_buf() - return next buffer from the list of ready buffers
+ */
void *v4l2_m2m_next_buf(struct v4l2_m2m_queue_ctx *q_ctx);
/**
@@ -233,6 +361,10 @@ struct vb2_queue *v4l2_m2m_get_dst_vq(struct v4l2_m2m_ctx *m2m_ctx)
return &m2m_ctx->cap_q_ctx.q;
}
+/**
+ * v4l2_m2m_buf_remove() - take off a buffer from the list of ready buffers and
+ * return it
+ */
void *v4l2_m2m_buf_remove(struct v4l2_m2m_queue_ctx *q_ctx);
/**
--
2.7.4
^ permalink raw reply related [flat|nested] 16+ messages in thread* [PATCH 03/15] [media] v4l2-mem2mem.h: document function arguments
2016-09-08 21:37 [PATCH 00/15] Fix another set of nitpick warnings Mauro Carvalho Chehab
2016-09-08 21:37 ` [PATCH 01/15] [media] mc-core.rst: fix a warning about an internal routine Mauro Carvalho Chehab
2016-09-08 21:37 ` [PATCH 02/15] [media] v4l2-mem2mem.h: move descriptions from .c file Mauro Carvalho Chehab
@ 2016-09-08 21:37 ` Mauro Carvalho Chehab
2016-09-08 21:37 ` [PATCH 04/15] [media] v4l2-mem2mem.h: document the public structures Mauro Carvalho Chehab
` (11 subsequent siblings)
14 siblings, 0 replies; 16+ messages in thread
From: Mauro Carvalho Chehab @ 2016-09-08 21:37 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Mauro Carvalho Chehab
There are lots of troubles with the function arguments on this
file. Fix them.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
include/media/v4l2-mem2mem.h | 93 +++++++++++++++++++++++++++++++++++++-------
1 file changed, 80 insertions(+), 13 deletions(-)
diff --git a/include/media/v4l2-mem2mem.h b/include/media/v4l2-mem2mem.h
index e5449a2c8475..78eadca27a21 100644
--- a/include/media/v4l2-mem2mem.h
+++ b/include/media/v4l2-mem2mem.h
@@ -97,11 +97,16 @@ struct v4l2_m2m_buffer {
/**
* v4l2_m2m_get_curr_priv() - return driver private data for the currently
* running instance or NULL if no instance is running
+ *
+ * @m2m_dev: pointer to struct &v4l2_m2m_dev
*/
void *v4l2_m2m_get_curr_priv(struct v4l2_m2m_dev *m2m_dev);
/**
* v4l2_m2m_get_vq() - return vb2_queue for the given type
+ *
+ * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
+ * @type: type of the V4L2 buffer, as defined by enum &v4l2_buf_type
*/
struct vb2_queue *v4l2_m2m_get_vq(struct v4l2_m2m_ctx *m2m_ctx,
enum v4l2_buf_type type);
@@ -109,7 +114,8 @@ struct vb2_queue *v4l2_m2m_get_vq(struct v4l2_m2m_ctx *m2m_ctx,
/**
* v4l2_m2m_try_schedule() - check whether an instance is ready to be added to
* the pending job queue and add it if so.
- * @m2m_ctx: m2m context assigned to the instance to be checked
+ *
+ * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
*
* There are three basic requirements an instance has to meet to be able to run:
* 1) at least one source buffer has to be queued,
@@ -132,6 +138,9 @@ void v4l2_m2m_try_schedule(struct v4l2_m2m_ctx *m2m_ctx);
* v4l2_m2m_job_finish() - inform the framework that a job has been finished
* and have it clean up
*
+ * @m2m_dev: pointer to struct &v4l2_m2m_dev
+ * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
+ *
* Called by a driver to yield back the device after it has finished with it.
* Should be called as soon as possible after reaching a state which allows
* other instances to take control of the device.
@@ -151,6 +160,10 @@ v4l2_m2m_buf_done(struct vb2_v4l2_buffer *buf, enum vb2_buffer_state state)
/**
* v4l2_m2m_reqbufs() - multi-queue-aware REQBUFS multiplexer
+ *
+ * @file: pointer to struct &file
+ * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
+ * @reqbufs: pointer to struct &v4l2_requestbuffers
*/
int v4l2_m2m_reqbufs(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
struct v4l2_requestbuffers *reqbufs);
@@ -158,6 +171,10 @@ int v4l2_m2m_reqbufs(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
/**
* v4l2_m2m_querybuf() - multi-queue-aware QUERYBUF multiplexer
*
+ * @file: pointer to struct &file
+ * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
+ * @buf: pointer to struct &v4l2_buffer
+ *
* See v4l2_m2m_mmap() documentation for details.
*/
int v4l2_m2m_querybuf(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
@@ -166,6 +183,10 @@ int v4l2_m2m_querybuf(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
/**
* v4l2_m2m_qbuf() - enqueue a source or destination buffer, depending on
* the type
+ *
+ * @file: pointer to struct &file
+ * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
+ * @buf: pointer to struct &v4l2_buffer
*/
int v4l2_m2m_qbuf(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
struct v4l2_buffer *buf);
@@ -173,6 +194,10 @@ int v4l2_m2m_qbuf(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
/**
* v4l2_m2m_dqbuf() - dequeue a source or destination buffer, depending on
* the type
+ *
+ * @file: pointer to struct &file
+ * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
+ * @buf: pointer to struct &v4l2_buffer
*/
int v4l2_m2m_dqbuf(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
struct v4l2_buffer *buf);
@@ -180,6 +205,10 @@ int v4l2_m2m_dqbuf(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
/**
* v4l2_m2m_prepare_buf() - prepare a source or destination buffer, depending on
* the type
+ *
+ * @file: pointer to struct &file
+ * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
+ * @buf: pointer to struct &v4l2_buffer
*/
int v4l2_m2m_prepare_buf(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
struct v4l2_buffer *buf);
@@ -187,6 +216,10 @@ int v4l2_m2m_prepare_buf(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
/**
* v4l2_m2m_create_bufs() - create a source or destination buffer, depending
* on the type
+ *
+ * @file: pointer to struct &file
+ * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
+ * @create: pointer to struct &v4l2_create_buffers
*/
int v4l2_m2m_create_bufs(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
struct v4l2_create_buffers *create);
@@ -194,18 +227,30 @@ int v4l2_m2m_create_bufs(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
/**
* v4l2_m2m_expbuf() - export a source or destination buffer, depending on
* the type
+ *
+ * @file: pointer to struct &file
+ * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
+ * @eb: pointer to struct &v4l2_exportbuffer
*/
int v4l2_m2m_expbuf(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
struct v4l2_exportbuffer *eb);
/**
* v4l2_m2m_streamon() - turn on streaming for a video queue
+ *
+ * @file: pointer to struct &file
+ * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
+ * @type: type of the V4L2 buffer, as defined by enum &v4l2_buf_type
*/
int v4l2_m2m_streamon(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
enum v4l2_buf_type type);
/**
* v4l2_m2m_streamoff() - turn off streaming for a video queue
+ *
+ * @file: pointer to struct &file
+ * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
+ * @type: type of the V4L2 buffer, as defined by enum &v4l2_buf_type
*/
int v4l2_m2m_streamoff(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
enum v4l2_buf_type type);
@@ -213,6 +258,10 @@ int v4l2_m2m_streamoff(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
/**
* v4l2_m2m_poll() - poll replacement, for destination buffers only
*
+ * @file: pointer to struct &file
+ * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
+ * @wait: pointer to struct &poll_table_struct
+ *
* Call from the driver's poll() function. Will poll both queues. If a buffer
* is available to dequeue (with dqbuf) from the source queue, this will
* indicate that a non-blocking write can be performed, while read will be
@@ -224,6 +273,10 @@ unsigned int v4l2_m2m_poll(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
/**
* v4l2_m2m_mmap() - source and destination queues-aware mmap multiplexer
*
+ * @file: pointer to struct &file
+ * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
+ * @vma: pointer to struct &vm_area_struct
+ *
* Call from driver's mmap() function. Will handle mmap() for both queues
* seamlessly for videobuffer, which will receive normal per-queue offsets and
* proper videobuf queue pointers. The differentiation is made outside videobuf
@@ -237,6 +290,8 @@ int v4l2_m2m_mmap(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
/**
* v4l2_m2m_init() - initialize per-driver m2m data
*
+ * @m2m_ops: pointer to struct v4l2_m2m_ops
+ *
* Usually called from driver's probe() function.
*/
struct v4l2_m2m_dev *v4l2_m2m_init(const struct v4l2_m2m_ops *m2m_ops);
@@ -244,16 +299,19 @@ struct v4l2_m2m_dev *v4l2_m2m_init(const struct v4l2_m2m_ops *m2m_ops);
/**
* v4l2_m2m_release() - cleans up and frees a m2m_dev structure
*
+ * @m2m_dev: pointer to struct &v4l2_m2m_dev
+ *
* Usually called from driver's remove() function.
*/
void v4l2_m2m_release(struct v4l2_m2m_dev *m2m_dev);
/**
* v4l2_m2m_ctx_init() - allocate and initialize a m2m context
- * @priv - driver's instance private data
- * @m2m_dev - a previously initialized m2m_dev struct
- * @vq_init - a callback for queue type-specific initialization function to be
- * used for initializing videobuf_queues
+ *
+ * @m2m_dev: a previously initialized m2m_dev struct
+ * @drv_priv: driver's instance private data
+ * @queue_init: a callback for queue type-specific initialization function
+ * to be used for initializing videobuf_queues
*
* Usually called from driver's open() function.
*/
@@ -276,6 +334,8 @@ static inline void v4l2_m2m_set_dst_buffered(struct v4l2_m2m_ctx *m2m_ctx,
/**
* v4l2_m2m_ctx_release() - release m2m context
*
+ * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
+ *
* Usually called from driver's release() function.
*/
void v4l2_m2m_ctx_release(struct v4l2_m2m_ctx *m2m_ctx);
@@ -283,6 +343,9 @@ void v4l2_m2m_ctx_release(struct v4l2_m2m_ctx *m2m_ctx);
/**
* v4l2_m2m_buf_queue() - add a buffer to the proper ready buffers list.
*
+ * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
+ * @vbuf: pointer to struct &vb2_v4l2_buffer
+ *
* Call from buf_queue(), videobuf_queue_ops callback.
*/
void v4l2_m2m_buf_queue(struct v4l2_m2m_ctx *m2m_ctx,
@@ -292,7 +355,7 @@ void v4l2_m2m_buf_queue(struct v4l2_m2m_ctx *m2m_ctx,
* v4l2_m2m_num_src_bufs_ready() - return the number of source buffers ready for
* use
*
- * @m2m_ctx: pointer to struct v4l2_m2m_ctx
+ * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
*/
static inline
unsigned int v4l2_m2m_num_src_bufs_ready(struct v4l2_m2m_ctx *m2m_ctx)
@@ -304,7 +367,7 @@ unsigned int v4l2_m2m_num_src_bufs_ready(struct v4l2_m2m_ctx *m2m_ctx)
* v4l2_m2m_num_src_bufs_ready() - return the number of destination buffers
* ready for use
*
- * @m2m_ctx: pointer to struct v4l2_m2m_ctx
+ * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
*/
static inline
unsigned int v4l2_m2m_num_dst_bufs_ready(struct v4l2_m2m_ctx *m2m_ctx)
@@ -314,6 +377,8 @@ unsigned int v4l2_m2m_num_dst_bufs_ready(struct v4l2_m2m_ctx *m2m_ctx)
/**
* v4l2_m2m_next_buf() - return next buffer from the list of ready buffers
+ *
+ * @q_ctx: pointer to struct @v4l2_m2m_queue_ctx
*/
void *v4l2_m2m_next_buf(struct v4l2_m2m_queue_ctx *q_ctx);
@@ -321,7 +386,7 @@ void *v4l2_m2m_next_buf(struct v4l2_m2m_queue_ctx *q_ctx);
* v4l2_m2m_next_src_buf() - return next source buffer from the list of ready
* buffers
*
- * @m2m_ctx: pointer to struct v4l2_m2m_ctx
+ * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
*/
static inline void *v4l2_m2m_next_src_buf(struct v4l2_m2m_ctx *m2m_ctx)
{
@@ -332,7 +397,7 @@ static inline void *v4l2_m2m_next_src_buf(struct v4l2_m2m_ctx *m2m_ctx)
* v4l2_m2m_next_dst_buf() - return next destination buffer from the list of
* ready buffers
*
- * @m2m_ctx: pointer to struct v4l2_m2m_ctx
+ * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
*/
static inline void *v4l2_m2m_next_dst_buf(struct v4l2_m2m_ctx *m2m_ctx)
{
@@ -342,7 +407,7 @@ static inline void *v4l2_m2m_next_dst_buf(struct v4l2_m2m_ctx *m2m_ctx)
/**
* v4l2_m2m_get_src_vq() - return vb2_queue for source buffers
*
- * @m2m_ctx: pointer to struct v4l2_m2m_ctx
+ * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
*/
static inline
struct vb2_queue *v4l2_m2m_get_src_vq(struct v4l2_m2m_ctx *m2m_ctx)
@@ -353,7 +418,7 @@ struct vb2_queue *v4l2_m2m_get_src_vq(struct v4l2_m2m_ctx *m2m_ctx)
/**
* v4l2_m2m_get_dst_vq() - return vb2_queue for destination buffers
*
- * @m2m_ctx: pointer to struct v4l2_m2m_ctx
+ * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
*/
static inline
struct vb2_queue *v4l2_m2m_get_dst_vq(struct v4l2_m2m_ctx *m2m_ctx)
@@ -364,6 +429,8 @@ struct vb2_queue *v4l2_m2m_get_dst_vq(struct v4l2_m2m_ctx *m2m_ctx)
/**
* v4l2_m2m_buf_remove() - take off a buffer from the list of ready buffers and
* return it
+ *
+ * @q_ctx: pointer to struct @v4l2_m2m_queue_ctx
*/
void *v4l2_m2m_buf_remove(struct v4l2_m2m_queue_ctx *q_ctx);
@@ -371,7 +438,7 @@ void *v4l2_m2m_buf_remove(struct v4l2_m2m_queue_ctx *q_ctx);
* v4l2_m2m_src_buf_remove() - take off a source buffer from the list of ready
* buffers and return it
*
- * @m2m_ctx: pointer to struct v4l2_m2m_ctx
+ * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
*/
static inline void *v4l2_m2m_src_buf_remove(struct v4l2_m2m_ctx *m2m_ctx)
{
@@ -382,7 +449,7 @@ static inline void *v4l2_m2m_src_buf_remove(struct v4l2_m2m_ctx *m2m_ctx)
* v4l2_m2m_dst_buf_remove() - take off a destination buffer from the list of
* ready buffers and return it
*
- * @m2m_ctx: pointer to struct v4l2_m2m_ctx
+ * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
*/
static inline void *v4l2_m2m_dst_buf_remove(struct v4l2_m2m_ctx *m2m_ctx)
{
--
2.7.4
^ permalink raw reply related [flat|nested] 16+ messages in thread* [PATCH 04/15] [media] v4l2-mem2mem.h: document the public structures
2016-09-08 21:37 [PATCH 00/15] Fix another set of nitpick warnings Mauro Carvalho Chehab
` (2 preceding siblings ...)
2016-09-08 21:37 ` [PATCH 03/15] [media] v4l2-mem2mem.h: document function arguments Mauro Carvalho Chehab
@ 2016-09-08 21:37 ` Mauro Carvalho Chehab
2016-09-08 21:37 ` [PATCH 05/15] [media] v4l2-mem2mem.h: make kernel-doc parse v4l2-mem2mem.h again Mauro Carvalho Chehab
` (10 subsequent siblings)
14 siblings, 0 replies; 16+ messages in thread
From: Mauro Carvalho Chehab @ 2016-09-08 21:37 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Mauro Carvalho Chehab
Most structures here are not documented. Add a documentation
for them.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
include/media/v4l2-mem2mem.h | 67 +++++++++++++++++++++++++++++++++-----------
1 file changed, 51 insertions(+), 16 deletions(-)
diff --git a/include/media/v4l2-mem2mem.h b/include/media/v4l2-mem2mem.h
index 78eadca27a21..f74ea7026c88 100644
--- a/include/media/v4l2-mem2mem.h
+++ b/include/media/v4l2-mem2mem.h
@@ -41,9 +41,9 @@
* This function does not have to (and will usually not) wait
* until the device enters a state when it can be stopped.
* @lock: optional. Define a driver's own lock callback, instead of using
- * m2m_ctx->q_lock.
+ * &v4l2_m2m_ctx->q_lock.
* @unlock: optional. Define a driver's own unlock callback, instead of
- * using m2m_ctx->q_lock.
+ * using &v4l2_m2m_ctx->q_lock.
*/
struct v4l2_m2m_ops {
void (*device_run)(void *priv);
@@ -53,31 +53,59 @@ struct v4l2_m2m_ops {
void (*unlock)(void *priv);
};
+/**
+ * struct v4l2_m2m_dev - opaque struct used to represent a V4L2 M2M device.
+ *
+ * This structure is has the per-device context for a memory to memory
+ * device, and it is used internally at v4l2-mem2mem.c.
+ */
struct v4l2_m2m_dev;
+/**
+ * struct v4l2_m2m_queue_ctx - represents a queue for buffers ready to be
+ * processed
+ *
+ * @q: pointer to struct &vb2_queue
+ * @rdy_queue: List of V4L2 mem-to-mem queues
+ * @rdy_spinlock: spin lock to protect the struct usage
+ * @num_rdy: number of buffers ready to be processed
+ * @buffered: is the queue buffered?
+ *
+ * Queue for buffers ready to be processed as soon as this
+ * instance receives access to the device.
+ */
+
struct v4l2_m2m_queue_ctx {
-/* private: internal use only */
struct vb2_queue q;
- /* Queue for buffers ready to be processed as soon as this
- * instance receives access to the device */
struct list_head rdy_queue;
spinlock_t rdy_spinlock;
u8 num_rdy;
bool buffered;
};
+/**
+ * struct v4l2_m2m_ctx - Memory to memory context structure
+ *
+ * @q_lock: struct &mutex lock
+ * @m2m_dev: pointer to struct &v4l2_m2m_dev
+ * @cap_q_ctx: Capture (output to memory) queue context
+ * @out_q_ctx: Output (input from memory) queue context
+ * @queue: List of memory to memory contexts
+ * @job_flags: Job queue flags, used internally by v4l2-mem2mem.c:
+ * %TRANS_QUEUED, %TRANS_RUNNING and %TRANS_ABORT.
+ * @finished: Wait queue used to signalize when a job queue finished.
+ * @priv: Instance private data
+ */
struct v4l2_m2m_ctx {
/* optional cap/out vb2 queues lock */
struct mutex *q_lock;
-/* private: internal use only */
+ /* internal use only */
struct v4l2_m2m_dev *m2m_dev;
- /* Capture (output to memory) queue context */
struct v4l2_m2m_queue_ctx cap_q_ctx;
- /* Output (input from memory) queue context */
struct v4l2_m2m_queue_ctx out_q_ctx;
/* For device job queue */
@@ -85,10 +113,15 @@ struct v4l2_m2m_ctx {
unsigned long job_flags;
wait_queue_head_t finished;
- /* Instance private data */
void *priv;
};
+/**
+ * struct v4l2_m2m_buffer - Memory to memory buffer
+ *
+ * @vb: pointer to struct &vb2_v4l2_buffer
+ * @list: list of m2m buffers
+ */
struct v4l2_m2m_buffer {
struct vb2_v4l2_buffer vb;
struct list_head list;
@@ -145,9 +178,9 @@ void v4l2_m2m_try_schedule(struct v4l2_m2m_ctx *m2m_ctx);
* Should be called as soon as possible after reaching a state which allows
* other instances to take control of the device.
*
- * This function has to be called only after device_run() callback has been
- * called on the driver. To prevent recursion, it should not be called directly
- * from the device_run() callback though.
+ * This function has to be called only after &v4l2_m2m_ops->device_run
+ * callback has been called on the driver. To prevent recursion, it should
+ * not be called directly from the &v4l2_m2m_ops->device_run callback though.
*/
void v4l2_m2m_job_finish(struct v4l2_m2m_dev *m2m_dev,
struct v4l2_m2m_ctx *m2m_ctx);
@@ -292,7 +325,9 @@ int v4l2_m2m_mmap(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
*
* @m2m_ops: pointer to struct v4l2_m2m_ops
*
- * Usually called from driver's probe() function.
+ * Usually called from driver's ``probe()`` function.
+ *
+ * Return: returns an opaque pointer to the internal data to handle M2M context
*/
struct v4l2_m2m_dev *v4l2_m2m_init(const struct v4l2_m2m_ops *m2m_ops);
@@ -301,7 +336,7 @@ struct v4l2_m2m_dev *v4l2_m2m_init(const struct v4l2_m2m_ops *m2m_ops);
*
* @m2m_dev: pointer to struct &v4l2_m2m_dev
*
- * Usually called from driver's remove() function.
+ * Usually called from driver's ``remove()`` function.
*/
void v4l2_m2m_release(struct v4l2_m2m_dev *m2m_dev);
@@ -313,7 +348,7 @@ void v4l2_m2m_release(struct v4l2_m2m_dev *m2m_dev);
* @queue_init: a callback for queue type-specific initialization function
* to be used for initializing videobuf_queues
*
- * Usually called from driver's open() function.
+ * Usually called from driver's ``open()`` function.
*/
struct v4l2_m2m_ctx *v4l2_m2m_ctx_init(struct v4l2_m2m_dev *m2m_dev,
void *drv_priv,
@@ -346,7 +381,7 @@ void v4l2_m2m_ctx_release(struct v4l2_m2m_ctx *m2m_ctx);
* @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
* @vbuf: pointer to struct &vb2_v4l2_buffer
*
- * Call from buf_queue(), videobuf_queue_ops callback.
+ * Call from videobuf_queue_ops->ops->buf_queue, videobuf_queue_ops callback.
*/
void v4l2_m2m_buf_queue(struct v4l2_m2m_ctx *m2m_ctx,
struct vb2_v4l2_buffer *vbuf);
--
2.7.4
^ permalink raw reply related [flat|nested] 16+ messages in thread* [PATCH 05/15] [media] v4l2-mem2mem.h: make kernel-doc parse v4l2-mem2mem.h again
2016-09-08 21:37 [PATCH 00/15] Fix another set of nitpick warnings Mauro Carvalho Chehab
` (3 preceding siblings ...)
2016-09-08 21:37 ` [PATCH 04/15] [media] v4l2-mem2mem.h: document the public structures Mauro Carvalho Chehab
@ 2016-09-08 21:37 ` Mauro Carvalho Chehab
2016-09-08 21:37 ` [PATCH 06/15] [media] conf_nitpick.py: ignore an opaque struct from v4l2-mem2mem.h Mauro Carvalho Chehab
` (9 subsequent siblings)
14 siblings, 0 replies; 16+ messages in thread
From: Mauro Carvalho Chehab @ 2016-09-08 21:37 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Mauro Carvalho Chehab
The kernel-doc C parser doesn't like opaque structures. So,
document it on another way.
This should get rid of this warning:
./include/media/v4l2-mem2mem.h:62: error: Cannot parse struct or union!
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
include/media/v4l2-mem2mem.h | 16 +++++-----------
1 file changed, 5 insertions(+), 11 deletions(-)
diff --git a/include/media/v4l2-mem2mem.h b/include/media/v4l2-mem2mem.h
index f74ea7026c88..9a7eb5605254 100644
--- a/include/media/v4l2-mem2mem.h
+++ b/include/media/v4l2-mem2mem.h
@@ -53,12 +53,6 @@ struct v4l2_m2m_ops {
void (*unlock)(void *priv);
};
-/**
- * struct v4l2_m2m_dev - opaque struct used to represent a V4L2 M2M device.
- *
- * This structure is has the per-device context for a memory to memory
- * device, and it is used internally at v4l2-mem2mem.c.
- */
struct v4l2_m2m_dev;
/**
@@ -88,7 +82,7 @@ struct v4l2_m2m_queue_ctx {
* struct v4l2_m2m_ctx - Memory to memory context structure
*
* @q_lock: struct &mutex lock
- * @m2m_dev: pointer to struct &v4l2_m2m_dev
+ * @m2m_dev: opaque pointer to the internal data to handle M2M context
* @cap_q_ctx: Capture (output to memory) queue context
* @out_q_ctx: Output (input from memory) queue context
* @queue: List of memory to memory contexts
@@ -131,7 +125,7 @@ struct v4l2_m2m_buffer {
* v4l2_m2m_get_curr_priv() - return driver private data for the currently
* running instance or NULL if no instance is running
*
- * @m2m_dev: pointer to struct &v4l2_m2m_dev
+ * @m2m_dev: opaque pointer to the internal data to handle M2M context
*/
void *v4l2_m2m_get_curr_priv(struct v4l2_m2m_dev *m2m_dev);
@@ -171,7 +165,7 @@ void v4l2_m2m_try_schedule(struct v4l2_m2m_ctx *m2m_ctx);
* v4l2_m2m_job_finish() - inform the framework that a job has been finished
* and have it clean up
*
- * @m2m_dev: pointer to struct &v4l2_m2m_dev
+ * @m2m_dev: opaque pointer to the internal data to handle M2M context
* @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
*
* Called by a driver to yield back the device after it has finished with it.
@@ -334,7 +328,7 @@ struct v4l2_m2m_dev *v4l2_m2m_init(const struct v4l2_m2m_ops *m2m_ops);
/**
* v4l2_m2m_release() - cleans up and frees a m2m_dev structure
*
- * @m2m_dev: pointer to struct &v4l2_m2m_dev
+ * @m2m_dev: opaque pointer to the internal data to handle M2M context
*
* Usually called from driver's ``remove()`` function.
*/
@@ -343,7 +337,7 @@ void v4l2_m2m_release(struct v4l2_m2m_dev *m2m_dev);
/**
* v4l2_m2m_ctx_init() - allocate and initialize a m2m context
*
- * @m2m_dev: a previously initialized m2m_dev struct
+ * @m2m_dev: opaque pointer to the internal data to handle M2M context
* @drv_priv: driver's instance private data
* @queue_init: a callback for queue type-specific initialization function
* to be used for initializing videobuf_queues
--
2.7.4
^ permalink raw reply related [flat|nested] 16+ messages in thread* [PATCH 06/15] [media] conf_nitpick.py: ignore an opaque struct from v4l2-mem2mem.h
2016-09-08 21:37 [PATCH 00/15] Fix another set of nitpick warnings Mauro Carvalho Chehab
` (4 preceding siblings ...)
2016-09-08 21:37 ` [PATCH 05/15] [media] v4l2-mem2mem.h: make kernel-doc parse v4l2-mem2mem.h again Mauro Carvalho Chehab
@ 2016-09-08 21:37 ` Mauro Carvalho Chehab
2016-09-08 21:37 ` [PATCH 07/15] [media] videobuf2-core.h: move function descriptions from c file Mauro Carvalho Chehab
` (8 subsequent siblings)
14 siblings, 0 replies; 16+ messages in thread
From: Mauro Carvalho Chehab @ 2016-09-08 21:37 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Jonathan Corbet,
Mauro Carvalho Chehab, Markus Heiser, linux-doc
The v4l2_m2m_dev is opaque: its meaning is only known by
v4l2-mem2mem.c. Ignore it on nitpick mode.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/media/conf_nitpick.py | 4 ++++
1 file changed, 4 insertions(+)
diff --git a/Documentation/media/conf_nitpick.py b/Documentation/media/conf_nitpick.py
index 1f3ef3ded2d4..f71bb947eb15 100644
--- a/Documentation/media/conf_nitpick.py
+++ b/Documentation/media/conf_nitpick.py
@@ -98,4 +98,8 @@ nitpick_ignore = [
("c:type", "usb_interface"),
("c:type", "v4l2_std_id"),
("c:type", "video_system_t"),
+
+ # Opaque structures
+
+ ("c:type", "v4l2_m2m_dev"),
]
--
2.7.4
^ permalink raw reply related [flat|nested] 16+ messages in thread* [PATCH 07/15] [media] videobuf2-core.h: move function descriptions from c file
2016-09-08 21:37 [PATCH 00/15] Fix another set of nitpick warnings Mauro Carvalho Chehab
` (5 preceding siblings ...)
2016-09-08 21:37 ` [PATCH 06/15] [media] conf_nitpick.py: ignore an opaque struct from v4l2-mem2mem.h Mauro Carvalho Chehab
@ 2016-09-08 21:37 ` Mauro Carvalho Chehab
2016-09-08 21:37 ` [PATCH 08/15] [media] videobuf2-core.h: document enum vb2_memory Mauro Carvalho Chehab
` (7 subsequent siblings)
14 siblings, 0 replies; 16+ messages in thread
From: Mauro Carvalho Chehab @ 2016-09-08 21:37 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Pawel Osciak,
Marek Szyprowski, Kyungmin Park, Mauro Carvalho Chehab
There are several functions that were documented at the .c
file. As we only include the headers, we need to move them to
there, in order to have documentation.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
drivers/media/v4l2-core/videobuf2-core.c | 254 -----------------------------
include/media/videobuf2-core.h | 269 +++++++++++++++++++++++++++++++
2 files changed, 269 insertions(+), 254 deletions(-)
diff --git a/drivers/media/v4l2-core/videobuf2-core.c b/drivers/media/v4l2-core/videobuf2-core.c
index bfe85879c563..21900202ff83 100644
--- a/drivers/media/v4l2-core/videobuf2-core.c
+++ b/drivers/media/v4l2-core/videobuf2-core.c
@@ -528,10 +528,6 @@ static int __vb2_queue_free(struct vb2_queue *q, unsigned int buffers)
return 0;
}
-/**
- * vb2_buffer_in_use() - return true if the buffer is in use and
- * the queue cannot be freed (by the means of REQBUFS(0)) call
- */
bool vb2_buffer_in_use(struct vb2_queue *q, struct vb2_buffer *vb)
{
unsigned int plane;
@@ -564,16 +560,6 @@ static bool __buffers_in_use(struct vb2_queue *q)
return false;
}
-/**
- * vb2_core_querybuf() - query video buffer information
- * @q: videobuf queue
- * @index: id number of the buffer
- * @pb: buffer struct passed from userspace
- *
- * Should be called from vidioc_querybuf ioctl handler in driver.
- * The passed buffer should have been verified.
- * This function fills the relevant information for the userspace.
- */
void vb2_core_querybuf(struct vb2_queue *q, unsigned int index, void *pb)
{
call_void_bufop(q, fill_user_buffer, q->bufs[index], pb);
@@ -620,10 +606,6 @@ static int __verify_dmabuf_ops(struct vb2_queue *q)
return 0;
}
-/**
- * vb2_verify_memory_type() - Check whether the memory type and buffer type
- * passed to a buffer operation are compatible with the queue.
- */
int vb2_verify_memory_type(struct vb2_queue *q,
enum vb2_memory memory, unsigned int type)
{
@@ -670,30 +652,6 @@ int vb2_verify_memory_type(struct vb2_queue *q,
}
EXPORT_SYMBOL(vb2_verify_memory_type);
-/**
- * vb2_core_reqbufs() - Initiate streaming
- * @q: videobuf2 queue
- * @memory: memory type
- * @count: requested buffer count
- *
- * Should be called from vidioc_reqbufs ioctl handler of a driver.
- * This function:
- * 1) verifies streaming parameters passed from the userspace,
- * 2) sets up the queue,
- * 3) negotiates number of buffers and planes per buffer with the driver
- * to be used during streaming,
- * 4) allocates internal buffer structures (struct vb2_buffer), according to
- * the agreed parameters,
- * 5) for MMAP memory type, allocates actual video memory, using the
- * 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_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 vidioc_reqbufs handler in driver.
- */
int vb2_core_reqbufs(struct vb2_queue *q, enum vb2_memory memory,
unsigned int *count)
{
@@ -819,22 +777,6 @@ int vb2_core_reqbufs(struct vb2_queue *q, enum vb2_memory memory,
}
EXPORT_SYMBOL_GPL(vb2_core_reqbufs);
-/**
- * vb2_core_create_bufs() - Allocate buffers and any required auxiliary structs
- * @q: videobuf2 queue
- * @memory: memory type
- * @count: requested buffer count
- * @parg: parameter passed to device driver
- *
- * Should be called from vidioc_create_bufs ioctl handler of a driver.
- * This function:
- * 1) verifies parameter sanity
- * 2) calls the .queue_setup() queue operation
- * 3) performs any necessary memory allocations
- *
- * The return values from this function are intended to be directly returned
- * from vidioc_create_bufs handler in driver.
- */
int vb2_core_create_bufs(struct vb2_queue *q, enum vb2_memory memory,
unsigned int *count, unsigned requested_planes,
const unsigned requested_sizes[])
@@ -924,14 +866,6 @@ int vb2_core_create_bufs(struct vb2_queue *q, enum vb2_memory memory,
}
EXPORT_SYMBOL_GPL(vb2_core_create_bufs);
-/**
- * vb2_plane_vaddr() - Return a kernel virtual address of a given plane
- * @vb: vb2_buffer to which the plane in question belongs to
- * @plane_no: plane number for which the address is to be returned
- *
- * This function returns a kernel virtual address of a given plane if
- * such a mapping exist, NULL otherwise.
- */
void *vb2_plane_vaddr(struct vb2_buffer *vb, unsigned int plane_no)
{
if (plane_no > vb->num_planes || !vb->planes[plane_no].mem_priv)
@@ -942,17 +876,6 @@ void *vb2_plane_vaddr(struct vb2_buffer *vb, unsigned int plane_no)
}
EXPORT_SYMBOL_GPL(vb2_plane_vaddr);
-/**
- * vb2_plane_cookie() - Return allocator specific cookie for the given plane
- * @vb: vb2_buffer to which the plane in question belongs to
- * @plane_no: plane number for which the cookie is to be returned
- *
- * This function returns an allocator specific cookie for a given plane if
- * available, NULL otherwise. The allocator should provide some simple static
- * inline function, which would convert this cookie to the allocator specific
- * type that can be used directly by the driver to access the buffer. This can
- * be for example physical address, pointer to scatter list or IOMMU mapping.
- */
void *vb2_plane_cookie(struct vb2_buffer *vb, unsigned int plane_no)
{
if (plane_no >= vb->num_planes || !vb->planes[plane_no].mem_priv)
@@ -962,26 +885,6 @@ void *vb2_plane_cookie(struct vb2_buffer *vb, unsigned int plane_no)
}
EXPORT_SYMBOL_GPL(vb2_plane_cookie);
-/**
- * vb2_buffer_done() - inform videobuf that an operation on a buffer is finished
- * @vb: vb2_buffer returned from the driver
- * @state: either VB2_BUF_STATE_DONE if the operation finished successfully,
- * VB2_BUF_STATE_ERROR if the operation finished with an error or
- * VB2_BUF_STATE_QUEUED if the driver wants to requeue buffers.
- * If start_streaming fails then it should return buffers with state
- * VB2_BUF_STATE_QUEUED to put them back into the queue.
- *
- * This function should be called by the driver after a hardware operation on
- * a buffer is finished and the buffer may be returned to userspace. The driver
- * cannot use this buffer anymore until it is queued back to it by videobuf
- * by the means of buf_queue callback. Only buffers previously queued to the
- * driver by buf_queue can be passed to this function.
- *
- * While streaming a buffer can only be returned in state DONE or ERROR.
- * The start_streaming op can also return them in case the DMA engine cannot
- * be started for some reason. In that case the buffers should be returned with
- * state QUEUED.
- */
void vb2_buffer_done(struct vb2_buffer *vb, enum vb2_buffer_state state)
{
struct vb2_queue *q = vb->vb2_queue;
@@ -1040,18 +943,6 @@ void vb2_buffer_done(struct vb2_buffer *vb, enum vb2_buffer_state state)
}
EXPORT_SYMBOL_GPL(vb2_buffer_done);
-/**
- * vb2_discard_done() - discard all buffers marked as DONE
- * @q: videobuf2 queue
- *
- * This function is intended to be used with suspend/resume operations. It
- * discards all 'done' buffers as they would be too old to be requested after
- * resume.
- *
- * Drivers must stop the hardware and synchronize with interrupt handlers and/or
- * delayed works before calling this function to make sure no buffer will be
- * touched by the driver and/or hardware.
- */
void vb2_discard_done(struct vb2_queue *q)
{
struct vb2_buffer *vb;
@@ -1384,22 +1275,6 @@ static int __buf_prepare(struct vb2_buffer *vb, const void *pb)
return ret;
}
-/**
- * vb2_core_prepare_buf() - Pass ownership of a buffer from userspace
- * to the kernel
- * @q: videobuf2 queue
- * @index: id number of the buffer
- * @pb: buffer structure passed from userspace to vidioc_prepare_buf
- * handler in driver
- *
- * Should be called from vidioc_prepare_buf ioctl handler of a driver.
- * 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,
- *
- * The return values from this function are intended to be directly returned
- * from vidioc_prepare_buf handler in driver.
- */
int vb2_core_prepare_buf(struct vb2_queue *q, unsigned int index, void *pb)
{
struct vb2_buffer *vb;
@@ -1488,24 +1363,6 @@ static int vb2_start_streaming(struct vb2_queue *q)
return ret;
}
-/**
- * vb2_core_qbuf() - Queue a buffer from userspace
- * @q: videobuf2 queue
- * @index: id number of the buffer
- * @pb: buffer structure passed from userspace to vidioc_qbuf handler
- * in driver
- *
- * Should be called from vidioc_qbuf ioctl handler of a driver.
- * The passed buffer should have been verified.
- * This function:
- * 1) if necessary, calls buf_prepare callback in the driver (if provided), in
- * which driver-specific buffer initialization can be performed,
- * 2) if streaming is on, queues the buffer in driver by the means of buf_queue
- * callback for processing.
- *
- * The return values from this function are intended to be directly returned
- * from vidioc_qbuf handler in driver.
- */
int vb2_core_qbuf(struct vb2_queue *q, unsigned int index, void *pb)
{
struct vb2_buffer *vb;
@@ -1686,15 +1543,6 @@ static int __vb2_get_done_vb(struct vb2_queue *q, struct vb2_buffer **vb,
return ret;
}
-/**
- * vb2_wait_for_all_buffers() - wait until all buffers are given back to vb2
- * @q: videobuf2 queue
- *
- * This function will wait until all buffers that have been given to the driver
- * by buf_queue() are given back to vb2 with vb2_buffer_done(). It doesn't call
- * wait_prepare, wait_finish pair. It is intended to be called with all locks
- * taken, for example from stop_streaming() callback.
- */
int vb2_wait_for_all_buffers(struct vb2_queue *q)
{
if (!q->streaming) {
@@ -1732,28 +1580,6 @@ static void __vb2_dqbuf(struct vb2_buffer *vb)
}
}
-/**
- * vb2_core_dqbuf() - Dequeue a buffer to the userspace
- * @q: videobuf2 queue
- * @pindex: pointer to the buffer index. May be NULL
- * @pb: buffer structure passed from userspace to vidioc_dqbuf handler
- * in driver
- * @nonblocking: if true, this call will not sleep waiting for a buffer if no
- * buffers ready for dequeuing are present. Normally the driver
- * would be passing (file->f_flags & O_NONBLOCK) here
- *
- * Should be called from vidioc_dqbuf ioctl handler of a driver.
- * The passed buffer should have been verified.
- * This function:
- * 1) calls buf_finish callback in the driver (if provided), in which
- * driver can perform any additional operations that may be required before
- * returning the buffer to userspace, such as cache sync,
- * 2) the buffer struct members are filled with relevant information for
- * the userspace.
- *
- * The return values from this function are intended to be directly returned
- * from vidioc_dqbuf handler in driver.
- */
int vb2_core_dqbuf(struct vb2_queue *q, unsigned int *pindex, void *pb,
bool nonblocking)
{
@@ -1917,19 +1743,6 @@ int vb2_core_streamon(struct vb2_queue *q, unsigned int type)
}
EXPORT_SYMBOL_GPL(vb2_core_streamon);
-/**
- * vb2_queue_error() - signal a fatal error on the queue
- * @q: videobuf2 queue
- *
- * Flag that a fatal unrecoverable error has occurred and wake up all processes
- * waiting on the queue. Polling will now set POLLERR and queuing and dequeuing
- * buffers will return -EIO.
- *
- * The error flag will be cleared when cancelling the queue, either from
- * vb2_streamoff or vb2_queue_release. Drivers should thus not call this
- * function before starting the stream, otherwise the error flag will remain set
- * until the queue is released when closing the device node.
- */
void vb2_queue_error(struct vb2_queue *q)
{
q->error = 1;
@@ -1992,19 +1805,6 @@ static int __find_plane_by_offset(struct vb2_queue *q, unsigned long off,
return -EINVAL;
}
-/**
- * vb2_core_expbuf() - Export a buffer as a file descriptor
- * @q: videobuf2 queue
- * @fd: file descriptor associated with DMABUF (set by driver) *
- * @type: buffer type
- * @index: id number of the buffer
- * @plane: index of the plane to be exported, 0 for single plane queues
- * @flags: flags for newly created file, currently only O_CLOEXEC is
- * supported, refer to manual of open syscall for more details
- *
- * The return values from this function are intended to be directly returned
- * from vidioc_expbuf handler in driver.
- */
int vb2_core_expbuf(struct vb2_queue *q, int *fd, unsigned int type,
unsigned int index, unsigned int plane, unsigned int flags)
{
@@ -2076,25 +1876,6 @@ int vb2_core_expbuf(struct vb2_queue *q, int *fd, unsigned int type,
}
EXPORT_SYMBOL_GPL(vb2_core_expbuf);
-/**
- * vb2_mmap() - map video buffers into application address space
- * @q: videobuf2 queue
- * @vma: vma passed to the mmap file operation handler in the driver
- *
- * Should be called from mmap file operation handler of a driver.
- * This function maps one plane of one of the available video buffers to
- * userspace. To map whole video memory allocated on reqbufs, this function
- * has to be called once per each plane per each buffer previously allocated.
- *
- * When the userspace application calls mmap, it passes to it an offset returned
- * to it earlier by the means of vidioc_querybuf handler. That offset acts as
- * a "cookie", which is then used to identify the plane to be mapped.
- * This function finds a plane with a matching offset and a mapping is performed
- * by the means of a provided memory operation.
- *
- * The return values from this function are intended to be directly returned
- * from the mmap handler in driver.
- */
int vb2_mmap(struct vb2_queue *q, struct vm_area_struct *vma)
{
unsigned long off = vma->vm_pgoff << PAGE_SHIFT;
@@ -2196,17 +1977,6 @@ unsigned long vb2_get_unmapped_area(struct vb2_queue *q,
EXPORT_SYMBOL_GPL(vb2_get_unmapped_area);
#endif
-/**
- * vb2_core_queue_init() - initialize a videobuf2 queue
- * @q: videobuf2 queue; this structure should be allocated in driver
- *
- * The vb2_queue structure should be allocated by the driver. The driver is
- * responsible of clearing it's content and setting initial values for some
- * required entries before calling this function.
- * q->ops, q->mem_ops, q->type and q->io_modes are mandatory. Please refer
- * to the struct vb2_queue description in include/media/videobuf2-core.h
- * for more information.
- */
int vb2_core_queue_init(struct vb2_queue *q)
{
/*
@@ -2236,14 +2006,6 @@ EXPORT_SYMBOL_GPL(vb2_core_queue_init);
static int __vb2_init_fileio(struct vb2_queue *q, int read);
static int __vb2_cleanup_fileio(struct vb2_queue *q);
-/**
- * vb2_core_queue_release() - stop streaming, release the queue and free memory
- * @q: videobuf2 queue
- *
- * This function stops streaming and performs necessary clean ups, including
- * freeing video buffer memory. The driver is responsible for freeing
- * the vb2_queue structure itself.
- */
void vb2_core_queue_release(struct vb2_queue *q)
{
__vb2_cleanup_fileio(q);
@@ -2254,22 +2016,6 @@ void vb2_core_queue_release(struct vb2_queue *q)
}
EXPORT_SYMBOL_GPL(vb2_core_queue_release);
-/**
- * vb2_core_poll() - implements poll userspace operation
- * @q: videobuf2 queue
- * @file: file argument passed to the poll file operation handler
- * @wait: wait argument passed to the poll file operation handler
- *
- * This function implements poll file operation handler for a driver.
- * For CAPTURE queues, if a buffer is ready to be dequeued, the userspace will
- * be informed that the file descriptor of a video device is available for
- * reading.
- * For OUTPUT queues, if a buffer is ready to be dequeued, the file descriptor
- * will be reported as available for writing.
- *
- * The return values from this function are intended to be directly returned
- * from poll handler in driver.
- */
unsigned int vb2_core_poll(struct vb2_queue *q, struct file *file,
poll_table *wait)
{
diff --git a/include/media/videobuf2-core.h b/include/media/videobuf2-core.h
index b6546db670ca..68f93dacb38f 100644
--- a/include/media/videobuf2-core.h
+++ b/include/media/videobuf2-core.h
@@ -536,35 +536,274 @@ struct vb2_queue {
#endif
};
+/**
+ * vb2_plane_vaddr() - Return a kernel virtual address of a given plane
+ * @vb: vb2_buffer to which the plane in question belongs to
+ * @plane_no: plane number for which the address is to be returned
+ *
+ * This function returns a kernel virtual address of a given plane if
+ * such a mapping exist, NULL otherwise.
+ */
void *vb2_plane_vaddr(struct vb2_buffer *vb, unsigned int plane_no);
+
+/**
+ * vb2_plane_cookie() - Return allocator specific cookie for the given plane
+ * @vb: vb2_buffer to which the plane in question belongs to
+ * @plane_no: plane number for which the cookie is to be returned
+ *
+ * This function returns an allocator specific cookie for a given plane if
+ * available, NULL otherwise. The allocator should provide some simple static
+ * inline function, which would convert this cookie to the allocator specific
+ * type that can be used directly by the driver to access the buffer. This can
+ * be for example physical address, pointer to scatter list or IOMMU mapping.
+ */
void *vb2_plane_cookie(struct vb2_buffer *vb, unsigned int plane_no);
+/**
+ * vb2_buffer_done() - inform videobuf that an operation on a buffer is finished
+ * @vb: vb2_buffer returned from the driver
+ * @state: either %VB2_BUF_STATE_DONE if the operation finished successfully,
+ * %VB2_BUF_STATE_ERROR if the operation finished with an error or
+ * %VB2_BUF_STATE_QUEUED if the driver wants to requeue buffers.
+ * If start_streaming fails then it should return buffers with state
+ * %VB2_BUF_STATE_QUEUED to put them back into the queue.
+ *
+ * This function should be called by the driver after a hardware operation on
+ * a buffer is finished and the buffer may be returned to userspace. The driver
+ * cannot use this buffer anymore until it is queued back to it by videobuf
+ * by the means of buf_queue callback. Only buffers previously queued to the
+ * driver by buf_queue can be passed to this function.
+ *
+ * While streaming a buffer can only be returned in state DONE or ERROR.
+ * The start_streaming op can also return them in case the DMA engine cannot
+ * be started for some reason. In that case the buffers should be returned with
+ * state QUEUED.
+ */
void vb2_buffer_done(struct vb2_buffer *vb, enum vb2_buffer_state state);
+
+/**
+ * vb2_discard_done() - discard all buffers marked as DONE
+ * @q: videobuf2 queue
+ *
+ * This function is intended to be used with suspend/resume operations. It
+ * discards all 'done' buffers as they would be too old to be requested after
+ * resume.
+ *
+ * Drivers must stop the hardware and synchronize with interrupt handlers and/or
+ * delayed works before calling this function to make sure no buffer will be
+ * touched by the driver and/or hardware.
+ */
void vb2_discard_done(struct vb2_queue *q);
+
+/**
+ * vb2_wait_for_all_buffers() - wait until all buffers are given back to vb2
+ * @q: videobuf2 queue
+ *
+ * This function will wait until all buffers that have been given to the driver
+ * by buf_queue() are given back to vb2 with vb2_buffer_done(). It doesn't call
+ * wait_prepare, wait_finish pair. It is intended to be called with all locks
+ * taken, for example from stop_streaming() callback.
+ */
int vb2_wait_for_all_buffers(struct vb2_queue *q);
+/**
+ * vb2_core_querybuf() - query video buffer information
+ * @q: videobuf queue
+ * @index: id number of the buffer
+ * @pb: buffer struct passed from userspace
+ *
+ * Should be called from vidioc_querybuf ioctl handler in driver.
+ * The passed buffer should have been verified.
+ * This function fills the relevant information for the userspace.
+ */
void vb2_core_querybuf(struct vb2_queue *q, unsigned int index, void *pb);
+
+/**
+ * vb2_core_reqbufs() - Initiate streaming
+ * @q: videobuf2 queue
+ * @memory: memory type
+ * @count: requested buffer count
+ *
+ * Should be called from vidioc_reqbufs ioctl handler of a driver.
+ * This function:
+ * 1) verifies streaming parameters passed from the userspace,
+ * 2) sets up the queue,
+ * 3) negotiates number of buffers and planes per buffer with the driver
+ * to be used during streaming,
+ * 4) allocates internal buffer structures (struct vb2_buffer), according to
+ * the agreed parameters,
+ * 5) for MMAP memory type, allocates actual video memory, using the
+ * 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_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 vidioc_reqbufs handler in driver.
+ */
int vb2_core_reqbufs(struct vb2_queue *q, enum vb2_memory memory,
unsigned int *count);
+
+/**
+ * vb2_core_create_bufs() - Allocate buffers and any required auxiliary structs
+ * @q: videobuf2 queue
+ * @memory: memory type
+ * @count: requested buffer count
+ * @parg: parameter passed to device driver
+ *
+ * Should be called from vidioc_create_bufs ioctl handler of a driver.
+ * This function:
+ * 1) verifies parameter sanity
+ * 2) calls the .queue_setup() queue operation
+ * 3) performs any necessary memory allocations
+ *
+ * The return values from this function are intended to be directly returned
+ * from vidioc_create_bufs handler in driver.
+ */
int vb2_core_create_bufs(struct vb2_queue *q, enum vb2_memory memory,
unsigned int *count, unsigned requested_planes,
const unsigned int requested_sizes[]);
+
+/**
+ * vb2_core_prepare_buf() - Pass ownership of a buffer from userspace
+ * to the kernel
+ * @q: videobuf2 queue
+ * @index: id number of the buffer
+ * @pb: buffer structure passed from userspace to vidioc_prepare_buf
+ * handler in driver
+ *
+ * Should be called from vidioc_prepare_buf ioctl handler of a driver.
+ * 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,
+ *
+ * The return values from this function are intended to be directly returned
+ * from vidioc_prepare_buf handler in driver.
+ */
int vb2_core_prepare_buf(struct vb2_queue *q, unsigned int index, void *pb);
+
+/**
+ * vb2_core_qbuf() - Queue a buffer from userspace
+ * @q: videobuf2 queue
+ * @index: id number of the buffer
+ * @pb: buffer structure passed from userspace to vidioc_qbuf handler
+ * in driver
+ *
+ * Should be called from vidioc_qbuf ioctl handler of a driver.
+ * The passed buffer should have been verified.
+ * This function:
+ * 1) if necessary, calls buf_prepare callback in the driver (if provided), in
+ * which driver-specific buffer initialization can be performed,
+ * 2) if streaming is on, queues the buffer in driver by the means of buf_queue
+ * callback for processing.
+ *
+ * The return values from this function are intended to be directly returned
+ * from vidioc_qbuf handler in driver.
+ */
int vb2_core_qbuf(struct vb2_queue *q, unsigned int index, void *pb);
+
+/**
+ * vb2_core_dqbuf() - Dequeue a buffer to the userspace
+ * @q: videobuf2 queue
+ * @pindex: pointer to the buffer index. May be NULL
+ * @pb: buffer structure passed from userspace to vidioc_dqbuf handler
+ * in driver
+ * @nonblocking: if true, this call will not sleep waiting for a buffer if no
+ * buffers ready for dequeuing are present. Normally the driver
+ * would be passing (file->f_flags & O_NONBLOCK) here
+ *
+ * Should be called from vidioc_dqbuf ioctl handler of a driver.
+ * The passed buffer should have been verified.
+ * This function:
+ * 1) calls buf_finish callback in the driver (if provided), in which
+ * driver can perform any additional operations that may be required before
+ * returning the buffer to userspace, such as cache sync,
+ * 2) the buffer struct members are filled with relevant information for
+ * the userspace.
+ *
+ * The return values from this function are intended to be directly returned
+ * from vidioc_dqbuf handler in driver.
+ */
int vb2_core_dqbuf(struct vb2_queue *q, unsigned int *pindex, void *pb,
bool nonblocking);
int vb2_core_streamon(struct vb2_queue *q, unsigned int type);
int vb2_core_streamoff(struct vb2_queue *q, unsigned int type);
+/**
+ * vb2_core_expbuf() - Export a buffer as a file descriptor
+ * @q: videobuf2 queue
+ * @fd: file descriptor associated with DMABUF (set by driver) *
+ * @type: buffer type
+ * @index: id number of the buffer
+ * @plane: index of the plane to be exported, 0 for single plane queues
+ * @flags: flags for newly created file, currently only O_CLOEXEC is
+ * supported, refer to manual of open syscall for more details
+ *
+ * The return values from this function are intended to be directly returned
+ * from vidioc_expbuf handler in driver.
+ */
int vb2_core_expbuf(struct vb2_queue *q, int *fd, unsigned int type,
unsigned int index, unsigned int plane, unsigned int flags);
+/**
+ * vb2_core_queue_init() - initialize a videobuf2 queue
+ * @q: videobuf2 queue; this structure should be allocated in driver
+ *
+ * The vb2_queue structure should be allocated by the driver. The driver is
+ * responsible of clearing it's content and setting initial values for some
+ * required entries before calling this function.
+ * q->ops, q->mem_ops, q->type and q->io_modes are mandatory. Please refer
+ * to the struct vb2_queue description in include/media/videobuf2-core.h
+ * for more information.
+ */
int vb2_core_queue_init(struct vb2_queue *q);
+
+/**
+ * vb2_core_queue_release() - stop streaming, release the queue and free memory
+ * @q: videobuf2 queue
+ *
+ * This function stops streaming and performs necessary clean ups, including
+ * freeing video buffer memory. The driver is responsible for freeing
+ * the vb2_queue structure itself.
+ */
void vb2_core_queue_release(struct vb2_queue *q);
+/**
+ * vb2_queue_error() - signal a fatal error on the queue
+ * @q: videobuf2 queue
+ *
+ * Flag that a fatal unrecoverable error has occurred and wake up all processes
+ * waiting on the queue. Polling will now set POLLERR and queuing and dequeuing
+ * buffers will return -EIO.
+ *
+ * The error flag will be cleared when cancelling the queue, either from
+ * vb2_streamoff or vb2_queue_release. Drivers should thus not call this
+ * function before starting the stream, otherwise the error flag will remain set
+ * until the queue is released when closing the device node.
+ */
void vb2_queue_error(struct vb2_queue *q);
+/**
+ * vb2_mmap() - map video buffers into application address space
+ * @q: videobuf2 queue
+ * @vma: vma passed to the mmap file operation handler in the driver
+ *
+ * Should be called from mmap file operation handler of a driver.
+ * This function maps one plane of one of the available video buffers to
+ * userspace. To map whole video memory allocated on reqbufs, this function
+ * has to be called once per each plane per each buffer previously allocated.
+ *
+ * When the userspace application calls mmap, it passes to it an offset returned
+ * to it earlier by the means of vidioc_querybuf handler. That offset acts as
+ * a "cookie", which is then used to identify the plane to be mapped.
+ * This function finds a plane with a matching offset and a mapping is performed
+ * by the means of a provided memory operation.
+ *
+ * The return values from this function are intended to be directly returned
+ * from the mmap handler in driver.
+ */
int vb2_mmap(struct vb2_queue *q, struct vm_area_struct *vma);
#ifndef CONFIG_MMU
unsigned long vb2_get_unmapped_area(struct vb2_queue *q,
@@ -573,6 +812,23 @@ unsigned long vb2_get_unmapped_area(struct vb2_queue *q,
unsigned long pgoff,
unsigned long flags);
#endif
+
+/**
+ * vb2_core_poll() - implements poll userspace operation
+ * @q: videobuf2 queue
+ * @file: file argument passed to the poll file operation handler
+ * @wait: wait argument passed to the poll file operation handler
+ *
+ * This function implements poll file operation handler for a driver.
+ * For CAPTURE queues, if a buffer is ready to be dequeued, the userspace will
+ * be informed that the file descriptor of a video device is available for
+ * reading.
+ * For OUTPUT queues, if a buffer is ready to be dequeued, the file descriptor
+ * will be reported as available for writing.
+ *
+ * The return values from this function are intended to be directly returned
+ * from poll handler in driver.
+ */
unsigned int vb2_core_poll(struct vb2_queue *q, struct file *file,
poll_table *wait);
size_t vb2_read(struct vb2_queue *q, char __user *data, size_t count,
@@ -717,7 +973,20 @@ static inline void vb2_clear_last_buffer_dequeued(struct vb2_queue *q)
* The following functions are not part of the vb2 core API, but are useful
* functions for videobuf2-*.
*/
+
+/**
+ * vb2_buffer_in_use() - return true if the buffer is in use and
+ * the queue cannot be freed (by the means of REQBUFS(0)) call
+ *
+ * @vb: buffer for which plane size should be returned
+ * @q: videobuf queue
+ */
bool vb2_buffer_in_use(struct vb2_queue *q, struct vb2_buffer *vb);
+
+/**
+ * vb2_verify_memory_type() - Check whether the memory type and buffer type
+ * passed to a buffer operation are compatible with the queue.
+ */
int vb2_verify_memory_type(struct vb2_queue *q,
enum vb2_memory memory, unsigned int type);
#endif /* _MEDIA_VIDEOBUF2_CORE_H */
--
2.7.4
^ permalink raw reply related [flat|nested] 16+ messages in thread* [PATCH 08/15] [media] videobuf2-core.h: document enum vb2_memory
2016-09-08 21:37 [PATCH 00/15] Fix another set of nitpick warnings Mauro Carvalho Chehab
` (6 preceding siblings ...)
2016-09-08 21:37 ` [PATCH 07/15] [media] videobuf2-core.h: move function descriptions from c file Mauro Carvalho Chehab
@ 2016-09-08 21:37 ` Mauro Carvalho Chehab
2016-09-08 21:37 ` [PATCH 09/15] [media] videobuf2-core.h: improve documentation Mauro Carvalho Chehab
` (6 subsequent siblings)
14 siblings, 0 replies; 16+ messages in thread
From: Mauro Carvalho Chehab @ 2016-09-08 21:37 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Pawel Osciak,
Marek Szyprowski, Kyungmin Park, Mauro Carvalho Chehab
This enum was not documented. Document it.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
include/media/videobuf2-core.h | 14 ++++++++++++++
1 file changed, 14 insertions(+)
diff --git a/include/media/videobuf2-core.h b/include/media/videobuf2-core.h
index 68f93dacb38f..65eeca83687a 100644
--- a/include/media/videobuf2-core.h
+++ b/include/media/videobuf2-core.h
@@ -20,6 +20,20 @@
#define VB2_MAX_FRAME (32)
#define VB2_MAX_PLANES (8)
+/**
+ * enum vb2_memory - type of memory model used to make the buffers visible
+ * on userspace.
+ *
+ * @VB2_MEMORY_UNKNOWN: Buffer status is unknown or it is not used yet on
+ * userspace.
+ * @VB2_MEMORY_MMAP: The buffers are allocated by the Kernel and it is
+ * memory mapped via mmap() ioctl. This model is
+ * also used when the user is using the buffers via
+ * read() or write() system calls.
+ * @VB2_MEMORY_USERPTR: The buffers was allocated in userspace and it is
+ * memory mapped via mmap() ioctl.
+ * @VB2_MEMORY_DMABUF: The buffers are passed to userspace via DMA buffer.
+ */
enum vb2_memory {
VB2_MEMORY_UNKNOWN = 0,
VB2_MEMORY_MMAP = 1,
--
2.7.4
^ permalink raw reply related [flat|nested] 16+ messages in thread* [PATCH 09/15] [media] videobuf2-core.h: improve documentation
2016-09-08 21:37 [PATCH 00/15] Fix another set of nitpick warnings Mauro Carvalho Chehab
` (7 preceding siblings ...)
2016-09-08 21:37 ` [PATCH 08/15] [media] videobuf2-core.h: document enum vb2_memory Mauro Carvalho Chehab
@ 2016-09-08 21:37 ` Mauro Carvalho Chehab
2016-09-08 21:37 ` [PATCH 10/15] [media] conf_nitpick.py: ignore C domain data used on vb2 Mauro Carvalho Chehab
` (5 subsequent siblings)
14 siblings, 0 replies; 16+ messages in thread
From: Mauro Carvalho Chehab @ 2016-09-08 21:37 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Pawel Osciak,
Marek Szyprowski, Kyungmin Park, Mauro Carvalho Chehab
There are several small issues with the documentation. Fix them,
in order to avoid producing warnings.
While here, also make checkpatch.pl happy.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
include/media/videobuf2-core.h | 143 ++++++++++++++++++++++++-----------------
1 file changed, 85 insertions(+), 58 deletions(-)
diff --git a/include/media/videobuf2-core.h b/include/media/videobuf2-core.h
index 65eeca83687a..9a144f2d9083 100644
--- a/include/media/videobuf2-core.h
+++ b/include/media/videobuf2-core.h
@@ -49,13 +49,13 @@ struct vb2_threadio_data;
* @alloc: allocate video memory and, optionally, allocator private data,
* return ERR_PTR() on failure or a pointer to allocator private,
* per-buffer data on success; the returned private structure
- * will then be passed as buf_priv argument to other ops in this
+ * will then be passed as @buf_priv argument to other ops in this
* structure. Additional gfp_flags to use when allocating the
* are also passed to this operation. These flags are from the
* gfp_flags field of vb2_queue.
* @put: inform the allocator that the buffer will no longer be used;
* usually will result in the allocator freeing the buffer (if
- * no other users of this buffer are present); the buf_priv
+ * no other users of this buffer are present); the @buf_priv
* argument is the allocator private per-buffer structure
* previously returned from the alloc callback.
* @get_dmabuf: acquire userspace memory for a hardware operation; used for
@@ -65,7 +65,7 @@ struct vb2_threadio_data;
* videobuf layer when queuing a video buffer of USERPTR type;
* should return an allocator private per-buffer structure
* associated with the buffer on success, ERR_PTR() on failure;
- * the returned private structure will then be passed as buf_priv
+ * the returned private structure will then be passed as @buf_priv
* argument to other ops in this structure.
* @put_userptr: inform the allocator that a USERPTR buffer will no longer
* be used.
@@ -75,7 +75,7 @@ struct vb2_threadio_data;
* allocator private per-buffer structure on success;
* this needs to be used for further accesses to the buffer.
* @detach_dmabuf: inform the exporter of the buffer that the current DMABUF
- * buffer is no longer used; the buf_priv argument is the
+ * buffer is no longer used; the @buf_priv argument is the
* allocator private per-buffer structure previously returned
* from the attach_dmabuf callback.
* @map_dmabuf: request for access to the dmabuf from allocator; the allocator
@@ -109,11 +109,13 @@ struct vb2_threadio_data;
*
* #) 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.
+ * #) Required ops for DMABUF types: attach_dmabuf, detach_dmabuf,
+ * map_dmabuf, unmap_dmabuf.
*/
struct vb2_mem_ops {
void *(*alloc)(struct device *dev, unsigned long attrs,
- unsigned long size, enum dma_data_direction dma_dir,
+ unsigned long size,
+ enum dma_data_direction dma_dir,
gfp_t gfp_flags);
void (*put)(void *buf_priv);
struct dma_buf *(*get_dmabuf)(void *buf_priv, unsigned long flags);
@@ -126,7 +128,8 @@ struct vb2_mem_ops {
void (*prepare)(void *buf_priv);
void (*finish)(void *buf_priv);
- void *(*attach_dmabuf)(struct device *dev, struct dma_buf *dbuf,
+ void *(*attach_dmabuf)(struct device *dev,
+ struct dma_buf *dbuf,
unsigned long size,
enum dma_data_direction dma_dir);
void (*detach_dmabuf)(void *buf_priv);
@@ -291,7 +294,7 @@ 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
@@ -302,11 +305,11 @@ struct vb2_buffer {
* 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
+ * 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
* number of buffers that are being allocated. When called
- * from %VIDIOC_CREATE_BUFS, \*num_planes != 0 and it
+ * 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
@@ -325,11 +328,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
@@ -353,24 +356,25 @@ struct vb2_buffer {
* 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\).
+ * by calling vb2_buffer_done() with %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
- * start_streaming won't be called until at least that
+ * @start_streaming won't be called until at least that
* 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
+ * 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 %VIDIOC_STREAMON ioctl;
- * might be called before start_streaming callback if user
- * pre-queued buffers before calling %VIDIOC_STREAMON.
+ * it is allways called after calling VIDIOC_STREAMON()
+ * ioctl; might be called before @start_streaming callback
+ * if user pre-queued buffers before calling
+ * VIDIOC_STREAMON().
*/
struct vb2_ops {
int (*queue_setup)(struct vb2_queue *q,
@@ -418,7 +422,7 @@ struct vb2_buf_ops {
*
* @type: private buffer type whose content is defined by the vb2-core
* caller. For example, for V4L2, it should match
- * the V4L2_BUF_TYPE_* in include/uapi/linux/videodev2.h
+ * the types defined on enum &v4l2_buf_type
* @io_modes: supported io methods (see vb2_io_modes enum)
* @dev: device to use for the default allocation context if the driver
* doesn't fill in the @alloc_devs array.
@@ -453,12 +457,12 @@ struct vb2_buf_ops {
* Typically this is 0, but it may be e.g. GFP_DMA or __GFP_DMA32
* to force the buffer allocation to a specific memory zone.
* @min_buffers_needed: the minimum number of buffers needed before
- * start_streaming() can be called. Used when a DMA engine
+ * @start_streaming can be called. Used when a DMA engine
* cannot be started unless at least this number of buffers
* have been queued into the driver.
*/
/*
- * Private elements (won't appear at the DocBook):
+ * Private elements (won't appear at the uAPI book):
* @mmap_lock: private mutex used when buffers are allocated/freed/mmapped
* @memory: current memory type used
* @bufs: videobuf buffer structures
@@ -471,7 +475,7 @@ struct vb2_buf_ops {
* @done_wq: waitqueue for processes waiting for buffers ready to be dequeued
* @alloc_devs: memory type/allocator-specific per-plane device
* @streaming: current streaming state
- * @start_streaming_called: start_streaming() was called successfully and we
+ * @start_streaming_called: @start_streaming was called successfully and we
* started streaming.
* @error: a fatal error occurred on the queue
* @waiting_for_buffers: used in poll() to check if vb2 is still waiting for
@@ -576,17 +580,18 @@ void *vb2_plane_cookie(struct vb2_buffer *vb, unsigned int plane_no);
/**
* vb2_buffer_done() - inform videobuf that an operation on a buffer is finished
* @vb: vb2_buffer returned from the driver
- * @state: either %VB2_BUF_STATE_DONE if the operation finished successfully,
- * %VB2_BUF_STATE_ERROR if the operation finished with an error or
- * %VB2_BUF_STATE_QUEUED if the driver wants to requeue buffers.
- * If start_streaming fails then it should return buffers with state
- * %VB2_BUF_STATE_QUEUED to put them back into the queue.
+ * @state: either %VB2_BUF_STATE_DONE if the operation finished
+ * successfully, %VB2_BUF_STATE_ERROR if the operation finished
+ * with an error or %VB2_BUF_STATE_QUEUED if the driver wants to
+ * requeue buffers. If start_streaming fails then it should return
+ * buffers with state %VB2_BUF_STATE_QUEUED to put them back into
+ * the queue.
*
* This function should be called by the driver after a hardware operation on
* a buffer is finished and the buffer may be returned to userspace. The driver
* cannot use this buffer anymore until it is queued back to it by videobuf
- * by the means of buf_queue callback. Only buffers previously queued to the
- * driver by buf_queue can be passed to this function.
+ * by the means of &vb2_ops->buf_queue callback. Only buffers previously queued
+ * to the driver by &vb2_ops->buf_queue can be passed to this function.
*
* While streaming a buffer can only be returned in state DONE or ERROR.
* The start_streaming op can also return them in case the DMA engine cannot
@@ -614,9 +619,9 @@ void vb2_discard_done(struct vb2_queue *q);
* @q: videobuf2 queue
*
* This function will wait until all buffers that have been given to the driver
- * by buf_queue() are given back to vb2 with vb2_buffer_done(). It doesn't call
- * wait_prepare, wait_finish pair. It is intended to be called with all locks
- * taken, for example from stop_streaming() callback.
+ * by &vb2_ops->buf_queue are given back to vb2 with vb2_buffer_done(). It
+ * doesn't call wait_prepare()/wait_finish() pair. It is intended to be called
+ * with all locks taken, for example from &vb2_ops->stop_streaming callback.
*/
int vb2_wait_for_all_buffers(struct vb2_queue *q);
@@ -639,14 +644,16 @@ void vb2_core_querybuf(struct vb2_queue *q, unsigned int index, void *pb);
* @count: requested buffer count
*
* Should be called from vidioc_reqbufs ioctl handler of a driver.
+ *
* This function:
- * 1) verifies streaming parameters passed from the userspace,
- * 2) sets up the queue,
- * 3) negotiates number of buffers and planes per buffer with the driver
+ *
+ * #) 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,
- * 4) allocates internal buffer structures (struct vb2_buffer), according to
+ * #) allocates internal buffer structures (struct vb2_buffer), according to
* the agreed parameters,
- * 5) for MMAP memory type, allocates actual video memory, using the
+ * #) for MMAP memory type, allocates actual video memory, using the
* memory handling/allocation routines provided during queue initialization
*
* If req->count is 0, all the memory will be freed instead.
@@ -664,20 +671,22 @@ int vb2_core_reqbufs(struct vb2_queue *q, enum vb2_memory memory,
* @q: videobuf2 queue
* @memory: memory type
* @count: requested buffer count
- * @parg: parameter passed to device driver
+ * @requested_planes: number of planes requested
+ * @requested_sizes: array with the size of the planes
*
- * Should be called from vidioc_create_bufs ioctl handler of a driver.
+ * Should be called from VIDIOC_CREATE_BUFS() ioctl handler of a driver.
* This function:
- * 1) verifies parameter sanity
- * 2) calls the .queue_setup() queue operation
- * 3) performs any necessary memory allocations
*
- * The return values from this function are intended to be directly returned
- * from vidioc_create_bufs handler in driver.
+ * #) verifies parameter sanity
+ * #) calls the .queue_setup() queue operation
+ * #) performs any necessary memory allocations
+ *
+ * Return: the return values from this function are intended to be directly
+ * returned from VIDIOC_CREATE_BUFS() handler in driver.
*/
int vb2_core_create_bufs(struct vb2_queue *q, enum vb2_memory memory,
- unsigned int *count, unsigned requested_planes,
- const unsigned int requested_sizes[]);
+ unsigned int *count, unsigned int requested_planes,
+ const unsigned int requested_sizes[]);
/**
* vb2_core_prepare_buf() - Pass ownership of a buffer from userspace
@@ -699,6 +708,7 @@ int vb2_core_prepare_buf(struct vb2_queue *q, unsigned int index, void *pb);
/**
* vb2_core_qbuf() - Queue a buffer from userspace
+ *
* @q: videobuf2 queue
* @index: id number of the buffer
* @pb: buffer structure passed from userspace to vidioc_qbuf handler
@@ -706,11 +716,13 @@ int vb2_core_prepare_buf(struct vb2_queue *q, unsigned int index, void *pb);
*
* Should be called from vidioc_qbuf ioctl handler of a driver.
* The passed buffer should have been verified.
+ *
* This function:
- * 1) if necessary, calls buf_prepare callback in the driver (if provided), in
+ *
+ * #) if necessary, calls buf_prepare callback in the driver (if provided), in
* which driver-specific buffer initialization can be performed,
- * 2) if streaming is on, queues the buffer in driver by the means of buf_queue
- * callback for processing.
+ * #) if streaming is on, queues the buffer in driver by the means of
+ * &vb2_ops->buf_queue callback for processing.
*
* The return values from this function are intended to be directly returned
* from vidioc_qbuf handler in driver.
@@ -729,11 +741,13 @@ int vb2_core_qbuf(struct vb2_queue *q, unsigned int index, void *pb);
*
* Should be called from vidioc_dqbuf ioctl handler of a driver.
* The passed buffer should have been verified.
+ *
* This function:
- * 1) calls buf_finish callback in the driver (if provided), in which
+ *
+ * #) calls buf_finish callback in the driver (if provided), in which
* driver can perform any additional operations that may be required before
* returning the buffer to userspace, such as cache sync,
- * 2) the buffer struct members are filled with relevant information for
+ * #) the buffer struct members are filled with relevant information for
* the userspace.
*
* The return values from this function are intended to be directly returned
@@ -819,6 +833,7 @@ void vb2_queue_error(struct vb2_queue *q);
* from the mmap handler in driver.
*/
int vb2_mmap(struct vb2_queue *q, struct vm_area_struct *vma);
+
#ifndef CONFIG_MMU
unsigned long vb2_get_unmapped_area(struct vb2_queue *q,
unsigned long addr,
@@ -844,14 +859,18 @@ unsigned long vb2_get_unmapped_area(struct vb2_queue *q,
* from poll handler in driver.
*/
unsigned int vb2_core_poll(struct vb2_queue *q, struct file *file,
- poll_table *wait);
+ poll_table *wait);
+
size_t vb2_read(struct vb2_queue *q, char __user *data, size_t count,
loff_t *ppos, int nonblock);
size_t vb2_write(struct vb2_queue *q, const char __user *data, size_t count,
loff_t *ppos, int nonblock);
-/*
- * vb2_thread_fnc - callback function for use with vb2_thread
+/**
+ * typedef vb2_thread_fnc - callback function for use with vb2_thread
+ *
+ * @vb: pointer to struct &vb2_buffer
+ * @priv: pointer to a private pointer
*
* This is called whenever a buffer is dequeued in the thread.
*/
@@ -867,9 +886,11 @@ typedef int (*vb2_thread_fnc)(struct vb2_buffer *vb, void *priv);
* This starts a thread that will queue and dequeue until an error occurs
* or @vb2_thread_stop is called.
*
- * This function should not be used for anything else but the videobuf2-dvb
- * support. If you think you have another good use-case for this, then please
- * contact the linux-media mailinglist first.
+ * .. attention::
+ *
+ * This function should not be used for anything else but the videobuf2-dvb
+ * support. If you think you have another good use-case for this, then please
+ * contact the linux-media mailing list first.
*/
int vb2_thread_start(struct vb2_queue *q, vb2_thread_fnc fnc, void *priv,
const char *thread_name);
@@ -1000,6 +1021,12 @@ bool vb2_buffer_in_use(struct vb2_queue *q, struct vb2_buffer *vb);
/**
* vb2_verify_memory_type() - Check whether the memory type and buffer type
* passed to a buffer operation are compatible with the queue.
+ *
+ * @q: videobuf queue
+ * @memory: memory model, as defined by enum &vb2_memory.
+ * @type: private buffer type whose content is defined by the vb2-core
+ * caller. For example, for V4L2, it should match
+ * the types defined on enum &v4l2_buf_type
*/
int vb2_verify_memory_type(struct vb2_queue *q,
enum vb2_memory memory, unsigned int type);
--
2.7.4
^ permalink raw reply related [flat|nested] 16+ messages in thread* [PATCH 10/15] [media] conf_nitpick.py: ignore C domain data used on vb2
2016-09-08 21:37 [PATCH 00/15] Fix another set of nitpick warnings Mauro Carvalho Chehab
` (8 preceding siblings ...)
2016-09-08 21:37 ` [PATCH 09/15] [media] videobuf2-core.h: improve documentation Mauro Carvalho Chehab
@ 2016-09-08 21:37 ` Mauro Carvalho Chehab
2016-09-08 21:37 ` [PATCH 11/15] [media] videobuf2-v4l2.h: get kernel-doc tags from C file Mauro Carvalho Chehab
` (4 subsequent siblings)
14 siblings, 0 replies; 16+ messages in thread
From: Mauro Carvalho Chehab @ 2016-09-08 21:37 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Jonathan Corbet,
Mauro Carvalho Chehab, Markus Heiser, linux-doc
Ignore external C domain structs and functions used by VB2
header.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/media/conf_nitpick.py | 4 ++++
1 file changed, 4 insertions(+)
diff --git a/Documentation/media/conf_nitpick.py b/Documentation/media/conf_nitpick.py
index f71bb947eb15..480d548af670 100644
--- a/Documentation/media/conf_nitpick.py
+++ b/Documentation/media/conf_nitpick.py
@@ -40,6 +40,8 @@ nitpick_ignore = [
("c:func", "struct fd_set"),
("c:func", "struct pollfd"),
("c:func", "usb_make_path"),
+ ("c:func", "wait_finish"),
+ ("c:func", "wait_prepare"),
("c:func", "write"),
("c:type", "atomic_t"),
@@ -67,6 +69,7 @@ nitpick_ignore = [
("c:type", "off_t"),
("c:type", "pci_dev"),
("c:type", "pdvbdev"),
+ ("c:type", "poll_table"),
("c:type", "platform_device"),
("c:type", "pollfd"),
("c:type", "poll_table_struct"),
@@ -98,6 +101,7 @@ nitpick_ignore = [
("c:type", "usb_interface"),
("c:type", "v4l2_std_id"),
("c:type", "video_system_t"),
+ ("c:type", "vm_area_struct"),
# Opaque structures
--
2.7.4
^ permalink raw reply related [flat|nested] 16+ messages in thread* [PATCH 11/15] [media] videobuf2-v4l2.h: get kernel-doc tags from C file
2016-09-08 21:37 [PATCH 00/15] Fix another set of nitpick warnings Mauro Carvalho Chehab
` (9 preceding siblings ...)
2016-09-08 21:37 ` [PATCH 10/15] [media] conf_nitpick.py: ignore C domain data used on vb2 Mauro Carvalho Chehab
@ 2016-09-08 21:37 ` Mauro Carvalho Chehab
2016-09-08 21:37 ` [PATCH 12/15] [media] videobuf2-v4l2.h: improve documentation Mauro Carvalho Chehab
` (3 subsequent siblings)
14 siblings, 0 replies; 16+ messages in thread
From: Mauro Carvalho Chehab @ 2016-09-08 21:37 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Pawel Osciak,
Marek Szyprowski, Kyungmin Park, Mauro Carvalho Chehab
There are several functions documented at the C file. Move
them to the header, as this is the one used to build the
media books.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
drivers/media/v4l2-core/videobuf2-v4l2.c | 142 -----------------------------
include/media/videobuf2-v4l2.h | 151 ++++++++++++++++++++++++++++++-
2 files changed, 150 insertions(+), 143 deletions(-)
diff --git a/drivers/media/v4l2-core/videobuf2-v4l2.c b/drivers/media/v4l2-core/videobuf2-v4l2.c
index 9cfbb6e4bc28..52ef8833f6b6 100644
--- a/drivers/media/v4l2-core/videobuf2-v4l2.c
+++ b/drivers/media/v4l2-core/videobuf2-v4l2.c
@@ -483,13 +483,6 @@ int vb2_querybuf(struct vb2_queue *q, struct v4l2_buffer *b)
}
EXPORT_SYMBOL(vb2_querybuf);
-/**
- * vb2_reqbufs() - Wrapper for vb2_core_reqbufs() that also verifies
- * the memory and type values.
- * @q: videobuf2 queue
- * @req: struct passed from userspace to vidioc_reqbufs handler
- * in driver
- */
int vb2_reqbufs(struct vb2_queue *q, struct v4l2_requestbuffers *req)
{
int ret = vb2_verify_memory_type(q, req->memory, req->type);
@@ -498,21 +491,6 @@ int vb2_reqbufs(struct vb2_queue *q, struct v4l2_requestbuffers *req)
}
EXPORT_SYMBOL_GPL(vb2_reqbufs);
-/**
- * vb2_prepare_buf() - Pass ownership of a buffer from userspace to the kernel
- * @q: videobuf2 queue
- * @b: buffer structure passed from userspace to vidioc_prepare_buf
- * handler in driver
- *
- * Should be called from vidioc_prepare_buf ioctl handler of a driver.
- * This function:
- * 1) verifies the passed buffer,
- * 2) calls buf_prepare callback in the driver (if provided), in which
- * driver-specific buffer initialization can be performed,
- *
- * The return values from this function are intended to be directly returned
- * from vidioc_prepare_buf handler in driver.
- */
int vb2_prepare_buf(struct vb2_queue *q, struct v4l2_buffer *b)
{
int ret;
@@ -528,13 +506,6 @@ int vb2_prepare_buf(struct vb2_queue *q, struct v4l2_buffer *b)
}
EXPORT_SYMBOL_GPL(vb2_prepare_buf);
-/**
- * vb2_create_bufs() - Wrapper for vb2_core_create_bufs() that also verifies
- * the memory and type values.
- * @q: videobuf2 queue
- * @create: creation parameters, passed from userspace to vidioc_create_bufs
- * handler in driver
- */
int vb2_create_bufs(struct vb2_queue *q, struct v4l2_create_buffers *create)
{
unsigned requested_planes = 1;
@@ -586,23 +557,6 @@ int vb2_create_bufs(struct vb2_queue *q, struct v4l2_create_buffers *create)
}
EXPORT_SYMBOL_GPL(vb2_create_bufs);
-/**
- * vb2_qbuf() - Queue a buffer from userspace
- * @q: videobuf2 queue
- * @b: buffer structure passed from userspace to vidioc_qbuf handler
- * in driver
- *
- * Should be called from vidioc_qbuf ioctl handler of a driver.
- * This function:
- * 1) verifies the passed buffer,
- * 2) if necessary, calls buf_prepare callback in the driver (if provided), in
- * which driver-specific buffer initialization can be performed,
- * 3) if streaming is on, queues the buffer in driver by the means of buf_queue
- * callback for processing.
- *
- * The return values from this function are intended to be directly returned
- * from vidioc_qbuf handler in driver.
- */
int vb2_qbuf(struct vb2_queue *q, struct v4l2_buffer *b)
{
int ret;
@@ -617,27 +571,6 @@ int vb2_qbuf(struct vb2_queue *q, struct v4l2_buffer *b)
}
EXPORT_SYMBOL_GPL(vb2_qbuf);
-/**
- * vb2_dqbuf() - Dequeue a buffer to the userspace
- * @q: videobuf2 queue
- * @b: buffer structure passed from userspace to vidioc_dqbuf handler
- * in driver
- * @nonblocking: if true, this call will not sleep waiting for a buffer if no
- * buffers ready for dequeuing are present. Normally the driver
- * would be passing (file->f_flags & O_NONBLOCK) here
- *
- * Should be called from vidioc_dqbuf ioctl handler of a driver.
- * This function:
- * 1) verifies the passed buffer,
- * 2) calls buf_finish callback in the driver (if provided), in which
- * driver can perform any additional operations that may be required before
- * returning the buffer to userspace, such as cache sync,
- * 3) the buffer struct members are filled with relevant information for
- * the userspace.
- *
- * The return values from this function are intended to be directly returned
- * from vidioc_dqbuf handler in driver.
- */
int vb2_dqbuf(struct vb2_queue *q, struct v4l2_buffer *b, bool nonblocking)
{
int ret;
@@ -664,19 +597,6 @@ int vb2_dqbuf(struct vb2_queue *q, struct v4l2_buffer *b, bool nonblocking)
}
EXPORT_SYMBOL_GPL(vb2_dqbuf);
-/**
- * vb2_streamon - start streaming
- * @q: videobuf2 queue
- * @type: type argument passed from userspace to vidioc_streamon handler
- *
- * Should be called from vidioc_streamon handler of a driver.
- * This function:
- * 1) verifies current state
- * 2) passes any previously queued buffers to the driver and starts streaming
- *
- * The return values from this function are intended to be directly returned
- * from vidioc_streamon handler in the driver.
- */
int vb2_streamon(struct vb2_queue *q, enum v4l2_buf_type type)
{
if (vb2_fileio_is_active(q)) {
@@ -687,21 +607,6 @@ int vb2_streamon(struct vb2_queue *q, enum v4l2_buf_type type)
}
EXPORT_SYMBOL_GPL(vb2_streamon);
-/**
- * vb2_streamoff - stop streaming
- * @q: videobuf2 queue
- * @type: type argument passed from userspace to vidioc_streamoff handler
- *
- * Should be called from vidioc_streamoff handler of a driver.
- * This function:
- * 1) verifies current state,
- * 2) stop streaming and dequeues any queued buffers, including those previously
- * passed to the driver (after waiting for the driver to finish).
- *
- * This call can be used for pausing playback.
- * The return values from this function are intended to be directly returned
- * from vidioc_streamoff handler in the driver
- */
int vb2_streamoff(struct vb2_queue *q, enum v4l2_buf_type type)
{
if (vb2_fileio_is_active(q)) {
@@ -712,15 +617,6 @@ int vb2_streamoff(struct vb2_queue *q, enum v4l2_buf_type type)
}
EXPORT_SYMBOL_GPL(vb2_streamoff);
-/**
- * vb2_expbuf() - Export a buffer as a file descriptor
- * @q: videobuf2 queue
- * @eb: export buffer structure passed from userspace to vidioc_expbuf
- * handler in driver
- *
- * The return values from this function are intended to be directly returned
- * from vidioc_expbuf handler in driver.
- */
int vb2_expbuf(struct vb2_queue *q, struct v4l2_exportbuffer *eb)
{
return vb2_core_expbuf(q, &eb->fd, eb->type, eb->index,
@@ -728,17 +624,6 @@ int vb2_expbuf(struct vb2_queue *q, struct v4l2_exportbuffer *eb)
}
EXPORT_SYMBOL_GPL(vb2_expbuf);
-/**
- * vb2_queue_init() - initialize a videobuf2 queue
- * @q: videobuf2 queue; this structure should be allocated in driver
- *
- * The vb2_queue structure should be allocated by the driver. The driver is
- * responsible of clearing it's content and setting initial values for some
- * required entries before calling this function.
- * q->ops, q->mem_ops, q->type and q->io_modes are mandatory. Please refer
- * to the struct vb2_queue description in include/media/videobuf2-core.h
- * for more information.
- */
int vb2_queue_init(struct vb2_queue *q)
{
/*
@@ -779,39 +664,12 @@ int vb2_queue_init(struct vb2_queue *q)
}
EXPORT_SYMBOL_GPL(vb2_queue_init);
-/**
- * vb2_queue_release() - stop streaming, release the queue and free memory
- * @q: videobuf2 queue
- *
- * This function stops streaming and performs necessary clean ups, including
- * freeing video buffer memory. The driver is responsible for freeing
- * the vb2_queue structure itself.
- */
void vb2_queue_release(struct vb2_queue *q)
{
vb2_core_queue_release(q);
}
EXPORT_SYMBOL_GPL(vb2_queue_release);
-/**
- * vb2_poll() - implements poll userspace operation
- * @q: videobuf2 queue
- * @file: file argument passed to the poll file operation handler
- * @wait: wait argument passed to the poll file operation handler
- *
- * This function implements poll file operation handler for a driver.
- * For CAPTURE queues, if a buffer is ready to be dequeued, the userspace will
- * be informed that the file descriptor of a video device is available for
- * reading.
- * For OUTPUT queues, if a buffer is ready to be dequeued, the file descriptor
- * will be reported as available for writing.
- *
- * If the driver uses struct v4l2_fh, then vb2_poll() will also check for any
- * pending events.
- *
- * The return values from this function are intended to be directly returned
- * from poll handler in driver.
- */
unsigned int vb2_poll(struct vb2_queue *q, struct file *file, poll_table *wait)
{
struct video_device *vfd = video_devdata(file);
diff --git a/include/media/videobuf2-v4l2.h b/include/media/videobuf2-v4l2.h
index 3cc836f76675..01b1b71fc6fd 100644
--- a/include/media/videobuf2-v4l2.h
+++ b/include/media/videobuf2-v4l2.h
@@ -49,22 +49,171 @@ struct vb2_v4l2_buffer {
container_of(vb, struct vb2_v4l2_buffer, vb2_buf)
int vb2_querybuf(struct vb2_queue *q, struct v4l2_buffer *b);
+
+/**
+ * vb2_reqbufs() - Wrapper for vb2_core_reqbufs() that also verifies
+ * the memory and type values.
+ * @q: videobuf2 queue
+ * @req: struct passed from userspace to vidioc_reqbufs handler
+ * in driver
+ */
int vb2_reqbufs(struct vb2_queue *q, struct v4l2_requestbuffers *req);
+/**
+ * vb2_create_bufs() - Wrapper for vb2_core_create_bufs() that also verifies
+ * the memory and type values.
+ * @q: videobuf2 queue
+ * @create: creation parameters, passed from userspace to vidioc_create_bufs
+ * handler in driver
+ */
int vb2_create_bufs(struct vb2_queue *q, struct v4l2_create_buffers *create);
+
+/**
+ * vb2_prepare_buf() - Pass ownership of a buffer from userspace to the kernel
+ * @q: videobuf2 queue
+ * @b: buffer structure passed from userspace to vidioc_prepare_buf
+ * handler in driver
+ *
+ * Should be called from vidioc_prepare_buf ioctl handler of a driver.
+ * This function:
+ * 1) verifies the passed buffer,
+ * 2) calls buf_prepare callback in the driver (if provided), in which
+ * driver-specific buffer initialization can be performed,
+ *
+ * The return values from this function are intended to be directly returned
+ * from vidioc_prepare_buf handler in driver.
+ */
int vb2_prepare_buf(struct vb2_queue *q, struct v4l2_buffer *b);
+/**
+ * vb2_qbuf() - Queue a buffer from userspace
+ * @q: videobuf2 queue
+ * @b: buffer structure passed from userspace to vidioc_qbuf handler
+ * in driver
+ *
+ * Should be called from vidioc_qbuf ioctl handler of a driver.
+ * This function:
+ * 1) verifies the passed buffer,
+ * 2) if necessary, calls buf_prepare callback in the driver (if provided), in
+ * which driver-specific buffer initialization can be performed,
+ * 3) if streaming is on, queues the buffer in driver by the means of buf_queue
+ * callback for processing.
+ *
+ * The return values from this function are intended to be directly returned
+ * from vidioc_qbuf handler in driver.
+ */
int vb2_qbuf(struct vb2_queue *q, struct v4l2_buffer *b);
+
+/**
+ * vb2_expbuf() - Export a buffer as a file descriptor
+ * @q: videobuf2 queue
+ * @eb: export buffer structure passed from userspace to vidioc_expbuf
+ * handler in driver
+ *
+ * The return values from this function are intended to be directly returned
+ * from vidioc_expbuf handler in driver.
+ */
int vb2_expbuf(struct vb2_queue *q, struct v4l2_exportbuffer *eb);
+
+/**
+ * vb2_dqbuf() - Dequeue a buffer to the userspace
+ * @q: videobuf2 queue
+ * @b: buffer structure passed from userspace to vidioc_dqbuf handler
+ * in driver
+ * @nonblocking: if true, this call will not sleep waiting for a buffer if no
+ * buffers ready for dequeuing are present. Normally the driver
+ * would be passing (file->f_flags & O_NONBLOCK) here
+ *
+ * Should be called from vidioc_dqbuf ioctl handler of a driver.
+ * This function:
+ * 1) verifies the passed buffer,
+ * 2) calls buf_finish callback in the driver (if provided), in which
+ * driver can perform any additional operations that may be required before
+ * returning the buffer to userspace, such as cache sync,
+ * 3) the buffer struct members are filled with relevant information for
+ * the userspace.
+ *
+ * The return values from this function are intended to be directly returned
+ * from vidioc_dqbuf handler in driver.
+ */
int vb2_dqbuf(struct vb2_queue *q, struct v4l2_buffer *b, bool nonblocking);
+/**
+ * vb2_streamon - start streaming
+ * @q: videobuf2 queue
+ * @type: type argument passed from userspace to vidioc_streamon handler
+ *
+ * Should be called from vidioc_streamon handler of a driver.
+ * This function:
+ * 1) verifies current state
+ * 2) passes any previously queued buffers to the driver and starts streaming
+ *
+ * The return values from this function are intended to be directly returned
+ * from vidioc_streamon handler in the driver.
+ */
int vb2_streamon(struct vb2_queue *q, enum v4l2_buf_type type);
+
+/**
+ * vb2_streamoff - stop streaming
+ * @q: videobuf2 queue
+ * @type: type argument passed from userspace to vidioc_streamoff handler
+ *
+ * Should be called from vidioc_streamoff handler of a driver.
+ * This function:
+ * 1) verifies current state,
+ * 2) stop streaming and dequeues any queued buffers, including those previously
+ * passed to the driver (after waiting for the driver to finish).
+ *
+ * This call can be used for pausing playback.
+ * The return values from this function are intended to be directly returned
+ * from vidioc_streamoff handler in the driver
+ */
int vb2_streamoff(struct vb2_queue *q, enum v4l2_buf_type type);
+/**
+ * vb2_queue_init() - initialize a videobuf2 queue
+ * @q: videobuf2 queue; this structure should be allocated in driver
+ *
+ * The vb2_queue structure should be allocated by the driver. The driver is
+ * responsible of clearing it's content and setting initial values for some
+ * required entries before calling this function.
+ * q->ops, q->mem_ops, q->type and q->io_modes are mandatory. Please refer
+ * to the struct vb2_queue description in include/media/videobuf2-core.h
+ * for more information.
+ */
int __must_check vb2_queue_init(struct vb2_queue *q);
+
+/**
+ * vb2_queue_release() - stop streaming, release the queue and free memory
+ * @q: videobuf2 queue
+ *
+ * This function stops streaming and performs necessary clean ups, including
+ * freeing video buffer memory. The driver is responsible for freeing
+ * the vb2_queue structure itself.
+ */
void vb2_queue_release(struct vb2_queue *q);
+
+/**
+ * vb2_poll() - implements poll userspace operation
+ * @q: videobuf2 queue
+ * @file: file argument passed to the poll file operation handler
+ * @wait: wait argument passed to the poll file operation handler
+ *
+ * This function implements poll file operation handler for a driver.
+ * For CAPTURE queues, if a buffer is ready to be dequeued, the userspace will
+ * be informed that the file descriptor of a video device is available for
+ * reading.
+ * For OUTPUT queues, if a buffer is ready to be dequeued, the file descriptor
+ * will be reported as available for writing.
+ *
+ * If the driver uses struct v4l2_fh, then vb2_poll() will also check for any
+ * pending events.
+ *
+ * The return values from this function are intended to be directly returned
+ * from poll handler in driver.
+ */
unsigned int vb2_poll(struct vb2_queue *q, struct file *file,
- poll_table *wait);
+ poll_table *wait);
/*
* The following functions are not part of the vb2 core API, but are simple
--
2.7.4
^ permalink raw reply related [flat|nested] 16+ messages in thread* [PATCH 12/15] [media] videobuf2-v4l2.h: improve documentation
2016-09-08 21:37 [PATCH 00/15] Fix another set of nitpick warnings Mauro Carvalho Chehab
` (10 preceding siblings ...)
2016-09-08 21:37 ` [PATCH 11/15] [media] videobuf2-v4l2.h: get kernel-doc tags from C file Mauro Carvalho Chehab
@ 2016-09-08 21:37 ` Mauro Carvalho Chehab
2016-09-08 21:37 ` [PATCH 13/15] [media] videobuf2-v4l2: document two helper functions Mauro Carvalho Chehab
` (2 subsequent siblings)
14 siblings, 0 replies; 16+ messages in thread
From: Mauro Carvalho Chehab @ 2016-09-08 21:37 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Pawel Osciak,
Marek Szyprowski, Kyungmin Park, Mauro Carvalho Chehab
There are a few issues at the documentation: fields not documented,
bad cross refrences, etc.
Fix them.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
include/media/videobuf2-v4l2.h | 52 +++++++++++++++++++++++++++---------------
1 file changed, 33 insertions(+), 19 deletions(-)
diff --git a/include/media/videobuf2-v4l2.h b/include/media/videobuf2-v4l2.h
index 01b1b71fc6fd..611d4f330a4c 100644
--- a/include/media/videobuf2-v4l2.h
+++ b/include/media/videobuf2-v4l2.h
@@ -25,11 +25,13 @@
/**
* struct vb2_v4l2_buffer - video buffer information for v4l2
+ *
* @vb2_buf: video buffer 2
* @flags: buffer informational flags
* @field: enum v4l2_field; field order of the image in the buffer
* @timecode: frame timecode
* @sequence: sequence count of this frame
+ *
* Should contain enough information to be able to cover all the fields
* of struct v4l2_buffer at videodev2.h
*/
@@ -53,6 +55,7 @@ int vb2_querybuf(struct vb2_queue *q, struct v4l2_buffer *b);
/**
* vb2_reqbufs() - Wrapper for vb2_core_reqbufs() that also verifies
* the memory and type values.
+ *
* @q: videobuf2 queue
* @req: struct passed from userspace to vidioc_reqbufs handler
* in driver
@@ -62,6 +65,7 @@ int vb2_reqbufs(struct vb2_queue *q, struct v4l2_requestbuffers *req);
/**
* vb2_create_bufs() - Wrapper for vb2_core_create_bufs() that also verifies
* the memory and type values.
+ *
* @q: videobuf2 queue
* @create: creation parameters, passed from userspace to vidioc_create_bufs
* handler in driver
@@ -70,15 +74,17 @@ int vb2_create_bufs(struct vb2_queue *q, struct v4l2_create_buffers *create);
/**
* vb2_prepare_buf() - Pass ownership of a buffer from userspace to the kernel
+ *
* @q: videobuf2 queue
* @b: buffer structure passed from userspace to vidioc_prepare_buf
* handler in driver
*
* Should be called from vidioc_prepare_buf ioctl handler of a driver.
* This function:
- * 1) verifies the passed buffer,
- * 2) calls buf_prepare callback in the driver (if provided), in which
- * driver-specific buffer initialization can be performed,
+ *
+ * #) verifies the passed buffer,
+ * #) calls buf_prepare callback in the driver (if provided), in which
+ * driver-specific buffer initialization can be performed.
*
* The return values from this function are intended to be directly returned
* from vidioc_prepare_buf handler in driver.
@@ -88,53 +94,57 @@ int vb2_prepare_buf(struct vb2_queue *q, struct v4l2_buffer *b);
/**
* vb2_qbuf() - Queue a buffer from userspace
* @q: videobuf2 queue
- * @b: buffer structure passed from userspace to vidioc_qbuf handler
+ * @b: buffer structure passed from userspace to VIDIOC_QBUF() handler
* in driver
*
- * Should be called from vidioc_qbuf ioctl handler of a driver.
+ * Should be called from VIDIOC_QBUF() ioctl handler of a driver.
+ *
* This function:
- * 1) verifies the passed buffer,
- * 2) if necessary, calls buf_prepare callback in the driver (if provided), in
+ *
+ * #) verifies the passed buffer,
+ * #) if necessary, calls buf_prepare callback in the driver (if provided), in
* which driver-specific buffer initialization can be performed,
- * 3) if streaming is on, queues the buffer in driver by the means of buf_queue
+ * #) if streaming is on, queues the buffer in driver by the means of buf_queue
* callback for processing.
*
* The return values from this function are intended to be directly returned
- * from vidioc_qbuf handler in driver.
+ * from VIDIOC_QBUF() handler in driver.
*/
int vb2_qbuf(struct vb2_queue *q, struct v4l2_buffer *b);
/**
* vb2_expbuf() - Export a buffer as a file descriptor
* @q: videobuf2 queue
- * @eb: export buffer structure passed from userspace to vidioc_expbuf
+ * @eb: export buffer structure passed from userspace to VIDIOC_EXPBUF()
* handler in driver
*
* The return values from this function are intended to be directly returned
- * from vidioc_expbuf handler in driver.
+ * from VIDIOC_EXPBUF() handler in driver.
*/
int vb2_expbuf(struct vb2_queue *q, struct v4l2_exportbuffer *eb);
/**
* vb2_dqbuf() - Dequeue a buffer to the userspace
* @q: videobuf2 queue
- * @b: buffer structure passed from userspace to vidioc_dqbuf handler
+ * @b: buffer structure passed from userspace to VIDIOC_DQBUF() handler
* in driver
* @nonblocking: if true, this call will not sleep waiting for a buffer if no
* buffers ready for dequeuing are present. Normally the driver
* would be passing (file->f_flags & O_NONBLOCK) here
*
- * Should be called from vidioc_dqbuf ioctl handler of a driver.
+ * Should be called from VIDIOC_DQBUF() ioctl handler of a driver.
+ *
* This function:
- * 1) verifies the passed buffer,
- * 2) calls buf_finish callback in the driver (if provided), in which
+ *
+ * #) verifies the passed buffer,
+ * #) calls buf_finish callback in the driver (if provided), in which
* driver can perform any additional operations that may be required before
* returning the buffer to userspace, such as cache sync,
- * 3) the buffer struct members are filled with relevant information for
+ * #) the buffer struct members are filled with relevant information for
* the userspace.
*
* The return values from this function are intended to be directly returned
- * from vidioc_dqbuf handler in driver.
+ * from VIDIOC_DQBUF() handler in driver.
*/
int vb2_dqbuf(struct vb2_queue *q, struct v4l2_buffer *b, bool nonblocking);
@@ -144,7 +154,9 @@ int vb2_dqbuf(struct vb2_queue *q, struct v4l2_buffer *b, bool nonblocking);
* @type: type argument passed from userspace to vidioc_streamon handler
*
* Should be called from vidioc_streamon handler of a driver.
+ *
* This function:
+ *
* 1) verifies current state
* 2) passes any previously queued buffers to the driver and starts streaming
*
@@ -159,9 +171,11 @@ int vb2_streamon(struct vb2_queue *q, enum v4l2_buf_type type);
* @type: type argument passed from userspace to vidioc_streamoff handler
*
* Should be called from vidioc_streamoff handler of a driver.
+ *
* This function:
- * 1) verifies current state,
- * 2) stop streaming and dequeues any queued buffers, including those previously
+ *
+ * #) verifies current state,
+ * #) stop streaming and dequeues any queued buffers, including those previously
* passed to the driver (after waiting for the driver to finish).
*
* This call can be used for pausing playback.
--
2.7.4
^ permalink raw reply related [flat|nested] 16+ messages in thread* [PATCH 13/15] [media] videobuf2-v4l2: document two helper functions
2016-09-08 21:37 [PATCH 00/15] Fix another set of nitpick warnings Mauro Carvalho Chehab
` (11 preceding siblings ...)
2016-09-08 21:37 ` [PATCH 12/15] [media] videobuf2-v4l2.h: improve documentation Mauro Carvalho Chehab
@ 2016-09-08 21:37 ` Mauro Carvalho Chehab
2016-09-08 21:37 ` [PATCH 14/15] [media] v4l2-flash-led-class.h: document v4l2_flash_ops Mauro Carvalho Chehab
2016-09-08 21:37 ` [PATCH 15/15] [media] v4l2-subdev: fix some references to v4l2_dev Mauro Carvalho Chehab
14 siblings, 0 replies; 16+ messages in thread
From: Mauro Carvalho Chehab @ 2016-09-08 21:37 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Pawel Osciak,
Marek Szyprowski, Kyungmin Park, Mauro Carvalho Chehab
Document vb2_ops_wait_prepare() and vb2_ops_wait_finish(),
in order to fix those two warnings:
Documentation/media/kapi/v4l2-dev.rst:166: WARNING: c:func reference target not found: vb2_ops_wait_prepare
Documentation/media/kapi/v4l2-dev.rst:166: WARNING: c:func reference target not found: vb2_ops_wait_finish
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
include/media/videobuf2-v4l2.h | 17 +++++++++++++++--
1 file changed, 15 insertions(+), 2 deletions(-)
diff --git a/include/media/videobuf2-v4l2.h b/include/media/videobuf2-v4l2.h
index 611d4f330a4c..036127c54bbf 100644
--- a/include/media/videobuf2-v4l2.h
+++ b/include/media/videobuf2-v4l2.h
@@ -268,9 +268,22 @@ unsigned long vb2_fop_get_unmapped_area(struct file *file, unsigned long addr,
unsigned long len, unsigned long pgoff, unsigned long flags);
#endif
-/* struct vb2_ops helpers, only use if vq->lock is non-NULL. */
-
+/**
+ * vb2_ops_wait_prepare - helper function to lock a struct &vb2_queue
+ *
+ * @vq: pointer to struct vb2_queue
+ *
+ * ..note:: only use if vq->lock is non-NULL.
+ */
void vb2_ops_wait_prepare(struct vb2_queue *vq);
+
+/**
+ * vb2_ops_wait_finish - helper function to unlock a struct &vb2_queue
+ *
+ * @vq: pointer to struct vb2_queue
+ *
+ * ..note:: only use if vq->lock is non-NULL.
+ */
void vb2_ops_wait_finish(struct vb2_queue *vq);
#endif /* _MEDIA_VIDEOBUF2_V4L2_H */
--
2.7.4
^ permalink raw reply related [flat|nested] 16+ messages in thread* [PATCH 14/15] [media] v4l2-flash-led-class.h: document v4l2_flash_ops
2016-09-08 21:37 [PATCH 00/15] Fix another set of nitpick warnings Mauro Carvalho Chehab
` (12 preceding siblings ...)
2016-09-08 21:37 ` [PATCH 13/15] [media] videobuf2-v4l2: document two helper functions Mauro Carvalho Chehab
@ 2016-09-08 21:37 ` Mauro Carvalho Chehab
2016-09-08 21:37 ` [PATCH 15/15] [media] v4l2-subdev: fix some references to v4l2_dev Mauro Carvalho Chehab
14 siblings, 0 replies; 16+ messages in thread
From: Mauro Carvalho Chehab @ 2016-09-08 21:37 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Mauro Carvalho Chehab
Fix this warning:
./include/media/v4l2-flash-led-class.h:103: WARNING: c:type reference target not found: v4l2_flash_ops
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
include/media/v4l2-flash-led-class.h | 15 +++++++++++----
1 file changed, 11 insertions(+), 4 deletions(-)
diff --git a/include/media/v4l2-flash-led-class.h b/include/media/v4l2-flash-led-class.h
index 3d184ab52274..b0fe4d6f4a5f 100644
--- a/include/media/v4l2-flash-led-class.h
+++ b/include/media/v4l2-flash-led-class.h
@@ -20,7 +20,7 @@ struct led_classdev;
struct v4l2_flash;
enum led_brightness;
-/*
+/**
* struct v4l2_flash_ctrl_data - flash control initialization data, filled
* basing on the features declared by the LED flash
* class driver in the v4l2_flash_config
@@ -33,14 +33,21 @@ struct v4l2_flash_ctrl_data {
u32 cid;
};
+/**
+ * struct v4l2_flash_ops - V4L2 flash operations
+ *
+ * @external_strobe_set: Setup strobing the flash by hardware pin state
+ * assertion.
+ * @intensity_to_led_brightness: Convert intensity to brightness in a device
+ * specific manner
+ * @led_brightness_to_intensity: convert brightness to intensity in a device
+ * specific manner.
+ */
struct v4l2_flash_ops {
- /* setup strobing the flash by hardware pin state assertion */
int (*external_strobe_set)(struct v4l2_flash *v4l2_flash,
bool enable);
- /* convert intensity to brightness in a device specific manner */
enum led_brightness (*intensity_to_led_brightness)
(struct v4l2_flash *v4l2_flash, s32 intensity);
- /* convert brightness to intensity in a device specific manner */
s32 (*led_brightness_to_intensity)
(struct v4l2_flash *v4l2_flash, enum led_brightness);
};
--
2.7.4
^ permalink raw reply related [flat|nested] 16+ messages in thread* [PATCH 15/15] [media] v4l2-subdev: fix some references to v4l2_dev
2016-09-08 21:37 [PATCH 00/15] Fix another set of nitpick warnings Mauro Carvalho Chehab
` (13 preceding siblings ...)
2016-09-08 21:37 ` [PATCH 14/15] [media] v4l2-flash-led-class.h: document v4l2_flash_ops Mauro Carvalho Chehab
@ 2016-09-08 21:37 ` Mauro Carvalho Chehab
14 siblings, 0 replies; 16+ messages in thread
From: Mauro Carvalho Chehab @ 2016-09-08 21:37 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Mauro Carvalho Chehab
There is a warning there, because it was pointing to a different
name. Fix it.
While here, use struct &foo, instead of &struct foo.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
include/media/v4l2-subdev.h | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/include/media/v4l2-subdev.h b/include/media/v4l2-subdev.h
index 2c1e328ccb1d..e175c2c891a8 100644
--- a/include/media/v4l2-subdev.h
+++ b/include/media/v4l2-subdev.h
@@ -764,7 +764,7 @@ struct v4l2_subdev_platform_data {
* @entity: pointer to &struct media_entity
* @list: List of sub-devices
* @owner: The owner is the same as the driver's &struct device owner.
- * @owner_v4l2_dev: true if the &sd->owner matches the owner of &v4l2_dev->dev
+ * @owner_v4l2_dev: true if the &sd->owner matches the owner of @v4l2_dev->dev
* ownner. Initialized by v4l2_device_register_subdev().
* @flags: subdev flags. Can be:
* %V4L2_SUBDEV_FL_IS_I2C - Set this flag if this subdev is a i2c device;
@@ -774,9 +774,9 @@ struct v4l2_subdev_platform_data {
* %V4L2_SUBDEV_FL_HAS_EVENTS - Set this flag if this subdev generates
* events.
*
- * @v4l2_dev: pointer to &struct v4l2_device
- * @ops: pointer to &struct v4l2_subdev_ops
- * @internal_ops: pointer to &struct v4l2_subdev_internal_ops.
+ * @v4l2_dev: pointer to struct &v4l2_device
+ * @ops: pointer to struct &v4l2_subdev_ops
+ * @internal_ops: pointer to struct &v4l2_subdev_internal_ops.
* Never call these internal ops from within a driver!
* @ctrl_handler: The control handler of this subdev. May be NULL.
* @name: Name of the sub-device. Please notice that the name must be unique.
--
2.7.4
^ permalink raw reply related [flat|nested] 16+ messages in thread