summaryrefslogtreecommitdiff
path: root/include
diff options
context:
space:
mode:
authorRussell King - ARM Linux admin <linux@armlinux.org.uk>2019-06-14 13:37:49 +0300
committerDavid S. Miller <davem@davemloft.net>2019-06-14 19:28:37 +0300
commit4add700968c7761acba88e70a0aa3f44e5ad359d (patch)
treea979fb944a5070151f5a4e2ff8ba612d8c0b9d36 /include
parent385097a3675749cbc9e97c085c0e5dfe4269ca51 (diff)
downloadlinux-4add700968c7761acba88e70a0aa3f44e5ad359d.tar.xz
net: phylink: further mac_config documentation improvements
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> Signed-off-by: David S. Miller <davem@davemloft.net>
Diffstat (limited to 'include')
-rw-r--r--include/linux/phylink.h13
1 files changed, 12 insertions, 1 deletions
diff --git a/include/linux/phylink.h b/include/linux/phylink.h
index 6411c624f63a..2d2e55dfea94 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