[PATCH] staging: vme_user: vme_bridge.h: Fix mutex without comment warning

[PATCH] staging: vme_user: vme_bridge.h: Fix mutex without comment warning

[Riyan Dhiman]

Adhere to Linux kernel coding style

Reported by checkpatch:

CHECK: mutex definition without comment

Signed-off-by: Riyan Dhiman <riyandhiman14@gmail.com>
---
 drivers/staging/vme_user/vme_bridge.h | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/drivers/staging/vme_user/vme_bridge.h b/drivers/staging/vme_user/vme_bridge.h
index 9bdc41bb6602..0b1f05944f0d 100644
--- a/drivers/staging/vme_user/vme_bridge.h
+++ b/drivers/staging/vme_user/vme_bridge.h
@@ -28,6 +28,7 @@ struct vme_master_resource {
 struct vme_slave_resource {
 	struct list_head list;
 	struct vme_bridge *parent;
+	/* Locking for VME slave resources */
 	struct mutex mtx;
 	int locked;
 	int number;
@@ -55,12 +56,14 @@ struct vme_dma_list {
 	struct list_head list;
 	struct vme_dma_resource *parent;
 	struct list_head entries;
+	/* Mutex to protect access to DMA list's entries */
 	struct mutex mtx;
 };
 
 struct vme_dma_resource {
 	struct list_head list;
 	struct vme_bridge *parent;
+	/* Mutex to protect DMA controller resources and ensure thread-safe operations */
 	struct mutex mtx;
 	int locked;
 	int number;
@@ -72,6 +75,7 @@ struct vme_dma_resource {
 struct vme_lm_resource {
 	struct list_head list;
 	struct vme_bridge *parent;
+	/* Mutex to protect LM Monitor resources and ensure thread-safe operations */
 	struct mutex mtx;
 	int locked;
 	int number;
-- 
2.39.2

Re: [PATCH] staging: vme_user: vme_bridge.h: Fix mutex without comment warning

[Greg KH]

On Wed, Jul 31, 2024 at 01:06:05PM +0530, Riyan Dhiman wrote:
> Adhere to Linux kernel coding style
> 
> Reported by checkpatch:
> 
> CHECK: mutex definition without comment
> 
> Signed-off-by: Riyan Dhiman <riyandhiman14@gmail.com>
> ---
>  drivers/staging/vme_user/vme_bridge.h | 4 ++++
>  1 file changed, 4 insertions(+)
> 
> diff --git a/drivers/staging/vme_user/vme_bridge.h b/drivers/staging/vme_user/vme_bridge.h
> index 9bdc41bb6602..0b1f05944f0d 100644
> --- a/drivers/staging/vme_user/vme_bridge.h
> +++ b/drivers/staging/vme_user/vme_bridge.h
> @@ -28,6 +28,7 @@ struct vme_master_resource {
>  struct vme_slave_resource {
>  	struct list_head list;
>  	struct vme_bridge *parent;
> +	/* Locking for VME slave resources */

Are you sure about all of these?  Please document them individually and
put the proof of that in the changelog text.

thanks,

greg k-h

Re: [PATCH] staging: vme_user: vme_bridge.h: Fix mutex without comment warning

[Greg KH]

A: http://en.wikipedia.org/wiki/Top_post
Q: Were do I find info about this thing called top-posting?
A: Because it messes up the order in which people normally read text.
Q: Why is top-posting such a bad thing?
A: Top-posting.
Q: What is the most annoying thing in e-mail?

A: No.
Q: Should I include quotations after my reply?

http://daringfireball.net/2007/07/on_top

On Wed, Jul 31, 2024 at 01:34:56PM +0530, Riyan Dhiman wrote:
> Hello,
> 
> Thank you for reviewing my patch. I received your feedback:
> > Are you sure about all of these?  Please document them individually and
> > put the proof of that in the changelog text.
> 
> I'd like to clarify a few points to ensure I address your concerns
> correctly:
> 
> 1. By "document them individually", do you mean I should submit
> separate patches for each mutex documentation change?

Yes.

> 2. Regarding the "proof" for the changelog text, could you please elaborate
> on what kind of proof you 're looking for? Should I include:
>  - References to the code where these mutexes are used?
>  - Explanations of the race conditions these mutexes prevent?
>  - Citations from the driver's design documentation (if available)?

Whatever you feel would be needed to convince everyone that the comment
is now correct.

> 3. Is there a preferred format or level of detail you'd like to see in the
> changelog for each documentation change?

What would you want to see if you had to review this type of change to
be comfortable accepting it?

thanks,

greg k-h