[PATCH v2] net: miiphybb: Update documentation

[Heinrich Schuchardt]

On 08.03.25 21:36, Marek Vasut wrote:
> Update the miiphybb documentation to match current implementation.
> The static struct bb_miiphy_bus bb_miiphy_buses[] array is removed.
> The example is updated to match current Renesas RAVB driver, which
> is one of the miiphybb users.
> 
> Reviewed-by: Paul Barker <paul.barker.ct at bp.renesas.com>
> Signed-off-by: Marek Vasut <marek.vasut+renesas at mailbox.org>
> ---
> Cc: Jim Liu <jim.t90615 at gmail.com>
> Cc: Joe Hershberger <joe.hershberger at ni.com>
> Cc: Mario Six <mario.six at gdsys.cc>
> Cc: Michael Chang <zhang971090220 at gmail.com>
> Cc: Nobuhiro Iwamatsu <iwamatsu at nigauri.org>
> Cc: Parvathi Bhogaraju <pbhogaraju at microsoft.com>
> Cc: Paul Barker <paul.barker.ct at bp.renesas.com>
> Cc: Ramon Fried <rfried.dev at gmail.com>
> Cc: Tom Rini <trini at konsulko.com>
> Cc: u-boot at lists.denx.de
> ---
> V2: - Fix language bugs
>      - Add RB from Paul
> ---
>   doc/README.bitbangMII | 66 ++++++++++++++++++++++++++++++-------------

It would be preferable to move this document into doc/devel/ as .rst file.

>   1 file changed, 47 insertions(+), 19 deletions(-)
> 
> diff --git a/doc/README.bitbangMII b/doc/README.bitbangMII
> index 05ab20376f3..78b4ef880cb 100644
> --- a/doc/README.bitbangMII
> +++ b/doc/README.bitbangMII
> @@ -1,39 +1,67 @@
> -This patch rewrites the miiphybb ( Bit-banged MII bus driver ) in order to
> -support an arbitrary number of mii buses. This feature is useful when your
> -board uses different mii buses for different phys and all (or a part) of these
> -buses are implemented via bit-banging mode.
> +The miiphybb ( Bit-banged MII bus driver ) supports an arbitrary number of
> +MII buses. This feature is useful when a driver uses different MII buses for
> +different PHYs and all (or a part) of these buses are implemented via
> +bit-banging mode.
>   
>   The driver requires that the following macros should be defined into the board

CONFIG_BITBANGMII=y enables the miiphybb driver.

>   configuration file:
>   
>   CONFIG_BITBANGMII	- Enable the miiphybb driver
>   
> -The board code needs to fill the bb_miiphy_buses[] array with a record for
> -each required bus and declare the bb_miiphy_buses_num variable with the
> -number of mii buses. The record (struct bb_miiphy_bus) has the following
> +The driver code needs to allocate a regular MDIO device using mdio_alloc()
> +and assign .read and .write accessors which wrap bb_miiphy_read() and
> +bb_miiphy_write() functions respectively. The bb_miiphy_read() and
> +bb_miiphy_write() functions take a pointer to a callback structure,
> +struct bb_miiphy_bus_ops. The struct bb_miiphy_bus_ops has the following
>   fields/callbacks (see miiphy.h for details):

Please, add the description of struct bb_miiphy_bus_op miiphy.h and add 
the file to the API documentation. You could also put the example and 
the programming guidance there.

Best regards

Heinrich

>   
> -char name[]	       - The symbolic name that must be equal to the MII bus
> -			 registered name
> -int (*init)()	       - Initialization function called at startup time (just
> -			 before the Ethernet initialization)
>   int (*mdio_active)()   - Activate the MDIO pin as output
>   int (*mdio_tristate)() - Activate the MDIO pin as input/tristate pin
>   int (*set_mdio)()      - Write the MDIO pin
>   int (*get_mdio)()      - Read the MDIO pin
>   int (*set_mdc)()       - Write the MDC pin
>   int (*delay)()	       - Delay function
> -void *priv	       - Private data used by board specific code
>   
> -The board code will look like:
> +The driver code will look like:
>   
> -struct bb_miiphy_bus bb_miiphy_buses[] = {
> - { .name = "miibus#1", .init = b1_init, .mdio_active = b1_mdio_active, ... },
> - { .name = "miibus#2", .init = b2_init, .mdio_active = b2_mdio_active, ... },
> - ...
> +static const struct bb_miiphy_bus_ops ravb_bb_miiphy_bus_ops = {
> +	.mdio_active	= ravb_bb_mdio_active,
> +	.mdio_tristate	= ravb_bb_mdio_tristate,
> +	.set_mdio	= ravb_bb_set_mdio,
> +	.get_mdio	= ravb_bb_get_mdio,
> +	.set_mdc	= ravb_bb_set_mdc,
> +	.delay		= ravb_bb_delay,
>   };
> -int bb_miiphy_buses_num = sizeof(bb_miiphy_buses) /
> -			  sizeof(bb_miiphy_buses[0]);
> +
> +static int ravb_bb_miiphy_read(struct mii_dev *miidev, int addr,
> +			       int devad, int reg)
> +{
> +	return bb_miiphy_read(miidev, &ravb_bb_miiphy_bus_ops,
> +			      addr, devad, reg);
> +}
> +
> +static int ravb_bb_miiphy_write(struct mii_dev *miidev, int addr,
> +				int devad, int reg, u16 value)
> +{
> +	return bb_miiphy_write(miidev, &ravb_bb_miiphy_bus_ops,
> +			       addr, devad, reg, value);
> +}
> +
> +static int ravb_probe(struct udevice *dev)
> +{
> +	struct mii_dev *mdiodev;
> +...
> +	mdiodev = mdio_alloc();
> +	if (!mdiodev)
> +		return -ENOMEM;
> +
> +	mdiodev->read = ravb_bb_miiphy_read;
> +	mdiodev->write = ravb_bb_miiphy_write;
> +	mdiodev->priv = eth;
> +	snprintf(mdiodev->name, sizeof(mdiodev->name), dev->name);
> +
> +	ret = mdio_register(mdiodev);
> +...
>   
>   2009 Industrie Dial Face S.p.A.
>        Luigi 'Comio' Mantellini <luigi.mantellini at idf-hit.com>