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 --- include/phy.h | 80 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 80 insertions(+)

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();