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

["Christophe Leroy (CS GROUP)" <chleroy@kernel.org>]

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.
>    */
>   
>