From: Randy Dunlap Date: Sun, 26 Oct 2025 22:45:58 +0000 (-0700) Subject: usb: mtu3: fix invalid kernel-doc in mtu3.h X-Git-Tag: v6.19-rc1~63^2~66 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=bf3371dfe3c4e735fd5a1e0c5506bce1bd418a56;p=thirdparty%2Fkernel%2Flinux.git usb: mtu3: fix invalid kernel-doc in mtu3.h Fix unconventional kernel-doc lines to avoid warnings. Summary of changes: - change non-kernel-doc comments from "/**" to "/*" - add "enum - short description" for undescribed enums - use leading '@' for describing enum members and struct members - add "struct - short description" for undescribed structs Repair and remove invalid or unconventional lines in mtu3.h: (This list is a combination of warnings from the old kernel-doc.pl and the new kernel-doc.py scripts. This combo provides better coverage of all problems.) mtu3.h:69: warning: This comment starts with '/**', but isn't a kernel-doc comment. * IP TRUNK version mtu3.h:69: warning: missing initial short description on line: * IP TRUNK version mtu3.h:78: warning: This comment starts with '/**', but isn't a kernel-doc comment. * Normally the device works on HS or SS, to simplify fifo management, mtu3.h:78: warning: missing initial short description on line: * Normally the device works on HS or SS, to simplify fifo management, mtu3.h:89: warning: This comment starts with '/**', but isn't a kernel-doc comment. * Maximum size of ep0 response buffer for ch9 requests, mtu3.h:89: warning: missing initial short description on line: * Maximum size of ep0 response buffer for ch9 requests, mtu3.h:106: warning: Cannot understand * @MU3D_EP0_STATE_SETUP: waits for SETUP or received a SETUP on line 106 - I thought it was a doc line mtu3.h:130: warning: cannot understand function prototype: 'enum mtu3_dr_force_mode' mtu3.h:137: warning: Cannot understand * @base: the base address of fifo on line 137 - I thought it was a doc line mtu3.h:148: warning: missing initial short description on line: * General Purpose Descriptor (GPD): mtu3.h:174: warning: cannot understand function prototype: 'struct qmu_gpd' mtu3.h:189: warning: cannot understand function prototype: 'struct mtu3_gpd_ring' mtu3.h:198: warning: Cannot understand * @vbus: vbus 5V used by host mode on line 198 - I thought it was a doc line mtu3.h:225: warning: Cannot understand * @mac_base: register base address of device MAC, exclude xHCI's on line 225 - I thought it was a doc line mtu3.h:275: warning: cannot understand function prototype: 'struct mtu3_ep' Warning: drivers/usb/mtu3/mtu3.h:135 Enum value 'MTU3_DR_FORCE_NONE' not described in enum 'mtu3_dr_force_mode' Warning: drivers/usb/mtu3/mtu3.h:135 Enum value 'MTU3_DR_FORCE_HOST' not described in enum 'mtu3_dr_force_mode' Warning: drivers/usb/mtu3/mtu3.h:135 Enum value 'MTU3_DR_FORCE_DEVICE' not described in enum 'mtu3_dr_force_mode' Warning: drivers/usb/mtu3/mtu3.h:270 Cannot find identifier on line: * @fifo_size: it is (@slot + 1) * @fifo_seg_size Warning: drivers/usb/mtu3/mtu3.h:271 Cannot find identifier on line: * @fifo_seg_size: it is roundup_pow_of_two(@maxp) Warning: drivers/usb/mtu3/mtu3.h:272 Cannot find identifier on line: */ Warning: drivers/usb/mtu3/mtu3.h:273 Cannot find identifier on line: struct mtu3_ep { Warning: drivers/usb/mtu3/mtu3.h:274 Cannot find identifier on line: struct usb_ep ep; Warning: drivers/usb/mtu3/mtu3.h:275 Cannot find identifier on line: char name[12]; Warning: drivers/usb/mtu3/mtu3.h:276 missing initial short description on line: struct mtu3 *mtu; This removes all of the invalid/unconventional kernel-doc attempts but still leaves quite a few struct members in structs ssusb_mtk, mtu3_ep, and mtu3 without kernel-doc descriptions. Signed-off-by: Randy Dunlap Link: https://patch.msgid.link/20251026224558.826143-2-rdunlap@infradead.org Signed-off-by: Greg Kroah-Hartman --- diff --git a/drivers/usb/mtu3/mtu3.h b/drivers/usb/mtu3/mtu3.h index 5e59f58940b54..ba5a63669e5f5 100644 --- a/drivers/usb/mtu3/mtu3.h +++ b/drivers/usb/mtu3/mtu3.h @@ -65,7 +65,7 @@ struct mtu3_request; #define MTU3_U3_IP_SLOT_DEFAULT 2 #define MTU3_U2_IP_SLOT_DEFAULT 1 -/** +/* * IP TRUNK version * from 0x1003 version, USB3 Gen2 is supported, two changes affect driver: * 1. MAXPKT and MULTI bits layout of TXCSR1 and RXCSR1 are adjusted, @@ -74,7 +74,7 @@ struct mtu3_request; */ #define MTU3_TRUNK_VERS_1003 0x1003 -/** +/* * Normally the device works on HS or SS, to simplify fifo management, * divide fifo into some 512B parts, use bitmap to manage it; And * 128 bits size of bitmap is large enough, that means it can manage @@ -85,7 +85,7 @@ struct mtu3_request; #define MTU3_FIFO_BIT_SIZE 128 #define MTU3_U2_IP_EP0_FIFO_SIZE 64 -/** +/* * Maximum size of ep0 response buffer for ch9 requests, * the SET_SEL request uses 6 so far, and GET_STATUS is 2 */ @@ -103,6 +103,7 @@ enum mtu3_speed { }; /** + * enum mtu3_g_ep0_state - endpoint 0 states * @MU3D_EP0_STATE_SETUP: waits for SETUP or received a SETUP * without data stage. * @MU3D_EP0_STATE_TX: IN data stage @@ -121,11 +122,12 @@ enum mtu3_g_ep0_state { }; /** - * MTU3_DR_FORCE_NONE: automatically switch host and peripheral mode + * enum mtu3_dr_force_mode - indicates host/OTG operating mode + * @MTU3_DR_FORCE_NONE: automatically switch host and peripheral mode * by IDPIN signal. - * MTU3_DR_FORCE_HOST: force to enter host mode and override OTG + * @MTU3_DR_FORCE_HOST: force to enter host mode and override OTG * IDPIN signal. - * MTU3_DR_FORCE_DEVICE: force to enter peripheral mode. + * @MTU3_DR_FORCE_DEVICE: force to enter peripheral mode. */ enum mtu3_dr_force_mode { MTU3_DR_FORCE_NONE = 0, @@ -134,6 +136,7 @@ enum mtu3_dr_force_mode { }; /** + * struct mtu3_fifo_info - HW FIFO description and management data * @base: the base address of fifo * @limit: the bitmap size in bits * @bitmap: fifo bitmap in unit of @MTU3_EP_FIFO_UNIT @@ -145,7 +148,7 @@ struct mtu3_fifo_info { }; /** - * General Purpose Descriptor (GPD): + * struct qmu_gpd - General Purpose Descriptor (GPD): * The format of TX GPD is a little different from RX one. * And the size of GPD is 16 bytes. * @@ -179,11 +182,13 @@ struct qmu_gpd { } __packed; /** -* dma: physical base address of GPD segment -* start: virtual base address of GPD segment -* end: the last GPD element -* enqueue: the first empty GPD to use -* dequeue: the first completed GPD serviced by ISR +* struct mtu3_gpd_ring - GPD ring descriptor +* @dma: physical base address of GPD segment +* @start: virtual base address of GPD segment +* @end: the last GPD element +* @enqueue: the first empty GPD to use +* @dequeue: the first completed GPD serviced by ISR +* * NOTE: the size of GPD ring should be >= 2 */ struct mtu3_gpd_ring { @@ -195,6 +200,7 @@ struct mtu3_gpd_ring { }; /** +* struct otg_switch_mtk - OTG/dual-role switch management * @vbus: vbus 5V used by host mode * @edev: external connector used to detect vbus and iddig changes * @id_nb : notifier for iddig(idpin) detection @@ -222,6 +228,7 @@ struct otg_switch_mtk { }; /** + * struct ssusb_mtk - SuperSpeed USB descriptor (MTK) * @mac_base: register base address of device MAC, exclude xHCI's * @ippc_base: register base address of IP Power and Clock interface (IPPC) * @vusb33: usb3.3V shared by device/host IP @@ -268,6 +275,7 @@ struct ssusb_mtk { }; /** + * struct mtu3_ep - common mtu3 endpoint description * @fifo_size: it is (@slot + 1) * @fifo_seg_size * @fifo_seg_size: it is roundup_pow_of_two(@maxp) */