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@infradead.org>
Link: https://patch.msgid.link/20251128055731.812460-1-rdunlap@infradead.org
Signed-off-by: Nishanth Menon <nm@ti.com>

diff --git a/drivers/firmware/ti_sci.h b/drivers/firmware/ti_sci.h
index 91f234550c4388238e7d629dd2300ce78648a6fd..4616127e33ff621518ae1be411fee658f0bc2c07 100644 (file)
--- 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: