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

Most structures here are not documented. Add a documentation
for them.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

1 files changed, 51 insertions, 16 deletions

diff --git a/include/media/v4l2-mem2mem.h b/include/media/v4l2-mem2mem.h
index 00410bd14772..cfa4f5e521a7 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);