| lists.openwall.net | lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC | |
|
Open Source and information security mailing list archives
| ||
|
Message-ID: <20251026224558.826143-2-rdunlap@infradead.org>
Date: Sun, 26 Oct 2025 15:45:58 -0700
From: Randy Dunlap <rdunlap@...radead.org>
To: linux-kernel@...r.kernel.org
Cc: Randy Dunlap <rdunlap@...radead.org>,
Chunfeng Yun <chunfeng.yun@...iatek.com>,
linux-arm-kernel@...ts.infradead.org,
linux-mediatek@...ts.infradead.org,
Matthias Brugger <matthias.bgg@...il.com>,
AngeloGioacchino Del Regno <angelogioacchino.delregno@...labora.com>,
Greg Kroah-Hartman <gregkh@...uxfoundation.org>,
Mauro Carvalho Chehab <mchehab@...nel.org>,
linux-usb@...r.kernel.org,
linux-doc@...r.kernel.org
Subject: [PATCH 2/2] 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 <enum-name> - short description" for undescribed enums
- use leading '@' for describing enum members and struct members
- add "struct <struct-name> - 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 <rdunlap@...radead.org>
---
Cc: Chunfeng Yun <chunfeng.yun@...iatek.com>
Cc: linux-arm-kernel@...ts.infradead.org
Cc: linux-mediatek@...ts.infradead.org
Cc: Matthias Brugger <matthias.bgg@...il.com>
Cc: AngeloGioacchino Del Regno <angelogioacchino.delregno@...labora.com>
Cc: Greg Kroah-Hartman <gregkh@...uxfoundation.org>
Cc: Mauro Carvalho Chehab <mchehab@...nel.org>
Cc: linux-usb@...r.kernel.org
Cc: linux-doc@...r.kernel.org
---
drivers/usb/mtu3/mtu3.h | 32 ++++++++++++++++++++------------
1 file changed, 20 insertions(+), 12 deletions(-)
--- linux-next.orig/drivers/usb/mtu3/mtu3.h
+++ linux-next/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)
*/
Powered by blists - more mailing lists