linux-kernel - Re: [PATCH net-next v2 1/9] net: ethernet: implement OPEN Alliance control transaction interface

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]

Date:   Thu, 26 Oct 2023 21:46:36 +0200
From:   Andrew Lunn <andrew@...n.ch>
To:     Parthiban.Veerasooran@...rochip.com
Cc:     davem@...emloft.net, edumazet@...gle.com, kuba@...nel.org,
        pabeni@...hat.com, robh+dt@...nel.org,
        krzysztof.kozlowski+dt@...aro.org, conor+dt@...nel.org,
        corbet@....net, Steen.Hegelund@...rochip.com,
        rdunlap@...radead.org, horms@...nel.org, casper.casan@...il.com,
        netdev@...r.kernel.org, devicetree@...r.kernel.org,
        linux-kernel@...r.kernel.org, linux-doc@...r.kernel.org,
        Horatiu.Vultur@...rochip.com, Woojung.Huh@...rochip.com,
        Nicolas.Ferre@...rochip.com, UNGLinuxDriver@...rochip.com,
        Thorsten.Kummermehr@...rochip.com
Subject: Re: [PATCH net-next v2 1/9] net: ethernet: implement OPEN Alliance
 control transaction interface

> Still if you feel like using "write" instead of "wnr" and "protect" 
> instead of "prote", I will change them in the next revision.

There is some value in using names from the standard, if they are
actually good names. But i guess most developers don't have a copy of
the standard by there side. 

You actually wrote in the patch:

+/* Control header */
+#define CTRL_HDR_DNC           BIT(31)         /* Data-Not-Control */
+#define CTRL_HDR_HDRB          BIT(30)         /* Received Header Bad */
+#define CTRL_HDR_WNR           BIT(29)         /* Write-Not-Read */
+#define CTRL_HDR_AID           BIT(28)         /* Address Increment Disable */
+#define CTRL_HDR_MMS           GENMASK(27, 24) /* Memory Map Selector */

The comments suggest you also don't think the names are particularly
good, otherwise you would not of added comments.

But if you instead had:

/* Control header */
#define CTRL_HDR_DATA_NOT_CTRL           BIT(31)
#define CTRL_HDR_HDR_RX_BAD              BIT(30)
#define CTRL_HDR_WRITE           	 BIT(29)
#define CTRL_HDR_ADDR_INC_DISABLE        BIT(28)
#define CTRL_HDR_MEM_MAP_SELECTOR        GENMASK(27, 24)

the names are probably sufficient that comments are not needed.  And
is should be easy for somebody to map these back to the names used in
the standard.

This also to some extent comes into the comment about coding style, a
function does one thing, is short, etc. Short functions tend to have
less indentation, meaning you can use longer names. And longer names
are more readable, making the function easier to understand, so it
does that one thing well.

    Andrew