On Thu, Feb 19, 2026 at 4:55 PM Randy Dunlap <[email protected]> wrote: > > Fix 45+ kernel-doc warnings in vmwgfx_drv.h: > - spell a struct name correctly > - don't have structs between kernel-doc and its struct > - end description of struct members with ':' > - start all kernel-doc lines with " *" > - mark private struct member and enum value with "private:" > - add kernel-doc for enum vmw_dma_map_mode > - add missing struct member comments > - add missing function parameter comments > - convert "/**" to "/*" for non-kernel-doc comments > - add missing "Returns:" comments for several functions > - correct a function parameter name > > to eliminate kernel-doc warnings (examples): > > Warning: drivers/gpu/drm/vmwgfx/vmwgfx_drv.h:128 struct vmw_bo; error: > Cannot parse struct or union! > Warning: drivers/gpu/drm/vmwgfx/vmwgfx_drv.h:151 struct member 'used_prio' > not described in 'vmw_resource' > Warning: drivers/gpu/drm/vmwgfx/vmwgfx_drv.h:151 struct member 'mob_node' > not described in 'vmw_resource' > Warning: drivers/gpu/drm/vmwgfx/vmwgfx_drv.h:199 bad line: SM4 device. > Warning: drivers/gpu/drm/vmwgfx/vmwgfx_drv.h:270 struct member 'private' > not described in 'vmw_res_cache_entry' > Warning: drivers/gpu/drm/vmwgfx/vmwgfx_drv.h:280 Enum value > 'vmw_dma_alloc_coherent' not described in enum 'vmw_dma_map_mode' > Warning: drivers/gpu/drm/vmwgfx/vmwgfx_drv.h:280 Enum value > 'vmw_dma_map_bind' not described in enum 'vmw_dma_map_mode' > Warning: drivers/gpu/drm/vmwgfx/vmwgfx_drv.h:295 struct member 'addrs' > not described in 'vmw_sg_table' > Warning: drivers/gpu/drm/vmwgfx/vmwgfx_drv.h:295 struct member 'mode' > not described in 'vmw_sg_table' > vmwgfx_drv.h:309: warning: Excess struct member 'num_regions' description > in 'vmw_sg_table' > Warning: drivers/gpu/drm/vmwgfx/vmwgfx_drv.h:402 struct member 'filp' > not described in 'vmw_sw_context' > Warning: drivers/gpu/drm/vmwgfx/vmwgfx_drv.h:732 This comment starts with > '/**', but isn't a kernel-doc comment. > Warning: drivers/gpu/drm/vmwgfx/vmwgfx_drv.h:742 This comment starts with > '/**', but isn't a kernel-doc comment. > Warning: drivers/gpu/drm/vmwgfx/vmwgfx_drv.h:762 This comment starts with > '/**', but isn't a kernel-doc comment. > Warning: drivers/gpu/drm/vmwgfx/vmwgfx_drv.h:887 No description found for > return value of 'vmw_fifo_caps' > Warning: drivers/gpu/drm/vmwgfx/vmwgfx_drv.h:901 No description found for > return value of 'vmw_is_cursor_bypass3_enabled' > Warning: drivers/gpu/drm/vmwgfx/vmwgfx_drv.h:906 This comment starts with > '/**', but isn't a kernel-doc comment. > Warning: drivers/gpu/drm/vmwgfx/vmwgfx_drv.h:961 This comment starts with > '/**', but isn't a kernel-doc comment. > Warning: drivers/gpu/drm/vmwgfx/vmwgfx_drv.h:996 This comment starts with > '/**', but isn't a kernel-doc comment. > Warning: drivers/gpu/drm/vmwgfx/vmwgfx_drv.h:1082 cannot understand > function prototype: 'const struct dma_buf_ops vmw_prime_dmabuf_ops;' > Warning: drivers/gpu/drm/vmwgfx/vmwgfx_drv.h:1303 struct member 'do_cpy' > not described in 'vmw_diff_cpy' > Warning: drivers/gpu/drm/vmwgfx/vmwgfx_drv.h:1385 function parameter 'fmt' > not described in 'VMW_DEBUG_KMS' > Warning: drivers/gpu/drm/vmwgfx/vmwgfx_drv.h:1389 This comment starts with > '/**', but isn't a kernel-doc comment. > Warning: drivers/gpu/drm/vmwgfx/vmwgfx_drv.h:1426 function parameter 'vmw' > not described in 'vmw_fifo_mem_read' > Warning: drivers/gpu/drm/vmwgfx/vmwgfx_drv.h:1426 No description found for > return value of 'vmw_fifo_mem_read' > Warning: drivers/gpu/drm/vmwgfx/vmwgfx_drv.h:1441 function parameter > 'fifo_reg' not described in 'vmw_fifo_mem_write' > > Signed-off-by: Randy Dunlap <[email protected]> > --- > Cc: Zack Rusin <[email protected]> > Cc: <[email protected]> > Cc: Maarten Lankhorst <[email protected]> > Cc: Maxime Ripard <[email protected]> > Cc: Thomas Zimmermann <[email protected]> > Cc: David Airlie <[email protected]> > Cc: Simona Vetter <[email protected]> > --- > drivers/gpu/drm/vmwgfx/vmwgfx_drv.h | 93 +++++++++++++++----------- > 1 file changed, 57 insertions(+), 36 deletions(-) > > --- linux-next-20260218.orig/drivers/gpu/drm/vmwgfx/vmwgfx_drv.h > +++ linux-next-20260218/drivers/gpu/drm/vmwgfx/vmwgfx_drv.h > @@ -96,12 +96,17 @@ struct vmwgfx_hash_item { > > struct vmw_res_func; > > +struct vmw_bo; > +struct vmw_bo; > +struct vmw_resource_dirty; > + > /** > - * struct vmw-resource - base class for hardware resources > + * struct vmw_resource - base class for hardware resources > * > * @kref: For refcounting. > * @dev_priv: Pointer to the device private for this resource. Immutable. > * @id: Device id. Protected by @dev_priv::resource_lock. > + * @used_prio: Priority for this resource. > * @guest_memory_size: Guest memory buffer size. Immutable. > * @res_dirty: Resource contains data not yet in the guest memory buffer. > * Protected by resource reserved. > @@ -117,18 +122,16 @@ struct vmw_res_func; > * pin-count greater than zero. It is not on the resource LRU lists and its > * guest memory buffer is pinned. Hence it can't be evicted. > * @func: Method vtable for this resource. Immutable. > - * @mob_node; Node for the MOB guest memory rbtree. Protected by > + * @mob_node: Node for the MOB guest memory rbtree. Protected by > * @guest_memory_bo reserved. > * @lru_head: List head for the LRU list. Protected by > @dev_priv::resource_lock. > * @binding_head: List head for the context binding list. Protected by > * the @dev_priv::binding_mutex > + * @dirty: resource's dirty tracker > * @res_free: The resource destructor. > * @hw_destroy: Callback to destroy the resource on the device, as part of > * resource destruction. > */ > -struct vmw_bo; > -struct vmw_bo; > -struct vmw_resource_dirty; > struct vmw_resource { > struct kref kref; > struct vmw_private *dev_priv; > @@ -196,8 +199,8 @@ struct vmw_surface_offset; > * @quality_level: Quality level. > * @autogen_filter: Filter for automatically generated mipmaps. > * @array_size: Number of array elements for a 1D/2D texture. For cubemap > - texture number of faces * array_size. This should be 0 for > pre > - SM4 device. > + * texture number of faces * array_size. This should be 0 for > pre > + * SM4 device. > * @buffer_byte_stride: Buffer byte stride. > * @num_sizes: Size of @sizes. For GB surface this should always be 1. > * @base_size: Surface dimension. > @@ -265,18 +268,24 @@ struct vmw_fifo_state { > struct vmw_res_cache_entry { > uint32_t handle; > struct vmw_resource *res; > + /* private: */ > void *private; > + /* public: */ > unsigned short valid_handle; > unsigned short valid; > }; > > /** > * enum vmw_dma_map_mode - indicate how to perform TTM page dma mappings. > + * @vmw_dma_alloc_coherent: Use TTM coherent pages > + * @vmw_dma_map_populate: Unmap from DMA just after unpopulate > + * @vmw_dma_map_bind: Unmap from DMA just before unbind > */ > enum vmw_dma_map_mode { > - vmw_dma_alloc_coherent, /* Use TTM coherent pages */ > - vmw_dma_map_populate, /* Unmap from DMA just after unpopulate */ > - vmw_dma_map_bind, /* Unmap from DMA just before unbind */ > + vmw_dma_alloc_coherent, > + vmw_dma_map_populate, > + vmw_dma_map_bind, > + /* private: */ > vmw_dma_map_max > }; > > @@ -284,8 +293,11 @@ enum vmw_dma_map_mode { > * struct vmw_sg_table - Scatter/gather table for binding, with additional > * device-specific information. > * > + * @mode: which page mapping mode to use > + * @pages: Array of page pointers to the pages. > + * @addrs: DMA addresses to the pages if coherent pages are used. > * @sgt: Pointer to a struct sg_table with binding information > - * @num_regions: Number of regions with device-address contiguous pages > + * @num_pages: Number of @pages > */ > struct vmw_sg_table { > enum vmw_dma_map_mode mode; > @@ -353,6 +365,7 @@ struct vmw_ctx_validation_info; > * than from user-space > * @fp: If @kernel is false, points to the file of the client. Otherwise > * NULL > + * @filp: DRM state for this file > * @cmd_bounce: Command bounce buffer used for command validation before > * copying to fifo space > * @cmd_bounce_size: Current command bounce buffer size > @@ -729,7 +742,7 @@ extern void vmw_svga_disable(struct vmw_ > bool vmwgfx_supported(struct vmw_private *vmw); > > > -/** > +/* > * GMR utilities - vmwgfx_gmr.c > */ > > @@ -739,7 +752,7 @@ extern int vmw_gmr_bind(struct vmw_priva > int gmr_id); > extern void vmw_gmr_unbind(struct vmw_private *dev_priv, int gmr_id); > > -/** > +/* > * User handles > */ > struct vmw_user_object { > @@ -759,7 +772,7 @@ void *vmw_user_object_map_size(struct vm > void vmw_user_object_unmap(struct vmw_user_object *uo); > bool vmw_user_object_is_mapped(struct vmw_user_object *uo); > > -/** > +/* > * Resource utilities - vmwgfx_resource.c > */ > struct vmw_user_resource_conv; > @@ -819,7 +832,7 @@ static inline bool vmw_resource_mob_atta > return !RB_EMPTY_NODE(&res->mob_node); > } > > -/** > +/* > * GEM related functionality - vmwgfx_gem.c > */ > struct vmw_bo_params; > @@ -833,7 +846,7 @@ extern int vmw_gem_object_create_ioctl(s > struct drm_file *filp); > extern void vmw_debugfs_gem_init(struct vmw_private *vdev); > > -/** > +/* > * Misc Ioctl functionality - vmwgfx_ioctl.c > */ > > @@ -846,7 +859,7 @@ extern int vmw_present_ioctl(struct drm_ > extern int vmw_present_readback_ioctl(struct drm_device *dev, void *data, > struct drm_file *file_priv); > > -/** > +/* > * Fifo utilities - vmwgfx_fifo.c > */ > > @@ -880,9 +893,11 @@ extern int vmw_cmd_flush(struct vmw_priv > > > /** > - * vmw_fifo_caps - Returns the capabilities of the FIFO command > + * vmw_fifo_caps - Get the capabilities of the FIFO command > * queue or 0 if fifo memory isn't present. > * @dev_priv: The device private context > + * > + * Returns: capabilities of the FIFO command or %0 if fifo memory not present > */ > static inline uint32_t vmw_fifo_caps(const struct vmw_private *dev_priv) > { > @@ -893,9 +908,11 @@ static inline uint32_t vmw_fifo_caps(con > > > /** > - * vmw_is_cursor_bypass3_enabled - Returns TRUE iff Cursor Bypass 3 > - * is enabled in the FIFO. > + * vmw_is_cursor_bypass3_enabled - check Cursor Bypass 3 enabled setting > + * in the FIFO. > * @dev_priv: The device private context > + * > + * Returns: %true iff Cursor Bypass 3 is enabled in the FIFO > */ > static inline bool > vmw_is_cursor_bypass3_enabled(const struct vmw_private *dev_priv) > @@ -903,7 +920,7 @@ vmw_is_cursor_bypass3_enabled(const stru > return (vmw_fifo_caps(dev_priv) & SVGA_FIFO_CAP_CURSOR_BYPASS_3) != 0; > } > > -/** > +/* > * TTM buffer object driver - vmwgfx_ttm_buffer.c > */ > > @@ -927,7 +944,7 @@ extern void vmw_piter_start(struct vmw_p > * > * @viter: Pointer to the iterator to advance. > * > - * Returns false if past the list of pages, true otherwise. > + * Returns: false if past the list of pages, true otherwise. > */ > static inline bool vmw_piter_next(struct vmw_piter *viter) > { > @@ -939,7 +956,7 @@ static inline bool vmw_piter_next(struct > * > * @viter: Pointer to the iterator > * > - * Returns the DMA address of the page pointed to by @viter. > + * Returns: the DMA address of the page pointed to by @viter. > */ > static inline dma_addr_t vmw_piter_dma_addr(struct vmw_piter *viter) > { > @@ -951,14 +968,14 @@ static inline dma_addr_t vmw_piter_dma_a > * > * @viter: Pointer to the iterator > * > - * Returns the DMA address of the page pointed to by @viter. > + * Returns: the DMA address of the page pointed to by @viter. > */ > static inline struct page *vmw_piter_page(struct vmw_piter *viter) > { > return viter->pages[viter->i]; > } > > -/** > +/* > * Command submission - vmwgfx_execbuf.c > */ > > @@ -993,7 +1010,7 @@ extern int vmw_execbuf_copy_fence_user(s > int32_t out_fence_fd); > bool vmw_cmd_describe(const void *buf, u32 *size, char const **cmd); > > -/** > +/* > * IRQs and wating - vmwgfx_irq.c > */ > > @@ -1016,7 +1033,7 @@ bool vmw_generic_waiter_add(struct vmw_p > bool vmw_generic_waiter_remove(struct vmw_private *dev_priv, > u32 flag, int *waiter_count); > > -/** > +/* > * Kernel modesetting - vmwgfx_kms.c > */ > > @@ -1048,7 +1065,7 @@ extern int vmw_resource_pin(struct vmw_r > extern void vmw_resource_unpin(struct vmw_resource *res); > extern enum vmw_res_type vmw_res_type(const struct vmw_resource *res); > > -/** > +/* > * Overlay control - vmwgfx_overlay.c > */ > > @@ -1063,20 +1080,20 @@ int vmw_overlay_unref(struct vmw_private > int vmw_overlay_num_overlays(struct vmw_private *dev_priv); > int vmw_overlay_num_free_overlays(struct vmw_private *dev_priv); > > -/** > +/* > * GMR Id manager > */ > > int vmw_gmrid_man_init(struct vmw_private *dev_priv, int type); > void vmw_gmrid_man_fini(struct vmw_private *dev_priv, int type); > > -/** > +/* > * System memory manager > */ > int vmw_sys_man_init(struct vmw_private *dev_priv); > void vmw_sys_man_fini(struct vmw_private *dev_priv); > > -/** > +/* > * Prime - vmwgfx_prime.c > */ > > @@ -1292,7 +1309,7 @@ extern void vmw_cmdbuf_irqthread(struct > * @line: The current line of the blit. > * @line_offset: Offset of the current line segment. > * @cpp: Bytes per pixel (granularity information). > - * @memcpy: Which memcpy function to use. > + * @do_cpy: Which memcpy function to use. > */ > struct vmw_diff_cpy { > struct drm_rect rect; > @@ -1380,13 +1397,14 @@ vm_fault_t vmw_bo_vm_mkwrite(struct vm_f > > /** > * VMW_DEBUG_KMS - Debug output for kernel mode-setting > + * @fmt: format string for the args > * > * This macro is for debugging vmwgfx mode-setting code. > */ > #define VMW_DEBUG_KMS(fmt, ...) > \ > DRM_DEBUG_DRIVER(fmt, ##__VA_ARGS__) > > -/** > +/* > * Inline helper functions > */ > > @@ -1417,11 +1435,13 @@ static inline void vmw_fifo_resource_dec > > /** > * vmw_fifo_mem_read - Perform a MMIO read from the fifo memory > - * > + * @vmw: The device private structure > * @fifo_reg: The fifo register to read from > * > * This function is intended to be equivalent to ioread32() on > * memremap'd memory, but without byteswapping. > + * > + * Returns: the value read > */ > static inline u32 vmw_fifo_mem_read(struct vmw_private *vmw, uint32 fifo_reg) > { > @@ -1431,8 +1451,9 @@ static inline u32 vmw_fifo_mem_read(stru > > /** > * vmw_fifo_mem_write - Perform a MMIO write to volatile memory > - * > - * @addr: The fifo register to write to > + * @vmw: The device private structure > + * @fifo_reg: The fifo register to write to > + * @value: The value to write > * > * This function is intended to be equivalent to iowrite32 on > * memremap'd memory, but without byteswapping.
Thank you! Applied to drm-misc-fixes. z
smime.p7s
Description: S/MIME Cryptographic Signature
