[PATCH] powerpc/ps3: fix ps3.h kernel-doc warnings

[PATCH] powerpc/ps3: fix ps3.h kernel-doc warnings

[Randy Dunlap]

Eliminate all kernel-doc warnings in ps3.h:
- add one missing struct member description
- add one missing function short description
- correct one enum name typo
- change several incomplete kernel-doc comments to plain "/*" comments

Examples:

Warning: arch/powerpc/include/asm/ps3.h:96 struct member 'dev' not
 described in 'ps3_dma_region'
Warning: arch/powerpc/include/asm/ps3.h:408 missing initial short
 description on line: * ps3_system_bus_set_drvdata -
Warning: arch/powerpc/include/asm/ps3.h:473 Enum value
 'PS3_LPM_TB_TYPE_INTERNAL' not described in enum 'ps3_lpm_tb_type'
Warning: arch/powerpc/include/asm/ps3.h:473 Excess enum value
 '@PS3_LPM_RIGHTS_USE_TB' description in 'ps3_lpm_tb_type'

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
---
Cc: Geoff Levand <geoff@infradead.org>
Cc: linuxppc-dev@lists.ozlabs.org
Cc: Madhavan Srinivasan <maddy@linux.ibm.com>
Cc: Michael Ellerman <mpe@ellerman.id.au>

 arch/powerpc/include/asm/ps3.h |   26 ++++++++++++++------------
 1 file changed, 14 insertions(+), 12 deletions(-)

--- linux-next-20260220.orig/arch/powerpc/include/asm/ps3.h
+++ linux-next-20260220/arch/powerpc/include/asm/ps3.h
@@ -65,6 +65,7 @@ struct ps3_dma_region_ops;
 
 /**
  * struct ps3_dma_region - A per device dma state variables structure
+ * @dev: The device that this struct describes.
  * @did: The HV device id.
  * @page_size: The ioc pagesize.
  * @region_type: The HV region type.
@@ -108,18 +109,19 @@ struct ps3_dma_region_ops {
 		     dma_addr_t bus_addr,
 		     unsigned long len);
 };
-/**
+
+struct ps3_system_bus_device;
+
+/*
  * struct ps3_dma_region_init - Helper to initialize structure variables
  *
  * Helper to properly initialize variables prior to calling
  * ps3_system_bus_device_register.
  */
-
-struct ps3_system_bus_device;
-
 int ps3_dma_region_init(struct ps3_system_bus_device *dev,
 	struct ps3_dma_region *r, enum ps3_dma_page_size page_size,
 	enum ps3_dma_region_type region_type, void *addr, unsigned long len);
+
 int ps3_dma_region_create(struct ps3_dma_region *r);
 int ps3_dma_region_free(struct ps3_dma_region *r);
 int ps3_dma_map(struct ps3_dma_region *r, unsigned long virt_addr,
@@ -136,7 +138,7 @@ enum ps3_mmio_page_size {
 };
 
 struct ps3_mmio_region_ops;
-/**
+/*
  * struct ps3_mmio_region - a per device mmio state variables structure
  *
  * Current systems can be supported with a single region per device.
@@ -155,13 +157,13 @@ struct ps3_mmio_region_ops {
 	int (*create)(struct ps3_mmio_region *);
 	int (*free)(struct ps3_mmio_region *);
 };
-/**
- * struct ps3_mmio_region_init - Helper to initialize structure variables
+
+/*
+ * ps3_mmio_region_init - Helper to initialize structure variables
  *
  * Helper to properly initialize variables prior to calling
  * ps3_system_bus_device_register.
  */
-
 int ps3_mmio_region_init(struct ps3_system_bus_device *dev,
 	struct ps3_mmio_region *r, unsigned long bus_addr, unsigned long len,
 	enum ps3_mmio_page_size page_size);
@@ -342,7 +344,7 @@ enum ps3_system_bus_device_type {
 	PS3_DEVICE_TYPE_LPM,
 };
 
-/**
+/*
  * struct ps3_system_bus_device - a device on the system bus
  */
 
@@ -371,7 +373,7 @@ struct ps3_system_bus_device {
 int ps3_open_hv_device(struct ps3_system_bus_device *dev);
 int ps3_close_hv_device(struct ps3_system_bus_device *dev);
 
-/**
+/*
  * struct ps3_system_bus_driver - a driver for a device on the system bus
  */
 
@@ -405,7 +407,7 @@ static inline struct ps3_system_bus_driv
 }
 
 /**
- * ps3_system_bus_set_drvdata -
+ * ps3_system_bus_set_drvdata - save driver private pointer in @dev
  * @dev: device structure
  * @data: Data to set
  */
@@ -464,7 +466,7 @@ enum ps3_lpm_rights {
  * enum ps3_lpm_tb_type - Type of trace buffer lv1 should use.
  *
  * @PS3_LPM_TB_TYPE_NONE: Do not use a trace buffer.
- * @PS3_LPM_RIGHTS_USE_TB: Use the lv1 internal trace buffer.  Must have
+ * @PS3_LPM_TB_TYPE_INTERNAL: Use the lv1 internal trace buffer.  Must have
  *  rights @PS3_LPM_RIGHTS_USE_TB.
  */
 

Re: [PATCH] powerpc/ps3: fix ps3.h kernel-doc warnings

[Christophe Leroy (CS GROUP)]

Hi Randy,

Le 22/02/2026 à 07:01, Randy Dunlap a écrit :
> Eliminate all kernel-doc warnings in ps3.h:
> - add one missing struct member description
> - add one missing function short description
> - correct one enum name typo
> - change several incomplete kernel-doc comments to plain "/*" comments
> 
> Examples:
> 
> Warning: arch/powerpc/include/asm/ps3.h:96 struct member 'dev' not
>   described in 'ps3_dma_region'
> Warning: arch/powerpc/include/asm/ps3.h:408 missing initial short
>   description on line: * ps3_system_bus_set_drvdata -
> Warning: arch/powerpc/include/asm/ps3.h:473 Enum value
>   'PS3_LPM_TB_TYPE_INTERNAL' not described in enum 'ps3_lpm_tb_type'
> Warning: arch/powerpc/include/asm/ps3.h:473 Excess enum value
>   '@PS3_LPM_RIGHTS_USE_TB' description in 'ps3_lpm_tb_type'
> 
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>

You sent a V2 with the same subject some time ago, see 
https://patchwork.ozlabs.org/project/linuxppc-dev/patch/20251129183636.1893634-1-rdunlap@infradead.org/

Is this patch something else, does it superseeds V2, or is it a wrong 
resend of V1 ?

Christophe

> ---
> Cc: Geoff Levand <geoff@infradead.org>
> Cc: linuxppc-dev@lists.ozlabs.org
> Cc: Madhavan Srinivasan <maddy@linux.ibm.com>
> Cc: Michael Ellerman <mpe@ellerman.id.au>
> 
>   arch/powerpc/include/asm/ps3.h |   26 ++++++++++++++------------
>   1 file changed, 14 insertions(+), 12 deletions(-)
> 
> --- linux-next-20260220.orig/arch/powerpc/include/asm/ps3.h
> +++ linux-next-20260220/arch/powerpc/include/asm/ps3.h
> @@ -65,6 +65,7 @@ struct ps3_dma_region_ops;
>   
>   /**
>    * struct ps3_dma_region - A per device dma state variables structure
> + * @dev: The device that this struct describes.
>    * @did: The HV device id.
>    * @page_size: The ioc pagesize.
>    * @region_type: The HV region type.
> @@ -108,18 +109,19 @@ struct ps3_dma_region_ops {
>   		     dma_addr_t bus_addr,
>   		     unsigned long len);
>   };
> -/**
> +
> +struct ps3_system_bus_device;
> +
> +/*
>    * struct ps3_dma_region_init - Helper to initialize structure variables
>    *
>    * Helper to properly initialize variables prior to calling
>    * ps3_system_bus_device_register.
>    */
> -
> -struct ps3_system_bus_device;
> -
>   int ps3_dma_region_init(struct ps3_system_bus_device *dev,
>   	struct ps3_dma_region *r, enum ps3_dma_page_size page_size,
>   	enum ps3_dma_region_type region_type, void *addr, unsigned long len);
> +
>   int ps3_dma_region_create(struct ps3_dma_region *r);
>   int ps3_dma_region_free(struct ps3_dma_region *r);
>   int ps3_dma_map(struct ps3_dma_region *r, unsigned long virt_addr,
> @@ -136,7 +138,7 @@ enum ps3_mmio_page_size {
>   };
>   
>   struct ps3_mmio_region_ops;
> -/**
> +/*
>    * struct ps3_mmio_region - a per device mmio state variables structure
>    *
>    * Current systems can be supported with a single region per device.
> @@ -155,13 +157,13 @@ struct ps3_mmio_region_ops {
>   	int (*create)(struct ps3_mmio_region *);
>   	int (*free)(struct ps3_mmio_region *);
>   };
> -/**
> - * struct ps3_mmio_region_init - Helper to initialize structure variables
> +
> +/*
> + * ps3_mmio_region_init - Helper to initialize structure variables
>    *
>    * Helper to properly initialize variables prior to calling
>    * ps3_system_bus_device_register.
>    */
> -
>   int ps3_mmio_region_init(struct ps3_system_bus_device *dev,
>   	struct ps3_mmio_region *r, unsigned long bus_addr, unsigned long len,
>   	enum ps3_mmio_page_size page_size);
> @@ -342,7 +344,7 @@ enum ps3_system_bus_device_type {
>   	PS3_DEVICE_TYPE_LPM,
>   };
>   
> -/**
> +/*
>    * struct ps3_system_bus_device - a device on the system bus
>    */
>   
> @@ -371,7 +373,7 @@ struct ps3_system_bus_device {
>   int ps3_open_hv_device(struct ps3_system_bus_device *dev);
>   int ps3_close_hv_device(struct ps3_system_bus_device *dev);
>   
> -/**
> +/*
>    * struct ps3_system_bus_driver - a driver for a device on the system bus
>    */
>   
> @@ -405,7 +407,7 @@ static inline struct ps3_system_bus_driv
>   }
>   
>   /**
> - * ps3_system_bus_set_drvdata -
> + * ps3_system_bus_set_drvdata - save driver private pointer in @dev
>    * @dev: device structure
>    * @data: Data to set
>    */
> @@ -464,7 +466,7 @@ enum ps3_lpm_rights {
>    * enum ps3_lpm_tb_type - Type of trace buffer lv1 should use.
>    *
>    * @PS3_LPM_TB_TYPE_NONE: Do not use a trace buffer.
> - * @PS3_LPM_RIGHTS_USE_TB: Use the lv1 internal trace buffer.  Must have
> + * @PS3_LPM_TB_TYPE_INTERNAL: Use the lv1 internal trace buffer.  Must have
>    *  rights @PS3_LPM_RIGHTS_USE_TB.
>    */
>   
> 

Re: [PATCH] powerpc/ps3: fix ps3.h kernel-doc warnings

[Randy Dunlap]

On 2/24/26 10:57 PM, Christophe Leroy (CS GROUP) wrote:
> Hi Randy,
> 
> Le 22/02/2026 à 07:01, Randy Dunlap a écrit :
>> Eliminate all kernel-doc warnings in ps3.h:
>> - add one missing struct member description
>> - add one missing function short description
>> - correct one enum name typo
>> - change several incomplete kernel-doc comments to plain "/*" comments
>>
>> Examples:
>>
>> Warning: arch/powerpc/include/asm/ps3.h:96 struct member 'dev' not
>>   described in 'ps3_dma_region'
>> Warning: arch/powerpc/include/asm/ps3.h:408 missing initial short
>>   description on line: * ps3_system_bus_set_drvdata -
>> Warning: arch/powerpc/include/asm/ps3.h:473 Enum value
>>   'PS3_LPM_TB_TYPE_INTERNAL' not described in enum 'ps3_lpm_tb_type'
>> Warning: arch/powerpc/include/asm/ps3.h:473 Excess enum value
>>   '@PS3_LPM_RIGHTS_USE_TB' description in 'ps3_lpm_tb_type'
>>
>> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> 
> You sent a V2 with the same subject some time ago, see https://patchwork.ozlabs.org/project/linuxppc-dev/patch/20251129183636.1893634-1-rdunlap@infradead.org/
> 
> Is this patch something else, does it superseeds V2, or is it a wrong resend of V1 ?

Yup, it's a wrong resend of v1. It means that my patch tracking system
failed me. Sorry about that.

-- 
~Randy

Re: [PATCH] powerpc/ps3: fix ps3.h kernel-doc warnings

[Christophe Leroy (CS GROUP)]

Le 26/02/2026 à 02:45, Randy Dunlap a écrit :
> 
> 
> On 2/24/26 10:57 PM, Christophe Leroy (CS GROUP) wrote:
>> Hi Randy,
>>
>> Le 22/02/2026 à 07:01, Randy Dunlap a écrit :
>>> Eliminate all kernel-doc warnings in ps3.h:
>>> - add one missing struct member description
>>> - add one missing function short description
>>> - correct one enum name typo
>>> - change several incomplete kernel-doc comments to plain "/*" comments
>>>
>>> Examples:
>>>
>>> Warning: arch/powerpc/include/asm/ps3.h:96 struct member 'dev' not
>>>    described in 'ps3_dma_region'
>>> Warning: arch/powerpc/include/asm/ps3.h:408 missing initial short
>>>    description on line: * ps3_system_bus_set_drvdata -
>>> Warning: arch/powerpc/include/asm/ps3.h:473 Enum value
>>>    'PS3_LPM_TB_TYPE_INTERNAL' not described in enum 'ps3_lpm_tb_type'
>>> Warning: arch/powerpc/include/asm/ps3.h:473 Excess enum value
>>>    '@PS3_LPM_RIGHTS_USE_TB' description in 'ps3_lpm_tb_type'
>>>
>>> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
>>
>> You sent a V2 with the same subject some time ago, see https://eur01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fpatchwork.ozlabs.org%2Fproject%2Flinuxppc-dev%2Fpatch%2F20251129183636.1893634-1-rdunlap%40infradead.org%2F&data=05%7C02%7Cchristophe.leroy%40csgroup.eu%7C5f40eabfbf95474b6c4608de74d8ad0e%7C8b87af7d86474dc78df45f69a2011bb5%7C0%7C0%7C639076671142017726%7CUnknown%7CTWFpbGZsb3d8eyJFbXB0eU1hcGkiOnRydWUsIlYiOiIwLjAuMDAwMCIsIlAiOiJXaW4zMiIsIkFOIjoiTWFpbCIsIldUIjoyfQ%3D%3D%7C0%7C%7C%7C&sdata=Bk2srZQMhhrA6rpHEFx2CIxSee8%2FUM2TIrNQSFpP8%2B4%3D&reserved=0
>>
>> Is this patch something else, does it superseeds V2, or is it a wrong resend of V1 ?
> 
> Yup, it's a wrong resend of v1. It means that my patch tracking system
> failed me. Sorry about that.
> 

Ok so I reject that one.

Here is the list of patches from you we have in the pipe:

https://patchwork.ozlabs.org/project/linuxppc-dev/list/?submitter=18663

Christophe

Re: [PATCH] powerpc/ps3: fix ps3.h kernel-doc warnings

[Randy Dunlap]

On 2/26/26 3:58 AM, Christophe Leroy (CS GROUP) wrote:
> 
> 
> Le 26/02/2026 à 02:45, Randy Dunlap a écrit :
>>
>>
>> On 2/24/26 10:57 PM, Christophe Leroy (CS GROUP) wrote:
>>> Hi Randy,
>>>
>>> Le 22/02/2026 à 07:01, Randy Dunlap a écrit :
>>>> Eliminate all kernel-doc warnings in ps3.h:
>>>> - add one missing struct member description
>>>> - add one missing function short description
>>>> - correct one enum name typo
>>>> - change several incomplete kernel-doc comments to plain "/*" comments
>>>>
>>>> Examples:
>>>>
>>>> Warning: arch/powerpc/include/asm/ps3.h:96 struct member 'dev' not
>>>>    described in 'ps3_dma_region'
>>>> Warning: arch/powerpc/include/asm/ps3.h:408 missing initial short
>>>>    description on line: * ps3_system_bus_set_drvdata -
>>>> Warning: arch/powerpc/include/asm/ps3.h:473 Enum value
>>>>    'PS3_LPM_TB_TYPE_INTERNAL' not described in enum 'ps3_lpm_tb_type'
>>>> Warning: arch/powerpc/include/asm/ps3.h:473 Excess enum value
>>>>    '@PS3_LPM_RIGHTS_USE_TB' description in 'ps3_lpm_tb_type'
>>>>
>>>> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
>>>
>>> You sent a V2 with the same subject some time ago, see https://eur01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fpatchwork.ozlabs.org%2Fproject%2Flinuxppc-dev%2Fpatch%2F20251129183636.1893634-1-rdunlap%40infradead.org%2F&data=05%7C02%7Cchristophe.leroy%40csgroup.eu%7C5f40eabfbf95474b6c4608de74d8ad0e%7C8b87af7d86474dc78df45f69a2011bb5%7C0%7C0%7C639076671142017726%7CUnknown%7CTWFpbGZsb3d8eyJFbXB0eU1hcGkiOnRydWUsIlYiOiIwLjAuMDAwMCIsIlAiOiJXaW4zMiIsIkFOIjoiTWFpbCIsIldUIjoyfQ%3D%3D%7C0%7C%7C%7C&sdata=Bk2srZQMhhrA6rpHEFx2CIxSee8%2FUM2TIrNQSFpP8%2B4%3D&reserved=0
>>>
>>> Is this patch something else, does it superseeds V2, or is it a wrong resend of V1 ?
>>
>> Yup, it's a wrong resend of v1. It means that my patch tracking system
>> failed me. Sorry about that.
>>
> 
> Ok so I reject that one.

ack.

> Here is the list of patches from you we have in the pipe:
> 
> https://patchwork.ozlabs.org/project/linuxppc-dev/list/?submitter=18663

Looks good. Thanks.

-- 
~Randy

[PATCH] powerpc/ps3: fix ps3.h kernel-doc warnings

[Randy Dunlap]

Fix some kernel-doc warnings in ps3.h:

- add @dev to struct ps3_dma_region
- don't mark a function as "struct"
- add Returns: description for one function
- add a short description for ps3_system_bus_set_drvdata()
- correct an enum @name

to eliminate these warnings:

Warning: arch/powerpc/include/asm/ps3.h:96 struct member 'dev' not
 described in 'ps3_dma_region'
Warning: arch/powerpc/include/asm/ps3.h:166 int
 ps3_mmio_region_init(struct ps3_system_bus_device *dev, struct
 ps3_mmio_region *r, unsigned long bus_addr, unsigned long len, enum
 ps3_mmio_page_size page_size); error: Cannot parse struct or union!
Warning: arch/powerpc/include/asm/ps3.h:167 No description found for
 return value of 'ps3_mmio_region_init'
Warning: arch/powerpc/include/asm/ps3.h:407 missing initial short
 description on line:
 * ps3_system_bus_set_drvdata -
Warning: arch/powerpc/include/asm/ps3.h:473 Enum value
 'PS3_LPM_TB_TYPE_INTERNAL' not described in enum 'ps3_lpm_tb_type'
Warning: arch/powerpc/include/asm/ps3.h:473 Excess enum value
 '@PS3_LPM_RIGHTS_USE_TB' description in 'ps3_lpm_tb_type'

This leaves struct members in several structs and function parameters in
one function still undescribed.

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
---
Cc: Geoff Levand <geoff@infradead.org>
Cc: Madhavan Srinivasan <maddy@linux.ibm.com>
Cc: Michael Ellerman <mpe@ellerman.id.au>
Cc: Nicholas Piggin <npiggin@gmail.com>
Cc: "Christophe Leroy (CS GROUP)" <chleroy@kernel.org>
---
 arch/powerpc/include/asm/ps3.h |    9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

--- linux-next-20251128.orig/arch/powerpc/include/asm/ps3.h
+++ linux-next-20251128/arch/powerpc/include/asm/ps3.h
@@ -65,6 +65,7 @@ struct ps3_dma_region_ops;
 
 /**
  * struct ps3_dma_region - A per device dma state variables structure
+ * @dev: device structure
  * @did: The HV device id.
  * @page_size: The ioc pagesize.
  * @region_type: The HV region type.
@@ -156,10 +157,12 @@ struct ps3_mmio_region_ops {
 	int (*free)(struct ps3_mmio_region *);
 };
 /**
- * struct ps3_mmio_region_init - Helper to initialize structure variables
+ * ps3_mmio_region_init - Helper to initialize structure variables
  *
  * Helper to properly initialize variables prior to calling
  * ps3_system_bus_device_register.
+ *
+ * Returns: %0 on success, %-errno on error (or BUG())
  */
 
 int ps3_mmio_region_init(struct ps3_system_bus_device *dev,
@@ -405,7 +408,7 @@ static inline struct ps3_system_bus_driv
 }
 
 /**
- * ps3_system_bus_set_drvdata -
+ * ps3_system_bus_set_drvdata - set driver's private data for this device
  * @dev: device structure
  * @data: Data to set
  */
@@ -464,7 +467,7 @@ enum ps3_lpm_rights {
  * enum ps3_lpm_tb_type - Type of trace buffer lv1 should use.
  *
  * @PS3_LPM_TB_TYPE_NONE: Do not use a trace buffer.
- * @PS3_LPM_RIGHTS_USE_TB: Use the lv1 internal trace buffer.  Must have
+ * @PS3_LPM_TB_TYPE_INTERNAL: Use the lv1 internal trace buffer.  Must have
  *  rights @PS3_LPM_RIGHTS_USE_TB.
  */
 

Re: [PATCH] powerpc/ps3: fix ps3.h kernel-doc warnings

[Randy Dunlap]

Hi,
I have an update (v2) for this patch.
Will send this weekend.

On 11/28/25 4:24 PM, Randy Dunlap wrote:
> Fix some kernel-doc warnings in ps3.h:
> 
> - add @dev to struct ps3_dma_region
> - don't mark a function as "struct"
> - add Returns: description for one function
> - add a short description for ps3_system_bus_set_drvdata()
> - correct an enum @name
> 
> to eliminate these warnings:
> 
> Warning: arch/powerpc/include/asm/ps3.h:96 struct member 'dev' not
>  described in 'ps3_dma_region'
> Warning: arch/powerpc/include/asm/ps3.h:166 int
>  ps3_mmio_region_init(struct ps3_system_bus_device *dev, struct
>  ps3_mmio_region *r, unsigned long bus_addr, unsigned long len, enum
>  ps3_mmio_page_size page_size); error: Cannot parse struct or union!
> Warning: arch/powerpc/include/asm/ps3.h:167 No description found for
>  return value of 'ps3_mmio_region_init'
> Warning: arch/powerpc/include/asm/ps3.h:407 missing initial short
>  description on line:
>  * ps3_system_bus_set_drvdata -
> Warning: arch/powerpc/include/asm/ps3.h:473 Enum value
>  'PS3_LPM_TB_TYPE_INTERNAL' not described in enum 'ps3_lpm_tb_type'
> Warning: arch/powerpc/include/asm/ps3.h:473 Excess enum value
>  '@PS3_LPM_RIGHTS_USE_TB' description in 'ps3_lpm_tb_type'
> 
> This leaves struct members in several structs and function parameters in
> one function still undescribed.
> 
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> ---
> Cc: Geoff Levand <geoff@infradead.org>
> Cc: Madhavan Srinivasan <maddy@linux.ibm.com>
> Cc: Michael Ellerman <mpe@ellerman.id.au>
> Cc: Nicholas Piggin <npiggin@gmail.com>
> Cc: "Christophe Leroy (CS GROUP)" <chleroy@kernel.org>
> ---
>  arch/powerpc/include/asm/ps3.h |    9 ++++++---
>  1 file changed, 6 insertions(+), 3 deletions(-)


-- 
~Randy