Skip to contentSkip to conversation

How to fix DocBook parsers for private fields inside #ifdefs

DISCUSSION Mauro Carvalho Chehab 3 participants 5 messages Oct 1, 2015 – Oct 11, 2015 Media (V4L/DVB)

lore
Share & tools
lore
#0 lore raw

Hi Jon,

I'm trying to cleanup some warnings when creating docbooks for a struct located at include/media/videobuf2-core.h.

This is the struct:

struct vb2_buffer {
        struct vb2_queue        *vb2_queue;
        unsigned int            index;
        unsigned int            type;
        unsigned int            memory;
        unsigned int            num_planes;
        struct vb2_plane        planes[VIDEO_MAX_PLANES];

        /* Private: internal use only */
        enum vb2_buffer_state   state;

        struct list_head        queued_entry;
        struct list_head        done_entry;
#ifdef CONFIG_VIDEO_ADV_DEBUG
        /*
         * Counters for how often these buffer-related ops are
         * called. Used to check for unbalanced ops.
         */
        u32             cnt_mem_alloc;

...
#endif
}

The data at the ifdef are used only for debugging purposes during driver development or driver testing and should not be used in production.

They're all after a private comment:

	/* Private: internal use only */

So, according with Documentation/kernel-doc-nano-HOWTO.txt, they shold have been ignored.

Still, the scripts produce warnings for them:

$ make cleandocs
$ make DOCBOOKS=device-drivers.xml htmldocs 2>&1|grep /media/

.//include/media/videobuf2-core.h:254: warning: No description found for parameter 'cnt_mem_alloc' .//include/media/videobuf2-core.h:254: warning: No description found for parameter 'cnt_mem_put' .//include/media/videobuf2-core.h:254: warning: No description found for parameter 'cnt_mem_get_dmabuf' .//include/media/videobuf2-core.h:254: warning: No description found for parameter 'cnt_mem_get_userptr' .//include/media/videobuf2-core.h:254: warning: No description found for parameter 'cnt_mem_put_userptr' .//include/media/videobuf2-core.h:254: warning: No description found for parameter 'cnt_mem_prepare' .//include/media/videobuf2-core.h:254: warning: No description found for parameter 'cnt_mem_finish' .//include/media/videobuf2-core.h:254: warning: No description found for parameter 'cnt_mem_attach_dmabuf' .//include/media/videobuf2-core.h:254: warning: No description found for parameter 'cnt_mem_detach_dmabuf' .//include/media/videobuf2-core.h:254: warning: No description found for parameter 'cnt_mem_map_dmabuf' .//include/media/videobuf2-core.h:254: warning: No description found for parameter 'cnt_mem_unmap_dmabuf' .//include/media/videobuf2-core.h:254: warning: No description found for parameter 'cnt_mem_vaddr' .//include/media/videobuf2-core.h:254: warning: No description found for parameter 'cnt_mem_cookie' .//include/media/videobuf2-core.h:254: warning: No description found for parameter 'cnt_mem_num_users' .//include/media/videobuf2-core.h:254: warning: No description found for parameter 'cnt_mem_mmap' .//include/media/videobuf2-core.h:254: warning: No description found for parameter 'cnt_buf_init' .//include/media/videobuf2-core.h:254: warning: No description found for parameter 'cnt_buf_prepare' .//include/media/videobuf2-core.h:254: warning: No description found for parameter 'cnt_buf_finish' .//include/media/videobuf2-core.h:254: warning: No description found for parameter 'cnt_buf_cleanup' .//include/media/videobuf2-core.h:254: warning: No description found for parameter 'cnt_buf_queue' .//include/media/videobuf2-core.h:254: warning: No description found for parameter 'cnt_buf_done'

I tried to add another private: after the #ifdef, but it still produces those warnings.

Any idea about how to fix it?

Thanks!
Mauro

#1 lore raw
Quoted 7 lines · On Thu, 1 Oct 2015 14:21:07 -0300 Mauro Carvalho Chehab…

They're all after a private comment:

	/* Private: internal use only */

So, according with Documentation/kernel-doc-nano-HOWTO.txt, they shold have been ignored.

Still, the scripts produce warnings for them:

Sorry, I've been away from the keyboard for a few days and am only now catching up.

The problem is that kernel-doc is dumb...the test is case-sensitive, so it needs to be "private:", not "Private:". I'm sure there's a magic perl regex parameter to make the test case-insensitive; when I get a chance I'll figure it out and put it in there.

(Of course, once you fix that glitch, you'll get gripes about the fields that are marked private but documented anyway. Like I said, kernel-doc is dumb.)

jon

#2 lore raw

Em Mon, 5 Oct 2015 04:56:35 -0600
Jonathan Corbet <[email protected]> escreveu:

Quoted 11 lines
Quoted 7 lines · On Thu, 1 Oct 2015 14:21:07 -0300 Mauro Carvalho Chehab…

They're all after a private comment:

	/* Private: internal use only */

So, according with Documentation/kernel-doc-nano-HOWTO.txt, they shold have been ignored.

Still, the scripts produce warnings for them:

Quoted 7 lines

Sorry, I've been away from the keyboard for a few days and am only now catching up.

The problem is that kernel-doc is dumb...the test is case-sensitive, so it needs to be "private:", not "Private:". I'm sure there's a magic perl regex parameter to make the test case-insensitive; when I get a chance I'll figure it out and put it in there.

Ah, that makes sense. Adding an "i" to the end of the regex expression should make it case-insensitive:

-       $members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gos;
-       $members =~ s/\/\*\s*private:.*//gos;
+       $members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
+       $members =~ s/\/\*\s*private:.*//gosi;

Patch enclosed. Yet, I guess nobody would try to use PRIVATE: So, another alternative would be to do, instead:

- $members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gos;
- $members =~ s/\/\*\s*private:.*//gos;
+ $members =~ s/\/\*\s*[Pp]rivate:.*?\/\*\s*public:.*?\*\///gos;
+ $members =~ s/\/\*\s*[Pp]rivate:.*//gos;

Whatever works best for you.

Quoted 3 lines

(Of course, once you fix that glitch, you'll get gripes about the fields that are marked private but documented anyway. Like I said, kernel-doc is dumb.)

Yeah, now I'm getting those warnings:

.//include/media/videobuf2-core.h:254: warning: Excess struct/union/enum/typedef member 'state' description in 'vb2_buffer' .//include/media/videobuf2-core.h:254: warning: Excess struct/union/enum/typedef member 'queued_entry' description in 'vb2_buffer' .//include/media/videobuf2-core.h:254: warning: Excess struct/union/enum/typedef member 'done_entry' description in 'vb2_buffer'

I'll fix that.

-

DocBook: Fix kernel-doc to be case-insensitive for private:

On some places, people could use Private: to tag the private fields of an struct. So, be case-insensitive when parsing "private:" meta-tag.

scripts/kernel-doc +2 -2
index 9a08fb5c1af6..702c6ac1350e 100755
@@ -1791,8 +1791,8 @@ sub dump_struct($$) {
 	$nested = $1;
 
 	# ignore members marked private:
-	$members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gos;
-	$members =~ s/\/\*\s*private:.*//gos;
+	$members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
+	$members =~ s/\/\*\s*private:.*//gosi;
 	# strip comments:
 	$members =~ s/\/\*.*?\*\///gos;
 	$nested =~ s/\/\*.*?\*\///gos;
#3 lore raw
reproduce: make htmldocs

Hi Mauro,

[auto build test WARNING on v4.3-rc4 -- if it's inappropriate base, please ignore]

reproduce: make htmldocs

All warnings (new ones prefixed by >>):

include/linux/init.h:1: warning: no structured comments found
kernel/sys.c:1: warning: no structured comments found
drivers/dma-buf/seqno-fence.c:1: warning: no structured comments found
drivers/dma-buf/reservation.c:1: warning: no structured comments found
include/linux/reservation.h:1: warning: no structured comments found
include/media/v4l2-dv-timings.h:29: warning: cannot understand function prototype: 'const struct v4l2_dv_timings v4l2_dv_timings_presets[]; ' include/media/v4l2-dv-timings.h:147: warning: No description found for parameter 'frame_height' include/media/v4l2-dv-timings.h:147: warning: No description found for parameter 'hfreq' include/media/v4l2-dv-timings.h:147: warning: No description found for parameter 'vsync' include/media/v4l2-dv-timings.h:147: warning: No description found for parameter 'active_width' include/media/v4l2-dv-timings.h:147: warning: No description found for parameter 'polarities' include/media/v4l2-dv-timings.h:147: warning: No description found for parameter 'interlaced' include/media/v4l2-dv-timings.h:147: warning: No description found for parameter 'fmt' include/media/v4l2-dv-timings.h:171: warning: No description found for parameter 'frame_height' include/media/v4l2-dv-timings.h:171: warning: No description found for parameter 'hfreq' include/media/v4l2-dv-timings.h:171: warning: No description found for parameter 'vsync' include/media/v4l2-dv-timings.h:171: warning: No description found for parameter 'polarities' include/media/v4l2-dv-timings.h:171: warning: No description found for parameter 'interlaced' include/media/v4l2-dv-timings.h:171: warning: No description found for parameter 'aspect' include/media/v4l2-dv-timings.h:171: warning: No description found for parameter 'fmt' include/media/v4l2-dv-timings.h:184: warning: No description found for parameter 'hor_landscape' include/media/v4l2-dv-timings.h:184: warning: No description found for parameter 'vert_portrait' include/media/videobuf2-core.h:112: warning: No description found for parameter 'get_dmabuf'

>> include/media/videobuf2-core.h:233: warning: Excess struct/union/enum/typedef member 'state' description in 'vb2_buffer'
>> include/media/videobuf2-core.h:233: warning: Excess struct/union/enum/typedef member 'queued_entry' description in 'vb2_buffer'
>> include/media/videobuf2-core.h:233: warning: Excess struct/union/enum/typedef member 'done_entry' description in 'vb2_buffer'
>> include/media/videobuf2-core.h:233: warning: Excess struct/union/enum/typedef member 'planes' description in 'vb2_buffer'

drivers/media/dvb-core/dvbdev.h:199: warning: Excess function parameter 'device' description in 'dvb_register_device' drivers/media/dvb-core/dvbdev.h:199: warning: Excess function parameter 'adapter_nums' description in 'dvb_register_device' include/linux/hsi/hsi.h:150: warning: Excess struct/union/enum/typedef member 'e_handler' description in 'hsi_client' include/linux/hsi/hsi.h:150: warning: Excess struct/union/enum/typedef member 'pclaimed' description in 'hsi_client' include/linux/hsi/hsi.h:150: warning: Excess struct/union/enum/typedef member 'nb' description in 'hsi_client'

vim +233 include/media/videobuf2-core.h

e23ccc0a Pawel Osciak          2010-10-11  106  	void		*(*vaddr)(void *buf_priv);
e23ccc0a Pawel Osciak          2010-10-11  107  	void		*(*cookie)(void *buf_priv);
e23ccc0a Pawel Osciak          2010-10-11  108  
e23ccc0a Pawel Osciak          2010-10-11  109  	unsigned int	(*num_users)(void *buf_priv);
e23ccc0a Pawel Osciak          2010-10-11  110  
e23ccc0a Pawel Osciak          2010-10-11  111  	int		(*mmap)(void *buf_priv, struct vm_area_struct *vma);
e23ccc0a Pawel Osciak          2010-10-11 @112  };
e23ccc0a Pawel Osciak          2010-10-11  113  
e23ccc0a Pawel Osciak          2010-10-11  114  struct vb2_plane {
e23ccc0a Pawel Osciak          2010-10-11  115  	void			*mem_priv;
c5384048 Sumit Semwal          2012-06-14  116  	struct dma_buf		*dbuf;
c5384048 Sumit Semwal          2012-06-14  117  	unsigned int		dbuf_mapped;
e23ccc0a Pawel Osciak          2010-10-11  118  };
e23ccc0a Pawel Osciak          2010-10-11  119  
e23ccc0a Pawel Osciak          2010-10-11  120  /**
e23ccc0a Pawel Osciak          2010-10-11  121   * enum vb2_io_modes - queue access methods
e23ccc0a Pawel Osciak          2010-10-11  122   * @VB2_MMAP:		driver supports MMAP with streaming API
e23ccc0a Pawel Osciak          2010-10-11  123   * @VB2_USERPTR:	driver supports USERPTR with streaming API
e23ccc0a Pawel Osciak          2010-10-11  124   * @VB2_READ:		driver supports read() style access
e23ccc0a Pawel Osciak          2010-10-11  125   * @VB2_WRITE:		driver supports write() style access
c5384048 Sumit Semwal          2012-06-14  126   * @VB2_DMABUF:		driver supports DMABUF with streaming API
e23ccc0a Pawel Osciak          2010-10-11  127   */
e23ccc0a Pawel Osciak          2010-10-11  128  enum vb2_io_modes {
e23ccc0a Pawel Osciak          2010-10-11  129  	VB2_MMAP	= (1 << 0),
e23ccc0a Pawel Osciak          2010-10-11  130  	VB2_USERPTR	= (1 << 1),
e23ccc0a Pawel Osciak          2010-10-11  131  	VB2_READ	= (1 << 2),
e23ccc0a Pawel Osciak          2010-10-11  132  	VB2_WRITE	= (1 << 3),
c5384048 Sumit Semwal          2012-06-14  133  	VB2_DMABUF	= (1 << 4),
e23ccc0a Pawel Osciak          2010-10-11  134  };
e23ccc0a Pawel Osciak          2010-10-11  135  
e23ccc0a Pawel Osciak          2010-10-11  136  /**
e23ccc0a Pawel Osciak          2010-10-11  137   * enum vb2_buffer_state - current video buffer state
e23ccc0a Pawel Osciak          2010-10-11  138   * @VB2_BUF_STATE_DEQUEUED:	buffer under userspace control
b18a8ff2 Hans Verkuil          2013-12-13  139   * @VB2_BUF_STATE_PREPARING:	buffer is being prepared in videobuf
ebc087d0 Guennadi Liakhovetski 2011-08-31  140   * @VB2_BUF_STATE_PREPARED:	buffer prepared in videobuf and by the driver
e23ccc0a Pawel Osciak          2010-10-11  141   * @VB2_BUF_STATE_QUEUED:	buffer queued in videobuf, but not in driver
6d058c56 Sakari Ailus          2015-07-03  142   * @VB2_BUF_STATE_REQUEUEING:	re-queue a buffer to the driver
e23ccc0a Pawel Osciak          2010-10-11  143   * @VB2_BUF_STATE_ACTIVE:	buffer queued in driver and possibly used
e23ccc0a Pawel Osciak          2010-10-11  144   *				in a hardware operation
e23ccc0a Pawel Osciak          2010-10-11  145   * @VB2_BUF_STATE_DONE:		buffer returned from driver to videobuf, but
e23ccc0a Pawel Osciak          2010-10-11  146   *				not yet dequeued to userspace
e23ccc0a Pawel Osciak          2010-10-11  147   * @VB2_BUF_STATE_ERROR:	same as above, but the operation on the buffer
e23ccc0a Pawel Osciak          2010-10-11  148   *				has ended with an error, which will be reported
e23ccc0a Pawel Osciak          2010-10-11  149   *				to the userspace when it is dequeued
e23ccc0a Pawel Osciak          2010-10-11  150   */
e23ccc0a Pawel Osciak          2010-10-11  151  enum vb2_buffer_state {
e23ccc0a Pawel Osciak          2010-10-11  152  	VB2_BUF_STATE_DEQUEUED,
b18a8ff2 Hans Verkuil          2013-12-13  153  	VB2_BUF_STATE_PREPARING,
ebc087d0 Guennadi Liakhovetski 2011-08-31  154  	VB2_BUF_STATE_PREPARED,
e23ccc0a Pawel Osciak          2010-10-11  155  	VB2_BUF_STATE_QUEUED,
6d058c56 Sakari Ailus          2015-07-03  156  	VB2_BUF_STATE_REQUEUEING,
e23ccc0a Pawel Osciak          2010-10-11  157  	VB2_BUF_STATE_ACTIVE,
e23ccc0a Pawel Osciak          2010-10-11  158  	VB2_BUF_STATE_DONE,
e23ccc0a Pawel Osciak          2010-10-11  159  	VB2_BUF_STATE_ERROR,
e23ccc0a Pawel Osciak          2010-10-11  160  };
e23ccc0a Pawel Osciak          2010-10-11  161  
e23ccc0a Pawel Osciak          2010-10-11  162  struct vb2_queue;
e23ccc0a Pawel Osciak          2010-10-11  163  
e23ccc0a Pawel Osciak          2010-10-11  164  /**
e23ccc0a Pawel Osciak          2010-10-11  165   * struct vb2_buffer - represents a video buffer
e23ccc0a Pawel Osciak          2010-10-11  166   * @v4l2_buf:		struct v4l2_buffer associated with this buffer; can
e23ccc0a Pawel Osciak          2010-10-11  167   *			be read by the driver and relevant entries can be
e23ccc0a Pawel Osciak          2010-10-11  168   *			changed by the driver in case of CAPTURE types
e23ccc0a Pawel Osciak          2010-10-11  169   *			(such as timestamp)
e23ccc0a Pawel Osciak          2010-10-11  170   * @v4l2_planes:	struct v4l2_planes associated with this buffer; can
e23ccc0a Pawel Osciak          2010-10-11  171   *			be read by the driver and relevant entries can be
e23ccc0a Pawel Osciak          2010-10-11  172   *			changed by the driver in case of CAPTURE types
e23ccc0a Pawel Osciak          2010-10-11  173   *			(such as bytesused); NOTE that even for single-planar
e23ccc0a Pawel Osciak          2010-10-11  174   *			types, the v4l2_planes[0] struct should be used
e23ccc0a Pawel Osciak          2010-10-11  175   *			instead of v4l2_buf for filling bytesused - drivers
e23ccc0a Pawel Osciak          2010-10-11  176   *			should use the vb2_set_plane_payload() function for that
e23ccc0a Pawel Osciak          2010-10-11  177   * @vb2_queue:		the queue to which this driver belongs
e23ccc0a Pawel Osciak          2010-10-11  178   * @num_planes:		number of planes in the buffer
e23ccc0a Pawel Osciak          2010-10-11  179   *			on an internal driver queue
e23ccc0a Pawel Osciak          2010-10-11  180   * @state:		current buffer state; do not change
e23ccc0a Pawel Osciak          2010-10-11  181   * @queued_entry:	entry on the queued buffers list, which holds all
e23ccc0a Pawel Osciak          2010-10-11  182   *			buffers queued from userspace
e23ccc0a Pawel Osciak          2010-10-11  183   * @done_entry:		entry on the list that stores all buffers ready to
e23ccc0a Pawel Osciak          2010-10-11  184   *			be dequeued to userspace
e23ccc0a Pawel Osciak          2010-10-11  185   * @planes:		private per-plane information; do not change
e23ccc0a Pawel Osciak          2010-10-11  186   */
e23ccc0a Pawel Osciak          2010-10-11  187  struct vb2_buffer {
e23ccc0a Pawel Osciak          2010-10-11  188  	struct v4l2_buffer	v4l2_buf;
e23ccc0a Pawel Osciak          2010-10-11  189  	struct v4l2_plane	v4l2_planes[VIDEO_MAX_PLANES];
e23ccc0a Pawel Osciak          2010-10-11  190  
e23ccc0a Pawel Osciak          2010-10-11  191  	struct vb2_queue	*vb2_queue;
e23ccc0a Pawel Osciak          2010-10-11  192  
e23ccc0a Pawel Osciak          2010-10-11  193  	unsigned int		num_planes;
e23ccc0a Pawel Osciak          2010-10-11  194  
e23ccc0a Pawel Osciak          2010-10-11  195  /* Private: internal use only */
e23ccc0a Pawel Osciak          2010-10-11  196  	enum vb2_buffer_state	state;
e23ccc0a Pawel Osciak          2010-10-11  197  
e23ccc0a Pawel Osciak          2010-10-11  198  	struct list_head	queued_entry;
e23ccc0a Pawel Osciak          2010-10-11  199  	struct list_head	done_entry;
e23ccc0a Pawel Osciak          2010-10-11  200  
e23ccc0a Pawel Osciak          2010-10-11  201  	struct vb2_plane	planes[VIDEO_MAX_PLANES];
b5b4541e Hans Verkuil          2014-01-29  202  
b5b4541e Hans Verkuil          2014-01-29  203  #ifdef CONFIG_VIDEO_ADV_DEBUG
b5b4541e Hans Verkuil          2014-01-29  204  	/*
b5b4541e Hans Verkuil          2014-01-29  205  	 * Counters for how often these buffer-related ops are
b5b4541e Hans Verkuil          2014-01-29  206  	 * called. Used to check for unbalanced ops.
b5b4541e Hans Verkuil          2014-01-29  207  	 */
b5b4541e Hans Verkuil          2014-01-29  208  	u32		cnt_mem_alloc;
b5b4541e Hans Verkuil          2014-01-29  209  	u32		cnt_mem_put;
b5b4541e Hans Verkuil          2014-01-29  210  	u32		cnt_mem_get_dmabuf;
b5b4541e Hans Verkuil          2014-01-29  211  	u32		cnt_mem_get_userptr;
b5b4541e Hans Verkuil          2014-01-29  212  	u32		cnt_mem_put_userptr;
b5b4541e Hans Verkuil          2014-01-29  213  	u32		cnt_mem_prepare;
b5b4541e Hans Verkuil          2014-01-29  214  	u32		cnt_mem_finish;
b5b4541e Hans Verkuil          2014-01-29  215  	u32		cnt_mem_attach_dmabuf;
b5b4541e Hans Verkuil          2014-01-29  216  	u32		cnt_mem_detach_dmabuf;
b5b4541e Hans Verkuil          2014-01-29  217  	u32		cnt_mem_map_dmabuf;
b5b4541e Hans Verkuil          2014-01-29  218  	u32		cnt_mem_unmap_dmabuf;
b5b4541e Hans Verkuil          2014-01-29  219  	u32		cnt_mem_vaddr;
b5b4541e Hans Verkuil          2014-01-29  220  	u32		cnt_mem_cookie;
b5b4541e Hans Verkuil          2014-01-29  221  	u32		cnt_mem_num_users;
b5b4541e Hans Verkuil          2014-01-29  222  	u32		cnt_mem_mmap;
b5b4541e Hans Verkuil          2014-01-29  223  
b5b4541e Hans Verkuil          2014-01-29  224  	u32		cnt_buf_init;
b5b4541e Hans Verkuil          2014-01-29  225  	u32		cnt_buf_prepare;
b5b4541e Hans Verkuil          2014-01-29  226  	u32		cnt_buf_finish;
b5b4541e Hans Verkuil          2014-01-29  227  	u32		cnt_buf_cleanup;
b5b4541e Hans Verkuil          2014-01-29  228  	u32		cnt_buf_queue;
b5b4541e Hans Verkuil          2014-01-29  229  
b5b4541e Hans Verkuil          2014-01-29  230  	/* This counts the number of calls to vb2_buffer_done() */
b5b4541e Hans Verkuil          2014-01-29  231  	u32		cnt_buf_done;
b5b4541e Hans Verkuil          2014-01-29  232  #endif
e23ccc0a Pawel Osciak          2010-10-11 @233  };
e23ccc0a Pawel Osciak          2010-10-11  234  
e23ccc0a Pawel Osciak          2010-10-11  235  /**
e23ccc0a Pawel Osciak          2010-10-11  236   * struct vb2_ops - driver-specific callbacks

:::::: The code at line 233 was first introduced by commit
:::::: e23ccc0ad9258634e6d52cedf473b35dc34416c7 [media] v4l: add videobuf2 Video for Linux 2 driver framework

:::::: TO: Pawel Osciak <[email protected]> :::::: CC: Mauro Carvalho Chehab <[email protected]>

---
0-DAY kernel test infrastructure Open Source Technology Center
https://lists.01.org/pipermail/kbuild-all Intel Corporation