Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux

net: phy: Document core PHY structures

Add kerneldoc for the core PHY data structures, a few inline functions
and exported functions which are not already documented.

v2
Typos
g/phy/PHY/s

Signed-off-by: Andrew Lunn <andrew@lunn.ch>
Signed-off-by: David S. Miller <davem@davemloft.net>

authored by

Andrew Lunn and committed by
David S. Miller
4069a572 39097ab6

+400 -133
+9
Documentation/networking/kapi.rst
··· 134 134 .. kernel-doc:: drivers/net/phy/phy.c 135 135 :internal: 136 136 137 + .. kernel-doc:: drivers/net/phy/phy-core.c 138 + :export: 139 + 140 + .. kernel-doc:: drivers/net/phy/phy-c45.c 141 + :export: 142 + 143 + .. kernel-doc:: include/linux/phy.h 144 + :internal: 145 + 137 146 .. kernel-doc:: drivers/net/phy/phy_device.c 138 147 :export: 139 148
+31 -1
drivers/net/phy/phy-core.c
··· 6 6 #include <linux/phy.h> 7 7 #include <linux/of.h> 8 8 9 + /** 10 + * phy_speed_to_str - Return a string representing the PHY link speed 11 + * 12 + * @speed: Speed of the link 13 + */ 9 14 const char *phy_speed_to_str(int speed) 10 15 { 11 16 BUILD_BUG_ON_MSG(__ETHTOOL_LINK_MODE_MASK_NBITS != 92, ··· 57 52 } 58 53 EXPORT_SYMBOL_GPL(phy_speed_to_str); 59 54 55 + /** 56 + * phy_duplex_to_str - Return string describing the duplex 57 + * 58 + * @duplex: Duplex setting to describe 59 + */ 60 60 const char *phy_duplex_to_str(unsigned int duplex) 61 61 { 62 62 if (duplex == DUPLEX_HALF) ··· 262 252 return __set_linkmode_max_speed(max_speed, phydev->supported); 263 253 } 264 254 255 + /** 256 + * phy_set_max_speed - Set the maximum speed the PHY should support 257 + * 258 + * @phydev: The phy_device struct 259 + * @max_speed: Maximum speed 260 + * 261 + * The PHY might be more capable than the MAC. For example a Fast Ethernet 262 + * is connected to a 1G PHY. This function allows the MAC to indicate its 263 + * maximum speed, and so limit what the PHY will advertise. 264 + */ 265 265 int phy_set_max_speed(struct phy_device *phydev, u32 max_speed) 266 266 { 267 267 int err; ··· 328 308 phydev->eee_broken_modes = broken; 329 309 } 330 310 311 + /** 312 + * phy_resolve_aneg_pause - Determine pause autoneg results 313 + * 314 + * @phydev: The phy_device struct 315 + * 316 + * Once autoneg has completed the local pause settings can be 317 + * resolved. Determine if pause and asymmetric pause should be used 318 + * by the MAC. 319 + */ 320 + 331 321 void phy_resolve_aneg_pause(struct phy_device *phydev) 332 322 { 333 323 if (phydev->duplex == DUPLEX_FULL) { ··· 351 321 EXPORT_SYMBOL_GPL(phy_resolve_aneg_pause); 352 322 353 323 /** 354 - * phy_resolve_aneg_linkmode - resolve the advertisements into phy settings 324 + * phy_resolve_aneg_linkmode - resolve the advertisements into PHY settings 355 325 * @phydev: The phy_device struct 356 326 * 357 327 * Resolve our and the link partner advertisements into their corresponding
+68 -1
drivers/net/phy/phy.c
··· 456 456 } 457 457 EXPORT_SYMBOL(phy_do_ioctl); 458 458 459 - /* same as phy_do_ioctl, but ensures that net_device is running */ 459 + /** 460 + * phy_do_ioctl_running - generic ndo_do_ioctl implementation but test first 461 + * 462 + * @dev: the net_device struct 463 + * @ifr: &struct ifreq for socket ioctl's 464 + * @cmd: ioctl cmd to execute 465 + * 466 + * Same as phy_do_ioctl, but ensures that net_device is running before 467 + * handling the ioctl. 468 + */ 460 469 int phy_do_ioctl_running(struct net_device *dev, struct ifreq *ifr, int cmd) 461 470 { 462 471 if (!netif_running(dev)) ··· 475 466 } 476 467 EXPORT_SYMBOL(phy_do_ioctl_running); 477 468 469 + /** 470 + * phy_queue_state_machine - Trigger the state machine to run soon 471 + * 472 + * @phydev: the phy_device struct 473 + * @jiffies: Run the state machine after these jiffies 474 + */ 478 475 void phy_queue_state_machine(struct phy_device *phydev, unsigned long jiffies) 479 476 { 480 477 mod_delayed_work(system_power_efficient_wq, &phydev->state_queue, ··· 488 473 } 489 474 EXPORT_SYMBOL(phy_queue_state_machine); 490 475 476 + /** 477 + * phy_queue_state_machine - Trigger the state machine to run now 478 + * 479 + * @phydev: the phy_device struct 480 + */ 491 481 static void phy_trigger_machine(struct phy_device *phydev) 492 482 { 493 483 phy_queue_state_machine(phydev, 0); ··· 509 489 phydev_err(phydev, "Error while aborting cable test"); 510 490 } 511 491 492 + /** 493 + * phy_ethtool_get_strings - Get the statistic counter names 494 + * 495 + * @phydev: the phy_device struct 496 + * @data: Where to put the strings 497 + */ 512 498 int phy_ethtool_get_strings(struct phy_device *phydev, u8 *data) 513 499 { 514 500 if (!phydev->drv) ··· 528 502 } 529 503 EXPORT_SYMBOL(phy_ethtool_get_strings); 530 504 505 + /** 506 + * phy_ethtool_get_sset_count - Get the number of statistic counters 507 + * 508 + * @phydev: the phy_device struct 509 + */ 531 510 int phy_ethtool_get_sset_count(struct phy_device *phydev) 532 511 { 533 512 int ret; ··· 554 523 } 555 524 EXPORT_SYMBOL(phy_ethtool_get_sset_count); 556 525 526 + /** 527 + * phy_ethtool_get_stats - Get the statistic counters 528 + * 529 + * @phydev: the phy_device struct 530 + * @stats: What counters to get 531 + * @data: Where to store the counters 532 + */ 557 533 int phy_ethtool_get_stats(struct phy_device *phydev, 558 534 struct ethtool_stats *stats, u64 *data) 559 535 { ··· 575 537 } 576 538 EXPORT_SYMBOL(phy_ethtool_get_stats); 577 539 540 + /** 541 + * phy_start_cable_test - Start a cable test 542 + * 543 + * @phydev: the phy_device struct 544 + * @extack: extack for reporting useful error messages 545 + */ 578 546 int phy_start_cable_test(struct phy_device *phydev, 579 547 struct netlink_ext_ack *extack) 580 548 { ··· 644 600 } 645 601 EXPORT_SYMBOL(phy_start_cable_test); 646 602 603 + /** 604 + * phy_start_cable_test_tdr - Start a raw TDR cable test 605 + * 606 + * @phydev: the phy_device struct 607 + * @extack: extack for reporting useful error messages 608 + * @config: Configuration of the test to run 609 + */ 647 610 int phy_start_cable_test_tdr(struct phy_device *phydev, 648 611 struct netlink_ext_ack *extack, 649 612 const struct phy_tdr_config *config) ··· 1414 1363 } 1415 1364 EXPORT_SYMBOL(phy_ethtool_set_eee); 1416 1365 1366 + /** 1367 + * phy_ethtool_set_wol - Configure Wake On LAN 1368 + * 1369 + * @phydev: target phy_device struct 1370 + * @wol: Configuration requested 1371 + */ 1417 1372 int phy_ethtool_set_wol(struct phy_device *phydev, struct ethtool_wolinfo *wol) 1418 1373 { 1419 1374 if (phydev->drv && phydev->drv->set_wol) ··· 1429 1372 } 1430 1373 EXPORT_SYMBOL(phy_ethtool_set_wol); 1431 1374 1375 + /** 1376 + * phy_ethtool_get_wol - Get the current Wake On LAN configuration 1377 + * 1378 + * @phydev: target phy_device struct 1379 + * @wol: Store the current configuration here 1380 + */ 1432 1381 void phy_ethtool_get_wol(struct phy_device *phydev, struct ethtool_wolinfo *wol) 1433 1382 { 1434 1383 if (phydev->drv && phydev->drv->get_wol) ··· 1468 1405 } 1469 1406 EXPORT_SYMBOL(phy_ethtool_set_link_ksettings); 1470 1407 1408 + /** 1409 + * phy_ethtool_nway_reset - Restart auto negotiation 1410 + * @ndev: Network device to restart autoneg for 1411 + */ 1471 1412 int phy_ethtool_nway_reset(struct net_device *ndev) 1472 1413 { 1473 1414 struct phy_device *phydev = ndev->phydev;
+292 -131
include/linux/phy.h
··· 82 82 #define PHY_POLL_CABLE_TEST 0x00000004 83 83 #define MDIO_DEVICE_IS_PHY 0x80000000 84 84 85 - /* Interface Mode definitions */ 85 + /** 86 + * enum phy_interface_t - Interface Mode definitions 87 + * 88 + * @PHY_INTERFACE_MODE_NA: Not Applicable - don't touch 89 + * @PHY_INTERFACE_MODE_INTERNAL: No interface, MAC and PHY combined 90 + * @PHY_INTERFACE_MODE_MII: Median-independent interface 91 + * @PHY_INTERFACE_MODE_GMII: Gigabit median-independent interface 92 + * @PHY_INTERFACE_MODE_SGMII: Serial gigabit media-independent interface 93 + * @PHY_INTERFACE_MODE_TBI: Ten Bit Interface 94 + * @PHY_INTERFACE_MODE_REVMII: Reverse Media Independent Interface 95 + * @PHY_INTERFACE_MODE_RMII: Reduced Media Independent Interface 96 + * @PHY_INTERFACE_MODE_RGMII: Reduced gigabit media-independent interface 97 + * @PHY_INTERFACE_MODE_RGMII_ID: RGMII with Internal RX+TX delay 98 + * @PHY_INTERFACE_MODE_RGMII_RXID: RGMII with Internal RX delay 99 + * @PHY_INTERFACE_MODE_RGMII_TXID: RGMII with Internal RX delay 100 + * @PHY_INTERFACE_MODE_RTBI: Reduced TBI 101 + * @PHY_INTERFACE_MODE_SMII: ??? MII 102 + * @PHY_INTERFACE_MODE_XGMII: 10 gigabit media-independent interface 103 + * @PHY_INTERFACE_MODE_XLGMII:40 gigabit media-independent interface 104 + * @PHY_INTERFACE_MODE_MOCA: Multimedia over Coax 105 + * @PHY_INTERFACE_MODE_QSGMII: Quad SGMII 106 + * @PHY_INTERFACE_MODE_TRGMII: Turbo RGMII 107 + * @PHY_INTERFACE_MODE_1000BASEX: 1000 BaseX 108 + * @PHY_INTERFACE_MODE_2500BASEX: 2500 BaseX 109 + * @PHY_INTERFACE_MODE_RXAUI: Reduced XAUI 110 + * @PHY_INTERFACE_MODE_XAUI: 10 Gigabit Attachment Unit Interface 111 + * @PHY_INTERFACE_MODE_10GBASER: 10G BaseR 112 + * @PHY_INTERFACE_MODE_USXGMII: Universal Serial 10GE MII 113 + * @PHY_INTERFACE_MODE_10GKR: 10GBASE-KR - with Clause 73 AN 114 + * @PHY_INTERFACE_MODE_MAX: Book keeping 115 + * 116 + * Describes the interface between the MAC and PHY. 117 + */ 86 118 typedef enum { 87 119 PHY_INTERFACE_MODE_NA, 88 120 PHY_INTERFACE_MODE_INTERNAL, ··· 148 116 } phy_interface_t; 149 117 150 118 /** 151 - * phy_supported_speeds - return all speeds currently supported by a phy device 152 - * @phy: The phy device to return supported speeds of. 119 + * phy_supported_speeds - return all speeds currently supported by a PHY device 120 + * @phy: The PHY device to return supported speeds of. 153 121 * @speeds: buffer to store supported speeds in. 154 122 * @size: size of speeds buffer. 155 123 * ··· 166 134 * phy_modes - map phy_interface_t enum to device tree binding of phy-mode 167 135 * @interface: enum phy_interface_t value 168 136 * 169 - * Description: maps 'enum phy_interface_t' defined in this file 137 + * Description: maps enum &phy_interface_t defined in this file 170 138 * into the device tree binding of 'phy-mode', so that Ethernet 171 - * device driver can get phy interface from device tree. 139 + * device driver can get PHY interface from device tree. 172 140 */ 173 141 static inline const char *phy_modes(phy_interface_t interface) 174 142 { ··· 247 215 struct sfp_upstream_ops; 248 216 struct sk_buff; 249 217 218 + /** 219 + * struct mdio_bus_stats - Statistics counters for MDIO busses 220 + * @transfers: Total number of transfers, i.e. @writes + @reads 221 + * @errors: Number of MDIO transfers that returned an error 222 + * @writes: Number of write transfers 223 + * @reads: Number of read transfers 224 + * @syncp: Synchronisation for incrementing statistics 225 + */ 250 226 struct mdio_bus_stats { 251 227 u64_stats_t transfers; 252 228 u64_stats_t errors; ··· 264 224 struct u64_stats_sync syncp; 265 225 }; 266 226 267 - /* Represents a shared structure between different phydev's in the same 227 + /** 228 + * struct phy_package_shared - Shared information in PHY packages 229 + * @addr: Common PHY address used to combine PHYs in one package 230 + * @refcnt: Number of PHYs connected to this shared data 231 + * @flags: Initialization of PHY package 232 + * @priv_size: Size of the shared private data @priv 233 + * @priv: Driver private data shared across a PHY package 234 + * 235 + * Represents a shared structure between different phydev's in the same 268 236 * package, for example a quad PHY. See phy_package_join() and 269 237 * phy_package_leave(). 270 238 */ ··· 295 247 #define PHY_SHARED_F_INIT_DONE 0 296 248 #define PHY_SHARED_F_PROBE_DONE 1 297 249 298 - /* 250 + /** 251 + * struct mii_bus - Represents an MDIO bus 252 + * 253 + * @owner: Who owns this device 254 + * @name: User friendly name for this MDIO device, or driver name 255 + * @id: Unique identifier for this bus, typical from bus hierarchy 256 + * @priv: Driver private data 257 + * 299 258 * The Bus class for PHYs. Devices which provide access to 300 259 * PHYs should register using this structure 301 260 */ ··· 311 256 const char *name; 312 257 char id[MII_BUS_ID_SIZE]; 313 258 void *priv; 259 + /** @read: Perform a read transfer on the bus */ 314 260 int (*read)(struct mii_bus *bus, int addr, int regnum); 261 + /** @write: Perform a write transfer on the bus */ 315 262 int (*write)(struct mii_bus *bus, int addr, int regnum, u16 val); 263 + /** @reset: Perform a reset of the bus */ 316 264 int (*reset)(struct mii_bus *bus); 265 + 266 + /** @stats: Statistic counters per device on the bus */ 317 267 struct mdio_bus_stats stats[PHY_MAX_ADDR]; 318 268 319 - /* 320 - * A lock to ensure that only one thing can read/write 269 + /** 270 + * @mdio_lock: A lock to ensure that only one thing can read/write 321 271 * the MDIO bus at a time 322 272 */ 323 273 struct mutex mdio_lock; 324 274 275 + /** @parent: Parent device of this bus */ 325 276 struct device *parent; 277 + /** @state: State of bus structure */ 326 278 enum { 327 279 MDIOBUS_ALLOCATED = 1, 328 280 MDIOBUS_REGISTERED, 329 281 MDIOBUS_UNREGISTERED, 330 282 MDIOBUS_RELEASED, 331 283 } state; 284 + 285 + /** @dev: Kernel device representation */ 332 286 struct device dev; 333 287 334 - /* list of all PHYs on bus */ 288 + /** @mdio_map: list of all MDIO devices on bus */ 335 289 struct mdio_device *mdio_map[PHY_MAX_ADDR]; 336 290 337 - /* PHY addresses to be ignored when probing */ 291 + /** @phy_mask: PHY addresses to be ignored when probing */ 338 292 u32 phy_mask; 339 293 340 - /* PHY addresses to ignore the TA/read failure */ 294 + /** @phy_ignore_ta_mask: PHY addresses to ignore the TA/read failure */ 341 295 u32 phy_ignore_ta_mask; 342 296 343 - /* 344 - * An array of interrupts, each PHY's interrupt at the index 297 + /** 298 + * @irq: An array of interrupts, each PHY's interrupt at the index 345 299 * matching its address 346 300 */ 347 301 int irq[PHY_MAX_ADDR]; 348 302 349 - /* GPIO reset pulse width in microseconds */ 303 + /** @reset_delay_us: GPIO reset pulse width in microseconds */ 350 304 int reset_delay_us; 351 - /* GPIO reset deassert delay in microseconds */ 305 + /** @reset_post_delay_us: GPIO reset deassert delay in microseconds */ 352 306 int reset_post_delay_us; 353 - /* RESET GPIO descriptor pointer */ 307 + /** @reset_gpiod: Reset GPIO descriptor pointer */ 354 308 struct gpio_desc *reset_gpiod; 355 309 356 - /* bus capabilities, used for probing */ 310 + /** @probe_capabilities: bus capabilities, used for probing */ 357 311 enum { 358 312 MDIOBUS_NO_CAP = 0, 359 313 MDIOBUS_C22, ··· 370 306 MDIOBUS_C22_C45, 371 307 } probe_capabilities; 372 308 373 - /* protect access to the shared element */ 309 + /** @shared_lock: protect access to the shared element */ 374 310 struct mutex shared_lock; 375 311 376 - /* shared state across different PHYs */ 312 + /** @shared: shared state across different PHYs */ 377 313 struct phy_package_shared *shared[PHY_MAX_ADDR]; 378 314 }; 379 315 #define to_mii_bus(d) container_of(d, struct mii_bus, dev) 380 316 381 - struct mii_bus *mdiobus_alloc_size(size_t); 317 + struct mii_bus *mdiobus_alloc_size(size_t size); 318 + 319 + /** 320 + * mdiobus_alloc - Allocate an MDIO bus structure 321 + * 322 + * The internal state of the MDIO bus will be set of MDIOBUS_ALLOCATED ready 323 + * for the driver to register the bus. 324 + */ 382 325 static inline struct mii_bus *mdiobus_alloc(void) 383 326 { 384 327 return mdiobus_alloc_size(0); ··· 412 341 #define PHY_INTERRUPT_DISABLED false 413 342 #define PHY_INTERRUPT_ENABLED true 414 343 415 - /* PHY state machine states: 344 + /** 345 + * enum phy_state - PHY state machine states: 416 346 * 417 - * DOWN: PHY device and driver are not ready for anything. probe 347 + * @PHY_DOWN: PHY device and driver are not ready for anything. probe 418 348 * should be called if and only if the PHY is in this state, 419 349 * given that the PHY device exists. 420 - * - PHY driver probe function will set the state to READY 350 + * - PHY driver probe function will set the state to @PHY_READY 421 351 * 422 - * READY: PHY is ready to send and receive packets, but the 352 + * @PHY_READY: PHY is ready to send and receive packets, but the 423 353 * controller is not. By default, PHYs which do not implement 424 354 * probe will be set to this state by phy_probe(). 425 355 * - start will set the state to UP 426 356 * 427 - * UP: The PHY and attached device are ready to do work. 357 + * @PHY_UP: The PHY and attached device are ready to do work. 428 358 * Interrupts should be started here. 429 - * - timer moves to NOLINK or RUNNING 359 + * - timer moves to @PHY_NOLINK or @PHY_RUNNING 430 360 * 431 - * NOLINK: PHY is up, but not currently plugged in. 432 - * - irq or timer will set RUNNING if link comes back 433 - * - phy_stop moves to HALTED 361 + * @PHY_NOLINK: PHY is up, but not currently plugged in. 362 + * - irq or timer will set @PHY_RUNNING if link comes back 363 + * - phy_stop moves to @PHY_HALTED 434 364 * 435 - * RUNNING: PHY is currently up, running, and possibly sending 365 + * @PHY_RUNNING: PHY is currently up, running, and possibly sending 436 366 * and/or receiving packets 437 - * - irq or timer will set NOLINK if link goes down 438 - * - phy_stop moves to HALTED 367 + * - irq or timer will set @PHY_NOLINK if link goes down 368 + * - phy_stop moves to @PHY_HALTED 439 369 * 440 - * CABLETEST: PHY is performing a cable test. Packet reception/sending 370 + * @PHY_CABLETEST: PHY is performing a cable test. Packet reception/sending 441 371 * is not expected to work, carrier will be indicated as down. PHY will be 442 372 * poll once per second, or on interrupt for it current state. 443 373 * Once complete, move to UP to restart the PHY. 444 - * - phy_stop aborts the running test and moves to HALTED 374 + * - phy_stop aborts the running test and moves to @PHY_HALTED 445 375 * 446 - * HALTED: PHY is up, but no polling or interrupts are done. Or 376 + * @PHY_HALTED: PHY is up, but no polling or interrupts are done. Or 447 377 * PHY is in an error state. 448 - * - phy_start moves to UP 378 + * - phy_start moves to @PHY_UP 449 379 */ 450 380 enum phy_state { 451 381 PHY_DOWN = 0, ··· 475 403 struct macsec_context; 476 404 struct macsec_ops; 477 405 478 - /* phy_device: An instance of a PHY 406 + /** 407 + * struct phy_device - An instance of a PHY 479 408 * 480 - * drv: Pointer to the driver for this PHY instance 481 - * phy_id: UID for this device found during discovery 482 - * c45_ids: 802.3-c45 Device Identifers if is_c45. 483 - * is_c45: Set to true if this phy uses clause 45 addressing. 484 - * is_internal: Set to true if this phy is internal to a MAC. 485 - * is_pseudo_fixed_link: Set to true if this phy is an Ethernet switch, etc. 486 - * is_gigabit_capable: Set to true if PHY supports 1000Mbps 487 - * has_fixups: Set to true if this phy has fixups/quirks. 488 - * suspended: Set to true if this phy has been suspended successfully. 489 - * suspended_by_mdio_bus: Set to true if this phy was suspended by MDIO bus. 490 - * sysfs_links: Internal boolean tracking sysfs symbolic links setup/removal. 491 - * loopback_enabled: Set true if this phy has been loopbacked successfully. 492 - * downshifted_rate: Set true if link speed has been downshifted. 493 - * state: state of the PHY for management purposes 494 - * dev_flags: Device-specific flags used by the PHY driver. 495 - * irq: IRQ number of the PHY's interrupt (-1 if none) 496 - * phy_timer: The timer for handling the state machine 497 - * sfp_bus_attached: flag indicating whether the SFP bus has been attached 498 - * sfp_bus: SFP bus attached to this PHY's fiber port 499 - * attached_dev: The attached enet driver's device instance ptr 500 - * adjust_link: Callback for the enet controller to respond to 501 - * changes in the link state. 502 - * macsec_ops: MACsec offloading ops. 409 + * @mdio: MDIO bus this PHY is on 410 + * @drv: Pointer to the driver for this PHY instance 411 + * @phy_id: UID for this device found during discovery 412 + * @c45_ids: 802.3-c45 Device Identifiers if is_c45. 413 + * @is_c45: Set to true if this PHY uses clause 45 addressing. 414 + * @is_internal: Set to true if this PHY is internal to a MAC. 415 + * @is_pseudo_fixed_link: Set to true if this PHY is an Ethernet switch, etc. 416 + * @is_gigabit_capable: Set to true if PHY supports 1000Mbps 417 + * @has_fixups: Set to true if this PHY has fixups/quirks. 418 + * @suspended: Set to true if this PHY has been suspended successfully. 419 + * @suspended_by_mdio_bus: Set to true if this PHY was suspended by MDIO bus. 420 + * @sysfs_links: Internal boolean tracking sysfs symbolic links setup/removal. 421 + * @loopback_enabled: Set true if this PHY has been loopbacked successfully. 422 + * @downshifted_rate: Set true if link speed has been downshifted. 423 + * @state: State of the PHY for management purposes 424 + * @dev_flags: Device-specific flags used by the PHY driver. 425 + * @irq: IRQ number of the PHY's interrupt (-1 if none) 426 + * @phy_timer: The timer for handling the state machine 427 + * @phylink: Pointer to phylink instance for this PHY 428 + * @sfp_bus_attached: Flag indicating whether the SFP bus has been attached 429 + * @sfp_bus: SFP bus attached to this PHY's fiber port 430 + * @attached_dev: The attached enet driver's device instance ptr 431 + * @adjust_link: Callback for the enet controller to respond to changes: in the 432 + * link state. 433 + * @phy_link_change: Callback for phylink for notification of link change 434 + * @macsec_ops: MACsec offloading ops. 503 435 * 504 - * speed, duplex, pause, supported, advertising, lp_advertising, 505 - * and autoneg are used like in mii_if_info 436 + * @speed: Current link speed 437 + * @duplex: Current duplex 438 + * @pause: Current pause 439 + * @asym_pause: Current asymmetric pause 440 + * @supported: Combined MAC/PHY supported linkmodes 441 + * @advertising: Currently advertised linkmodes 442 + * @adv_old: Saved advertised while power saving for WoL 443 + * @lp_advertising: Current link partner advertised linkmodes 444 + * @eee_broken_modes: Energy efficient ethernet modes which should be prohibited 445 + * @autoneg: Flag autoneg being used 446 + * @link: Current link state 447 + * @autoneg_complete: Flag auto negotiation of the link has completed 448 + * @mdix: Current crossover 449 + * @mdix_ctrl: User setting of crossover 450 + * @interrupts: Flag interrupts have been enabled 451 + * @interface: enum phy_interface_t value 452 + * @skb: Netlink message for cable diagnostics 453 + * @nest: Netlink nest used for cable diagnostics 454 + * @ehdr: nNtlink header for cable diagnostics 455 + * @phy_led_triggers: Array of LED triggers 456 + * @phy_num_led_triggers: Number of triggers in @phy_led_triggers 457 + * @led_link_trigger: LED trigger for link up/down 458 + * @last_triggered: last LED trigger for link speed 459 + * @master_slave_set: User requested master/slave configuration 460 + * @master_slave_get: Current master/slave advertisement 461 + * @master_slave_state: Current master/slave configuration 462 + * @mii_ts: Pointer to time stamper callbacks 463 + * @lock: Mutex for serialization access to PHY 464 + * @state_queue: Work queue for state machine 465 + * @shared: Pointer to private data shared by phys in one package 466 + * @priv: Pointer to driver private data 506 467 * 507 468 * interrupts currently only supports enabled or disabled, 508 469 * but could be changed in the future to support enabling ··· 655 550 #define to_phy_device(d) container_of(to_mdio_device(d), \ 656 551 struct phy_device, mdio) 657 552 658 - /* A structure containing possible configuration parameters 553 + /** 554 + * struct phy_tdr_config - Configuration of a TDR raw test 555 + * 556 + * @first: Distance for first data collection point 557 + * @last: Distance for last data collection point 558 + * @step: Step between data collection points 559 + * @pair: Bitmap of cable pairs to collect data for 560 + * 561 + * A structure containing possible configuration parameters 659 562 * for a TDR cable test. The driver does not need to implement 660 563 * all the parameters, but should report what is actually used. 564 + * All distances are in centimeters. 661 565 */ 662 566 struct phy_tdr_config { 663 567 u32 first; ··· 676 562 }; 677 563 #define PHY_PAIR_ALL -1 678 564 679 - /* struct phy_driver: Driver structure for a particular PHY type 565 + /** 566 + * struct phy_driver - Driver structure for a particular PHY type 680 567 * 681 - * driver_data: static driver data 682 - * phy_id: The result of reading the UID registers of this PHY 568 + * @mdiodrv: Data common to all MDIO devices 569 + * @phy_id: The result of reading the UID registers of this PHY 683 570 * type, and ANDing them with the phy_id_mask. This driver 684 571 * only works for PHYs with IDs which match this field 685 - * name: The friendly name of this PHY type 686 - * phy_id_mask: Defines the important bits of the phy_id 687 - * features: A mandatory list of features (speed, duplex, etc) 572 + * @name: The friendly name of this PHY type 573 + * @phy_id_mask: Defines the important bits of the phy_id 574 + * @features: A mandatory list of features (speed, duplex, etc) 688 575 * supported by this PHY 689 - * flags: A bitfield defining certain other features this PHY 576 + * @flags: A bitfield defining certain other features this PHY 690 577 * supports (like interrupts) 578 + * @driver_data: Static driver data 691 579 * 692 580 * All functions are optional. If config_aneg or read_status 693 581 * are not implemented, the phy core uses the genphy versions. ··· 708 592 u32 flags; 709 593 const void *driver_data; 710 594 711 - /* 712 - * Called to issue a PHY software reset 595 + /** 596 + * @soft_reset: Called to issue a PHY software reset 713 597 */ 714 598 int (*soft_reset)(struct phy_device *phydev); 715 599 716 - /* 717 - * Called to initialize the PHY, 600 + /** 601 + * @config_init: Called to initialize the PHY, 718 602 * including after a reset 719 603 */ 720 604 int (*config_init)(struct phy_device *phydev); 721 605 722 - /* 723 - * Called during discovery. Used to set 606 + /** 607 + * @probe: Called during discovery. Used to set 724 608 * up device-specific structures, if any 725 609 */ 726 610 int (*probe)(struct phy_device *phydev); 727 611 728 - /* 729 - * Probe the hardware to determine what abilities it has. 730 - * Should only set phydev->supported. 612 + /** 613 + * @get_features: Probe the hardware to determine what 614 + * abilities it has. Should only set phydev->supported. 731 615 */ 732 616 int (*get_features)(struct phy_device *phydev); 733 617 734 618 /* PHY Power Management */ 619 + /** @suspend: Suspend the hardware, saving state if needed */ 735 620 int (*suspend)(struct phy_device *phydev); 621 + /** @resume: Resume the hardware, restoring state if needed */ 736 622 int (*resume)(struct phy_device *phydev); 737 623 738 - /* 739 - * Configures the advertisement and resets 624 + /** 625 + * @config_aneg: Configures the advertisement and resets 740 626 * autonegotiation if phydev->autoneg is on, 741 627 * forces the speed to the current settings in phydev 742 628 * if phydev->autoneg is off 743 629 */ 744 630 int (*config_aneg)(struct phy_device *phydev); 745 631 746 - /* Determines the auto negotiation result */ 632 + /** @aneg_done: Determines the auto negotiation result */ 747 633 int (*aneg_done)(struct phy_device *phydev); 748 634 749 - /* Determines the negotiated speed and duplex */ 635 + /** @read_status: Determines the negotiated speed and duplex */ 750 636 int (*read_status)(struct phy_device *phydev); 751 637 752 - /* Clears any pending interrupts */ 638 + /** @ack_interrupt: Clears any pending interrupts */ 753 639 int (*ack_interrupt)(struct phy_device *phydev); 754 640 755 - /* Enables or disables interrupts */ 641 + /** @config_intr: Enables or disables interrupts */ 756 642 int (*config_intr)(struct phy_device *phydev); 757 643 758 - /* 759 - * Checks if the PHY generated an interrupt. 644 + /** 645 + * @did_interrupt: Checks if the PHY generated an interrupt. 760 646 * For multi-PHY devices with shared PHY interrupt pin 761 647 * Set interrupt bits have to be cleared. 762 648 */ 763 649 int (*did_interrupt)(struct phy_device *phydev); 764 650 765 - /* Override default interrupt handling */ 651 + /** @handle_interrupt: Override default interrupt handling */ 766 652 irqreturn_t (*handle_interrupt)(struct phy_device *phydev); 767 653 768 - /* Clears up any memory if needed */ 654 + /** @remove: Clears up any memory if needed */ 769 655 void (*remove)(struct phy_device *phydev); 770 656 771 - /* Returns true if this is a suitable driver for the given 772 - * phydev. If NULL, matching is based on phy_id and 773 - * phy_id_mask. 657 + /** 658 + * @match_phy_device: Returns true if this is a suitable 659 + * driver for the given phydev. If NULL, matching is based on 660 + * phy_id and phy_id_mask. 774 661 */ 775 662 int (*match_phy_device)(struct phy_device *phydev); 776 663 777 - /* Some devices (e.g. qnap TS-119P II) require PHY register changes to 778 - * enable Wake on LAN, so set_wol is provided to be called in the 779 - * ethernet driver's set_wol function. */ 664 + /** 665 + * @set_wol: Some devices (e.g. qnap TS-119P II) require PHY 666 + * register changes to enable Wake on LAN, so set_wol is 667 + * provided to be called in the ethernet driver's set_wol 668 + * function. 669 + */ 780 670 int (*set_wol)(struct phy_device *dev, struct ethtool_wolinfo *wol); 781 671 782 - /* See set_wol, but for checking whether Wake on LAN is enabled. */ 672 + /** 673 + * @get_wol: See set_wol, but for checking whether Wake on LAN 674 + * is enabled. 675 + */ 783 676 void (*get_wol)(struct phy_device *dev, struct ethtool_wolinfo *wol); 784 677 785 - /* 786 - * Called to inform a PHY device driver when the core is about to 787 - * change the link state. This callback is supposed to be used as 788 - * fixup hook for drivers that need to take action when the link 789 - * state changes. Drivers are by no means allowed to mess with the 678 + /** 679 + * @link_change_notify: Called to inform a PHY device driver 680 + * when the core is about to change the link state. This 681 + * callback is supposed to be used as fixup hook for drivers 682 + * that need to take action when the link state 683 + * changes. Drivers are by no means allowed to mess with the 790 684 * PHY device structure in their implementations. 791 685 */ 792 686 void (*link_change_notify)(struct phy_device *dev); 793 687 794 - /* 795 - * Phy specific driver override for reading a MMD register. 796 - * This function is optional for PHY specific drivers. When 797 - * not provided, the default MMD read function will be used 798 - * by phy_read_mmd(), which will use either a direct read for 799 - * Clause 45 PHYs or an indirect read for Clause 22 PHYs. 800 - * devnum is the MMD device number within the PHY device, 801 - * regnum is the register within the selected MMD device. 688 + /** 689 + * @read_mmd: PHY specific driver override for reading a MMD 690 + * register. This function is optional for PHY specific 691 + * drivers. When not provided, the default MMD read function 692 + * will be used by phy_read_mmd(), which will use either a 693 + * direct read for Clause 45 PHYs or an indirect read for 694 + * Clause 22 PHYs. devnum is the MMD device number within the 695 + * PHY device, regnum is the register within the selected MMD 696 + * device. 802 697 */ 803 698 int (*read_mmd)(struct phy_device *dev, int devnum, u16 regnum); 804 699 805 - /* 806 - * Phy specific driver override for writing a MMD register. 807 - * This function is optional for PHY specific drivers. When 808 - * not provided, the default MMD write function will be used 809 - * by phy_write_mmd(), which will use either a direct write for 810 - * Clause 45 PHYs, or an indirect write for Clause 22 PHYs. 811 - * devnum is the MMD device number within the PHY device, 812 - * regnum is the register within the selected MMD device. 813 - * val is the value to be written. 700 + /** 701 + * @write_mmd: PHY specific driver override for writing a MMD 702 + * register. This function is optional for PHY specific 703 + * drivers. When not provided, the default MMD write function 704 + * will be used by phy_write_mmd(), which will use either a 705 + * direct write for Clause 45 PHYs, or an indirect write for 706 + * Clause 22 PHYs. devnum is the MMD device number within the 707 + * PHY device, regnum is the register within the selected MMD 708 + * device. val is the value to be written. 814 709 */ 815 710 int (*write_mmd)(struct phy_device *dev, int devnum, u16 regnum, 816 711 u16 val); 817 712 713 + /** @read_page: Return the current PHY register page number */ 818 714 int (*read_page)(struct phy_device *dev); 715 + /** @write_page: Set the current PHY register page number */ 819 716 int (*write_page)(struct phy_device *dev, int page); 820 717 821 - /* Get the size and type of the eeprom contained within a plug-in 822 - * module */ 718 + /** 719 + * @module_info: Get the size and type of the eeprom contained 720 + * within a plug-in module 721 + */ 823 722 int (*module_info)(struct phy_device *dev, 824 723 struct ethtool_modinfo *modinfo); 825 724 826 - /* Get the eeprom information from the plug-in module */ 725 + /** 726 + * @module_eeprom: Get the eeprom information from the plug-in 727 + * module 728 + */ 827 729 int (*module_eeprom)(struct phy_device *dev, 828 730 struct ethtool_eeprom *ee, u8 *data); 829 731 830 - /* Start a cable test */ 732 + /** @cable_test_start: Start a cable test */ 831 733 int (*cable_test_start)(struct phy_device *dev); 832 734 833 - /* Start a raw TDR cable test */ 735 + /** @cable_test_tdr_start: Start a raw TDR cable test */ 834 736 int (*cable_test_tdr_start)(struct phy_device *dev, 835 737 const struct phy_tdr_config *config); 836 738 837 - /* Once per second, or on interrupt, request the status of the 838 - * test. 739 + /** 740 + * @cable_test_get_status: Once per second, or on interrupt, 741 + * request the status of the test. 839 742 */ 840 743 int (*cable_test_get_status)(struct phy_device *dev, bool *finished); 841 744 842 - /* Get statistics from the phy using ethtool */ 745 + /* Get statistics from the PHY using ethtool */ 746 + /** @get_sset_count: Number of statistic counters */ 843 747 int (*get_sset_count)(struct phy_device *dev); 748 + /** @get_strings: Names of the statistic counters */ 844 749 void (*get_strings)(struct phy_device *dev, u8 *data); 750 + /** @get_stats: Return the statistic counter values */ 845 751 void (*get_stats)(struct phy_device *dev, 846 752 struct ethtool_stats *stats, u64 *data); 847 753 848 754 /* Get and Set PHY tunables */ 755 + /** @get_tunable: Return the value of a tunable */ 849 756 int (*get_tunable)(struct phy_device *dev, 850 757 struct ethtool_tunable *tuna, void *data); 758 + /** @set_tunable: Set the value of a tunable */ 851 759 int (*set_tunable)(struct phy_device *dev, 852 760 struct ethtool_tunable *tuna, 853 761 const void *data); 762 + /** @set_loopback: Set the loopback mood of the PHY */ 854 763 int (*set_loopback)(struct phy_device *dev, bool enable); 764 + /** @get_sqi: Get the signal quality indication */ 855 765 int (*get_sqi)(struct phy_device *dev); 766 + /** @get_sqi_max: Get the maximum signal quality indication */ 856 767 int (*get_sqi_max)(struct phy_device *dev); 857 768 }; 858 769 #define to_phy_driver(d) container_of(to_mdio_common_driver(d), \ ··· 1033 890 */ 1034 891 int phy_read_mmd(struct phy_device *phydev, int devad, u32 regnum); 1035 892 893 + /** 894 + * phy_read_mmd_poll_timeout - Periodically poll a PHY register until a 895 + * condition is met or a timeout occurs 896 + * 897 + * @phydev: The phy_device struct 898 + * @devaddr: The MMD to read from 899 + * @regnum: The register on the MMD to read 900 + * @val: Variable to read the register into 901 + * @cond: Break condition (usually involving @val) 902 + * @sleep_us: Maximum time to sleep between reads in us (0 903 + * tight-loops). Should be less than ~20ms since usleep_range 904 + * is used (see Documentation/timers/timers-howto.rst). 905 + * @timeout_us: Timeout in us, 0 means never timeout 906 + * @sleep_before_read: if it is true, sleep @sleep_us before read. 907 + * Returns 0 on success and -ETIMEDOUT upon a timeout. In either 908 + * case, the last read value at @args is stored in @val. Must not 909 + * be called from atomic context if sleep_us or timeout_us are used. 910 + */ 1036 911 #define phy_read_mmd_poll_timeout(phydev, devaddr, regnum, val, cond, \ 1037 912 sleep_us, timeout_us, sleep_before_read) \ 1038 913 ({ \ ··· 1322 1161 /** 1323 1162 * phy_interface_mode_is_rgmii - Convenience function for testing if a 1324 1163 * PHY interface mode is RGMII (all variants) 1325 - * @mode: the phy_interface_t enum 1164 + * @mode: the &phy_interface_t enum 1326 1165 */ 1327 1166 static inline bool phy_interface_mode_is_rgmii(phy_interface_t mode) 1328 1167 { ··· 1331 1170 }; 1332 1171 1333 1172 /** 1334 - * phy_interface_mode_is_8023z() - does the phy interface mode use 802.3z 1173 + * phy_interface_mode_is_8023z() - does the PHY interface mode use 802.3z 1335 1174 * negotiation 1336 1175 * @mode: one of &enum phy_interface_t 1337 1176 * 1338 - * Returns true if the phy interface mode uses the 16-bit negotiation 1177 + * Returns true if the PHY interface mode uses the 16-bit negotiation 1339 1178 * word as defined in 802.3z. (See 802.3-2015 37.2.1 Config_Reg encoding) 1340 1179 */ 1341 1180 static inline bool phy_interface_mode_is_8023z(phy_interface_t mode) ··· 1354 1193 return phy_interface_mode_is_rgmii(phydev->interface); 1355 1194 }; 1356 1195 1357 - /* 1196 + /** 1358 1197 * phy_is_pseudo_fixed_link - Convenience function for testing if this 1359 1198 * PHY is the CPU port facing side of an Ethernet switch, or similar. 1360 1199 * @phydev: the phy_device struct