tjh.dev / kernel
Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux
1
fork

Configure Feed

Select the types of activity you want to include in your feed.

drm/vmwgfx: fix kernel-doc warnings in vmwgfx_drv.h

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 <rdunlap@infradead.org>
Signed-off-by: Zack Rusin <zack.rusin@broadcom.com>
Link: https://patch.msgid.link/20260219215548.470810-1-rdunlap@infradead.org

authored by

Randy Dunlap and committed by
Zack Rusin c7feff27 49973e2a

+57 -36
+57 -36
drivers/gpu/drm/vmwgfx/vmwgfx_drv.h
··· 96 96 97 97 struct vmw_res_func; 98 98 99 + struct vmw_bo; 100 + struct vmw_bo; 101 + struct vmw_resource_dirty; 102 + 99 103 /** 100 - * struct vmw-resource - base class for hardware resources 104 + * struct vmw_resource - base class for hardware resources 101 105 * 102 106 * @kref: For refcounting. 103 107 * @dev_priv: Pointer to the device private for this resource. Immutable. 104 108 * @id: Device id. Protected by @dev_priv::resource_lock. 109 + * @used_prio: Priority for this resource. 105 110 * @guest_memory_size: Guest memory buffer size. Immutable. 106 111 * @res_dirty: Resource contains data not yet in the guest memory buffer. 107 112 * Protected by resource reserved. ··· 122 117 * pin-count greater than zero. It is not on the resource LRU lists and its 123 118 * guest memory buffer is pinned. Hence it can't be evicted. 124 119 * @func: Method vtable for this resource. Immutable. 125 - * @mob_node; Node for the MOB guest memory rbtree. Protected by 120 + * @mob_node: Node for the MOB guest memory rbtree. Protected by 126 121 * @guest_memory_bo reserved. 127 122 * @lru_head: List head for the LRU list. Protected by @dev_priv::resource_lock. 128 123 * @binding_head: List head for the context binding list. Protected by 129 124 * the @dev_priv::binding_mutex 125 + * @dirty: resource's dirty tracker 130 126 * @res_free: The resource destructor. 131 127 * @hw_destroy: Callback to destroy the resource on the device, as part of 132 128 * resource destruction. 133 129 */ 134 - struct vmw_bo; 135 - struct vmw_bo; 136 - struct vmw_resource_dirty; 137 130 struct vmw_resource { 138 131 struct kref kref; 139 132 struct vmw_private *dev_priv; ··· 199 196 * @quality_level: Quality level. 200 197 * @autogen_filter: Filter for automatically generated mipmaps. 201 198 * @array_size: Number of array elements for a 1D/2D texture. For cubemap 202 - texture number of faces * array_size. This should be 0 for pre 203 - SM4 device. 199 + * texture number of faces * array_size. This should be 0 for pre 200 + * SM4 device. 204 201 * @buffer_byte_stride: Buffer byte stride. 205 202 * @num_sizes: Size of @sizes. For GB surface this should always be 1. 206 203 * @base_size: Surface dimension. ··· 268 265 struct vmw_res_cache_entry { 269 266 uint32_t handle; 270 267 struct vmw_resource *res; 268 + /* private: */ 271 269 void *private; 270 + /* public: */ 272 271 unsigned short valid_handle; 273 272 unsigned short valid; 274 273 }; 275 274 276 275 /** 277 276 * enum vmw_dma_map_mode - indicate how to perform TTM page dma mappings. 277 + * @vmw_dma_alloc_coherent: Use TTM coherent pages 278 + * @vmw_dma_map_populate: Unmap from DMA just after unpopulate 279 + * @vmw_dma_map_bind: Unmap from DMA just before unbind 278 280 */ 279 281 enum vmw_dma_map_mode { 280 - vmw_dma_alloc_coherent, /* Use TTM coherent pages */ 281 - vmw_dma_map_populate, /* Unmap from DMA just after unpopulate */ 282 - vmw_dma_map_bind, /* Unmap from DMA just before unbind */ 282 + vmw_dma_alloc_coherent, 283 + vmw_dma_map_populate, 284 + vmw_dma_map_bind, 285 + /* private: */ 283 286 vmw_dma_map_max 284 287 }; 285 288 ··· 293 284 * struct vmw_sg_table - Scatter/gather table for binding, with additional 294 285 * device-specific information. 295 286 * 287 + * @mode: which page mapping mode to use 288 + * @pages: Array of page pointers to the pages. 289 + * @addrs: DMA addresses to the pages if coherent pages are used. 296 290 * @sgt: Pointer to a struct sg_table with binding information 297 - * @num_regions: Number of regions with device-address contiguous pages 291 + * @num_pages: Number of @pages 298 292 */ 299 293 struct vmw_sg_table { 300 294 enum vmw_dma_map_mode mode; ··· 365 353 * than from user-space 366 354 * @fp: If @kernel is false, points to the file of the client. Otherwise 367 355 * NULL 356 + * @filp: DRM state for this file 368 357 * @cmd_bounce: Command bounce buffer used for command validation before 369 358 * copying to fifo space 370 359 * @cmd_bounce_size: Current command bounce buffer size ··· 742 729 bool vmwgfx_supported(struct vmw_private *vmw); 743 730 744 731 745 - /** 732 + /* 746 733 * GMR utilities - vmwgfx_gmr.c 747 734 */ 748 735 ··· 752 739 int gmr_id); 753 740 extern void vmw_gmr_unbind(struct vmw_private *dev_priv, int gmr_id); 754 741 755 - /** 742 + /* 756 743 * User handles 757 744 */ 758 745 struct vmw_user_object { ··· 772 759 void vmw_user_object_unmap(struct vmw_user_object *uo); 773 760 bool vmw_user_object_is_mapped(struct vmw_user_object *uo); 774 761 775 - /** 762 + /* 776 763 * Resource utilities - vmwgfx_resource.c 777 764 */ 778 765 struct vmw_user_resource_conv; ··· 832 819 return !RB_EMPTY_NODE(&res->mob_node); 833 820 } 834 821 835 - /** 822 + /* 836 823 * GEM related functionality - vmwgfx_gem.c 837 824 */ 838 825 struct vmw_bo_params; ··· 846 833 struct drm_file *filp); 847 834 extern void vmw_debugfs_gem_init(struct vmw_private *vdev); 848 835 849 - /** 836 + /* 850 837 * Misc Ioctl functionality - vmwgfx_ioctl.c 851 838 */ 852 839 ··· 859 846 extern int vmw_present_readback_ioctl(struct drm_device *dev, void *data, 860 847 struct drm_file *file_priv); 861 848 862 - /** 849 + /* 863 850 * Fifo utilities - vmwgfx_fifo.c 864 851 */ 865 852 ··· 893 880 894 881 895 882 /** 896 - * vmw_fifo_caps - Returns the capabilities of the FIFO command 883 + * vmw_fifo_caps - Get the capabilities of the FIFO command 897 884 * queue or 0 if fifo memory isn't present. 898 885 * @dev_priv: The device private context 886 + * 887 + * Returns: capabilities of the FIFO command or %0 if fifo memory not present 899 888 */ 900 889 static inline uint32_t vmw_fifo_caps(const struct vmw_private *dev_priv) 901 890 { ··· 908 893 909 894 910 895 /** 911 - * vmw_is_cursor_bypass3_enabled - Returns TRUE iff Cursor Bypass 3 912 - * is enabled in the FIFO. 896 + * vmw_is_cursor_bypass3_enabled - check Cursor Bypass 3 enabled setting 897 + * in the FIFO. 913 898 * @dev_priv: The device private context 899 + * 900 + * Returns: %true iff Cursor Bypass 3 is enabled in the FIFO 914 901 */ 915 902 static inline bool 916 903 vmw_is_cursor_bypass3_enabled(const struct vmw_private *dev_priv) ··· 920 903 return (vmw_fifo_caps(dev_priv) & SVGA_FIFO_CAP_CURSOR_BYPASS_3) != 0; 921 904 } 922 905 923 - /** 906 + /* 924 907 * TTM buffer object driver - vmwgfx_ttm_buffer.c 925 908 */ 926 909 ··· 944 927 * 945 928 * @viter: Pointer to the iterator to advance. 946 929 * 947 - * Returns false if past the list of pages, true otherwise. 930 + * Returns: false if past the list of pages, true otherwise. 948 931 */ 949 932 static inline bool vmw_piter_next(struct vmw_piter *viter) 950 933 { ··· 956 939 * 957 940 * @viter: Pointer to the iterator 958 941 * 959 - * Returns the DMA address of the page pointed to by @viter. 942 + * Returns: the DMA address of the page pointed to by @viter. 960 943 */ 961 944 static inline dma_addr_t vmw_piter_dma_addr(struct vmw_piter *viter) 962 945 { ··· 968 951 * 969 952 * @viter: Pointer to the iterator 970 953 * 971 - * Returns the DMA address of the page pointed to by @viter. 954 + * Returns: the DMA address of the page pointed to by @viter. 972 955 */ 973 956 static inline struct page *vmw_piter_page(struct vmw_piter *viter) 974 957 { 975 958 return viter->pages[viter->i]; 976 959 } 977 960 978 - /** 961 + /* 979 962 * Command submission - vmwgfx_execbuf.c 980 963 */ 981 964 ··· 1010 993 int32_t out_fence_fd); 1011 994 bool vmw_cmd_describe(const void *buf, u32 *size, char const **cmd); 1012 995 1013 - /** 996 + /* 1014 997 * IRQs and wating - vmwgfx_irq.c 1015 998 */ 1016 999 ··· 1033 1016 bool vmw_generic_waiter_remove(struct vmw_private *dev_priv, 1034 1017 u32 flag, int *waiter_count); 1035 1018 1036 - /** 1019 + /* 1037 1020 * Kernel modesetting - vmwgfx_kms.c 1038 1021 */ 1039 1022 ··· 1065 1048 extern void vmw_resource_unpin(struct vmw_resource *res); 1066 1049 extern enum vmw_res_type vmw_res_type(const struct vmw_resource *res); 1067 1050 1068 - /** 1051 + /* 1069 1052 * Overlay control - vmwgfx_overlay.c 1070 1053 */ 1071 1054 ··· 1080 1063 int vmw_overlay_num_overlays(struct vmw_private *dev_priv); 1081 1064 int vmw_overlay_num_free_overlays(struct vmw_private *dev_priv); 1082 1065 1083 - /** 1066 + /* 1084 1067 * GMR Id manager 1085 1068 */ 1086 1069 1087 1070 int vmw_gmrid_man_init(struct vmw_private *dev_priv, int type); 1088 1071 void vmw_gmrid_man_fini(struct vmw_private *dev_priv, int type); 1089 1072 1090 - /** 1073 + /* 1091 1074 * System memory manager 1092 1075 */ 1093 1076 int vmw_sys_man_init(struct vmw_private *dev_priv); 1094 1077 void vmw_sys_man_fini(struct vmw_private *dev_priv); 1095 1078 1096 - /** 1079 + /* 1097 1080 * Prime - vmwgfx_prime.c 1098 1081 */ 1099 1082 ··· 1309 1292 * @line: The current line of the blit. 1310 1293 * @line_offset: Offset of the current line segment. 1311 1294 * @cpp: Bytes per pixel (granularity information). 1312 - * @memcpy: Which memcpy function to use. 1295 + * @do_cpy: Which memcpy function to use. 1313 1296 */ 1314 1297 struct vmw_diff_cpy { 1315 1298 struct drm_rect rect; ··· 1397 1380 1398 1381 /** 1399 1382 * VMW_DEBUG_KMS - Debug output for kernel mode-setting 1383 + * @fmt: format string for the args 1400 1384 * 1401 1385 * This macro is for debugging vmwgfx mode-setting code. 1402 1386 */ 1403 1387 #define VMW_DEBUG_KMS(fmt, ...) \ 1404 1388 DRM_DEBUG_DRIVER(fmt, ##__VA_ARGS__) 1405 1389 1406 - /** 1390 + /* 1407 1391 * Inline helper functions 1408 1392 */ 1409 1393 ··· 1435 1417 1436 1418 /** 1437 1419 * vmw_fifo_mem_read - Perform a MMIO read from the fifo memory 1438 - * 1420 + * @vmw: The device private structure 1439 1421 * @fifo_reg: The fifo register to read from 1440 1422 * 1441 1423 * This function is intended to be equivalent to ioread32() on 1442 1424 * memremap'd memory, but without byteswapping. 1425 + * 1426 + * Returns: the value read 1443 1427 */ 1444 1428 static inline u32 vmw_fifo_mem_read(struct vmw_private *vmw, uint32 fifo_reg) 1445 1429 { ··· 1451 1431 1452 1432 /** 1453 1433 * vmw_fifo_mem_write - Perform a MMIO write to volatile memory 1454 - * 1455 - * @addr: The fifo register to write to 1434 + * @vmw: The device private structure 1435 + * @fifo_reg: The fifo register to write to 1436 + * @value: The value to write 1456 1437 * 1457 1438 * This function is intended to be equivalent to iowrite32 on 1458 1439 * memremap'd memory, but without byteswapping.