aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorRandy Dunlap <randy.dunlap@oracle.com>2007-03-06 05:41:48 -0500
committerJeff Garzik <jeff@garzik.org>2007-04-28 11:00:57 -0400
commitb3df0da886ffdb3e70c3197f589e959e5f8c9c04 (patch)
tree7a1f564d31835f31ebab9da370dace187b0aefc6
parent56e1393f82349d8206fe7feb94db96b065c55e51 (diff)
phy layer: add kernel-doc + DocBook
Convert function documentation in drivers/net/phy/ to kernel-doc and add it to DocBook. Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Jeff Garzik <jeff@garzik.org>
-rw-r--r--Documentation/DocBook/kernel-api.tmpl6
-rw-r--r--drivers/net/phy/mdio_bus.c19
-rw-r--r--drivers/net/phy/phy.c188
-rw-r--r--drivers/net/phy/phy_device.c114
4 files changed, 232 insertions, 95 deletions
diff --git a/Documentation/DocBook/kernel-api.tmpl b/Documentation/DocBook/kernel-api.tmpl
index 0bb90237e23..b61dfc79e1b 100644
--- a/Documentation/DocBook/kernel-api.tmpl
+++ b/Documentation/DocBook/kernel-api.tmpl
@@ -236,6 +236,12 @@ X!Ilib/string.c
236!Enet/core/dev.c 236!Enet/core/dev.c
237!Enet/ethernet/eth.c 237!Enet/ethernet/eth.c
238!Iinclude/linux/etherdevice.h 238!Iinclude/linux/etherdevice.h
239!Edrivers/net/phy/phy.c
240!Idrivers/net/phy/phy.c
241!Edrivers/net/phy/phy_device.c
242!Idrivers/net/phy/phy_device.c
243!Edrivers/net/phy/mdio_bus.c
244!Idrivers/net/phy/mdio_bus.c
239<!-- FIXME: Removed for now since no structured comments in source 245<!-- FIXME: Removed for now since no structured comments in source
240X!Enet/core/wireless.c 246X!Enet/core/wireless.c
241--> 247-->
diff --git a/drivers/net/phy/mdio_bus.c b/drivers/net/phy/mdio_bus.c
index b31ce278bf3..fc4aee96cdf 100644
--- a/drivers/net/phy/mdio_bus.c
+++ b/drivers/net/phy/mdio_bus.c
@@ -35,10 +35,14 @@
35#include <asm/irq.h> 35#include <asm/irq.h>
36#include <asm/uaccess.h> 36#include <asm/uaccess.h>
37 37
38/* mdiobus_register 38/**
39 * mdiobus_register - bring up all the PHYs on a given bus and attach them to bus
40 * @bus: target mii_bus
39 * 41 *
40 * description: Called by a bus driver to bring up all the PHYs 42 * Description: Called by a bus driver to bring up all the PHYs
41 * on a given bus, and attach them to the bus 43 * on a given bus, and attach them to the bus.
44 *
45 * Returns 0 on success or < 0 on error.
42 */ 46 */
43int mdiobus_register(struct mii_bus *bus) 47int mdiobus_register(struct mii_bus *bus)
44{ 48{
@@ -114,10 +118,13 @@ void mdiobus_unregister(struct mii_bus *bus)
114} 118}
115EXPORT_SYMBOL(mdiobus_unregister); 119EXPORT_SYMBOL(mdiobus_unregister);
116 120
117/* mdio_bus_match 121/**
122 * mdio_bus_match - determine if given PHY driver supports the given PHY device
123 * @dev: target PHY device
124 * @drv: given PHY driver
118 * 125 *
119 * description: Given a PHY device, and a PHY driver, return 1 if 126 * Description: Given a PHY device, and a PHY driver, return 1 if
120 * the driver supports the device. Otherwise, return 0 127 * the driver supports the device. Otherwise, return 0.
121 */ 128 */
122static int mdio_bus_match(struct device *dev, struct device_driver *drv) 129static int mdio_bus_match(struct device *dev, struct device_driver *drv)
123{ 130{
diff --git a/drivers/net/phy/phy.c b/drivers/net/phy/phy.c
index c94a1fb3a4b..a602d06d85a 100644
--- a/drivers/net/phy/phy.c
+++ b/drivers/net/phy/phy.c
@@ -39,7 +39,9 @@
39#include <asm/irq.h> 39#include <asm/irq.h>
40#include <asm/uaccess.h> 40#include <asm/uaccess.h>
41 41
42/* Convenience function to print out the current phy status 42/**
43 * phy_print_status - Convenience function to print out the current phy status
44 * @phydev: the phy_device struct
43 */ 45 */
44void phy_print_status(struct phy_device *phydev) 46void phy_print_status(struct phy_device *phydev)
45{ 47{
@@ -55,10 +57,15 @@ void phy_print_status(struct phy_device *phydev)
55EXPORT_SYMBOL(phy_print_status); 57EXPORT_SYMBOL(phy_print_status);
56 58
57 59
58/* Convenience functions for reading/writing a given PHY 60/**
59 * register. They MUST NOT be called from interrupt context, 61 * phy_read - Convenience function for reading a given PHY register
62 * @phydev: the phy_device struct
63 * @regnum: register number to read
64 *
65 * NOTE: MUST NOT be called from interrupt context,
60 * because the bus read/write functions may wait for an interrupt 66 * because the bus read/write functions may wait for an interrupt
61 * to conclude the operation. */ 67 * to conclude the operation.
68 */
62int phy_read(struct phy_device *phydev, u16 regnum) 69int phy_read(struct phy_device *phydev, u16 regnum)
63{ 70{
64 int retval; 71 int retval;
@@ -72,6 +79,16 @@ int phy_read(struct phy_device *phydev, u16 regnum)
72} 79}
73EXPORT_SYMBOL(phy_read); 80EXPORT_SYMBOL(phy_read);
74 81
82/**
83 * phy_write - Convenience function for writing a given PHY register
84 * @phydev: the phy_device struct
85 * @regnum: register number to write
86 * @val: value to write to @regnum
87 *
88 * NOTE: MUST NOT be called from interrupt context,
89 * because the bus read/write functions may wait for an interrupt
90 * to conclude the operation.
91 */
75int phy_write(struct phy_device *phydev, u16 regnum, u16 val) 92int phy_write(struct phy_device *phydev, u16 regnum, u16 val)
76{ 93{
77 int err; 94 int err;
@@ -85,7 +102,15 @@ int phy_write(struct phy_device *phydev, u16 regnum, u16 val)
85} 102}
86EXPORT_SYMBOL(phy_write); 103EXPORT_SYMBOL(phy_write);
87 104
88 105/**
106 * phy_clear_interrupt - Ack the phy device's interrupt
107 * @phydev: the phy_device struct
108 *
109 * If the @phydev driver has an ack_interrupt function, call it to
110 * ack and clear the phy device's interrupt.
111 *
112 * Returns 0 on success on < 0 on error.
113 */
89int phy_clear_interrupt(struct phy_device *phydev) 114int phy_clear_interrupt(struct phy_device *phydev)
90{ 115{
91 int err = 0; 116 int err = 0;
@@ -96,7 +121,13 @@ int phy_clear_interrupt(struct phy_device *phydev)
96 return err; 121 return err;
97} 122}
98 123
99 124/**
125 * phy_config_interrupt - configure the PHY device for the requested interrupts
126 * @phydev: the phy_device struct
127 * @interrupts: interrupt flags to configure for this @phydev
128 *
129 * Returns 0 on success on < 0 on error.
130 */
100int phy_config_interrupt(struct phy_device *phydev, u32 interrupts) 131int phy_config_interrupt(struct phy_device *phydev, u32 interrupts)
101{ 132{
102 int err = 0; 133 int err = 0;
@@ -109,9 +140,11 @@ int phy_config_interrupt(struct phy_device *phydev, u32 interrupts)
109} 140}
110 141
111 142
112/* phy_aneg_done 143/**
144 * phy_aneg_done - return auto-negotiation status
145 * @phydev: target phy_device struct
113 * 146 *
114 * description: Reads the status register and returns 0 either if 147 * Description: Reads the status register and returns 0 either if
115 * auto-negotiation is incomplete, or if there was an error. 148 * auto-negotiation is incomplete, or if there was an error.
116 * Returns BMSR_ANEGCOMPLETE if auto-negotiation is done. 149 * Returns BMSR_ANEGCOMPLETE if auto-negotiation is done.
117 */ 150 */
@@ -173,9 +206,12 @@ static const struct phy_setting settings[] = {
173 206
174#define MAX_NUM_SETTINGS (sizeof(settings)/sizeof(struct phy_setting)) 207#define MAX_NUM_SETTINGS (sizeof(settings)/sizeof(struct phy_setting))
175 208
176/* phy_find_setting 209/**
210 * phy_find_setting - find a PHY settings array entry that matches speed & duplex
211 * @speed: speed to match
212 * @duplex: duplex to match
177 * 213 *
178 * description: Searches the settings array for the setting which 214 * Description: Searches the settings array for the setting which
179 * matches the desired speed and duplex, and returns the index 215 * matches the desired speed and duplex, and returns the index
180 * of that setting. Returns the index of the last setting if 216 * of that setting. Returns the index of the last setting if
181 * none of the others match. 217 * none of the others match.
@@ -192,11 +228,12 @@ static inline int phy_find_setting(int speed, int duplex)
192 return idx < MAX_NUM_SETTINGS ? idx : MAX_NUM_SETTINGS - 1; 228 return idx < MAX_NUM_SETTINGS ? idx : MAX_NUM_SETTINGS - 1;
193} 229}
194 230
195/* phy_find_valid 231/**
196 * idx: The first index in settings[] to search 232 * phy_find_valid - find a PHY setting that matches the requested features mask
197 * features: A mask of the valid settings 233 * @idx: The first index in settings[] to search
234 * @features: A mask of the valid settings
198 * 235 *
199 * description: Returns the index of the first valid setting less 236 * Description: Returns the index of the first valid setting less
200 * than or equal to the one pointed to by idx, as determined by 237 * than or equal to the one pointed to by idx, as determined by
201 * the mask in features. Returns the index of the last setting 238 * the mask in features. Returns the index of the last setting
202 * if nothing else matches. 239 * if nothing else matches.
@@ -209,11 +246,13 @@ static inline int phy_find_valid(int idx, u32 features)
209 return idx < MAX_NUM_SETTINGS ? idx : MAX_NUM_SETTINGS - 1; 246 return idx < MAX_NUM_SETTINGS ? idx : MAX_NUM_SETTINGS - 1;
210} 247}
211 248
212/* phy_sanitize_settings 249/**
250 * phy_sanitize_settings - make sure the PHY is set to supported speed and duplex
251 * @phydev: the target phy_device struct
213 * 252 *
214 * description: Make sure the PHY is set to supported speeds and 253 * Description: Make sure the PHY is set to supported speeds and
215 * duplexes. Drop down by one in this order: 1000/FULL, 254 * duplexes. Drop down by one in this order: 1000/FULL,
216 * 1000/HALF, 100/FULL, 100/HALF, 10/FULL, 10/HALF 255 * 1000/HALF, 100/FULL, 100/HALF, 10/FULL, 10/HALF.
217 */ 256 */
218void phy_sanitize_settings(struct phy_device *phydev) 257void phy_sanitize_settings(struct phy_device *phydev)
219{ 258{
@@ -232,16 +271,17 @@ void phy_sanitize_settings(struct phy_device *phydev)
232} 271}
233EXPORT_SYMBOL(phy_sanitize_settings); 272EXPORT_SYMBOL(phy_sanitize_settings);
234 273
235/* phy_ethtool_sset: 274/**
236 * A generic ethtool sset function. Handles all the details 275 * phy_ethtool_sset - generic ethtool sset function, handles all the details
276 * @phydev: target phy_device struct
277 * @cmd: ethtool_cmd
237 * 278 *
238 * A few notes about parameter checking: 279 * A few notes about parameter checking:
239 * - We don't set port or transceiver, so we don't care what they 280 * - We don't set port or transceiver, so we don't care what they
240 * were set to. 281 * were set to.
241 * - phy_start_aneg() will make sure forced settings are sane, and 282 * - phy_start_aneg() will make sure forced settings are sane, and
242 * choose the next best ones from the ones selected, so we don't 283 * choose the next best ones from the ones selected, so we don't
243 * care if ethtool tries to give us bad values 284 * care if ethtool tries to give us bad values.
244 *
245 */ 285 */
246int phy_ethtool_sset(struct phy_device *phydev, struct ethtool_cmd *cmd) 286int phy_ethtool_sset(struct phy_device *phydev, struct ethtool_cmd *cmd)
247{ 287{
@@ -304,9 +344,15 @@ int phy_ethtool_gset(struct phy_device *phydev, struct ethtool_cmd *cmd)
304} 344}
305EXPORT_SYMBOL(phy_ethtool_gset); 345EXPORT_SYMBOL(phy_ethtool_gset);
306 346
307/* Note that this function is currently incompatible with the 347/**
348 * phy_mii_ioctl - generic PHY MII ioctl interface
349 * @phydev: the phy_device struct
350 * @mii_data: MII ioctl data
351 * @cmd: ioctl cmd to execute
352 *
353 * Note that this function is currently incompatible with the
308 * PHYCONTROL layer. It changes registers without regard to 354 * PHYCONTROL layer. It changes registers without regard to
309 * current state. Use at own risk 355 * current state. Use at own risk.
310 */ 356 */
311int phy_mii_ioctl(struct phy_device *phydev, 357int phy_mii_ioctl(struct phy_device *phydev,
312 struct mii_ioctl_data *mii_data, int cmd) 358 struct mii_ioctl_data *mii_data, int cmd)
@@ -358,13 +404,14 @@ int phy_mii_ioctl(struct phy_device *phydev,
358 return 0; 404 return 0;
359} 405}
360 406
361/* phy_start_aneg 407/**
408 * phy_start_aneg - start auto-negotiation for this PHY device
409 * @phydev: the phy_device struct
362 * 410 *
363 * description: Sanitizes the settings (if we're not 411 * Description: Sanitizes the settings (if we're not autonegotiating
364 * autonegotiating them), and then calls the driver's 412 * them), and then calls the driver's config_aneg function.
365 * config_aneg function. If the PHYCONTROL Layer is operating, 413 * If the PHYCONTROL Layer is operating, we change the state to
366 * we change the state to reflect the beginning of 414 * reflect the beginning of Auto-negotiation or forcing.
367 * Auto-negotiation or forcing.
368 */ 415 */
369int phy_start_aneg(struct phy_device *phydev) 416int phy_start_aneg(struct phy_device *phydev)
370{ 417{
@@ -400,15 +447,19 @@ EXPORT_SYMBOL(phy_start_aneg);
400static void phy_change(struct work_struct *work); 447static void phy_change(struct work_struct *work);
401static void phy_timer(unsigned long data); 448static void phy_timer(unsigned long data);
402 449
403/* phy_start_machine: 450/**
451 * phy_start_machine - start PHY state machine tracking
452 * @phydev: the phy_device struct
453 * @handler: callback function for state change notifications
404 * 454 *
405 * description: The PHY infrastructure can run a state machine 455 * Description: The PHY infrastructure can run a state machine
406 * which tracks whether the PHY is starting up, negotiating, 456 * which tracks whether the PHY is starting up, negotiating,
407 * etc. This function starts the timer which tracks the state 457 * etc. This function starts the timer which tracks the state
408 * of the PHY. If you want to be notified when the state 458 * of the PHY. If you want to be notified when the state changes,
409 * changes, pass in the callback, otherwise, pass NULL. If you 459 * pass in the callback @handler, otherwise, pass NULL. If you
410 * want to maintain your own state machine, do not call this 460 * want to maintain your own state machine, do not call this
411 * function. */ 461 * function.
462 */
412void phy_start_machine(struct phy_device *phydev, 463void phy_start_machine(struct phy_device *phydev,
413 void (*handler)(struct net_device *)) 464 void (*handler)(struct net_device *))
414{ 465{
@@ -420,9 +471,11 @@ void phy_start_machine(struct phy_device *phydev,
420 mod_timer(&phydev->phy_timer, jiffies + HZ); 471 mod_timer(&phydev->phy_timer, jiffies + HZ);
421} 472}
422 473
423/* phy_stop_machine 474/**
475 * phy_stop_machine - stop the PHY state machine tracking
476 * @phydev: target phy_device struct
424 * 477 *
425 * description: Stops the state machine timer, sets the state to UP 478 * Description: Stops the state machine timer, sets the state to UP
426 * (unless it wasn't up yet). This function must be called BEFORE 479 * (unless it wasn't up yet). This function must be called BEFORE
427 * phy_detach. 480 * phy_detach.
428 */ 481 */
@@ -438,12 +491,14 @@ void phy_stop_machine(struct phy_device *phydev)
438 phydev->adjust_state = NULL; 491 phydev->adjust_state = NULL;
439} 492}
440 493
441/* phy_force_reduction 494/**
495 * phy_force_reduction - reduce PHY speed/duplex settings by one step
496 * @phydev: target phy_device struct
442 * 497 *
443 * description: Reduces the speed/duplex settings by 498 * Description: Reduces the speed/duplex settings by one notch,
444 * one notch. The order is so: 499 * in this order--
445 * 1000/FULL, 1000/HALF, 100/FULL, 100/HALF, 500 * 1000/FULL, 1000/HALF, 100/FULL, 100/HALF, 10/FULL, 10/HALF.
446 * 10/FULL, 10/HALF. The function bottoms out at 10/HALF. 501 * The function bottoms out at 10/HALF.
447 */ 502 */
448static void phy_force_reduction(struct phy_device *phydev) 503static void phy_force_reduction(struct phy_device *phydev)
449{ 504{
@@ -464,7 +519,9 @@ static void phy_force_reduction(struct phy_device *phydev)
464} 519}
465 520
466 521
467/* phy_error: 522/**
523 * phy_error - enter HALTED state for this PHY device
524 * @phydev: target phy_device struct
468 * 525 *
469 * Moves the PHY to the HALTED state in response to a read 526 * Moves the PHY to the HALTED state in response to a read
470 * or write error, and tells the controller the link is down. 527 * or write error, and tells the controller the link is down.
@@ -478,9 +535,12 @@ void phy_error(struct phy_device *phydev)
478 spin_unlock(&phydev->lock); 535 spin_unlock(&phydev->lock);
479} 536}
480 537
481/* phy_interrupt 538/**
539 * phy_interrupt - PHY interrupt handler
540 * @irq: interrupt line
541 * @phy_dat: phy_device pointer
482 * 542 *
483 * description: When a PHY interrupt occurs, the handler disables 543 * Description: When a PHY interrupt occurs, the handler disables
484 * interrupts, and schedules a work task to clear the interrupt. 544 * interrupts, and schedules a work task to clear the interrupt.
485 */ 545 */
486static irqreturn_t phy_interrupt(int irq, void *phy_dat) 546static irqreturn_t phy_interrupt(int irq, void *phy_dat)
@@ -501,7 +561,10 @@ static irqreturn_t phy_interrupt(int irq, void *phy_dat)
501 return IRQ_HANDLED; 561 return IRQ_HANDLED;
502} 562}
503 563
504/* Enable the interrupts from the PHY side */ 564/**
565 * phy_enable_interrupts - Enable the interrupts from the PHY side
566 * @phydev: target phy_device struct
567 */
505int phy_enable_interrupts(struct phy_device *phydev) 568int phy_enable_interrupts(struct phy_device *phydev)
506{ 569{
507 int err; 570 int err;
@@ -517,7 +580,10 @@ int phy_enable_interrupts(struct phy_device *phydev)
517} 580}
518EXPORT_SYMBOL(phy_enable_interrupts); 581EXPORT_SYMBOL(phy_enable_interrupts);
519 582
520/* Disable the PHY interrupts from the PHY side */ 583/**
584 * phy_disable_interrupts - Disable the PHY interrupts from the PHY side
585 * @phydev: target phy_device struct
586 */
521int phy_disable_interrupts(struct phy_device *phydev) 587int phy_disable_interrupts(struct phy_device *phydev)
522{ 588{
523 int err; 589 int err;
@@ -543,13 +609,15 @@ phy_err:
543} 609}
544EXPORT_SYMBOL(phy_disable_interrupts); 610EXPORT_SYMBOL(phy_disable_interrupts);
545 611
546/* phy_start_interrupts 612/**
613 * phy_start_interrupts - request and enable interrupts for a PHY device
614 * @phydev: target phy_device struct
547 * 615 *
548 * description: Request the interrupt for the given PHY. If 616 * Description: Request the interrupt for the given PHY.
549 * this fails, then we set irq to PHY_POLL. 617 * If this fails, then we set irq to PHY_POLL.
550 * Otherwise, we enable the interrupts in the PHY. 618 * Otherwise, we enable the interrupts in the PHY.
551 * Returns 0 on success.
552 * This should only be called with a valid IRQ number. 619 * This should only be called with a valid IRQ number.
620 * Returns 0 on success or < 0 on error.
553 */ 621 */
554int phy_start_interrupts(struct phy_device *phydev) 622int phy_start_interrupts(struct phy_device *phydev)
555{ 623{
@@ -574,6 +642,10 @@ int phy_start_interrupts(struct phy_device *phydev)
574} 642}
575EXPORT_SYMBOL(phy_start_interrupts); 643EXPORT_SYMBOL(phy_start_interrupts);
576 644
645/**
646 * phy_stop_interrupts - disable interrupts from a PHY device
647 * @phydev: target phy_device struct
648 */
577int phy_stop_interrupts(struct phy_device *phydev) 649int phy_stop_interrupts(struct phy_device *phydev)
578{ 650{
579 int err; 651 int err;
@@ -596,7 +668,10 @@ int phy_stop_interrupts(struct phy_device *phydev)
596EXPORT_SYMBOL(phy_stop_interrupts); 668EXPORT_SYMBOL(phy_stop_interrupts);
597 669
598 670
599/* Scheduled by the phy_interrupt/timer to handle PHY changes */ 671/**
672 * phy_change - Scheduled by the phy_interrupt/timer to handle PHY changes
673 * @work: work_struct that describes the work to be done
674 */
600static void phy_change(struct work_struct *work) 675static void phy_change(struct work_struct *work)
601{ 676{
602 int err; 677 int err;
@@ -630,7 +705,10 @@ phy_err:
630 phy_error(phydev); 705 phy_error(phydev);
631} 706}
632 707
633/* Bring down the PHY link, and stop checking the status. */ 708/**
709 * phy_stop - Bring down the PHY link, and stop checking the status
710 * @phydev: target phy_device struct
711 */
634void phy_stop(struct phy_device *phydev) 712void phy_stop(struct phy_device *phydev)
635{ 713{
636 spin_lock(&phydev->lock); 714 spin_lock(&phydev->lock);
@@ -659,9 +737,11 @@ out_unlock:
659} 737}
660 738
661 739
662/* phy_start 740/**
741 * phy_start - start or restart a PHY device
742 * @phydev: target phy_device struct
663 * 743 *
664 * description: Indicates the attached device's readiness to 744 * Description: Indicates the attached device's readiness to
665 * handle PHY-related work. Used during startup to start the 745 * handle PHY-related work. Used during startup to start the
666 * PHY, and after a call to phy_stop() to resume operation. 746 * PHY, and after a call to phy_stop() to resume operation.
667 * Also used to indicate the MDIO bus has cleared an error 747 * Also used to indicate the MDIO bus has cleared an error
diff --git a/drivers/net/phy/phy_device.c b/drivers/net/phy/phy_device.c
index 8f01952c485..a8b74cdab1e 100644
--- a/drivers/net/phy/phy_device.c
+++ b/drivers/net/phy/phy_device.c
@@ -74,11 +74,13 @@ struct phy_device* phy_device_create(struct mii_bus *bus, int addr, int phy_id)
74} 74}
75EXPORT_SYMBOL(phy_device_create); 75EXPORT_SYMBOL(phy_device_create);
76 76
77/* get_phy_device 77/**
78 * get_phy_device - reads the specified PHY device and returns its @phy_device struct
79 * @bus: the target MII bus
80 * @addr: PHY address on the MII bus
78 * 81 *
79 * description: Reads the ID registers of the PHY at addr on the 82 * Description: Reads the ID registers of the PHY at @addr on the
80 * bus, then allocates and returns the phy_device to 83 * @bus, then allocates and returns the phy_device to represent it.
81 * represent it.
82 */ 84 */
83struct phy_device * get_phy_device(struct mii_bus *bus, int addr) 85struct phy_device * get_phy_device(struct mii_bus *bus, int addr)
84{ 86{
@@ -112,23 +114,33 @@ struct phy_device * get_phy_device(struct mii_bus *bus, int addr)
112 return dev; 114 return dev;
113} 115}
114 116
115/* phy_prepare_link: 117/**
118 * phy_prepare_link - prepares the PHY layer to monitor link status
119 * @phydev: target phy_device struct
120 * @handler: callback function for link status change notifications
116 * 121 *
117 * description: Tells the PHY infrastructure to handle the 122 * Description: Tells the PHY infrastructure to handle the
118 * gory details on monitoring link status (whether through 123 * gory details on monitoring link status (whether through
119 * polling or an interrupt), and to call back to the 124 * polling or an interrupt), and to call back to the
120 * connected device driver when the link status changes. 125 * connected device driver when the link status changes.
121 * If you want to monitor your own link state, don't call 126 * If you want to monitor your own link state, don't call
122 * this function */ 127 * this function.
128 */
123void phy_prepare_link(struct phy_device *phydev, 129void phy_prepare_link(struct phy_device *phydev,
124 void (*handler)(struct net_device *)) 130 void (*handler)(struct net_device *))
125{ 131{
126 phydev->adjust_link = handler; 132 phydev->adjust_link = handler;
127} 133}
128 134
129/* phy_connect: 135/**
136 * phy_connect - connect an ethernet device to a PHY device
137 * @dev: the network device to connect
138 * @phy_id: the PHY device to connect
139 * @handler: callback function for state change notifications
140 * @flags: PHY device's dev_flags
141 * @interface: PHY device's interface
130 * 142 *
131 * description: Convenience function for connecting ethernet 143 * Description: Convenience function for connecting ethernet
132 * devices to PHY devices. The default behavior is for 144 * devices to PHY devices. The default behavior is for
133 * the PHY infrastructure to handle everything, and only notify 145 * the PHY infrastructure to handle everything, and only notify
134 * the connected driver when the link status changes. If you 146 * the connected driver when the link status changes. If you
@@ -158,6 +170,10 @@ struct phy_device * phy_connect(struct net_device *dev, const char *phy_id,
158} 170}
159EXPORT_SYMBOL(phy_connect); 171EXPORT_SYMBOL(phy_connect);
160 172
173/**
174 * phy_disconnect - disable interrupts, stop state machine, and detach a PHY device
175 * @phydev: target phy_device struct
176 */
161void phy_disconnect(struct phy_device *phydev) 177void phy_disconnect(struct phy_device *phydev)
162{ 178{
163 if (phydev->irq > 0) 179 if (phydev->irq > 0)
@@ -171,21 +187,25 @@ void phy_disconnect(struct phy_device *phydev)
171} 187}
172EXPORT_SYMBOL(phy_disconnect); 188EXPORT_SYMBOL(phy_disconnect);
173 189
174/* phy_attach: 190static int phy_compare_id(struct device *dev, void *data)
191{
192 return strcmp((char *)data, dev->bus_id) ? 0 : 1;
193}
194
195/**
196 * phy_attach - attach a network device to a particular PHY device
197 * @dev: network device to attach
198 * @phy_id: PHY device to attach
199 * @flags: PHY device's dev_flags
200 * @interface: PHY device's interface
175 * 201 *
176 * description: Called by drivers to attach to a particular PHY 202 * Description: Called by drivers to attach to a particular PHY
177 * device. The phy_device is found, and properly hooked up 203 * device. The phy_device is found, and properly hooked up
178 * to the phy_driver. If no driver is attached, then the 204 * to the phy_driver. If no driver is attached, then the
179 * genphy_driver is used. The phy_device is given a ptr to 205 * genphy_driver is used. The phy_device is given a ptr to
180 * the attaching device, and given a callback for link status 206 * the attaching device, and given a callback for link status
181 * change. The phy_device is returned to the attaching 207 * change. The phy_device is returned to the attaching driver.
182 * driver.
183 */ 208 */
184static int phy_compare_id(struct device *dev, void *data)
185{
186 return strcmp((char *)data, dev->bus_id) ? 0 : 1;
187}
188
189struct phy_device *phy_attach(struct net_device *dev, 209struct phy_device *phy_attach(struct net_device *dev,
190 const char *phy_id, u32 flags, phy_interface_t interface) 210 const char *phy_id, u32 flags, phy_interface_t interface)
191{ 211{
@@ -246,6 +266,10 @@ struct phy_device *phy_attach(struct net_device *dev,
246} 266}
247EXPORT_SYMBOL(phy_attach); 267EXPORT_SYMBOL(phy_attach);
248 268
269/**
270 * phy_detach - detach a PHY device from its network device
271 * @phydev: target phy_device struct
272 */
249void phy_detach(struct phy_device *phydev) 273void phy_detach(struct phy_device *phydev)
250{ 274{
251 phydev->attached_dev = NULL; 275 phydev->attached_dev = NULL;
@@ -262,11 +286,13 @@ EXPORT_SYMBOL(phy_detach);
262 286
263/* Generic PHY support and helper functions */ 287/* Generic PHY support and helper functions */
264 288
265/* genphy_config_advert 289/**
290 * genphy_config_advert - sanitize and advertise auto-negotation parameters
291 * @phydev: target phy_device struct
266 * 292 *
267 * description: Writes MII_ADVERTISE with the appropriate values, 293 * Description: Writes MII_ADVERTISE with the appropriate values,
268 * after sanitizing the values to make sure we only advertise 294 * after sanitizing the values to make sure we only advertise
269 * what is supported 295 * what is supported.
270 */ 296 */
271int genphy_config_advert(struct phy_device *phydev) 297int genphy_config_advert(struct phy_device *phydev)
272{ 298{
@@ -328,11 +354,14 @@ int genphy_config_advert(struct phy_device *phydev)
328} 354}
329EXPORT_SYMBOL(genphy_config_advert); 355EXPORT_SYMBOL(genphy_config_advert);
330 356
331/* genphy_setup_forced 357/**
358 * genphy_setup_forced - configures/forces speed/duplex from @phydev
359 * @phydev: target phy_device struct
332 * 360 *
333 * description: Configures MII_BMCR to force speed/duplex 361 * Description: Configures MII_BMCR to force speed/duplex
334 * to the values in phydev. Assumes that the values are valid. 362 * to the values in phydev. Assumes that the values are valid.
335 * Please see phy_sanitize_settings() */ 363 * Please see phy_sanitize_settings().
364 */
336int genphy_setup_forced(struct phy_device *phydev) 365int genphy_setup_forced(struct phy_device *phydev)
337{ 366{
338 int ctl = BMCR_RESET; 367 int ctl = BMCR_RESET;
@@ -361,7 +390,10 @@ int genphy_setup_forced(struct phy_device *phydev)
361} 390}
362 391
363 392
364/* Enable and Restart Autonegotiation */ 393/**
394 * genphy_restart_aneg - Enable and Restart Autonegotiation
395 * @phydev: target phy_device struct
396 */
365int genphy_restart_aneg(struct phy_device *phydev) 397int genphy_restart_aneg(struct phy_device *phydev)
366{ 398{
367 int ctl; 399 int ctl;
@@ -382,11 +414,13 @@ int genphy_restart_aneg(struct phy_device *phydev)
382} 414}
383 415
384 416
385/* genphy_config_aneg 417/**
418 * genphy_config_aneg - restart auto-negotiation or write BMCR
419 * @phydev: target phy_device struct
386 * 420 *
387 * description: If auto-negotiation is enabled, we configure the 421 * Description: If auto-negotiation is enabled, we configure the
388 * advertising, and then restart auto-negotiation. If it is not 422 * advertising, and then restart auto-negotiation. If it is not
389 * enabled, then we write the BMCR 423 * enabled, then we write the BMCR.
390 */ 424 */
391int genphy_config_aneg(struct phy_device *phydev) 425int genphy_config_aneg(struct phy_device *phydev)
392{ 426{
@@ -406,11 +440,13 @@ int genphy_config_aneg(struct phy_device *phydev)
406} 440}
407EXPORT_SYMBOL(genphy_config_aneg); 441EXPORT_SYMBOL(genphy_config_aneg);
408 442
409/* genphy_update_link 443/**
444 * genphy_update_link - update link status in @phydev
445 * @phydev: target phy_device struct
410 * 446 *
411 * description: Update the value in phydev->link to reflect the 447 * Description: Update the value in phydev->link to reflect the
412 * current link value. In order to do this, we need to read 448 * current link value. In order to do this, we need to read
413 * the status register twice, keeping the second value 449 * the status register twice, keeping the second value.
414 */ 450 */
415int genphy_update_link(struct phy_device *phydev) 451int genphy_update_link(struct phy_device *phydev)
416{ 452{
@@ -437,9 +473,11 @@ int genphy_update_link(struct phy_device *phydev)
437} 473}
438EXPORT_SYMBOL(genphy_update_link); 474EXPORT_SYMBOL(genphy_update_link);
439 475
440/* genphy_read_status 476/**
477 * genphy_read_status - check the link status and update current link state
478 * @phydev: target phy_device struct
441 * 479 *
442 * description: Check the link, then figure out the current state 480 * Description: Check the link, then figure out the current state
443 * by comparing what we advertise with what the link partner 481 * by comparing what we advertise with what the link partner
444 * advertises. Start by checking the gigabit possibilities, 482 * advertises. Start by checking the gigabit possibilities,
445 * then move on to 10/100. 483 * then move on to 10/100.
@@ -579,9 +617,11 @@ static int genphy_config_init(struct phy_device *phydev)
579} 617}
580 618
581 619
582/* phy_probe 620/**
621 * phy_probe - probe and init a PHY device
622 * @dev: device to probe and init
583 * 623 *
584 * description: Take care of setting up the phy_device structure, 624 * Description: Take care of setting up the phy_device structure,
585 * set the state to READY (the driver's init function should 625 * set the state to READY (the driver's init function should
586 * set it to STARTING if needed). 626 * set it to STARTING if needed).
587 */ 627 */
@@ -643,6 +683,10 @@ static int phy_remove(struct device *dev)
643 return 0; 683 return 0;
644} 684}
645 685
686/**
687 * phy_driver_register - register a phy_driver with the PHY layer
688 * @new_driver: new phy_driver to register
689 */
646int phy_driver_register(struct phy_driver *new_driver) 690int phy_driver_register(struct phy_driver *new_driver)
647{ 691{
648 int retval; 692 int retval;