diff mbox series

[net] net: phylink: further mac_config documentation improvements

Message ID 20190614103749.s6pahlazm4hqyurg@shell.armlinux.org.uk
State Accepted
Delegated to: David Miller
Headers show
Series [net] net: phylink: further mac_config documentation improvements | expand

Commit Message

Russell King (Oracle) June 14, 2019, 10:37 a.m. UTC 
While reviewing the DPAA2 work, it has become apparent that we need
better documentation about which members of the phylink link state
structure are valid in the mac_config call.  Improve this
documentation.

Signed-off-by: Russell King <rmk+kernel@armlinux.org.uk>
---
 include/linux/phylink.h | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

Comments

David Miller June 14, 2019, 4:28 p.m. UTC | #1 
From: Russell King - ARM Linux admin <linux@armlinux.org.uk>
Date: Fri, 14 Jun 2019 11:37:49 +0100

> While reviewing the DPAA2 work, it has become apparent that we need
> better documentation about which members of the phylink link state
> structure are valid in the mac_config call.  Improve this
> documentation.
> 
> Signed-off-by: Russell King <rmk+kernel@armlinux.org.uk>

Applied, thanks.
diff mbox series

Patch

diff --git a/include/linux/phylink.h b/include/linux/phylink.h
index 6411c624f63a..ca74f4e343c6 100644
--- a/include/linux/phylink.h
+++ b/include/linux/phylink.h
@@ -123,11 +123,20 @@  int mac_link_state(struct net_device *ndev,
  * @mode: one of %MLO_AN_FIXED, %MLO_AN_PHY, %MLO_AN_INBAND.
  * @state: a pointer to a &struct phylink_link_state.
  *
+ * Note - not all members of @state are valid.  In particular,
+ * @state->lp_advertising, @state->link, @state->an_complete are never
+ * guaranteed to be correct, and so any mac_config() implementation must
+ * never reference these fields.
+ *
  * The action performed depends on the currently selected mode:
  *
  * %MLO_AN_FIXED, %MLO_AN_PHY:
  *   Configure the specified @state->speed, @state->duplex and
- *   @state->pause (%MLO_PAUSE_TX / %MLO_PAUSE_RX) mode.
+ *   @state->pause (%MLO_PAUSE_TX / %MLO_PAUSE_RX) modes over a link
+ *   specified by @state->interface.  @state->advertising may be used,
+ *   but is not required.  Other members of @state must be ignored.
+ *
+ *   Valid state members: interface, speed, duplex, pause, advertising.
  *
  * %MLO_AN_INBAND:
  *   place the link in an inband negotiation mode (such as 802.3z
@@ -150,6 +159,8 @@  int mac_link_state(struct net_device *ndev,
  *   responsible for reading the configuration word and configuring
  *   itself accordingly.
  *
+ *   Valid state members: interface, an_enabled, pause, advertising.
+ *
  * Implementations are expected to update the MAC to reflect the
  * requested settings - i.o.w., if nothing has changed between two
  * calls, no action is expected.  If only flow control settings have