Re: [PATCH net-next v3 2/8] dt-bindings: net: Add SoC-e SWIP MDIO controller

[Vasilij Strassheim <v.strassheim@linutronix.de>]

On Wed, 2026-09-30 at 17:14 +0200, Andrew Lunn wrote:
> On Wed, Sep 30, 2026 at 04:00:56PM +0200, Vasilij Strassheim wrote:
> > On Sat, 2026-09-26 at 00:55 +0200, Andrew Lunn wrote:
> > > > The controller exposes separate register regions for transaction data
> > > > and for the shared transaction control and external bus selector
> > > > register.
> > > 
> > > > +examples:
> > > > +  - |
> > > > +    mdio@204 {
> > > > +        compatible = "soce,swip-mdio-23-02";
> > > > +        reg = <0x204 0xc>, <0x200 0x4>;
> > > 
> > > At least in the example, they are not separate?
> > 
> > Not separate regions but registers...
> > I'm obviously bad at documenting things.
> > 
> > The current information in the commit message is misleading and
> > irrelevant. Looking at the bot's feedback, it's at the same time not
> > clear enough yet that the mdio controller part is mapped within the
> > switch memory and can't be used separately from it.
> > 
> > I will update the commit message to something like this:
> > Add a binding for the MDIO controller integrated into SoC-e SWIP
> > Ethernet switch IP cores.
> > The controller shares the memory of the synthesized switch IP core and
> > cannot be used independently.
> 
> I think part of the issue is the compatible. That suggests it is a
> separate device, with its own driver. But it is actually driven by the
> switch driver.

I can't avoid the compatible right now. Somehow it is still a separate
functionality. I hope the following example doesn't cause unnecessary
confusion, but rather helps to understand the system better:

The relationship between the MDIO controller and the switch core is more
like that of tools in a Swiss Army knife.
There are a few standalone tools, such as the knife and the screwdriver.
These can also be described on their own. But they only make sense when
they are attached to the knife as a whole. As soon as one takes it
apart, the individual tools can no longer be used effectively. At the
same time, no one needs to worry about the screwdriver if they only need
the knife.

I haven't found anything that I could use as a reference for the
documentation, so far. So right now, I can't think of a better solution
than document it as clearly as possible for the next version.
Do you (or anyone else) have any advice on the best way for me to describe
this in the documentation?

> 
>        Andrew

Thanks,
Vasilij