[PATCH 0/3] soc: qcom: rpmh: fix kernel-doc issues

[PATCH 0/3] soc: qcom: rpmh: fix kernel-doc issues

[Maulik Shah]

Fix several kernel-doc issues across the rpmh driver files:

- rpmh-internal.h: add missing @ver and @regs members to struct rsc_drv,
  add a missing kernel-doc block for struct rsc_ver, and update four
  struct comments to use the 'struct name -' format.

- rpmh.c: fix a typo in struct batch_cache_req title, fix function
  comment format for five functions, add a missing kernel-doc block for
  rpmh_tx_done(), add missing Return: tags to four functions, fix the
  struct cache_req format, and fix the inaccurate rpmh_write_batch()
  description which incorrectly stated that SLEEP/WAKE_ONLY requests
  are sent without caching.

- rpmh-rsc.c: fix copy-paste titles in rpmh_rsc_pd_callback() and
  rpmh_rsc_cpu_pm_callback() which both incorrectly read 'Check if any
  of the AMCs are busy'.

Signed-off-by: Maulik Shah <maulik.shah@oss.qualcomm.com>
---
Maulik Shah (3):
      soc: qcom: rpmh-internal: fix kernel-doc issues in rpmh-internal.h
      soc: qcom: rpmh: fix kernel-doc issues in rpmh.c
      soc: qcom: rpmh-rsc: fix kernel-doc issues in rpmh-rsc.c

 drivers/soc/qcom/rpmh-internal.h | 16 ++++++++++++----
 drivers/soc/qcom/rpmh-rsc.c      |  4 ++--
 drivers/soc/qcom/rpmh.c          | 40 ++++++++++++++++++++++++++++------------
 3 files changed, 42 insertions(+), 18 deletions(-)
---
base-commit: 415606a7be939835db9b0d6b711887586646346d
change-id: 20260802-b4b4-rpmh-kdoc-0216ab4b2597

Best regards,
--  
Maulik Shah <maulik.shah@oss.qualcomm.com>

[PATCH 1/3] soc: qcom: rpmh-internal: fix kernel-doc issues in rpmh-internal.h

[Maulik Shah]

kernel-doc emits two warnings for rpmh-internal.h:

  Warning: drivers/soc/qcom/rpmh-internal.h:136 struct member 'ver' not described in 'rsc_drv'
  Warning: drivers/soc/qcom/rpmh-internal.h:136 struct member 'regs' not described in 'rsc_drv'

Fix them by adding @ver and @regs entries to the struct rsc_drv
documentation.

While at it, add a missing kernel-doc block for struct rsc_ver, and
update the remaining struct kernel-doc comments (struct tcs_group,
struct rpmh_request, struct rpmh_ctrlr, struct rsc_drv) to use the
'struct name -' format documented in
Documentation/doc-guide/kernel-doc.rst.

No functional impact.

Assisted-by: Claude:claude-sonnet-5
Signed-off-by: Maulik Shah <maulik.shah@oss.qualcomm.com>
---
 drivers/soc/qcom/rpmh-internal.h | 16 ++++++++++++----
 1 file changed, 12 insertions(+), 4 deletions(-)

diff --git a/drivers/soc/qcom/rpmh-internal.h b/drivers/soc/qcom/rpmh-internal.h
index e3cf1beff803..39441a25af9b 100644
--- a/drivers/soc/qcom/rpmh-internal.h
+++ b/drivers/soc/qcom/rpmh-internal.h
@@ -20,7 +20,7 @@
 struct rsc_drv;
 
 /**
- * struct tcs_group: group of Trigger Command Sets (TCS) to send state requests
+ * struct tcs_group - group of Trigger Command Sets (TCS) to send state requests
  * to the controller
  *
  * @drv:       The controller.
@@ -53,7 +53,7 @@ struct tcs_group {
 };
 
 /**
- * struct rpmh_request: the message to be sent to rpmh-rsc
+ * struct rpmh_request - the message to be sent to rpmh-rsc
  *
  * @msg: the request
  * @cmd: the payload that will be part of the @msg
@@ -70,7 +70,7 @@ struct rpmh_request {
 };
 
 /**
- * struct rpmh_ctrlr: our representation of the controller
+ * struct rpmh_ctrlr - our representation of the controller
  *
  * @cache: the list of cached requests
  * @cache_lock: synchronize access to the cache data
@@ -84,13 +84,19 @@ struct rpmh_ctrlr {
 	struct list_head batch_cache;
 };
 
+/**
+ * struct rsc_ver - Hardware version of the RSC controller.
+ *
+ * @major: Major version number.
+ * @minor: Minor version number.
+ */
 struct rsc_ver {
 	u32 major;
 	u32 minor;
 };
 
 /**
- * struct rsc_drv: the Direct Resource Voter (DRV) of the
+ * struct rsc_drv - the Direct Resource Voter (DRV) of the
  * Resource State Coordinator controller (RSC)
  *
  * @name:               Controller identifier.
@@ -116,6 +122,8 @@ struct rsc_ver {
  *                      slot
  * @client:             Handle to the DRV's client.
  * @dev:                RSC device.
+ * @ver:                HW version of the RSC controller.
+ * @regs:               Pointer to the register offset table for this version.
  */
 struct rsc_drv {
 	const char *name;

-- 
2.43.0

[PATCH 2/3] soc: qcom: rpmh: fix kernel-doc issues in rpmh.c

[Maulik Shah]

Six documentation issues in rpmh.c:

- struct batch_cache_req has a typo in its title: 'batch catch'
  should be 'batch cache'. Fix it.

- __rpmh_write(), rpmh_write_async(), rpmh_write(), rpmh_write_batch()
  and rpmh_invalidate() use 'name: title' format instead of the
  'name() - title' format documented in
  Documentation/doc-guide/kernel-doc.rst. Fix all of them.

- rpmh_tx_done() has no kernel-doc comment. Add one describing its
  purpose as the RSC driver callback for active-only transfer
  completion.

- __rpmh_write(), rpmh_write_async(), rpmh_write() and
  rpmh_write_batch() are missing Return: tags. Add them.

- struct cache_req uses 'struct name:' format instead of the
  'struct name -' format documented in
  Documentation/doc-guide/kernel-doc.rst. Fix it.

- rpmh_write_batch() has an inaccurate description: it says requests
  are sent 'without caching' and that SLEEP/WAKE_ONLY requests are
  sent as fire-and-forget. In reality, SLEEP/WAKE_ONLY requests are
  cached in batch_cache and returned immediately; they are only sent
  to the controller later by rpmh_flush(). Fix the description.

No functional impact.

Assisted-by: Claude:claude-sonnet-5
Signed-off-by: Maulik Shah <maulik.shah@oss.qualcomm.com>
---
 drivers/soc/qcom/rpmh.c | 40 ++++++++++++++++++++++++++++------------
 1 file changed, 28 insertions(+), 12 deletions(-)

diff --git a/drivers/soc/qcom/rpmh.c b/drivers/soc/qcom/rpmh.c
index ca37da3dc2b1..f725b1135388 100644
--- a/drivers/soc/qcom/rpmh.c
+++ b/drivers/soc/qcom/rpmh.c
@@ -41,7 +41,7 @@
 #define ctrlr_to_drv(ctrlr) container_of(ctrlr, struct rsc_drv, client)
 
 /**
- * struct cache_req: the request object for caching
+ * struct cache_req - the request object for caching
  *
  * @addr: the address of the resource
  * @sleep_val: the sleep vote
@@ -56,7 +56,7 @@ struct cache_req {
 };
 
 /**
- * struct batch_cache_req - An entry in our batch catch
+ * struct batch_cache_req - An entry in our batch cache
  *
  * @list: linked list obj
  * @count: number of messages
@@ -76,6 +76,14 @@ static struct rpmh_ctrlr *get_rpmh_ctrlr(const struct device *dev)
 	return &drv->client;
 }
 
+/**
+ * rpmh_tx_done() - Signal the completion of a RPMH transfer.
+ * @msg: The request that was previously sent.
+ *
+ * Called by the RSC driver when an active-only transfer is complete.
+ * Signals any blocking waiter and frees the message if it was dynamically
+ * allocated.
+ */
 void rpmh_tx_done(const struct tcs_request *msg)
 {
 	struct rpmh_request *rpm_msg = container_of(msg, struct rpmh_request,
@@ -157,7 +165,7 @@ static struct cache_req *cache_rpm_request(struct rpmh_ctrlr *ctrlr,
 }
 
 /**
- * __rpmh_write: Cache and send the RPMH request
+ * __rpmh_write() - Cache and send the RPMH request.
  *
  * @dev: The device making the request
  * @state: Active/Sleep request type
@@ -166,6 +174,8 @@ static struct cache_req *cache_rpm_request(struct rpmh_ctrlr *ctrlr,
  * Cache the RPMH request and send if the state is ACTIVE_ONLY.
  * SLEEP/WAKE_ONLY requests are not sent to the controller at
  * this time. Use rpmh_flush() to send them to the controller.
+ *
+ * Return: 0 on success, negative error code on failure.
  */
 static int __rpmh_write(const struct device *dev, enum rpmh_state state,
 			struct rpmh_request *rpm_msg)
@@ -209,7 +219,7 @@ static int __fill_rpmh_msg(struct rpmh_request *req, enum rpmh_state state,
 }
 
 /**
- * rpmh_write_async: Write a set of RPMH commands
+ * rpmh_write_async() - Write a set of RPMH commands.
  *
  * @dev: The device making the request
  * @state: Active/sleep set
@@ -218,6 +228,8 @@ static int __fill_rpmh_msg(struct rpmh_request *req, enum rpmh_state state,
  *
  * Write a set of RPMH commands, the order of commands is maintained
  * and will be sent as a single shot.
+ *
+ * Return: 0 on success, negative error code on failure.
  */
 int rpmh_write_async(const struct device *dev, enum rpmh_state state,
 		     const struct tcs_cmd *cmd, u32 n)
@@ -241,7 +253,7 @@ int rpmh_write_async(const struct device *dev, enum rpmh_state state,
 EXPORT_SYMBOL_GPL(rpmh_write_async);
 
 /**
- * rpmh_write: Write a set of RPMH commands and block until response
+ * rpmh_write() - Write a set of RPMH commands and block until response
  *
  * @dev: The device making the request
  * @state: Active/sleep set
@@ -249,6 +261,8 @@ EXPORT_SYMBOL_GPL(rpmh_write_async);
  * @n: The number of elements in @cmd
  *
  * May sleep. Do not call from atomic contexts.
+ *
+ * Return: 0 on success, negative error code on failure.
  */
 int rpmh_write(const struct device *dev, enum rpmh_state state,
 	       const struct tcs_cmd *cmd, u32 n)
@@ -303,7 +317,7 @@ static int flush_batch(struct rpmh_ctrlr *ctrlr)
 }
 
 /**
- * rpmh_write_batch: Write multiple sets of RPMH commands and wait for the
+ * rpmh_write_batch() - Write multiple sets of RPMH commands and wait for the
  * batch to finish.
  *
  * @dev: the device making the request
@@ -311,13 +325,15 @@ static int flush_batch(struct rpmh_ctrlr *ctrlr)
  * @cmd: The payload data
  * @n: The array of count of elements in each batch, 0 terminated.
  *
- * Write a request to the RSC controller without caching. If the request
- * state is ACTIVE, then the requests are treated as completion request
- * and sent to the controller immediately. The function waits until all the
- * commands are complete. If the request was to SLEEP or WAKE_ONLY, then the
- * request is sent as fire-n-forget and no ack is expected.
+ * If the request state is ACTIVE_ONLY, the requests are sent to the
+ * controller immediately and the function waits until all commands are
+ * complete. If the state is SLEEP or WAKE_ONLY, the requests are cached
+ * and the function returns immediately; they are sent to the controller
+ * later by rpmh_flush().
  *
  * May sleep. Do not call from atomic contexts for ACTIVE_ONLY requests.
+ *
+ * Return: 0 on success, negative error code on failure.
  */
 int rpmh_write_batch(const struct device *dev, enum rpmh_state state,
 		     const struct tcs_cmd *cmd, u32 *n)
@@ -480,7 +496,7 @@ int rpmh_flush(struct rpmh_ctrlr *ctrlr)
 }
 
 /**
- * rpmh_invalidate: Invalidate sleep and wake sets in batch_cache
+ * rpmh_invalidate() - Invalidate sleep and wake sets in batch_cache
  *
  * @dev: The device making the request
  *

-- 
2.43.0

[PATCH 3/3] soc: qcom: rpmh-rsc: fix kernel-doc issues in rpmh-rsc.c

[Maulik Shah]

Two documentation issues in rpmh-rsc.c:

- rpmh_rsc_pd_callback() has a copy-paste title 'Check if any of
  the AMCs are busy' which describes rpmh_rsc_ctrlr_is_busy() not
  this function. Fix the title to accurately describe what this
  callback does: flush sleep/wake TCS data on PM domain power-off.

- rpmh_rsc_cpu_pm_callback() has the same copy-paste title 'Check
  if any of the AMCs are busy'. Fix the title to accurately describe
  what this callback does: flush sleep/wake TCS data when all CPUs
  enter power down.

No functional impact.

Assisted-by: Claude:claude-sonnet-5
Signed-off-by: Maulik Shah <maulik.shah@oss.qualcomm.com>
---
 drivers/soc/qcom/rpmh-rsc.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/drivers/soc/qcom/rpmh-rsc.c b/drivers/soc/qcom/rpmh-rsc.c
index 66928ca40b9a..f5251519ec85 100644
--- a/drivers/soc/qcom/rpmh-rsc.c
+++ b/drivers/soc/qcom/rpmh-rsc.c
@@ -833,7 +833,7 @@ void rpmh_rsc_write_next_wakeup(struct rsc_drv *drv)
 }
 
 /**
- * rpmh_rsc_cpu_pm_callback() - Check if any of the AMCs are busy.
+ * rpmh_rsc_cpu_pm_callback() - CPU PM notifier to flush sleep/wake TCS data.
  * @nfb:    Pointer to the notifier block in struct rsc_drv.
  * @action: CPU_PM_ENTER, CPU_PM_ENTER_FAILED, or CPU_PM_EXIT.
  * @v:      Unused
@@ -914,7 +914,7 @@ static int rpmh_rsc_cpu_pm_callback(struct notifier_block *nfb,
 }
 
 /**
- * rpmh_rsc_pd_callback() - Check if any of the AMCs are busy.
+ * rpmh_rsc_pd_callback() - PM domain callback to flush sleep/wake TCS data.
  * @nfb:    Pointer to the genpd notifier block in struct rsc_drv.
  * @action: GENPD_NOTIFY_PRE_OFF, GENPD_NOTIFY_OFF, GENPD_NOTIFY_PRE_ON or GENPD_NOTIFY_ON.
  * @v:      Unused

-- 
2.43.0

Re: [PATCH 1/3] soc: qcom: rpmh-internal: fix kernel-doc issues in rpmh-internal.h

[Konrad Dybcio]

On 8/2/26 3:28 PM, Maulik Shah wrote:
> kernel-doc emits two warnings for rpmh-internal.h:
> 
>   Warning: drivers/soc/qcom/rpmh-internal.h:136 struct member 'ver' not described in 'rsc_drv'
>   Warning: drivers/soc/qcom/rpmh-internal.h:136 struct member 'regs' not described in 'rsc_drv'
> 
> Fix them by adding @ver and @regs entries to the struct rsc_drv
> documentation.
> 
> While at it, add a missing kernel-doc block for struct rsc_ver, and
> update the remaining struct kernel-doc comments (struct tcs_group,
> struct rpmh_request, struct rpmh_ctrlr, struct rsc_drv) to use the
> 'struct name -' format documented in
> Documentation/doc-guide/kernel-doc.rst.
> 
> No functional impact.
> 
> Assisted-by: Claude:claude-sonnet-5
> Signed-off-by: Maulik Shah <maulik.shah@oss.qualcomm.com>
> ---

Reviewed-by: Konrad Dybcio <konrad.dybcio@oss.qualcomm.com>

Konrad

Re: [PATCH 2/3] soc: qcom: rpmh: fix kernel-doc issues in rpmh.c

[Konrad Dybcio]

On 8/2/26 3:28 PM, Maulik Shah wrote:
> Six documentation issues in rpmh.c:

[...]

> +/**
> + * rpmh_tx_done() - Signal the completion of a RPMH transfer.

nit: "an RPMH" (because the R is pronounced with a leading "vowel sound")

Reviewed-by: Konrad Dybcio <konrad.dybcio@oss.qualcomm.com>

Konrad

Re: [PATCH 3/3] soc: qcom: rpmh-rsc: fix kernel-doc issues in rpmh-rsc.c

[Konrad Dybcio]

On 8/2/26 3:28 PM, Maulik Shah wrote:
> Two documentation issues in rpmh-rsc.c:
> 
> - rpmh_rsc_pd_callback() has a copy-paste title 'Check if any of
>   the AMCs are busy' which describes rpmh_rsc_ctrlr_is_busy() not
>   this function. Fix the title to accurately describe what this
>   callback does: flush sleep/wake TCS data on PM domain power-off.
> 
> - rpmh_rsc_cpu_pm_callback() has the same copy-paste title 'Check
>   if any of the AMCs are busy'. Fix the title to accurately describe
>   what this callback does: flush sleep/wake TCS data when all CPUs
>   enter power down.
> 
> No functional impact.
> 
> Assisted-by: Claude:claude-sonnet-5
> Signed-off-by: Maulik Shah <maulik.shah@oss.qualcomm.com>
> ---

Reviewed-by: Konrad Dybcio <konrad.dybcio@oss.qualcomm.com>

Konrad