Re: [PATCH net-next v2 3/3] net: phylink: add separate pcs operations structure

[Russell King - ARM Linux admin <linux@armlinux.org.uk>]

On Sun, Mar 29, 2020 at 01:42:08PM -0700, Florian Fainelli wrote:
> 
> 
> On 3/29/2020 9:01 AM, Russell King wrote:
> > Add a separate set of PCS operations, which MAC drivers can use to
> > couple phylink with their associated MAC PCS layer.  The PCS
> > operations include:
> > 
> > - pcs_get_state() - reads the link up/down, resolved speed, duplex
> >    and pause from the PCS.
> > - pcs_config() - configures the PCS for the specified mode, PHY
> >    interface type, and setting the advertisement.
> > - pcs_an_restart() - restarts 802.3 in-band negotiation with the
> >    link partner
> > - pcs_link_up() - informs the PCS that link has come up, and the
> >    parameters of the link. Link parameters are used to program the
> >    PCS for fixed speed and non-inband modes.
> > 
> > Signed-off-by: Russell King <rmk+kernel@armlinux.org.uk>
> > ---
> 
> Although your kernel documentation is pretty comprehensive, I am fairly
> sure people are going to get confused about whether they need to
> implement pcs_an_restart vs. mac_an_restart and pcs_get_state vs.
> mac_pcs_get_state (with the possibility of a naming confusion for the
> latter). Maybe some guidelines in the comment as to which one to
> implement could save some support.

If one is making use of the PCS operations, then the PCS operations
are used in preference to the MAC operations in all cases except the
pcs_config() and pcs_link_up() methods.

This is already documented with:

 * When present, this overrides mac_pcs_get_state() in &struct
 * phylink_mac_ops.

 * When PCS ops are present, this overrides mac_an_restart() in &struct
 * phylink_mac_ops.

I'm not sure adding more words will help - in my experience, the more
words that are used, the more people nitpick and mess up.

-- 
RMK's Patch system: https://www.armlinux.org.uk/developer/patches/
FTTC broadband for 0.8mile line in suburbia: sync at 10.2Mbps down 587kbps up