Commit 5fa5edbe authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab

[media] v4l2-mem2mem.h: document the public structures

Most structures here are not documented. Add a documentation
for them.
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
parent dcbd8735
...@@ -41,9 +41,9 @@ ...@@ -41,9 +41,9 @@
* This function does not have to (and will usually not) wait * This function does not have to (and will usually not) wait
* until the device enters a state when it can be stopped. * until the device enters a state when it can be stopped.
* @lock: optional. Define a driver's own lock callback, instead of using * @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 * @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 { struct v4l2_m2m_ops {
void (*device_run)(void *priv); void (*device_run)(void *priv);
...@@ -53,31 +53,59 @@ struct v4l2_m2m_ops { ...@@ -53,31 +53,59 @@ struct v4l2_m2m_ops {
void (*unlock)(void *priv); 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_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 { struct v4l2_m2m_queue_ctx {
/* private: internal use only */
struct vb2_queue q; 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; struct list_head rdy_queue;
spinlock_t rdy_spinlock; spinlock_t rdy_spinlock;
u8 num_rdy; u8 num_rdy;
bool buffered; 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 { struct v4l2_m2m_ctx {
/* optional cap/out vb2 queues lock */ /* optional cap/out vb2 queues lock */
struct mutex *q_lock; struct mutex *q_lock;
/* private: internal use only */ /* internal use only */
struct v4l2_m2m_dev *m2m_dev; struct v4l2_m2m_dev *m2m_dev;
/* Capture (output to memory) queue context */
struct v4l2_m2m_queue_ctx cap_q_ctx; struct v4l2_m2m_queue_ctx cap_q_ctx;
/* Output (input from memory) queue context */
struct v4l2_m2m_queue_ctx out_q_ctx; struct v4l2_m2m_queue_ctx out_q_ctx;
/* For device job queue */ /* For device job queue */
...@@ -85,10 +113,15 @@ struct v4l2_m2m_ctx { ...@@ -85,10 +113,15 @@ struct v4l2_m2m_ctx {
unsigned long job_flags; unsigned long job_flags;
wait_queue_head_t finished; wait_queue_head_t finished;
/* Instance private data */
void *priv; 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 v4l2_m2m_buffer {
struct vb2_v4l2_buffer vb; struct vb2_v4l2_buffer vb;
struct list_head list; struct list_head list;
...@@ -145,9 +178,9 @@ void v4l2_m2m_try_schedule(struct v4l2_m2m_ctx *m2m_ctx); ...@@ -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 * Should be called as soon as possible after reaching a state which allows
* other instances to take control of the device. * other instances to take control of the device.
* *
* This function has to be called only after device_run() callback has been * This function has to be called only after &v4l2_m2m_ops->device_run
* called on the driver. To prevent recursion, it should not be called directly * callback has been called on the driver. To prevent recursion, it should
* from the device_run() callback though. * not be called directly from the &v4l2_m2m_ops->device_run callback though.
*/ */
void v4l2_m2m_job_finish(struct v4l2_m2m_dev *m2m_dev, void v4l2_m2m_job_finish(struct v4l2_m2m_dev *m2m_dev,
struct v4l2_m2m_ctx *m2m_ctx); struct v4l2_m2m_ctx *m2m_ctx);
...@@ -292,7 +325,9 @@ int v4l2_m2m_mmap(struct file *file, 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 * @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); 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); ...@@ -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 * @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); void v4l2_m2m_release(struct v4l2_m2m_dev *m2m_dev);
...@@ -313,7 +348,7 @@ 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 * @queue_init: a callback for queue type-specific initialization function
* to be used for initializing videobuf_queues * 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, struct v4l2_m2m_ctx *v4l2_m2m_ctx_init(struct v4l2_m2m_dev *m2m_dev,
void *drv_priv, void *drv_priv,
...@@ -346,7 +381,7 @@ void v4l2_m2m_ctx_release(struct v4l2_m2m_ctx *m2m_ctx); ...@@ -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 * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
* @vbuf: pointer to struct &vb2_v4l2_buffer * @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, void v4l2_m2m_buf_queue(struct v4l2_m2m_ctx *m2m_ctx,
struct vb2_v4l2_buffer *vbuf); struct vb2_v4l2_buffer *vbuf);
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment