| Message ID | 20230317081718.2650744-3-lee@kernel.org (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | None | expand |
Hi Lee, Thank you for the patch. On Fri, Mar 17, 2023 at 08:16:43AM +0000, Lee Jones wrote: > Fixes the following W=1 kernel build warning(s): > > drivers/gpu/drm/xlnx/zynqmp_disp.c:151: warning: Function parameter or member 'blend' not described in 'zynqmp_disp' > drivers/gpu/drm/xlnx/zynqmp_disp.c:151: warning: Function parameter or member 'avbuf' not described in 'zynqmp_disp' > drivers/gpu/drm/xlnx/zynqmp_disp.c:151: warning: Function parameter or member 'audio' not described in 'zynqmp_disp' > > Cc: Hyun Kwon <hyun.kwon@xilinx.com> > Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com> > Cc: David Airlie <airlied@gmail.com> > Cc: Daniel Vetter <daniel@ffwll.ch> > Cc: Michal Simek <michal.simek@xilinx.com> > Cc: dri-devel@lists.freedesktop.org > Cc: linux-arm-kernel@lists.infradead.org > Signed-off-by: Lee Jones <lee@kernel.org> > --- > drivers/gpu/drm/xlnx/zynqmp_disp.c | 6 +++--- > 1 file changed, 3 insertions(+), 3 deletions(-) > > diff --git a/drivers/gpu/drm/xlnx/zynqmp_disp.c b/drivers/gpu/drm/xlnx/zynqmp_disp.c > index 3b87eebddc979..63358f4898625 100644 > --- a/drivers/gpu/drm/xlnx/zynqmp_disp.c > +++ b/drivers/gpu/drm/xlnx/zynqmp_disp.c > @@ -128,9 +128,9 @@ struct zynqmp_disp_layer { > * struct zynqmp_disp - Display controller > * @dev: Device structure > * @dpsub: Display subsystem > - * @blend.base: Register I/O base address for the blender > - * @avbuf.base: Register I/O base address for the audio/video buffer manager > - * @audio.base: Registers I/O base address for the audio mixer > + * @blend: .base: Register I/O base address for the blender > + * @avbuf: .base: Register I/O base address for the audio/video buffer manager > + * @audio: .base: Registers I/O base address for the audio mixer This is a hack, it won't work properly if the nested structures get extended with more fields. Is there a correct kerneldoc syntax for this code construct ? > * @layers: Layers (planes) > */ > struct zynqmp_disp {
On Sun, 19 Mar 2023, Laurent Pinchart wrote: > Hi Lee, > > Thank you for the patch. > > On Fri, Mar 17, 2023 at 08:16:43AM +0000, Lee Jones wrote: > > Fixes the following W=1 kernel build warning(s): > > > > drivers/gpu/drm/xlnx/zynqmp_disp.c:151: warning: Function parameter or member 'blend' not described in 'zynqmp_disp' > > drivers/gpu/drm/xlnx/zynqmp_disp.c:151: warning: Function parameter or member 'avbuf' not described in 'zynqmp_disp' > > drivers/gpu/drm/xlnx/zynqmp_disp.c:151: warning: Function parameter or member 'audio' not described in 'zynqmp_disp' > > > > Cc: Hyun Kwon <hyun.kwon@xilinx.com> > > Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com> > > Cc: David Airlie <airlied@gmail.com> > > Cc: Daniel Vetter <daniel@ffwll.ch> > > Cc: Michal Simek <michal.simek@xilinx.com> > > Cc: dri-devel@lists.freedesktop.org > > Cc: linux-arm-kernel@lists.infradead.org > > Signed-off-by: Lee Jones <lee@kernel.org> > > --- > > drivers/gpu/drm/xlnx/zynqmp_disp.c | 6 +++--- > > 1 file changed, 3 insertions(+), 3 deletions(-) > > > > diff --git a/drivers/gpu/drm/xlnx/zynqmp_disp.c b/drivers/gpu/drm/xlnx/zynqmp_disp.c > > index 3b87eebddc979..63358f4898625 100644 > > --- a/drivers/gpu/drm/xlnx/zynqmp_disp.c > > +++ b/drivers/gpu/drm/xlnx/zynqmp_disp.c > > @@ -128,9 +128,9 @@ struct zynqmp_disp_layer { > > * struct zynqmp_disp - Display controller > > * @dev: Device structure > > * @dpsub: Display subsystem > > - * @blend.base: Register I/O base address for the blender > > - * @avbuf.base: Register I/O base address for the audio/video buffer manager > > - * @audio.base: Registers I/O base address for the audio mixer > > + * @blend: .base: Register I/O base address for the blender > > + * @avbuf: .base: Register I/O base address for the audio/video buffer manager > > + * @audio: .base: Registers I/O base address for the audio mixer > > This is a hack, it won't work properly if the nested structures get > extended with more fields. The original doc is a hack, for it is not recognised kerneldoc format. :) > Is there a correct kerneldoc syntax for this code construct ? Not that I'm aware of. Unless it's been added since my last round of this stuff. > > * @layers: Layers (planes) > > */ > > struct zynqmp_disp { > > -- > Regards, > > Laurent Pinchart -- Lee Jones [李琼斯]
Hi Lee, (CC'ing Jon and Mauro) On Mon, Mar 20, 2023 at 08:17:00AM +0000, Lee Jones wrote: > On Sun, 19 Mar 2023, Laurent Pinchart wrote: > > Thank you for the patch. > > > > On Fri, Mar 17, 2023 at 08:16:43AM +0000, Lee Jones wrote: > > > Fixes the following W=1 kernel build warning(s): > > > > > > drivers/gpu/drm/xlnx/zynqmp_disp.c:151: warning: Function parameter or member 'blend' not described in 'zynqmp_disp' > > > drivers/gpu/drm/xlnx/zynqmp_disp.c:151: warning: Function parameter or member 'avbuf' not described in 'zynqmp_disp' > > > drivers/gpu/drm/xlnx/zynqmp_disp.c:151: warning: Function parameter or member 'audio' not described in 'zynqmp_disp' > > > > > > Cc: Hyun Kwon <hyun.kwon@xilinx.com> > > > Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com> > > > Cc: David Airlie <airlied@gmail.com> > > > Cc: Daniel Vetter <daniel@ffwll.ch> > > > Cc: Michal Simek <michal.simek@xilinx.com> > > > Cc: dri-devel@lists.freedesktop.org > > > Cc: linux-arm-kernel@lists.infradead.org > > > Signed-off-by: Lee Jones <lee@kernel.org> > > > --- > > > drivers/gpu/drm/xlnx/zynqmp_disp.c | 6 +++--- > > > 1 file changed, 3 insertions(+), 3 deletions(-) > > > > > > diff --git a/drivers/gpu/drm/xlnx/zynqmp_disp.c b/drivers/gpu/drm/xlnx/zynqmp_disp.c > > > index 3b87eebddc979..63358f4898625 100644 > > > --- a/drivers/gpu/drm/xlnx/zynqmp_disp.c > > > +++ b/drivers/gpu/drm/xlnx/zynqmp_disp.c > > > @@ -128,9 +128,9 @@ struct zynqmp_disp_layer { > > > * struct zynqmp_disp - Display controller > > > * @dev: Device structure > > > * @dpsub: Display subsystem > > > - * @blend.base: Register I/O base address for the blender > > > - * @avbuf.base: Register I/O base address for the audio/video buffer manager > > > - * @audio.base: Registers I/O base address for the audio mixer > > > + * @blend: .base: Register I/O base address for the blender > > > + * @avbuf: .base: Register I/O base address for the audio/video buffer manager > > > + * @audio: .base: Registers I/O base address for the audio mixer > > > > This is a hack, it won't work properly if the nested structures get > > extended with more fields. > > The original doc is a hack, for it is not recognised kerneldoc format. :) I'll claim it's a bug, not a hack :-D > > Is there a correct kerneldoc syntax for this code construct ? > > Not that I'm aware of. > > Unless it's been added since my last round of this stuff. I haven't seen anything either. I tried moving the documentation inline, and the scripts/kernel-doc script ignores the comment blocks for the inner fields. Mauro, Jon, is this a known issue ? If so, are there plans to fix it ? What's the recommended way to proceed here ? > > > * @layers: Layers (planes) > > > */ > > > struct zynqmp_disp {
Jon, Mauro, would you have any feedback on this ? On Tue, Mar 21, 2023 at 01:15:51AM +0200, Laurent Pinchart wrote: > Hi Lee, > > (CC'ing Jon and Mauro) > > On Mon, Mar 20, 2023 at 08:17:00AM +0000, Lee Jones wrote: > > On Sun, 19 Mar 2023, Laurent Pinchart wrote: > > > Thank you for the patch. > > > > > > On Fri, Mar 17, 2023 at 08:16:43AM +0000, Lee Jones wrote: > > > > Fixes the following W=1 kernel build warning(s): > > > > > > > > drivers/gpu/drm/xlnx/zynqmp_disp.c:151: warning: Function parameter or member 'blend' not described in 'zynqmp_disp' > > > > drivers/gpu/drm/xlnx/zynqmp_disp.c:151: warning: Function parameter or member 'avbuf' not described in 'zynqmp_disp' > > > > drivers/gpu/drm/xlnx/zynqmp_disp.c:151: warning: Function parameter or member 'audio' not described in 'zynqmp_disp' > > > > > > > > Cc: Hyun Kwon <hyun.kwon@xilinx.com> > > > > Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com> > > > > Cc: David Airlie <airlied@gmail.com> > > > > Cc: Daniel Vetter <daniel@ffwll.ch> > > > > Cc: Michal Simek <michal.simek@xilinx.com> > > > > Cc: dri-devel@lists.freedesktop.org > > > > Cc: linux-arm-kernel@lists.infradead.org > > > > Signed-off-by: Lee Jones <lee@kernel.org> > > > > --- > > > > drivers/gpu/drm/xlnx/zynqmp_disp.c | 6 +++--- > > > > 1 file changed, 3 insertions(+), 3 deletions(-) > > > > > > > > diff --git a/drivers/gpu/drm/xlnx/zynqmp_disp.c b/drivers/gpu/drm/xlnx/zynqmp_disp.c > > > > index 3b87eebddc979..63358f4898625 100644 > > > > --- a/drivers/gpu/drm/xlnx/zynqmp_disp.c > > > > +++ b/drivers/gpu/drm/xlnx/zynqmp_disp.c > > > > @@ -128,9 +128,9 @@ struct zynqmp_disp_layer { > > > > * struct zynqmp_disp - Display controller > > > > * @dev: Device structure > > > > * @dpsub: Display subsystem > > > > - * @blend.base: Register I/O base address for the blender > > > > - * @avbuf.base: Register I/O base address for the audio/video buffer manager > > > > - * @audio.base: Registers I/O base address for the audio mixer > > > > + * @blend: .base: Register I/O base address for the blender > > > > + * @avbuf: .base: Register I/O base address for the audio/video buffer manager > > > > + * @audio: .base: Registers I/O base address for the audio mixer > > > > > > This is a hack, it won't work properly if the nested structures get > > > extended with more fields. > > > > The original doc is a hack, for it is not recognised kerneldoc format. :) > > I'll claim it's a bug, not a hack :-D > > > > Is there a correct kerneldoc syntax for this code construct ? > > > > Not that I'm aware of. > > > > Unless it's been added since my last round of this stuff. > > I haven't seen anything either. I tried moving the documentation inline, > and the scripts/kernel-doc script ignores the comment blocks for the > inner fields. > > Mauro, Jon, is this a known issue ? If so, are there plans to fix it ? > What's the recommended way to proceed here ? > > > > > * @layers: Layers (planes) > > > > */ > > > > struct zynqmp_disp {
Laurent Pinchart <laurent.pinchart@ideasonboard.com> writes: > I haven't seen anything either. I tried moving the documentation inline, > and the scripts/kernel-doc script ignores the comment blocks for the > inner fields. > > Mauro, Jon, is this a known issue ? If so, are there plans to fix it ? > What's the recommended way to proceed here ? As far as I can recall, nobody has ever complained about problems with nested structure definitions like that; kernel-doc certainly isn't set up to handle such a thing. It could certainly be added, but it would require somebody diving into that delightful code to do that work. I can't promise to be able to do that in the near future. Sorry, jon
diff --git a/drivers/gpu/drm/xlnx/zynqmp_disp.c b/drivers/gpu/drm/xlnx/zynqmp_disp.c index 3b87eebddc979..63358f4898625 100644 --- a/drivers/gpu/drm/xlnx/zynqmp_disp.c +++ b/drivers/gpu/drm/xlnx/zynqmp_disp.c @@ -128,9 +128,9 @@ struct zynqmp_disp_layer { * struct zynqmp_disp - Display controller * @dev: Device structure * @dpsub: Display subsystem - * @blend.base: Register I/O base address for the blender - * @avbuf.base: Register I/O base address for the audio/video buffer manager - * @audio.base: Registers I/O base address for the audio mixer + * @blend: .base: Register I/O base address for the blender + * @avbuf: .base: Register I/O base address for the audio/video buffer manager + * @audio: .base: Registers I/O base address for the audio mixer * @layers: Layers (planes) */ struct zynqmp_disp {
Fixes the following W=1 kernel build warning(s): drivers/gpu/drm/xlnx/zynqmp_disp.c:151: warning: Function parameter or member 'blend' not described in 'zynqmp_disp' drivers/gpu/drm/xlnx/zynqmp_disp.c:151: warning: Function parameter or member 'avbuf' not described in 'zynqmp_disp' drivers/gpu/drm/xlnx/zynqmp_disp.c:151: warning: Function parameter or member 'audio' not described in 'zynqmp_disp' Cc: Hyun Kwon <hyun.kwon@xilinx.com> Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Cc: David Airlie <airlied@gmail.com> Cc: Daniel Vetter <daniel@ffwll.ch> Cc: Michal Simek <michal.simek@xilinx.com> Cc: dri-devel@lists.freedesktop.org Cc: linux-arm-kernel@lists.infradead.org Signed-off-by: Lee Jones <lee@kernel.org> --- drivers/gpu/drm/xlnx/zynqmp_disp.c | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)