linux-kernel - [PATCH] firmware: ti_sci.h: fix all kernel-doc warnings

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
Hash Suite: Windows password security audit tool. GUI, reports in PDF.
[<prev] [next>] [day] [month] [year] [list]
Message-ID: <20251128055731.812460-1-rdunlap@infradead.org>
Date: Thu, 27 Nov 2025 21:57:31 -0800
From: Randy Dunlap <rdunlap@...radead.org>
To: linux-kernel@...r.kernel.org
Cc: Randy Dunlap <rdunlap@...radead.org>,
	Nishanth Menon <nm@...com>,
	Tero Kristo <kristo@...nel.org>,
	Santosh Shilimkar <ssantosh@...nel.org>,
	linux-arm-kernel@...ts.infradead.org
Subject: [PATCH] firmware: ti_sci.h: fix all kernel-doc warnings

Modify kernel-doc comments in ti_sci.h to eliminate all kernel-doc
warnings:

* use correct/matching struct names in kdoc comments
* use correct struct member names in kdoc comments
* add a ':' after struct member names where needed
* change a blank kdoc line to " *"
* convert 3 structs to kernel-doc comments:
  struct ti_sci_msg_rm_udmap_tx_ch_cfg_req
  struct ti_sci_msg_rm_udmap_rx_ch_cfg_req
  struct ti_sci_msg_rm_udmap_flow_cfg_req

Fixes 13 kernel-doc warnings:

Warning: drivers/firmware/ti_sci.h:609 expecting prototype for struct
 tisci_msg_req_prepare_sleep. Prototype was for struct
 ti_sci_msg_req_prepare_sleep instead
Warning: drivers/firmware/ti_sci.h:609 struct member 'hdr' not described
 in 'ti_sci_msg_req_prepare_sleep'
Warning: drivers/firmware/ti_sci.h:609 struct member 'mode' not described
 in 'ti_sci_msg_req_prepare_sleep'
Warning: drivers/firmware/ti_sci.h:609 struct member 'ctx_lo' not described
 in 'ti_sci_msg_req_prepare_sleep'
Warning: drivers/firmware/ti_sci.h:609 struct member 'ctx_hi' not described
 in 'ti_sci_msg_req_prepare_sleep'
Warning: drivers/firmware/ti_sci.h:609 struct member 'debug_flags' not
 described in 'ti_sci_msg_req_prepare_sleep'
Warning: drivers/firmware/ti_sci.h:623 expecting prototype for struct
 tisci_msg_set_io_isolation_req. Prototype was for struct
 ti_sci_msg_req_set_io_isolation instead
Warning: drivers/firmware/ti_sci.h:696 struct member 'latency' not
 described in 'ti_sci_msg_req_lpm_set_latency_constraint'
Warning: drivers/firmware/ti_sci.h:857 bad line:
Warning: drivers/firmware/ti_sci.h:1002 This comment starts with '/**', but
 isn't a kernel-doc comment. Refer to Documentation/doc-guide/kernel-doc.rst
 * Configures a Navigator Subsystem UDMAP transmit channel
Warning: drivers/firmware/ti_sci.h:1130 This comment starts with '/**', but
 isn't a kernel-doc comment. Refer to Documentation/doc-guide/kernel-doc.rst
 * Configures a Navigator Subsystem UDMAP receive channel
Warning: drivers/firmware/ti_sci.h:1249 This comment starts with '/**', but
 isn't a kernel-doc comment. Refer to Documentation/doc-guide/kernel-doc.rst
 * Configures a Navigator Subsystem UDMAP receive flow
Warning: drivers/firmware/ti_sci.h:1421 struct member 'valid_params'
 not described in 'ti_sci_msg_rm_udmap_flow_cfg_req'

Signed-off-by: Randy Dunlap <rdunlap@...radead.org>
---
Cc: Nishanth Menon <nm@...com>
Cc: Tero Kristo <kristo@...nel.org>
Cc: Santosh Shilimkar <ssantosh@...nel.org>
Cc: linux-arm-kernel@...ts.infradead.org
---
 drivers/firmware/ti_sci.h |   29 ++++++++++++++++-------------
 1 file changed, 16 insertions(+), 13 deletions(-)

--- linux-next-20251127.orig/drivers/firmware/ti_sci.h
+++ linux-next-20251127/drivers/firmware/ti_sci.h
@@ -580,13 +580,13 @@ struct ti_sci_msg_resp_get_clock_freq {
 } __packed;
 
 /**
- * struct tisci_msg_req_prepare_sleep - Request for TISCI_MSG_PREPARE_SLEEP.
+ * struct ti_sci_msg_req_prepare_sleep - Request for TISCI_MSG_PREPARE_SLEEP.
  *
- * @hdr				TISCI header to provide ACK/NAK flags to the host.
- * @mode			Low power mode to enter.
- * @ctx_lo			Low 32-bits of physical pointer to address to use for context save.
- * @ctx_hi			High 32-bits of physical pointer to address to use for context save.
- * @debug_flags			Flags that can be set to halt the sequence during suspend or
+ * @hdr:			TISCI header to provide ACK/NAK flags to the host.
+ * @mode:			Low power mode to enter.
+ * @ctx_lo:			Low 32-bits of physical pointer to address to use for context save.
+ * @ctx_hi:			High 32-bits of physical pointer to address to use for context save.
+ * @debug_flags:		Flags that can be set to halt the sequence during suspend or
  *				resume to allow JTAG connection and debug.
  *
  * This message is used as the first step of entering a low power mode. It
@@ -610,7 +610,7 @@ struct ti_sci_msg_req_prepare_sleep {
 } __packed;
 
 /**
- * struct tisci_msg_set_io_isolation_req - Request for TI_SCI_MSG_SET_IO_ISOLATION.
+ * struct ti_sci_msg_req_set_io_isolation - Request for TI_SCI_MSG_SET_IO_ISOLATION.
  *
  * @hdr:	Generic header
  * @state:	The deseared state of the IO isolation.
@@ -676,7 +676,7 @@ struct ti_sci_msg_req_lpm_set_device_con
  * TISCI_MSG_LPM_SET_LATENCY_CONSTRAINT.
  *
  * @hdr:	TISCI header to provide ACK/NAK flags to the host.
- * @wkup_latency:	The maximum acceptable latency to wake up from low power mode
+ * @latency:	The maximum acceptable latency to wake up from low power mode
  *			in milliseconds. The deeper the state, the higher the latency.
  * @state:	The desired state of wakeup latency constraint: set or clear.
  * @rsvd:	Reserved for future use.
@@ -855,7 +855,7 @@ struct ti_sci_msg_rm_ring_cfg_req {
  * UDMAP transmit channels mapped to source threads will have their
  * TCHAN_THRD_ID register programmed with the destination thread if the pairing
  * is successful.
-
+ *
  * @dst_thread: PSI-L destination thread ID within the PSI-L System thread map.
  * PSI-L destination threads start at index 0x8000.  The request is NACK'd if
  * the destination thread is not greater than or equal to 0x8000.
@@ -1000,7 +1000,8 @@ struct rm_ti_sci_msg_udmap_rx_flow_opt_c
 } __packed;
 
 /**
- * Configures a Navigator Subsystem UDMAP transmit channel
+ * struct ti_sci_msg_rm_udmap_tx_ch_cfg_req - Configures a
+ *	Navigator Subsystem UDMAP transmit channel
  *
  * Configures the non-real-time registers of a Navigator Subsystem UDMAP
  * transmit channel.  The channel index must be assigned to the host defined
@@ -1128,7 +1129,8 @@ struct ti_sci_msg_rm_udmap_tx_ch_cfg_req
 } __packed;
 
 /**
- * Configures a Navigator Subsystem UDMAP receive channel
+ * struct ti_sci_msg_rm_udmap_rx_ch_cfg_req - Configures a
+ *	Navigator Subsystem UDMAP receive channel
  *
  * Configures the non-real-time registers of a Navigator Subsystem UDMAP
  * receive channel.  The channel index must be assigned to the host defined
@@ -1247,7 +1249,8 @@ struct ti_sci_msg_rm_udmap_rx_ch_cfg_req
 } __packed;
 
 /**
- * Configures a Navigator Subsystem UDMAP receive flow
+ * struct ti_sci_msg_rm_udmap_flow_cfg_req - Configures a
+ *	Navigator Subsystem UDMAP receive flow
  *
  * Configures a Navigator Subsystem UDMAP receive flow's registers.
  * Configuration does not include the flow registers which handle size-based
@@ -1258,7 +1261,7 @@ struct ti_sci_msg_rm_udmap_rx_ch_cfg_req
  *
  * @hdr: Standard TISCI header
  *
- * @valid_params
+ * @valid_params:
  * Bitfield defining validity of rx flow configuration parameters.  The
  * rx flow configuration fields are not valid, and will not be used for flow
  * configuration, if their corresponding valid bit is zero.  Valid bit usage: