diff options
author | Alex Marginean <alexandru.marginean@nxp.com> | 2019-07-11 18:32:56 +0300 |
---|---|---|
committer | Joe Hershberger <joe.hershberger@ni.com> | 2019-07-19 00:37:13 +0300 |
commit | c38ac2893cc8f56365ab1084b2c5b06fc31dd697 (patch) | |
tree | bc477aae2481f2d48a5c469487fa1c9df5ce2e7a | |
parent | 3bf135b6c367ec67258a67eefbe1eeb7b984e12d (diff) | |
download | u-boot-c38ac2893cc8f56365ab1084b2c5b06fc31dd697.tar.xz |
net: add comments to phy APIs
Added a comment on the limitations of phy_find_by_mask API when scanning
MDIO buses with multiple PHYs present. Added short descriptions to the
other APIs in phy.h for consistency.
Signed-off-by: Alex Marginean <alexm.osslist@gmail.com>
Acked-by: Joe Hershberger <joe.hershberger@ni.com>
Reviewed-by: Bin Meng <bmeng.cn@gmail.com>
-rw-r--r-- | include/phy.h | 80 |
1 files changed, 80 insertions, 0 deletions
diff --git a/include/phy.h b/include/phy.h index d01435d1aa..f4530faeb9 100644 --- a/include/phy.h +++ b/include/phy.h @@ -246,15 +246,71 @@ static inline int is_10g_interface(phy_interface_t interface) #endif +/** + * phy_init() - Initializes the PHY drivers + * + * This function registers all available PHY drivers + * + * @return 0 if OK, -ve on error + */ int phy_init(void); + +/** + * phy_reset() - Resets the specified PHY + * + * Issues a reset of the PHY and waits for it to complete + * + * @phydev: PHY to reset + * @return 0 if OK, -ve on error + */ int phy_reset(struct phy_device *phydev); + +/** + * phy_find_by_mask() - Searches for a PHY on the specified MDIO bus + * + * The function checks the PHY addresses flagged in phy_mask and returns a + * phy_device pointer if it detects a PHY. + * This function should only be called if just one PHY is expected to be present + * in the set of addresses flagged in phy_mask. If multiple PHYs are present, + * it is undefined which of these PHYs is returned. + * + * @bus: MII/MDIO bus to scan + * @phy_mask: bitmap of PYH addresses to scan + * @interface: type of MAC-PHY interface + * @return pointer to phy_device if a PHY is found, or NULL otherwise + */ struct phy_device *phy_find_by_mask(struct mii_dev *bus, unsigned phy_mask, phy_interface_t interface); + #ifdef CONFIG_DM_ETH + +/** + * phy_connect_dev() - Associates the given pair of PHY and Ethernet devices + * @phydev: PHY device + * @dev: Ethernet device + */ void phy_connect_dev(struct phy_device *phydev, struct udevice *dev); + +/** + * phy_connect() - Creates a PHY device for the Ethernet interface + * + * Creates a PHY device for the PHY at the given address, if one doesn't exist + * already, and associates it with the Ethernet device. + * The function may be called with addr <= 0, in this case addr value is ignored + * and the bus is scanned to detect a PHY. Scanning should only be used if only + * one PHY is expected to be present on the MDIO bus, otherwise it is undefined + * which PHY is returned. + * + * @bus: MII/MDIO bus that hosts the PHY + * @addr: PHY address on MDIO bus + * @dev: Ethernet device to associate to the PHY + * @interface: type of MAC-PHY interface + * @return pointer to phy_device if a PHY is found, or NULL otherwise + */ struct phy_device *phy_connect(struct mii_dev *bus, int addr, struct udevice *dev, phy_interface_t interface); + static inline ofnode phy_get_ofnode(struct phy_device *phydev) { if (ofnode_valid(phydev->node)) @@ -263,10 +319,34 @@ static inline ofnode phy_get_ofnode(struct phy_device *phydev) return dev_ofnode(phydev->dev); } #else + +/** + * phy_connect_dev() - Associates the given pair of PHY and Ethernet devices + * @phydev: PHY device + * @dev: Ethernet device + */ void phy_connect_dev(struct phy_device *phydev, struct eth_device *dev); + +/** + * phy_connect() - Creates a PHY device for the Ethernet interface + * + * Creates a PHY device for the PHY at the given address, if one doesn't exist + * already, and associates it with the Ethernet device. + * The function may be called with addr <= 0, in this case addr value is ignored + * and the bus is scanned to detect a PHY. Scanning should only be used if only + * one PHY is expected to be present on the MDIO bus, otherwise it is undefined + * which PHY is returned. + * + * @bus: MII/MDIO bus that hosts the PHY + * @addr: PHY address on MDIO bus + * @dev: Ethernet device to associate to the PHY + * @interface: type of MAC-PHY interface + * @return pointer to phy_device if a PHY is found, or NULL otherwise + */ struct phy_device *phy_connect(struct mii_dev *bus, int addr, struct eth_device *dev, phy_interface_t interface); + static inline ofnode phy_get_ofnode(struct phy_device *phydev) { return ofnode_null(); |