Re: [PATCH net-next 06/10] docs: net: refresh netdev feature guidance

[Jakub Kicinski <kuba@kernel.org>]

On Tue, 26 May 2026 20:41:10 +0200 Maxime Chevallier wrote:
> >   
> >    1. netdev->hw_features set contains features whose state may possibly
> >       be changed (enabled or disabled) for a particular device by user's
> > -    request.  This set should be initialized in ndo_init callback and not
> > -    changed later.
> > +    request.  Drivers normally initialize this set before registration or
> > +    in the ndo_init callback. Changes after registration should be made
> > +    very carefully as other parts of the code may assume hw_features are
> > +    static. At the very least changes must be made under rtnl_lock and
> > +    the netdev instance lock, and followed by netdev_update_features().  
> Feel free to keep this description as-is, but can we get somewhere the
> actual meaning of "hw" in "hw_features" ? I've seen this cause confusion
> before as this is sometimes wrongly interpreted as "Hardware features",
> which isn't correct as the hardware may do stuff without allowing users
> to change that behaviour.
> 
> I vaguely recall something along the lines of "Host-Writeable features",
> but I am not sure at all about that...

Hm. I assumed the hw in hw_features stands for hardware.
The magic behavior of host controllable vs hardwired was
probably added later without renaming the field.

As you indicate the usual confusion is that it's legal to have 
a feature in ->features which is not set in ->hw_features which 
means that features is hardwired "on", it can't be disabled by
the user.

The current text does say this: "features whose state may [..]
be changed [..] by user's request". But perhaps it's not emphatic
enough.

Main question is whether this series should be clarifying
this or our criteria is that the series doesn't _add_ confusion,
even if it doesn't clarify all the potential confusion points? :)