linux-kernel - Re: [PATCH 01/20] drm/xlnx/zynqmp_disp: Use correct kerneldoc formatting in zynqmp

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-ID: <05e511c7-596d-c9c6-51d8-8883c6a62599@infradead.org>
Date:   Mon, 28 Aug 2023 12:33:14 -0700
From:   Randy Dunlap <rdunlap@...radead.org>
To:     Laurent Pinchart <laurent.pinchart@...asonboard.com>,
        Lee Jones <lee@...nel.org>
Cc:     linux-kernel@...r.kernel.org, Hyun Kwon <hyun.kwon@...inx.com>,
        David Airlie <airlied@...il.com>,
        Daniel Vetter <daniel@...ll.ch>,
        Michal Simek <michal.simek@...inx.com>,
        dri-devel@...ts.freedesktop.org,
        linux-arm-kernel@...ts.infradead.org
Subject: Re: [PATCH 01/20] drm/xlnx/zynqmp_disp: Use correct kerneldoc
 formatting in zynqmp_disp

Hi--

On 8/28/23 09:39, Laurent Pinchart wrote:
> Hi Lee,
> 
> Thank you for the patch.
> 
> On Thu, Aug 24, 2023 at 08:36:46AM +0100, 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'
>>
>> Signed-off-by: Lee Jones <lee@...nel.org>
>> ---
>> Cc: Hyun Kwon <hyun.kwon@...inx.com>
>> Cc: Laurent Pinchart <laurent.pinchart@...asonboard.com>
>> Cc: David Airlie <airlied@...il.com>
>> Cc: Daniel Vetter <daniel@...ll.ch>
>> Cc: Michal Simek <michal.simek@...inx.com>
>> Cc: dri-devel@...ts.freedesktop.org
>> Cc: linux-arm-kernel@...ts.infradead.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 407bc07cec69a..7c64ab11fe2b0 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 really a hack to work around the warning, and not a clean fix.
> kerneldoc is still today unable, as far as I understand, to document
> nested structures. That's annoying, and the warning is a good way to

kernel-doc for nested structs/unions is documented in Documentation/doc-guide/kernel-doc.rst.

This isn't pretty, but this fixes the warnings for me: (massage the
descriptions as you see fit)


---
 drivers/gpu/drm/xlnx/zynqmp_disp.c |    3 +++
 1 file changed, 3 insertions(+)

diff -- a/drivers/gpu/drm/xlnx/zynqmp_disp.c b/drivers/gpu/drm/xlnx/zynqmp_disp.c
--- a/drivers/gpu/drm/xlnx/zynqmp_disp.c
+++ b/drivers/gpu/drm/xlnx/zynqmp_disp.c
@@ -128,8 +128,11 @@ struct zynqmp_disp_layer {
  * struct zynqmp_disp - Display controller
  * @dev: Device structure
  * @dpsub: Display subsystem
+ * @blend: blender struct
  * @blend.base: Register I/O base address for the blender
+ * @avbuf: audio/video buffer manager struct
  * @avbuf.base: Register I/O base address for the audio/video buffer manager
+ * @audio: audio mixer struct
  * @audio.base: Registers I/O base address for the audio mixer
  * @layers: Layers (planes)
  */


> remind us that it needs to be fixed. I'd be tempted to keep the warning
> for that reason.
> 
>>   * @layers: Layers (planes)
>>   */
>>  struct zynqmp_disp {
> 

-- 
~Randy