From nobody Mon Dec 1 21:30:00 2025 Received: from bombadil.infradead.org (bombadil.infradead.org [198.137.202.133]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id D60A71FC8 for ; Fri, 28 Nov 2025 05:57:32 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=198.137.202.133 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1764309455; cv=none; b=QACcOhTObfZj8pYFBG52F2z+lkitudYUQCsR3QN3F8+51aGihFIx1muO4Tey2BEfoJ5R+x5kU1/DhW9KkDZH7ODb2wn9Oc3lnP1arCGjurr35JlvfeCADVWxJvofv99EmBP24D1wPAk679Xw9mYCQNUz1c5gS8q7Wy9MKJXwWRM= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1764309455; c=relaxed/simple; bh=jKdu5T4T9Nyi15JdeOba1P0ttTsxwRHuIyCKeVw1H4A=; h=From:To:Cc:Subject:Date:Message-ID:MIME-Version; b=r1SqwyLiZD4MIQKtOTo9G0V6mQlAUyt8zAeq7h68NbSn9DmLBasp+Z9jGpaueCFy1QbQRnLc2Wl5opMXP31vBW7uG93dldWHkhHwsMTT4UNz0KGjkHEA5Kb/xqjU+y9A2UnZRtQ7k8J017MexofoFn/V02jsji3WDlB606hGAIo= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=infradead.org; spf=none smtp.mailfrom=infradead.org; dkim=pass (2048-bit key) header.d=infradead.org header.i=@infradead.org header.b=WHznoTsl; arc=none smtp.client-ip=198.137.202.133 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=infradead.org Authentication-Results: smtp.subspace.kernel.org; spf=none smtp.mailfrom=infradead.org Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=infradead.org header.i=@infradead.org header.b="WHznoTsl" DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20210309; h=Content-Transfer-Encoding: MIME-Version:Message-ID:Date:Subject:Cc:To:From:Sender:Reply-To:Content-Type: Content-ID:Content-Description:In-Reply-To:References; bh=98g6X3S/iJSm9qbCDckyxRmdDucwdo57Y2Adtbm1tHc=; b=WHznoTslr2TRu/+f5vIBGiFe20 1bDcLQ8JC2W8kUTKLjZFF4XmIDnPQpFug0fvqmynLmsiRKubgzX597UEkqX4VjKDCScGRKGiUBS78 iikhX78sVrW+2n0msxpTz+4op/3mH22aWMmIJFL6dpQChVB13H8vM7tkghi/nknFmdgZ/tB1PBNMU wBzC2kCw5SwqVkzcuEdU2FqPyGNuxQEJITL3HrdWYLw7EahsQd8izycxKiHHpJvhTc7Jcrs7EtmMR tT7kWe1Gi7CwyrXDUtBnVkQPRfz/5iSfEk42B+VJPrGR9FcCCJ8I5F479ZAxdCQyrgLVZ/bF2occK txxgKNIg==; Received: from [50.53.43.113] (helo=bombadil.infradead.org) by bombadil.infradead.org with esmtpsa (Exim 4.98.2 #2 (Red Hat Linux)) id 1vOrU4-000000001EQ-0Vwc; Fri, 28 Nov 2025 05:57:32 +0000 From: Randy Dunlap To: linux-kernel@vger.kernel.org Cc: Randy Dunlap , Nishanth Menon , Tero Kristo , Santosh Shilimkar , linux-arm-kernel@lists.infradead.org Subject: [PATCH] firmware: ti_sci.h: fix all kernel-doc warnings Date: Thu, 27 Nov 2025 21:57:31 -0800 Message-ID: <20251128055731.812460-1-rdunlap@infradead.org> X-Mailer: git-send-email 2.52.0 Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" 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 --- Cc: Nishanth Menon Cc: Tero Kristo Cc: Santosh Shilimkar Cc: linux-arm-kernel@lists.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; =20 /** - * struct tisci_msg_req_prepare_sleep - Request for TISCI_MSG_PREPARE_SLEE= P. + * struct ti_sci_msg_req_prepare_sleep - Request for TISCI_MSG_PREPARE_SLE= EP. * - * @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 contex= t save. - * @debug_flags Flags that can be set to halt the sequence during suspen= d 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 contex= t save. + * @ctx_hi: High 32-bits of physical pointer to address to use for conte= xt save. + * @debug_flags: Flags that can be set to halt the sequence during suspen= d 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; =20 /** - * struct tisci_msg_set_io_isolation_req - Request for TI_SCI_MSG_SET_IO_I= SOLATION. + * 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 pa= iring * 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; =20 /** - * 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 defin= ed @@ -1128,7 +1129,8 @@ struct ti_sci_msg_rm_udmap_tx_ch_cfg_req } __packed; =20 /** - * 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; =20 /** - * 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-bas= ed @@ -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 fl= ow * configuration, if their corresponding valid bit is zero. Valid bit usa= ge: