sfp-phylink.rst 9.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284
  1. .. SPDX-License-Identifier: GPL-2.0
  2. =======
  3. phylink
  4. =======
  5. Overview
  6. ========
  7. phylink is a mechanism to support hot-pluggable networking modules
  8. directly connected to a MAC without needing to re-initialise the
  9. adapter on hot-plug events.
  10. phylink supports conventional phylib-based setups, fixed link setups
  11. and SFP (Small Formfactor Pluggable) modules at present.
  12. Modes of operation
  13. ==================
  14. phylink has several modes of operation, which depend on the firmware
  15. settings.
  16. 1. PHY mode
  17. In PHY mode, we use phylib to read the current link settings from
  18. the PHY, and pass them to the MAC driver. We expect the MAC driver
  19. to configure exactly the modes that are specified without any
  20. negotiation being enabled on the link.
  21. 2. Fixed mode
  22. Fixed mode is the same as PHY mode as far as the MAC driver is
  23. concerned.
  24. 3. In-band mode
  25. In-band mode is used with 802.3z, SGMII and similar interface modes,
  26. and we are expecting to use and honor the in-band negotiation or
  27. control word sent across the serdes channel.
  28. By example, what this means is that:
  29. .. code-block:: none
  30. &eth {
  31. phy = <&phy>;
  32. phy-mode = "sgmii";
  33. };
  34. does not use in-band SGMII signalling. The PHY is expected to follow
  35. exactly the settings given to it in its :c:func:`mac_config` function.
  36. The link should be forced up or down appropriately in the
  37. :c:func:`mac_link_up` and :c:func:`mac_link_down` functions.
  38. .. code-block:: none
  39. &eth {
  40. managed = "in-band-status";
  41. phy = <&phy>;
  42. phy-mode = "sgmii";
  43. };
  44. uses in-band mode, where results from the PHY's negotiation are passed
  45. to the MAC through the SGMII control word, and the MAC is expected to
  46. acknowledge the control word. The :c:func:`mac_link_up` and
  47. :c:func:`mac_link_down` functions must not force the MAC side link
  48. up and down.
  49. Rough guide to converting a network driver to sfp/phylink
  50. =========================================================
  51. This guide briefly describes how to convert a network driver from
  52. phylib to the sfp/phylink support. Please send patches to improve
  53. this documentation.
  54. 1. Optionally split the network driver's phylib update function into
  55. two parts dealing with link-down and link-up. This can be done as
  56. a separate preparation commit.
  57. An older example of this preparation can be found in git commit
  58. fc548b991fb0, although this was splitting into three parts; the
  59. link-up part now includes configuring the MAC for the link settings.
  60. Please see :c:func:`mac_link_up` for more information on this.
  61. 2. Replace::
  62. select FIXED_PHY
  63. select PHYLIB
  64. with::
  65. select PHYLINK
  66. in the driver's Kconfig stanza.
  67. 3. Add::
  68. #include <linux/phylink.h>
  69. to the driver's list of header files.
  70. 4. Add::
  71. struct phylink *phylink;
  72. struct phylink_config phylink_config;
  73. to the driver's private data structure. We shall refer to the
  74. driver's private data pointer as ``priv`` below, and the driver's
  75. private data structure as ``struct foo_priv``.
  76. 5. Replace the following functions:
  77. .. flat-table::
  78. :header-rows: 1
  79. :widths: 1 1
  80. :stub-columns: 0
  81. * - Original function
  82. - Replacement function
  83. * - phy_start(phydev)
  84. - phylink_start(priv->phylink)
  85. * - phy_stop(phydev)
  86. - phylink_stop(priv->phylink)
  87. * - phy_mii_ioctl(phydev, ifr, cmd)
  88. - phylink_mii_ioctl(priv->phylink, ifr, cmd)
  89. * - phy_ethtool_get_wol(phydev, wol)
  90. - phylink_ethtool_get_wol(priv->phylink, wol)
  91. * - phy_ethtool_set_wol(phydev, wol)
  92. - phylink_ethtool_set_wol(priv->phylink, wol)
  93. * - phy_disconnect(phydev)
  94. - phylink_disconnect_phy(priv->phylink)
  95. Please note that some of these functions must be called under the
  96. rtnl lock, and will warn if not. This will normally be the case,
  97. except if these are called from the driver suspend/resume paths.
  98. 6. Add/replace ksettings get/set methods with:
  99. .. code-block:: c
  100. static int foo_ethtool_set_link_ksettings(struct net_device *dev,
  101. const struct ethtool_link_ksettings *cmd)
  102. {
  103. struct foo_priv *priv = netdev_priv(dev);
  104. return phylink_ethtool_ksettings_set(priv->phylink, cmd);
  105. }
  106. static int foo_ethtool_get_link_ksettings(struct net_device *dev,
  107. struct ethtool_link_ksettings *cmd)
  108. {
  109. struct foo_priv *priv = netdev_priv(dev);
  110. return phylink_ethtool_ksettings_get(priv->phylink, cmd);
  111. }
  112. 7. Replace the call to::
  113. phy_dev = of_phy_connect(dev, node, link_func, flags, phy_interface);
  114. and associated code with a call to::
  115. err = phylink_of_phy_connect(priv->phylink, node, flags);
  116. For the most part, ``flags`` can be zero; these flags are passed to
  117. the of_phy_attach() inside this function call if a PHY is specified
  118. in the DT node ``node``.
  119. ``node`` should be the DT node which contains the network phy property,
  120. fixed link properties, and will also contain the sfp property.
  121. The setup of fixed links should also be removed; these are handled
  122. internally by phylink.
  123. of_phy_connect() was also passed a function pointer for link updates.
  124. This function is replaced by a different form of MAC updates
  125. described below in (8).
  126. Manipulation of the PHY's supported/advertised happens within phylink
  127. based on the validate callback, see below in (8).
  128. Note that the driver no longer needs to store the ``phy_interface``,
  129. and also note that ``phy_interface`` becomes a dynamic property,
  130. just like the speed, duplex etc. settings.
  131. Finally, note that the MAC driver has no direct access to the PHY
  132. anymore; that is because in the phylink model, the PHY can be
  133. dynamic.
  134. 8. Add a :c:type:`struct phylink_mac_ops <phylink_mac_ops>` instance to
  135. the driver, which is a table of function pointers, and implement
  136. these functions. The old link update function for
  137. :c:func:`of_phy_connect` becomes three methods: :c:func:`mac_link_up`,
  138. :c:func:`mac_link_down`, and :c:func:`mac_config`. If step 1 was
  139. performed, then the functionality will have been split there.
  140. It is important that if in-band negotiation is used,
  141. :c:func:`mac_link_up` and :c:func:`mac_link_down` do not prevent the
  142. in-band negotiation from completing, since these functions are called
  143. when the in-band link state changes - otherwise the link will never
  144. come up.
  145. The :c:func:`validate` method should mask the supplied supported mask,
  146. and ``state->advertising`` with the supported ethtool link modes.
  147. These are the new ethtool link modes, so bitmask operations must be
  148. used. For an example, see drivers/net/ethernet/marvell/mvneta.c.
  149. The :c:func:`mac_link_state` method is used to read the link state
  150. from the MAC, and report back the settings that the MAC is currently
  151. using. This is particularly important for in-band negotiation
  152. methods such as 1000base-X and SGMII.
  153. The :c:func:`mac_link_up` method is used to inform the MAC that the
  154. link has come up. The call includes the negotiation mode and interface
  155. for reference only. The finalised link parameters are also supplied
  156. (speed, duplex and flow control/pause enablement settings) which
  157. should be used to configure the MAC when the MAC and PCS are not
  158. tightly integrated, or when the settings are not coming from in-band
  159. negotiation.
  160. The :c:func:`mac_config` method is used to update the MAC with the
  161. requested state, and must avoid unnecessarily taking the link down
  162. when making changes to the MAC configuration. This means the
  163. function should modify the state and only take the link down when
  164. absolutely necessary to change the MAC configuration. An example
  165. of how to do this can be found in :c:func:`mvneta_mac_config` in
  166. drivers/net/ethernet/marvell/mvneta.c.
  167. For further information on these methods, please see the inline
  168. documentation in :c:type:`struct phylink_mac_ops <phylink_mac_ops>`.
  169. 9. Remove calls to of_parse_phandle() for the PHY,
  170. of_phy_register_fixed_link() for fixed links etc. from the probe
  171. function, and replace with:
  172. .. code-block:: c
  173. struct phylink *phylink;
  174. priv->phylink_config.dev = &dev.dev;
  175. priv->phylink_config.type = PHYLINK_NETDEV;
  176. phylink = phylink_create(&priv->phylink_config, node, phy_mode, &phylink_ops);
  177. if (IS_ERR(phylink)) {
  178. err = PTR_ERR(phylink);
  179. fail probe;
  180. }
  181. priv->phylink = phylink;
  182. and arrange to destroy the phylink in the probe failure path as
  183. appropriate and the removal path too by calling:
  184. .. code-block:: c
  185. phylink_destroy(priv->phylink);
  186. 10. Arrange for MAC link state interrupts to be forwarded into
  187. phylink, via:
  188. .. code-block:: c
  189. phylink_mac_change(priv->phylink, link_is_up);
  190. where ``link_is_up`` is true if the link is currently up or false
  191. otherwise. If a MAC is unable to provide these interrupts, then
  192. it should set ``priv->phylink_config.pcs_poll = true;`` in step 9.
  193. 11. Verify that the driver does not call::
  194. netif_carrier_on()
  195. netif_carrier_off()
  196. as these will interfere with phylink's tracking of the link state,
  197. and cause phylink to omit calls via the :c:func:`mac_link_up` and
  198. :c:func:`mac_link_down` methods.
  199. Network drivers should call phylink_stop() and phylink_start() via their
  200. suspend/resume paths, which ensures that the appropriate
  201. :c:type:`struct phylink_mac_ops <phylink_mac_ops>` methods are called
  202. as necessary.
  203. For information describing the SFP cage in DT, please see the binding
  204. documentation in the kernel source tree
  205. ``Documentation/devicetree/bindings/net/sff,sfp.txt``