From fdce161afe29b40e84853ec821cbd7bbd727bf58 Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Thu, 27 Nov 2025 21:57:31 -0800 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 Link: https://patch.msgid.link/20251128055731.812460-1-rdunlap@infradead.org Signed-off-by: Nishanth Menon --- drivers/firmware/ti_sci.h | 29 ++++++++++++++++------------- 1 file changed, 16 insertions(+), 13 deletions(-) diff --git a/drivers/firmware/ti_sci.h b/drivers/firmware/ti_sci.h index 91f234550c43..4616127e33ff 100644 --- a/drivers/firmware/ti_sci.h +++ b/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_constraint { * 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_cfg { } __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: