linux-kernel - Re: [PATCH net-next v4 02/12] net: ethernet: oa

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] [thread-next>] [day] [month] [year] [list]

Message-ID: <9b9d0be5-fa62-402f-be10-f0a4b77ed066@microchip.com>
Date: Tue, 23 Apr 2024 04:38:26 +0000
From: <Parthiban.Veerasooran@...rochip.com>
To: <andrew@...n.ch>
CC: <davem@...emloft.net>, <edumazet@...gle.com>, <kuba@...nel.org>,
	<pabeni@...hat.com>, <horms@...nel.org>, <saeedm@...dia.com>,
	<anthony.l.nguyen@...el.com>, <netdev@...r.kernel.org>,
	<linux-kernel@...r.kernel.org>, <corbet@....net>,
	<linux-doc@...r.kernel.org>, <robh+dt@...nel.org>,
	<krzysztof.kozlowski+dt@...aro.org>, <conor+dt@...nel.org>,
	<devicetree@...r.kernel.org>, <Horatiu.Vultur@...rochip.com>,
	<ruanjinjie@...wei.com>, <Steen.Hegelund@...rochip.com>,
	<vladimir.oltean@....com>, <UNGLinuxDriver@...rochip.com>,
	<Thorsten.Kummermehr@...rochip.com>, <Pier.Beruto@...emi.com>,
	<Selvamani.Rajagopal@...emi.com>, <Nicolas.Ferre@...rochip.com>,
	<benjamin.bigler@...nformulastudent.ch>
Subject: Re: [PATCH net-next v4 02/12] net: ethernet: oa_tc6: implement
 register write operation

Hi Andrew,

On 23/04/24 5:18 am, Andrew Lunn wrote:
> EXTERNAL EMAIL: Do not click links or open attachments unless you know the content is safe
> 
>> +/**
>> + * oa_tc6_write_registers - function for writing multiple consecutive registers.
>> + * @tc6: oa_tc6 struct.
>> + * @address: address of the first register to be written in the MAC-PHY.
>> + * @value: values to be written from the starting register address @address.
>> + * @length: number of consecutive registers to be written from @address.
>> + *
>> + * Maximum of 128 consecutive registers can be written starting at @address.
>> + *
>> + * Returns 0 on success otherwise failed.
>> + */
> 
OK. In this case kernel-doc tool takes it as **Description** that's why 
didn't complaint any error when I run the below command,

$ scripts/kernel-doc -v -none drivers/net/ethernet/oa_tc6.c

drivers/net/ethernet/oa_tc6.c:313: info: Scanning doc for function 
oa_tc6_read_registers
drivers/net/ethernet/oa_tc6.c:343: info: Scanning doc for function 
oa_tc6_read_register
drivers/net/ethernet/oa_tc6.c:357: info: Scanning doc for function 
oa_tc6_write_registers
drivers/net/ethernet/oa_tc6.c:387: info: Scanning doc for function 
oa_tc6_write_register
drivers/net/ethernet/oa_tc6.c:1154: info: Scanning doc for function 
oa_tc6_start_xmit
drivers/net/ethernet/oa_tc6.c:1185: info: Scanning doc for function 
oa_tc6_init
drivers/net/ethernet/oa_tc6.c:1306: info: Scanning doc for function 
oa_tc6_exit

Got this info from below link,

https://elixir.bootlin.com/linux/latest/source/Documentation/doc-guide/kernel-doc.rst#L53

https://elixir.bootlin.com/linux/latest/source/Documentation/doc-guide/kernel-doc.rst#L81

> I think the static analyser tools are getting more picky, and what
> 'Return:' .
> 
> https://elixir.bootlin.com/linux/latest/source/Documentation/doc-guide/kernel-doc.rst#L86
> 
> All the examples use Return:
OK. Thanks for the info. I will change it and also in other APIs as well 
in the next version.

Ex:
Return: 0 on success otherwise failed.
> 
> That document also says:
> 
> The documentation format is verified by the kernel build when it is
> requested to perform extra gcc checks::
> 
>          make W=n
Unfortunately it didn't complaint anything as "Returns" line considered 
as **Description** I guess.
> 
> And if patchwork can apply your patches, it also checks for problems
> like this.
OK. If I understand this correctly the above change will resolve this.

Best regards,
Parthiban V
> 
>      Andrew