phylink.h 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496
  1. #ifndef NETDEV_PCS_H
  2. #define NETDEV_PCS_H
  3. #include <linux/phy.h>
  4. #include <linux/spinlock.h>
  5. #include <linux/workqueue.h>
  6. struct device_node;
  7. struct ethtool_cmd;
  8. struct fwnode_handle;
  9. struct net_device;
  10. enum {
  11. MLO_PAUSE_NONE,
  12. MLO_PAUSE_RX = BIT(0),
  13. MLO_PAUSE_TX = BIT(1),
  14. MLO_PAUSE_TXRX_MASK = MLO_PAUSE_TX | MLO_PAUSE_RX,
  15. MLO_PAUSE_AN = BIT(2),
  16. MLO_AN_PHY = 0, /* Conventional PHY */
  17. MLO_AN_FIXED, /* Fixed-link mode */
  18. MLO_AN_INBAND, /* In-band protocol */
  19. };
  20. static inline bool phylink_autoneg_inband(unsigned int mode)
  21. {
  22. return mode == MLO_AN_INBAND;
  23. }
  24. /**
  25. * struct phylink_link_state - link state structure
  26. * @advertising: ethtool bitmask containing advertised link modes
  27. * @lp_advertising: ethtool bitmask containing link partner advertised link
  28. * modes
  29. * @interface: link &typedef phy_interface_t mode
  30. * @speed: link speed, one of the SPEED_* constants.
  31. * @duplex: link duplex mode, one of DUPLEX_* constants.
  32. * @pause: link pause state, described by MLO_PAUSE_* constants.
  33. * @link: true if the link is up.
  34. * @an_enabled: true if autonegotiation is enabled/desired.
  35. * @an_complete: true if autonegotiation has completed.
  36. */
  37. struct phylink_link_state {
  38. __ETHTOOL_DECLARE_LINK_MODE_MASK(advertising);
  39. __ETHTOOL_DECLARE_LINK_MODE_MASK(lp_advertising);
  40. phy_interface_t interface;
  41. int speed;
  42. int duplex;
  43. int pause;
  44. unsigned int link:1;
  45. unsigned int an_enabled:1;
  46. unsigned int an_complete:1;
  47. };
  48. enum phylink_op_type {
  49. PHYLINK_NETDEV = 0,
  50. PHYLINK_DEV,
  51. };
  52. /**
  53. * struct phylink_config - PHYLINK configuration structure
  54. * @dev: a pointer to a struct device associated with the MAC
  55. * @type: operation type of PHYLINK instance
  56. * @pcs_poll: MAC PCS cannot provide link change interrupt
  57. * @poll_fixed_state: if true, starts link_poll,
  58. * if MAC link is at %MLO_AN_FIXED mode.
  59. * @get_fixed_state: callback to execute to determine the fixed link state,
  60. * if MAC link is at %MLO_AN_FIXED mode.
  61. */
  62. struct phylink_config {
  63. struct device *dev;
  64. enum phylink_op_type type;
  65. bool pcs_poll;
  66. bool poll_fixed_state;
  67. void (*get_fixed_state)(struct phylink_config *config,
  68. struct phylink_link_state *state);
  69. };
  70. /**
  71. * struct phylink_mac_ops - MAC operations structure.
  72. * @validate: Validate and update the link configuration.
  73. * @mac_pcs_get_state: Read the current link state from the hardware.
  74. * @mac_prepare: prepare for a major reconfiguration of the interface.
  75. * @mac_config: configure the MAC for the selected mode and state.
  76. * @mac_finish: finish a major reconfiguration of the interface.
  77. * @mac_an_restart: restart 802.3z BaseX autonegotiation.
  78. * @mac_link_down: take the link down.
  79. * @mac_link_up: allow the link to come up.
  80. *
  81. * The individual methods are described more fully below.
  82. */
  83. struct phylink_mac_ops {
  84. void (*validate)(struct phylink_config *config,
  85. unsigned long *supported,
  86. struct phylink_link_state *state);
  87. void (*mac_pcs_get_state)(struct phylink_config *config,
  88. struct phylink_link_state *state);
  89. int (*mac_prepare)(struct phylink_config *config, unsigned int mode,
  90. phy_interface_t iface);
  91. void (*mac_config)(struct phylink_config *config, unsigned int mode,
  92. const struct phylink_link_state *state);
  93. int (*mac_finish)(struct phylink_config *config, unsigned int mode,
  94. phy_interface_t iface);
  95. void (*mac_an_restart)(struct phylink_config *config);
  96. void (*mac_link_down)(struct phylink_config *config, unsigned int mode,
  97. phy_interface_t interface);
  98. void (*mac_link_up)(struct phylink_config *config,
  99. struct phy_device *phy, unsigned int mode,
  100. phy_interface_t interface, int speed, int duplex,
  101. bool tx_pause, bool rx_pause);
  102. };
  103. #if 0 /* For kernel-doc purposes only. */
  104. /**
  105. * validate - Validate and update the link configuration
  106. * @config: a pointer to a &struct phylink_config.
  107. * @supported: ethtool bitmask for supported link modes.
  108. * @state: a pointer to a &struct phylink_link_state.
  109. *
  110. * Clear bits in the @supported and @state->advertising masks that
  111. * are not supportable by the MAC.
  112. *
  113. * Note that the PHY may be able to transform from one connection
  114. * technology to another, so, eg, don't clear 1000BaseX just
  115. * because the MAC is unable to BaseX mode. This is more about
  116. * clearing unsupported speeds and duplex settings. The port modes
  117. * should not be cleared; phylink_set_port_modes() will help with this.
  118. *
  119. * If the @state->interface mode is %PHY_INTERFACE_MODE_1000BASEX
  120. * or %PHY_INTERFACE_MODE_2500BASEX, select the appropriate mode
  121. * based on @state->advertising and/or @state->speed and update
  122. * @state->interface accordingly. See phylink_helper_basex_speed().
  123. *
  124. * When @state->interface is %PHY_INTERFACE_MODE_NA, phylink expects the
  125. * MAC driver to return all supported link modes.
  126. *
  127. * If the @state->interface mode is not supported, then the @supported
  128. * mask must be cleared.
  129. */
  130. void validate(struct phylink_config *config, unsigned long *supported,
  131. struct phylink_link_state *state);
  132. /**
  133. * mac_pcs_get_state() - Read the current inband link state from the hardware
  134. * @config: a pointer to a &struct phylink_config.
  135. * @state: a pointer to a &struct phylink_link_state.
  136. *
  137. * Read the current inband link state from the MAC PCS, reporting the
  138. * current speed in @state->speed, duplex mode in @state->duplex, pause
  139. * mode in @state->pause using the %MLO_PAUSE_RX and %MLO_PAUSE_TX bits,
  140. * negotiation completion state in @state->an_complete, and link up state
  141. * in @state->link. If possible, @state->lp_advertising should also be
  142. * populated.
  143. */
  144. void mac_pcs_get_state(struct phylink_config *config,
  145. struct phylink_link_state *state);
  146. /**
  147. * mac_prepare() - prepare to change the PHY interface mode
  148. * @config: a pointer to a &struct phylink_config.
  149. * @mode: one of %MLO_AN_FIXED, %MLO_AN_PHY, %MLO_AN_INBAND.
  150. * @iface: interface mode to switch to
  151. *
  152. * phylink will call this method at the beginning of a full initialisation
  153. * of the link, which includes changing the interface mode or at initial
  154. * startup time. It may be called for the current mode. The MAC driver
  155. * should perform whatever actions are required, e.g. disabling the
  156. * Serdes PHY.
  157. *
  158. * This will be the first call in the sequence:
  159. * - mac_prepare()
  160. * - mac_config()
  161. * - pcs_config()
  162. * - possible pcs_an_restart()
  163. * - mac_finish()
  164. *
  165. * Returns zero on success, or negative errno on failure which will be
  166. * reported to the kernel log.
  167. */
  168. int mac_prepare(struct phylink_config *config, unsigned int mode,
  169. phy_interface_t iface);
  170. /**
  171. * mac_config() - configure the MAC for the selected mode and state
  172. * @config: a pointer to a &struct phylink_config.
  173. * @mode: one of %MLO_AN_FIXED, %MLO_AN_PHY, %MLO_AN_INBAND.
  174. * @state: a pointer to a &struct phylink_link_state.
  175. *
  176. * Note - not all members of @state are valid. In particular,
  177. * @state->lp_advertising, @state->link, @state->an_complete are never
  178. * guaranteed to be correct, and so any mac_config() implementation must
  179. * never reference these fields.
  180. *
  181. * (this requires a rewrite - please refer to mac_link_up() for situations
  182. * where the PCS and MAC are not tightly integrated.)
  183. *
  184. * In all negotiation modes, as defined by @mode, @state->pause indicates the
  185. * pause settings which should be applied as follows. If %MLO_PAUSE_AN is not
  186. * set, %MLO_PAUSE_TX and %MLO_PAUSE_RX indicate whether the MAC should send
  187. * pause frames and/or act on received pause frames respectively. Otherwise,
  188. * the results of in-band negotiation/status from the MAC PCS should be used
  189. * to control the MAC pause mode settings.
  190. *
  191. * The action performed depends on the currently selected mode:
  192. *
  193. * %MLO_AN_FIXED, %MLO_AN_PHY:
  194. * Configure for non-inband negotiation mode, where the link settings
  195. * are completely communicated via mac_link_up(). The physical link
  196. * protocol from the MAC is specified by @state->interface.
  197. *
  198. * @state->advertising may be used, but is not required.
  199. *
  200. * Older drivers (prior to the mac_link_up() change) may use @state->speed,
  201. * @state->duplex and @state->pause to configure the MAC, but this is
  202. * deprecated; such drivers should be converted to use mac_link_up().
  203. *
  204. * Other members of @state must be ignored.
  205. *
  206. * Valid state members: interface, advertising.
  207. * Deprecated state members: speed, duplex, pause.
  208. *
  209. * %MLO_AN_INBAND:
  210. * place the link in an inband negotiation mode (such as 802.3z
  211. * 1000base-X or Cisco SGMII mode depending on the @state->interface
  212. * mode). In both cases, link state management (whether the link
  213. * is up or not) is performed by the MAC, and reported via the
  214. * mac_pcs_get_state() callback. Changes in link state must be made
  215. * by calling phylink_mac_change().
  216. *
  217. * Interface mode specific details are mentioned below.
  218. *
  219. * If in 802.3z mode, the link speed is fixed, dependent on the
  220. * @state->interface. Duplex and pause modes are negotiated via
  221. * the in-band configuration word. Advertised pause modes are set
  222. * according to the @state->an_enabled and @state->advertising
  223. * flags. Beware of MACs which only support full duplex at gigabit
  224. * and higher speeds.
  225. *
  226. * If in Cisco SGMII mode, the link speed and duplex mode are passed
  227. * in the serial bitstream 16-bit configuration word, and the MAC
  228. * should be configured to read these bits and acknowledge the
  229. * configuration word. Nothing is advertised by the MAC. The MAC is
  230. * responsible for reading the configuration word and configuring
  231. * itself accordingly.
  232. *
  233. * Valid state members: interface, an_enabled, pause, advertising.
  234. *
  235. * Implementations are expected to update the MAC to reflect the
  236. * requested settings - i.o.w., if nothing has changed between two
  237. * calls, no action is expected. If only flow control settings have
  238. * changed, flow control should be updated *without* taking the link
  239. * down. This "update" behaviour is critical to avoid bouncing the
  240. * link up status.
  241. */
  242. void mac_config(struct phylink_config *config, unsigned int mode,
  243. const struct phylink_link_state *state);
  244. /**
  245. * mac_finish() - finish a to change the PHY interface mode
  246. * @config: a pointer to a &struct phylink_config.
  247. * @mode: one of %MLO_AN_FIXED, %MLO_AN_PHY, %MLO_AN_INBAND.
  248. * @iface: interface mode to switch to
  249. *
  250. * phylink will call this if it called mac_prepare() to allow the MAC to
  251. * complete any necessary steps after the MAC and PCS have been configured
  252. * for the @mode and @iface. E.g. a MAC driver may wish to re-enable the
  253. * Serdes PHY here if it was previously disabled by mac_prepare().
  254. *
  255. * Returns zero on success, or negative errno on failure which will be
  256. * reported to the kernel log.
  257. */
  258. int mac_finish(struct phylink_config *config, unsigned int mode,
  259. phy_interface_t iface);
  260. /**
  261. * mac_an_restart() - restart 802.3z BaseX autonegotiation
  262. * @config: a pointer to a &struct phylink_config.
  263. */
  264. void mac_an_restart(struct phylink_config *config);
  265. /**
  266. * mac_link_down() - take the link down
  267. * @config: a pointer to a &struct phylink_config.
  268. * @mode: link autonegotiation mode
  269. * @interface: link &typedef phy_interface_t mode
  270. *
  271. * If @mode is not an in-band negotiation mode (as defined by
  272. * phylink_autoneg_inband()), force the link down and disable any
  273. * Energy Efficient Ethernet MAC configuration. Interface type
  274. * selection must be done in mac_config().
  275. */
  276. void mac_link_down(struct phylink_config *config, unsigned int mode,
  277. phy_interface_t interface);
  278. /**
  279. * mac_link_up() - allow the link to come up
  280. * @config: a pointer to a &struct phylink_config.
  281. * @phy: any attached phy
  282. * @mode: link autonegotiation mode
  283. * @interface: link &typedef phy_interface_t mode
  284. * @speed: link speed
  285. * @duplex: link duplex
  286. * @tx_pause: link transmit pause enablement status
  287. * @rx_pause: link receive pause enablement status
  288. *
  289. * Configure the MAC for an established link.
  290. *
  291. * @speed, @duplex, @tx_pause and @rx_pause indicate the finalised link
  292. * settings, and should be used to configure the MAC block appropriately
  293. * where these settings are not automatically conveyed from the PCS block,
  294. * or if in-band negotiation (as defined by phylink_autoneg_inband(@mode))
  295. * is disabled.
  296. *
  297. * Note that when 802.3z in-band negotiation is in use, it is possible
  298. * that the user wishes to override the pause settings, and this should
  299. * be allowed when considering the implementation of this method.
  300. *
  301. * If in-band negotiation mode is disabled, allow the link to come up. If
  302. * @phy is non-%NULL, configure Energy Efficient Ethernet by calling
  303. * phy_init_eee() and perform appropriate MAC configuration for EEE.
  304. * Interface type selection must be done in mac_config().
  305. */
  306. void mac_link_up(struct phylink_config *config, struct phy_device *phy,
  307. unsigned int mode, phy_interface_t interface,
  308. int speed, int duplex, bool tx_pause, bool rx_pause);
  309. #endif
  310. struct phylink_pcs_ops;
  311. /**
  312. * struct phylink_pcs - PHYLINK PCS instance
  313. * @ops: a pointer to the &struct phylink_pcs_ops structure
  314. * @poll: poll the PCS for link changes
  315. *
  316. * This structure is designed to be embedded within the PCS private data,
  317. * and will be passed between phylink and the PCS.
  318. */
  319. struct phylink_pcs {
  320. const struct phylink_pcs_ops *ops;
  321. bool poll;
  322. };
  323. /**
  324. * struct phylink_pcs_ops - MAC PCS operations structure.
  325. * @pcs_get_state: read the current MAC PCS link state from the hardware.
  326. * @pcs_config: configure the MAC PCS for the selected mode and state.
  327. * @pcs_an_restart: restart 802.3z BaseX autonegotiation.
  328. * @pcs_link_up: program the PCS for the resolved link configuration
  329. * (where necessary).
  330. */
  331. struct phylink_pcs_ops {
  332. void (*pcs_get_state)(struct phylink_pcs *pcs,
  333. struct phylink_link_state *state);
  334. int (*pcs_config)(struct phylink_pcs *pcs, unsigned int mode,
  335. phy_interface_t interface,
  336. const unsigned long *advertising,
  337. bool permit_pause_to_mac);
  338. void (*pcs_an_restart)(struct phylink_pcs *pcs);
  339. void (*pcs_link_up)(struct phylink_pcs *pcs, unsigned int mode,
  340. phy_interface_t interface, int speed, int duplex);
  341. };
  342. #if 0 /* For kernel-doc purposes only. */
  343. /**
  344. * pcs_get_state() - Read the current inband link state from the hardware
  345. * @pcs: a pointer to a &struct phylink_pcs.
  346. * @state: a pointer to a &struct phylink_link_state.
  347. *
  348. * Read the current inband link state from the MAC PCS, reporting the
  349. * current speed in @state->speed, duplex mode in @state->duplex, pause
  350. * mode in @state->pause using the %MLO_PAUSE_RX and %MLO_PAUSE_TX bits,
  351. * negotiation completion state in @state->an_complete, and link up state
  352. * in @state->link. If possible, @state->lp_advertising should also be
  353. * populated.
  354. *
  355. * When present, this overrides mac_pcs_get_state() in &struct
  356. * phylink_mac_ops.
  357. */
  358. void pcs_get_state(struct phylink_pcs *pcs,
  359. struct phylink_link_state *state);
  360. /**
  361. * pcs_config() - Configure the PCS mode and advertisement
  362. * @pcs: a pointer to a &struct phylink_pcs.
  363. * @mode: one of %MLO_AN_FIXED, %MLO_AN_PHY, %MLO_AN_INBAND.
  364. * @interface: interface mode to be used
  365. * @advertising: adertisement ethtool link mode mask
  366. * @permit_pause_to_mac: permit forwarding pause resolution to MAC
  367. *
  368. * Configure the PCS for the operating mode, the interface mode, and set
  369. * the advertisement mask. @permit_pause_to_mac indicates whether the
  370. * hardware may forward the pause mode resolution to the MAC.
  371. *
  372. * When operating in %MLO_AN_INBAND, inband should always be enabled,
  373. * otherwise inband should be disabled.
  374. *
  375. * For SGMII, there is no advertisement from the MAC side, the PCS should
  376. * be programmed to acknowledge the inband word from the PHY.
  377. *
  378. * For 1000BASE-X, the advertisement should be programmed into the PCS.
  379. *
  380. * For most 10GBASE-R, there is no advertisement.
  381. */
  382. int pcs_config(struct phylink_pcs *pcs, unsigned int mode,
  383. phy_interface_t interface, const unsigned long *advertising,
  384. bool permit_pause_to_mac);
  385. /**
  386. * pcs_an_restart() - restart 802.3z BaseX autonegotiation
  387. * @pcs: a pointer to a &struct phylink_pcs.
  388. *
  389. * When PCS ops are present, this overrides mac_an_restart() in &struct
  390. * phylink_mac_ops.
  391. */
  392. void pcs_an_restart(struct phylink_pcs *pcs);
  393. /**
  394. * pcs_link_up() - program the PCS for the resolved link configuration
  395. * @pcs: a pointer to a &struct phylink_pcs.
  396. * @mode: link autonegotiation mode
  397. * @interface: link &typedef phy_interface_t mode
  398. * @speed: link speed
  399. * @duplex: link duplex
  400. *
  401. * This call will be made just before mac_link_up() to inform the PCS of
  402. * the resolved link parameters. For example, a PCS operating in SGMII
  403. * mode without in-band AN needs to be manually configured for the link
  404. * and duplex setting. Otherwise, this should be a no-op.
  405. */
  406. void pcs_link_up(struct phylink_pcs *pcs, unsigned int mode,
  407. phy_interface_t interface, int speed, int duplex);
  408. #endif
  409. struct phylink *phylink_create(struct phylink_config *, struct fwnode_handle *,
  410. phy_interface_t iface,
  411. const struct phylink_mac_ops *mac_ops);
  412. void phylink_set_pcs(struct phylink *, struct phylink_pcs *pcs);
  413. void phylink_destroy(struct phylink *);
  414. int phylink_connect_phy(struct phylink *, struct phy_device *);
  415. int phylink_of_phy_connect(struct phylink *, struct device_node *, u32 flags);
  416. void phylink_disconnect_phy(struct phylink *);
  417. void phylink_mac_change(struct phylink *, bool up);
  418. void phylink_start(struct phylink *);
  419. void phylink_stop(struct phylink *);
  420. void phylink_ethtool_get_wol(struct phylink *, struct ethtool_wolinfo *);
  421. int phylink_ethtool_set_wol(struct phylink *, struct ethtool_wolinfo *);
  422. int phylink_ethtool_ksettings_get(struct phylink *,
  423. struct ethtool_link_ksettings *);
  424. int phylink_ethtool_ksettings_set(struct phylink *,
  425. const struct ethtool_link_ksettings *);
  426. int phylink_ethtool_nway_reset(struct phylink *);
  427. void phylink_ethtool_get_pauseparam(struct phylink *,
  428. struct ethtool_pauseparam *);
  429. int phylink_ethtool_set_pauseparam(struct phylink *,
  430. struct ethtool_pauseparam *);
  431. int phylink_get_eee_err(struct phylink *);
  432. int phylink_init_eee(struct phylink *, bool);
  433. int phylink_ethtool_get_eee(struct phylink *, struct ethtool_eee *);
  434. int phylink_ethtool_set_eee(struct phylink *, struct ethtool_eee *);
  435. int phylink_mii_ioctl(struct phylink *, struct ifreq *, int);
  436. int phylink_speed_down(struct phylink *pl, bool sync);
  437. int phylink_speed_up(struct phylink *pl);
  438. #define phylink_zero(bm) \
  439. bitmap_zero(bm, __ETHTOOL_LINK_MODE_MASK_NBITS)
  440. #define __phylink_do_bit(op, bm, mode) \
  441. op(ETHTOOL_LINK_MODE_ ## mode ## _BIT, bm)
  442. #define phylink_set(bm, mode) __phylink_do_bit(__set_bit, bm, mode)
  443. #define phylink_clear(bm, mode) __phylink_do_bit(__clear_bit, bm, mode)
  444. #define phylink_test(bm, mode) __phylink_do_bit(test_bit, bm, mode)
  445. void phylink_set_port_modes(unsigned long *bits);
  446. void phylink_helper_basex_speed(struct phylink_link_state *state);
  447. void phylink_mii_c22_pcs_get_state(struct mdio_device *pcs,
  448. struct phylink_link_state *state);
  449. int phylink_mii_c22_pcs_set_advertisement(struct mdio_device *pcs,
  450. phy_interface_t interface,
  451. const unsigned long *advertising);
  452. int phylink_mii_c22_pcs_config(struct mdio_device *pcs, unsigned int mode,
  453. phy_interface_t interface,
  454. const unsigned long *advertising);
  455. void phylink_mii_c22_pcs_an_restart(struct mdio_device *pcs);
  456. void phylink_mii_c45_pcs_get_state(struct mdio_device *pcs,
  457. struct phylink_link_state *state);
  458. void phylink_decode_usxgmii_word(struct phylink_link_state *state,
  459. uint16_t lpa);
  460. #endif