Re: [PATCH v2 16/17] media: videobuf2-core: improve kernel-doc markups

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Hi,

On 2017-09-27 23:46, Mauro Carvalho Chehab wrote:
Now that nested structs are supported, change the
documentation to use it. While here, add cross-references
where pertinent and use monotonic fonts where pertinent,
using the right markup tags.

Signed-off-by: Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx>

Acked-by: Marek Szyprowski <m.szyprowski@xxxxxxxxxxx>

---
  include/media/videobuf2-core.h | 59 +++++++++++++++++++++---------------------
  1 file changed, 29 insertions(+), 30 deletions(-)

diff --git a/include/media/videobuf2-core.h b/include/media/videobuf2-core.h
index ef9b64398c8c..5f4df060affb 100644
--- a/include/media/videobuf2-core.h
+++ b/include/media/videobuf2-core.h
@@ -69,7 +69,7 @@ struct vb2_threadio_data;
   *		 argument to other ops in this structure.
   * @put_userptr: inform the allocator that a USERPTR buffer will no longer
   *		 be used.
- * @attach_dmabuf: attach a shared struct dma_buf for a hardware operation;
+ * @attach_dmabuf: attach a shared &struct dma_buf for a hardware operation;
   *		   used for DMABUF memory types; dev is the alloc device
   *		   dbuf is the shared dma_buf; returns ERR_PTR() on failure;
   *		   allocator private per-buffer structure on success;
@@ -153,20 +153,19 @@ struct vb2_mem_ops {
   * @length:	size of this plane (NOT the payload) in bytes
   * @min_length:	minimum required size of this plane (NOT the payload) in bytes.
   *		@length is always greater or equal to @min_length.
- * @offset:	when memory in the associated struct vb2_buffer is
- *		VB2_MEMORY_MMAP, equals the offset from the start of
+ * @m:		Union with memtype-specific data
+ * @m.offset:	when memory in the associated struct vb2_buffer is
+ *		%VB2_MEMORY_MMAP, equals the offset from the start of
   *		the device memory for this plane (or is a "cookie" that
   *		should be passed to mmap() called on the video node)
- * @userptr:	when memory is VB2_MEMORY_USERPTR, a userspace pointer
+ * @m.userptr:	when memory is %VB2_MEMORY_USERPTR, a userspace pointer
   *		pointing to this plane
- * @fd:		when memory is VB2_MEMORY_DMABUF, a userspace file
+ * @m.fd:	when memory is %VB2_MEMORY_DMABUF, a userspace file
   *		descriptor associated with this plane
- * @m:		Union with memtype-specific data (@offset, @userptr or
- *		@fd).
   * @data_offset:	offset in the plane to the start of data; usually 0,
   *		unless there is a header in front of the data
   * Should contain enough information to be able to cover all the fields
- * of struct v4l2_plane at videodev2.h
+ * of &struct v4l2_plane at videodev2.h
   */
  struct vb2_plane {
  	void			*mem_priv;
@@ -356,7 +355,7 @@ 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() with %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
@@ -366,7 +365,7 @@ struct vb2_buffer {
   *			should stop any DMA transactions or wait until they
   *			finish and give back all buffers it got from &buf_queue
   *			callback by calling vb2_buffer_done() with either
- *			%VB2_BUF_STATE_DONE or %VB2_BUF_STATE_ERROR; may use
+ *			%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
@@ -401,13 +400,13 @@ struct vb2_ops {
   * @verify_planes_array: Verify that a given user space structure contains
   *			enough planes for the buffer. This is called
   *			for each dequeued buffer.
- * @fill_user_buffer:	given a vb2_buffer fill in the userspace structure.
+ * @fill_user_buffer:	given a &vb2_buffer fill in the userspace structure.
   *			For V4L2 this is a struct v4l2_buffer.
- * @fill_vb2_buffer:	given a userspace structure, fill in the vb2_buffer.
+ * @fill_vb2_buffer:	given a userspace structure, fill in the &vb2_buffer.
   *			If the userspace structure is invalid, then this op
   *			will return an error.
   * @copy_timestamp:	copy the timestamp from a userspace structure to
- *			the vb2_buffer struct.
+ *			the &vb2_buffer struct.
   */
  struct vb2_buf_ops {
  	int (*verify_planes_array)(struct vb2_buffer *vb, const void *pb);
@@ -428,10 +427,10 @@ struct vb2_buf_ops {
   *		doesn't fill in the @alloc_devs array.
   * @dma_attrs:	DMA attributes to use for the DMA.
   * @bidirectional: when this flag is set the DMA direction for the buffers of
- *		this queue will be overridden with DMA_BIDIRECTIONAL direction.
+ *		this queue will be overridden with %DMA_BIDIRECTIONAL direction.
   *		This is useful in cases where the hardware (firmware) writes to
- *		a buffer which is mapped as read (DMA_TO_DEVICE), or reads from
- *		buffer which is mapped for write (DMA_FROM_DEVICE) in order
+ *		a buffer which is mapped as read (%DMA_TO_DEVICE), or reads from
+ *		buffer which is mapped for write (%DMA_FROM_DEVICE) in order
   *		to satisfy some internal hardware restrictions or adds a padding
   *		needed by the processing algorithm. In case the DMA mapping is
   *		not bidirectional but the hardware (firmware) trying to access
@@ -440,10 +439,10 @@ struct vb2_buf_ops {
   * @fileio_read_once:		report EOF after reading the first buffer
   * @fileio_write_immediately:	queue buffer after each write() call
   * @allow_zero_bytesused:	allow bytesused == 0 to be passed to the driver
- * @quirk_poll_must_check_waiting_for_buffers: Return POLLERR at poll when QBUF
+ * @quirk_poll_must_check_waiting_for_buffers: Return %POLLERR at poll when QBUF
   *              has not been called. This is a vb1 idiom that has been adopted
   *              also by vb2.
- * @lock:	pointer to a mutex that protects the vb2_queue struct. The
+ * @lock:	pointer to a mutex that protects the &vb2_queue struct. The
   *		driver can set this to a mutex to let the v4l2 core serialize
   *		the queuing ioctls. If the driver wants to handle locking
   *		itself, then this should be set to NULL. This lock is not used
@@ -464,7 +463,7 @@ struct vb2_buf_ops {
   * @timestamp_flags: Timestamp flags; V4L2_BUF_FLAG_TIMESTAMP_* and
   *		V4L2_BUF_FLAG_TSTAMP_SRC_*
   * @gfp_flags:	additional gfp flags used when allocating the buffers.
- *		Typically this is 0, but it may be e.g. GFP_DMA or __GFP_DMA32
+ *		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
@@ -491,13 +490,13 @@ struct vb2_buf_ops {
   * @error:	a fatal error occurred on the queue
   * @waiting_for_buffers: used in poll() to check if vb2 is still waiting for
   *		buffers. Only set for capture queues if qbuf has not yet been
- *		called since poll() needs to return POLLERR in that situation.
+ *		called since poll() needs to return %POLLERR in that situation.
   * @is_multiplanar: set if buffer type is multiplanar
   * @is_output:	set if buffer type is output
   * @copy_timestamp: set if vb2-core should set timestamps
   * @last_buffer_dequeued: used in poll() and DQBUF to immediately return if the
   *		last decoded buffer was already dequeued. Set for capture queues
- *		when a buffer with the V4L2_BUF_FLAG_LAST is dequeued.
+ *		when a buffer with the %V4L2_BUF_FLAG_LAST is dequeued.
   * @fileio:	file io emulator internal data, used only if emulator is active
   * @threadio:	thread io internal data, used only if thread is active
   */
@@ -569,7 +568,7 @@ struct vb2_queue {
/**
   * vb2_plane_vaddr() - Return a kernel virtual address of a given plane
- * @vb:		vb2_buffer to which the plane in question belongs to
+ * @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
@@ -579,7 +578,7 @@ 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
+ * @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
@@ -644,7 +643,7 @@ int vb2_wait_for_all_buffers(struct vb2_queue *q);
   * @index:	id number of the buffer
   * @pb:		buffer struct passed from userspace
   *
- * Should be called from vidioc_querybuf ioctl handler in driver.
+ * 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.
   */
@@ -656,7 +655,7 @@ void vb2_core_querybuf(struct vb2_queue *q, unsigned int index, void *pb);
   * @memory: memory type
   * @count: requested buffer count
   *
- * Should be called from vidioc_reqbufs ioctl handler of a driver.
+ * Should be called from &vidioc_reqbufs ioctl handler of a driver.
   *
   * This function:
   *
@@ -664,7 +663,7 @@ void vb2_core_querybuf(struct vb2_queue *q, unsigned int index, void *pb);
   * #) sets up the queue,
   * #) negotiates number of buffers and planes per buffer with the driver
   *    to be used during streaming,
- * #) allocates internal buffer structures (struct vb2_buffer), according to
+ * #) allocates internal buffer structures (&struct vb2_buffer), according to
   *    the agreed parameters,
   * #) for MMAP memory type, allocates actual video memory, using the
   *    memory handling/allocation routines provided during queue initialization
@@ -779,7 +778,7 @@ int vb2_core_streamoff(struct vb2_queue *q, unsigned int type);
   * @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
+ * @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
@@ -792,7 +791,7 @@ int vb2_core_expbuf(struct vb2_queue *q, int *fd, unsigned int type,
   * 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
+ * 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
@@ -819,8 +818,8 @@ void vb2_core_queue_release(struct vb2_queue *q);
   * 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
+ * The error flag will be cleared when canceling 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.
   */

Best regards
--
Marek Szyprowski, PhD
Samsung R&D Institute Poland

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html



[Index of Archives]     [Kernel Newbies]     [Security]     [Netfilter]     [Bugtraq]     [Linux FS]     [Yosemite Forum]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Samba]     [Video 4 Linux]     [Device Mapper]     [Linux Resources]

  Powered by Linux