@@ -155,6 +155,21 @@ PHY Support
.. kernel-doc:: drivers/net/phy/mdio_bus.c
:internal:
+.. kernel-doc:: drivers/net/phy/mdio_device.c
+ :export:
+
+.. kernel-doc:: drivers/net/phy/mdio_device.c
+ :internal:
+
+.. kernel-doc:: drivers/net/phy/mdio_devres.c
+ :export:
+
+.. kernel-doc:: include/linux/mdio.h
+ :internal:
+
+.. kernel-doc:: drivers/net/phy/mdio-boardinfo.c
+ :export:
+
PHYLINK
-------
@@ -106,6 +106,15 @@ int mdiobus_unregister_device(struct mdio_device *mdiodev)
}
EXPORT_SYMBOL(mdiobus_unregister_device);
+/**
+ * mdiobus_get_phy - Get the device at the address on the bus
+ *
+ * @bus: MDIO bus of interest
+ * @addr: Address on bus of device
+ *
+ * If there is a device registered on the bus for the given address
+ * return the device. Else return NULL.
+ */
struct phy_device *mdiobus_get_phy(struct mii_bus *bus, int addr)
{
struct mdio_device *mdiodev = bus->mdio_map[addr];
@@ -120,6 +129,16 @@ struct phy_device *mdiobus_get_phy(struct mii_bus *bus, int addr)
}
EXPORT_SYMBOL(mdiobus_get_phy);
+/**
+ * mdiobus_is_registered_device - Is there a device registered at the
+ * address on the bus
+ *
+ * @bus: MDIO bus of interest
+ * @addr: Address on bus of device
+ *
+ * Returns True if there is a device registered on the bus for the given address.
+ * Otherwise False.
+ */
bool mdiobus_is_registered_device(struct mii_bus *bus, int addr)
{
return bus->mdio_map[addr];
@@ -603,6 +622,14 @@ int __mdiobus_register(struct mii_bus *bus, struct module *owner)
}
EXPORT_SYMBOL(__mdiobus_register);
+/**
+ * mdiobus_unregister - Unregister an MDIO bus
+ *
+ * @bus: target mii_bus
+ *
+ * For all devices on the bus, any GPIOs held are released. If the bus
+ * as a reset GPIO the devices on the bus are put into reset
+ */
void mdiobus_unregister(struct mii_bus *bus)
{
struct mdio_device *mdiodev;
@@ -1002,6 +1029,11 @@ struct bus_type mdio_bus_type = {
};
EXPORT_SYMBOL(mdio_bus_type);
+/**
+ * mdio_bus_init - Initialize the MDIO bus subsystem
+ *
+ * Register the MDIO bus class and the MDIO bus type
+ */
int __init mdio_bus_init(void)
{
int ret;
@@ -1018,6 +1050,11 @@ int __init mdio_bus_init(void)
EXPORT_SYMBOL_GPL(mdio_bus_init);
#if IS_ENABLED(CONFIG_PHYLIB)
+/**
+ * mdio_bus_exit - Cleanup the MDIO bus subsystem
+ *
+ * Unregister the MDIO bus class and the MDIO bus type
+ */
void mdio_bus_exit(void)
{
class_unregister(&mdio_bus_class);
@@ -44,6 +44,12 @@ int mdio_device_bus_match(struct device *dev, struct device_driver *drv)
return strcmp(mdiodev->modalias, drv->name) == 0;
}
+/**
+ * mdio_device_create - Create an MDIO device
+ *
+ * @bus: Bus the device is on
+ * @addr: Address of the device on the bus
+ */
struct mdio_device *mdio_device_create(struct mii_bus *bus, int addr)
{
struct mdio_device *mdiodev;
@@ -113,6 +119,17 @@ void mdio_device_remove(struct mdio_device *mdiodev)
}
EXPORT_SYMBOL(mdio_device_remove);
+/**
+ * mdio_device_reset - Reset the MDIO device
+ *
+ * @mdiodev: Device to reset
+ * @value: 1 for reset, 0 for out of reset
+ *
+ * Place the device into our out of reset, depending on the value of
+ * @value. Reset the device via a GPIO of a reset controller. If
+ * delays have been defined, wait the given time after change the
+ * reset.
+ */
void mdio_device_reset(struct mdio_device *mdiodev, int value)
{
unsigned int d;
@@ -206,6 +223,10 @@ int mdio_driver_register(struct mdio_driver *drv)
}
EXPORT_SYMBOL(mdio_driver_register);
+/**
+ * mdio_driver_unregister - Unregister an MDIO driver
+ * @drv: mdio_driver to unregister
+ */
void mdio_driver_unregister(struct mdio_driver *drv)
{
struct mdio_driver_common *mdiodrv = &drv->mdiodrv;
@@ -31,6 +31,21 @@ enum mdio_mutex_lock_class {
MDIO_MUTEX_NESTED,
};
+/**
+ * struct mdio_device - A device on an MDIO bus
+ *
+ * @dev: Kernel device representation
+ * @bus: The MDIO bus this device is on
+ * @modalias: Alias of device driver
+ * @bus_match: Function to match driver to device
+ * @device_free: Free any resources used by the device
+ * @device_remove: Called before removing the device from the kernel
+ * @flags: Flags about the device, e.g. is it a PHY
+ * @reset_gpio: GPIO to reset the device
+ * @reset_ctrl: Reset controller to reset the device
+ * @reset_assert_delay: How long to old the device in reset
+ * @reset_deassert_delay: How long to wait after resetting the device
+ */
struct mdio_device {
struct device dev;
@@ -41,7 +56,7 @@ struct mdio_device {
void (*device_free)(struct mdio_device *mdiodev);
void (*device_remove)(struct mdio_device *mdiodev);
- /* Bus address of the MDIO device (0-31) */
+ /** @addr: Bus address of the MDIO device (0-31) */
int addr;
int flags;
struct gpio_desc *reset_gpio;
@@ -51,7 +66,12 @@ struct mdio_device {
};
#define to_mdio_device(d) container_of(d, struct mdio_device, dev)
-/* struct mdio_driver_common: Common to all MDIO drivers */
+/**
+ * struct mdio_driver_common - Common to all MDIO drivers
+ *
+ * @driver: Kernel driver representation
+ * @flags: Flags about this driver
+ */
struct mdio_driver_common {
struct device_driver driver;
int flags;
@@ -60,28 +80,41 @@ struct mdio_driver_common {
#define to_mdio_common_driver(d) \
container_of(d, struct mdio_driver_common, driver)
-/* struct mdio_driver: Generic MDIO driver */
+/**
+ * struct mdio_driver - Generic MDIO driver
+ * @mdiodrv: Common part to all MDIO drivers
+ */
struct mdio_driver {
struct mdio_driver_common mdiodrv;
- /*
- * Called during discovery. Used to set
+ /**
+ * @probe: Called during discovery. Used to set
* up device-specific structures, if any
*/
int (*probe)(struct mdio_device *mdiodev);
- /* Clears up any memory if needed */
+ /** @remove: Clears up any memory if needed */
void (*remove)(struct mdio_device *mdiodev);
};
#define to_mdio_driver(d) \
container_of(to_mdio_common_driver(d), struct mdio_driver, mdiodrv)
-/* device driver data */
+/**
+ * mdiodev_set_drvdata - Set the device driver data
+ *
+ * @mdio: MDIO device to set the driver data for
+ * @data: Pointer to the data
+ */
static inline void mdiodev_set_drvdata(struct mdio_device *mdio, void *data)
{
dev_set_drvdata(&mdio->dev, data);
}
+/**
+ * mdiodev_get_drvdata - Get the device driver data associated with the device
+ *
+ * @mdio: MDIO device to get the driver data for
+ */
static inline void *mdiodev_get_drvdata(struct mdio_device *mdio)
{
return dev_get_drvdata(&mdio->dev);
@@ -96,16 +129,31 @@ int mdio_driver_register(struct mdio_driver *drv);
void mdio_driver_unregister(struct mdio_driver *drv);
int mdio_device_bus_match(struct device *dev, struct device_driver *drv);
+/**
+ * mdio_phy_id_is_c45 - Is the PHY id for a C45 transfer
+ *
+ * @phy_id: PHY address to determine if it is C45, otherwise C22
+ */
static inline bool mdio_phy_id_is_c45(int phy_id)
{
return (phy_id & MDIO_PHY_ID_C45) && !(phy_id & ~MDIO_PHY_ID_C45_MASK);
}
+/*
+ * mdio_phy_id_prtad - Return the part address
+ *
+ * @phy_id: PHY address to return the part address of
+ */
static inline __u16 mdio_phy_id_prtad(int phy_id)
{
return (phy_id & MDIO_PHY_ID_PRTAD) >> 5;
}
+/*
+ * mdio_phy_id_devad - Return the device address
+ *
+ * @phy_id: PHY address to return the device address of
+ */
static inline __u16 mdio_phy_id_devad(int phy_id)
{
return phy_id & MDIO_PHY_ID_DEVAD;
@@ -334,6 +382,15 @@ int mdiobus_write_nested(struct mii_bus *bus, int addr, u32 regnum, u16 val);
int mdiobus_modify(struct mii_bus *bus, int addr, u32 regnum, u16 mask,
u16 set);
+/**
+ * mdiobus_c44_addr - Construct a C45 Address
+ *
+ * @devad: Device address
+ * @regnum: Register number
+ *
+ * C45 accesses comprise of a device address and a register address, plus
+ * a flag to indicate it is a C45 address.
+ */
static inline u32 mdiobus_c45_addr(int devad, u16 regnum)
{
return MII_ADDR_C45 | devad << MII_DEVADDR_C45_SHIFT | regnum;
@@ -352,12 +409,29 @@ static inline int __mdiobus_c45_write(struct mii_bus *bus, int prtad, int devad,
val);
}
+/**
+ * mdiobus_c45_read - Helper to perform a C45 read
+ *
+ * @bus: MDIO bus the device is on
+ * @prtad: Part address
+ * @devad: Device address
+ * @regnum: Register to read
+ */
static inline int mdiobus_c45_read(struct mii_bus *bus, int prtad, int devad,
u16 regnum)
{
return mdiobus_read(bus, prtad, mdiobus_c45_addr(devad, regnum));
}
+/**
+ * mdiobus_c45_write - Helper to perform a C45 write
+ *
+ * @bus: MDIO bus the device is on
+ * @prtad: Part address
+ * @devad: Device address
+ * @regnum: Register to write
+ * @val: Value to write to the register
+ */
static inline int mdiobus_c45_write(struct mii_bus *bus, int prtad, int devad,
u16 regnum, u16 val)
{
Document the main structures, a few inline helpers and exported functions which are not already documented. Signed-off-by: Andrew Lunn <andrew@lunn.ch> --- Documentation/networking/kapi.rst | 15 ++++++ drivers/net/phy/mdio_bus.c | 37 +++++++++++++ drivers/net/phy/mdio_device.c | 21 ++++++++ include/linux/mdio.h | 88 ++++++++++++++++++++++++++++--- 4 files changed, 154 insertions(+), 7 deletions(-)