[RFC PATCH] dt-binding: net: sfp binding documentation

[RFC PATCH] dt-binding: net: sfp binding documentation

[Baruch Siach]

Add device-tree binding documentation SFP transceivers. Support for SFP
transceivers has been recently introduced (drivers/net/phy/sfp.c).

Signed-off-by: Baruch Siach <baruch@tkos.co.il>
---

The SFP driver is on net-next.

Not sure about the rate-select-gpio property name. The SFP+ standard
(not supported yet) uses two signals, RS0 and RS1. RS0 is compatible
with the SFP rate select signal, while RS1 controls the Tx rate.
---
 Documentation/devicetree/bindings/net/sff-sfp.txt | 24 +++++++++++++++++++++++
 1 file changed, 24 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/net/sff-sfp.txt

diff --git a/Documentation/devicetree/bindings/net/sff-sfp.txt b/Documentation/devicetree/bindings/net/sff-sfp.txt
new file mode 100644
index 000000000000..f0c27bc3925e
--- /dev/null
+++ b/Documentation/devicetree/bindings/net/sff-sfp.txt
@@ -0,0 +1,24 @@
+Small Form Factor (SFF) Committee Small Form-factor Pluggable (SFP)
+Transceiver
+
+Required properties:
+
+- compatible : must be "sff,sfp"
+
+Optional Properties:
+
+- i2c-bus : phandle of an I2C bus controller for the SFP two wire serial
+  interface
+
+- moddef0-gpio : phandle of the MOD-DEF0 (AKA Mod_ABS) module presence input
+  gpio signal
+
+- los-gpio : phandle of the Receiver Loss of Signal Indication input gpio
+  signal
+
+- tx-fault-gpio : phandle of the Module Transmitter Fault input gpio signal
+
+- tx-disable-gpio : phandle of the Transmitter Disable output gpio signal
+
+- rate-select-gpio : phandle of the Rx Signaling Rate Select (AKA RS0) output
+  gpio
-- 
2.14.1

Re: [RFC PATCH] dt-binding: net: sfp binding documentation

[Russell King - ARM Linux]

On Sun, Aug 20, 2017 at 01:28:06PM +0300, Baruch Siach wrote:
> Add device-tree binding documentation SFP transceivers. Support for SFP
> transceivers has been recently introduced (drivers/net/phy/sfp.c).
> 
> Signed-off-by: Baruch Siach <baruch@tkos.co.il>
> ---
> 
> The SFP driver is on net-next.
> 
> Not sure about the rate-select-gpio property name. The SFP+ standard
> (not supported yet) uses two signals, RS0 and RS1. RS0 is compatible
> with the SFP rate select signal, while RS1 controls the Tx rate.

SFP+ is usable with this, but the platforms I have do not wire the
rate select pins on the SFP+ sockets to GPIOs, but hard-wire them.

Note that I didn't expect the SFP code to just get merged with very
little in the way of real in-depth review of things like:

* the way the SFP code works, and its structure
* analysis of the bindings checking that they're fit for everyone's
  purposes.

The implementation that I've designed is based around the boards that
I have access to and the various public SFP documentation.  I think
documenting the bindings suggests that they are stable - I don't think
we're really ready to make that assertion yet - there may be things
that have been missed which will only come up when other people start
using this code.

> ---
>  Documentation/devicetree/bindings/net/sff-sfp.txt | 24 +++++++++++++++++++++++
>  1 file changed, 24 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/net/sff-sfp.txt
> 
> diff --git a/Documentation/devicetree/bindings/net/sff-sfp.txt b/Documentation/devicetree/bindings/net/sff-sfp.txt
> new file mode 100644
> index 000000000000..f0c27bc3925e
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/net/sff-sfp.txt
> @@ -0,0 +1,24 @@
> +Small Form Factor (SFF) Committee Small Form-factor Pluggable (SFP)
> +Transceiver
> +
> +Required properties:
> +
> +- compatible : must be "sff,sfp"
> +
> +Optional Properties:
> +
> +- i2c-bus : phandle of an I2C bus controller for the SFP two wire serial
> +  interface

The code as it currently stands pretty much requires an I2C bus to be
functional - but when I wrote the code, I left the possibility open for
an implementation (eg, network driver) to provide its own functionality
for reading the I2C EEPROM on the module.  Some adapters which already
have SFP support do this.

Hence, for current implementations, this is required.

> +
> +- moddef0-gpio : phandle of the MOD-DEF0 (AKA Mod_ABS) module presence input
> +  gpio signal
> +
> +- los-gpio : phandle of the Receiver Loss of Signal Indication input gpio
> +  signal
> +
> +- tx-fault-gpio : phandle of the Module Transmitter Fault input gpio signal
> +
> +- tx-disable-gpio : phandle of the Transmitter Disable output gpio signal
> +
> +- rate-select-gpio : phandle of the Rx Signaling Rate Select (AKA RS0) output
> +  gpio
> -- 
> 2.14.1
> 

-- 
RMK's Patch system: http://www.armlinux.org.uk/developer/patches/
FTTC broadband for 0.8mile line in suburbia: sync at 8.8Mbps down 630kbps up
According to speedtest.net: 8.21Mbps down 510kbps up

Re: [RFC PATCH] dt-binding: net: sfp binding documentation

[Andrew Lunn]

> The implementation that I've designed is based around the boards that
> I have access to and the various public SFP documentation.  I think
> documenting the bindings suggests that they are stable - I don't think
> we're really ready to make that assertion yet - there may be things
> that have been missed which will only come up when other people start
> using this code.

Hi Russell

That was the point of merging the code. It gets it into people hands
so they can start using it. I want to add support for DSA to make use
of phylink, since i have a couple of boards with SFF connected to
switch ports. I know Cumulus have interest in the code, for their
switches and so do Westermo. 

       Andrew
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC PATCH] dt-binding: net: sfp binding documentation

[Baruch Siach]

Hi Russell,

On Mon, Aug 21, 2017 at 01:53:17PM +0100, Russell King - ARM Linux wrote:
> On Sun, Aug 20, 2017 at 01:28:06PM +0300, Baruch Siach wrote:
> > Add device-tree binding documentation SFP transceivers. Support for SFP
> > transceivers has been recently introduced (drivers/net/phy/sfp.c).
> > 
> > Signed-off-by: Baruch Siach <baruch@tkos.co.il>
> > ---
> > 
> > The SFP driver is on net-next.
> > 
> > Not sure about the rate-select-gpio property name. The SFP+ standard
> > (not supported yet) uses two signals, RS0 and RS1. RS0 is compatible
> > with the SFP rate select signal, while RS1 controls the Tx rate.
> 
> SFP+ is usable with this, but the platforms I have do not wire the
> rate select pins on the SFP+ sockets to GPIOs, but hard-wire them.

So maybe naming this signal 'rate-select0-gpio' would make it more future 
(SPF+) proof? Or 'rate-select-rx-gpio'?

> Note that I didn't expect the SFP code to just get merged with very
> little in the way of real in-depth review of things like:
> 
> * the way the SFP code works, and its structure
> * analysis of the bindings checking that they're fit for everyone's
>   purposes.

I was also surprised to see the "sff,sfp" compatible string with no ack from 
DT maintainers. Hence this RFC.

> The implementation that I've designed is based around the boards that
> I have access to and the various public SFP documentation.  I think
> documenting the bindings suggests that they are stable - I don't think
> we're really ready to make that assertion yet - there may be things
> that have been missed which will only come up when other people start
> using this code.

baruch

-- 
     http://baruch.siach.name/blog/                  ~. .~   Tk Open Systems
=}------------------------------------------------ooO--U--Ooo------------{=
   - baruch@tkos.co.il - tel: +972.2.679.5364, http://www.tkos.co.il -

Re: [RFC PATCH] dt-binding: net: sfp binding documentation

[Rob Herring]

On Mon, Aug 21, 2017 at 10:06 AM, Baruch Siach <baruch-NswTu9S1W3P6gbPvEgmw2w@public.gmane.org> wrote:
> Hi Russell,
>
> On Mon, Aug 21, 2017 at 01:53:17PM +0100, Russell King - ARM Linux wrote:
>> On Sun, Aug 20, 2017 at 01:28:06PM +0300, Baruch Siach wrote:
>> > Add device-tree binding documentation SFP transceivers. Support for SFP
>> > transceivers has been recently introduced (drivers/net/phy/sfp.c).
>> >
>> > Signed-off-by: Baruch Siach <baruch-NswTu9S1W3P6gbPvEgmw2w@public.gmane.org>
>> > ---
>> >
>> > The SFP driver is on net-next.
>> >
>> > Not sure about the rate-select-gpio property name. The SFP+ standard
>> > (not supported yet) uses two signals, RS0 and RS1. RS0 is compatible
>> > with the SFP rate select signal, while RS1 controls the Tx rate.
>>
>> SFP+ is usable with this, but the platforms I have do not wire the
>> rate select pins on the SFP+ sockets to GPIOs, but hard-wire them.
>
> So maybe naming this signal 'rate-select0-gpio' would make it more future
> (SPF+) proof? Or 'rate-select-rx-gpio'?

Just extend it by making it an array of 2 gpios.

Rob
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC PATCH] dt-binding: net: sfp binding documentation

[Russell King - ARM Linux]

On Mon, Aug 21, 2017 at 02:12:42PM -0500, Rob Herring wrote:
> On Mon, Aug 21, 2017 at 10:06 AM, Baruch Siach <baruch@tkos.co.il> wrote:
> > Hi Russell,
> >
> > On Mon, Aug 21, 2017 at 01:53:17PM +0100, Russell King - ARM Linux wrote:
> >> On Sun, Aug 20, 2017 at 01:28:06PM +0300, Baruch Siach wrote:
> >> > Add device-tree binding documentation SFP transceivers. Support for SFP
> >> > transceivers has been recently introduced (drivers/net/phy/sfp.c).
> >> >
> >> > Signed-off-by: Baruch Siach <baruch@tkos.co.il>
> >> > ---
> >> >
> >> > The SFP driver is on net-next.
> >> >
> >> > Not sure about the rate-select-gpio property name. The SFP+ standard
> >> > (not supported yet) uses two signals, RS0 and RS1. RS0 is compatible
> >> > with the SFP rate select signal, while RS1 controls the Tx rate.
> >>
> >> SFP+ is usable with this, but the platforms I have do not wire the
> >> rate select pins on the SFP+ sockets to GPIOs, but hard-wire them.
> >
> > So maybe naming this signal 'rate-select0-gpio' would make it more future
> > (SPF+) proof? Or 'rate-select-rx-gpio'?
> 
> Just extend it by making it an array of 2 gpios.

What do you do if you have only one rate select wired up and it doesn't
correspond with the first?

-- 
RMK's Patch system: http://www.armlinux.org.uk/developer/patches/
FTTC broadband for 0.8mile line in suburbia: sync at 8.8Mbps down 630kbps up
According to speedtest.net: 8.21Mbps down 510kbps up

Re: [RFC PATCH] dt-binding: net: sfp binding documentation

[Rob Herring]

On Wed, Aug 23, 2017 at 8:57 AM, Russell King - ARM Linux
<linux-I+IVW8TIWO2tmTQ+vhA3Yw@public.gmane.org> wrote:
> On Mon, Aug 21, 2017 at 02:12:42PM -0500, Rob Herring wrote:
>> On Mon, Aug 21, 2017 at 10:06 AM, Baruch Siach <baruch-NswTu9S1W3P6gbPvEgmw2w@public.gmane.org> wrote:
>> > Hi Russell,
>> >
>> > On Mon, Aug 21, 2017 at 01:53:17PM +0100, Russell King - ARM Linux wrote:
>> >> On Sun, Aug 20, 2017 at 01:28:06PM +0300, Baruch Siach wrote:
>> >> > Add device-tree binding documentation SFP transceivers. Support for SFP
>> >> > transceivers has been recently introduced (drivers/net/phy/sfp.c).
>> >> >
>> >> > Signed-off-by: Baruch Siach <baruch-NswTu9S1W3P6gbPvEgmw2w@public.gmane.org>
>> >> > ---
>> >> >
>> >> > The SFP driver is on net-next.
>> >> >
>> >> > Not sure about the rate-select-gpio property name. The SFP+ standard
>> >> > (not supported yet) uses two signals, RS0 and RS1. RS0 is compatible
>> >> > with the SFP rate select signal, while RS1 controls the Tx rate.
>> >>
>> >> SFP+ is usable with this, but the platforms I have do not wire the
>> >> rate select pins on the SFP+ sockets to GPIOs, but hard-wire them.
>> >
>> > So maybe naming this signal 'rate-select0-gpio' would make it more future
>> > (SPF+) proof? Or 'rate-select-rx-gpio'?
>>
>> Just extend it by making it an array of 2 gpios.
>
> What do you do if you have only one rate select wired up and it doesn't
> correspond with the first?

Seems unlikely, but possible I guess. In that case, 2 properties is
probably better. Otherwise, you'd have to put in -1 or 0 for the first
phandle.

Rob
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC PATCH] dt-binding: net: sfp binding documentation

[Russell King - ARM Linux]

On Mon, Aug 21, 2017 at 06:06:53PM +0300, Baruch Siach wrote:
> Hi Russell,
> 
> On Mon, Aug 21, 2017 at 01:53:17PM +0100, Russell King - ARM Linux wrote:
> > Note that I didn't expect the SFP code to just get merged with very
> > little in the way of real in-depth review of things like:
> > 
> > * the way the SFP code works, and its structure
> > * analysis of the bindings checking that they're fit for everyone's
> >   purposes.
> 
> I was also surprised to see the "sff,sfp" compatible string with no ack from 
> DT maintainers. Hence this RFC.

I've been pushed into submitting the code for merging, and I hadn't
got around to writing the DT docs (thanks for doing that).  As I've
already said, I'm disappointed that the code didn't get more of a
review before it was merged - it seems Linux review is not what it
was, people care more about reviewing for spelling errors and style
than code structure and functionality, stating that "if we don't like
it we can always rework it" or similar.

It also seems that people believe that they can't make use of other
people's work until it gets merged into mainline kernels (which is
what has been behind the pressure of getting this merged.)

What isn't realised is that having other people use the code before
it gets merged allows design issues to be identified and resolved
when there is great flexibility available - for example, changing the
DT binding.  Once it's merged, changing DT bindings becomes harder,
especially if they need to be changed in an incompatible way.

I'm fed up about this, and way past caring about these details today
through.

-- 
RMK's Patch system: http://www.armlinux.org.uk/developer/patches/
FTTC broadband for 0.8mile line in suburbia: sync at 8.8Mbps down 630kbps up
According to speedtest.net: 8.21Mbps down 510kbps up

Re: [RFC PATCH] dt-binding: net: sfp binding documentation

[Rob Herring]

On Sun, Aug 20, 2017 at 5:28 AM, Baruch Siach <baruch-NswTu9S1W3P6gbPvEgmw2w@public.gmane.org> wrote:
> Add device-tree binding documentation SFP transceivers. Support for SFP
> transceivers has been recently introduced (drivers/net/phy/sfp.c).
>
> Signed-off-by: Baruch Siach <baruch-NswTu9S1W3P6gbPvEgmw2w@public.gmane.org>
> ---
>
> The SFP driver is on net-next.
>
> Not sure about the rate-select-gpio property name. The SFP+ standard
> (not supported yet) uses two signals, RS0 and RS1. RS0 is compatible
> with the SFP rate select signal, while RS1 controls the Tx rate.
> ---
>  Documentation/devicetree/bindings/net/sff-sfp.txt | 24 +++++++++++++++++++++++
>  1 file changed, 24 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/net/sff-sfp.txt
>
> diff --git a/Documentation/devicetree/bindings/net/sff-sfp.txt b/Documentation/devicetree/bindings/net/sff-sfp.txt
> new file mode 100644
> index 000000000000..f0c27bc3925e
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/net/sff-sfp.txt
> @@ -0,0 +1,24 @@
> +Small Form Factor (SFF) Committee Small Form-factor Pluggable (SFP)
> +Transceiver
> +
> +Required properties:
> +
> +- compatible : must be "sff,sfp"

Need to document "sff" vendor prefix.

Kind of a short name, but I guess it is sufficient. Are there
revisions of the standard (not SFP+) or more than one form factor (I
don't recall any)?

> +
> +Optional Properties:
> +
> +- i2c-bus : phandle of an I2C bus controller for the SFP two wire serial
> +  interface

Why not a child of the i2c bus it is on? IOW, what should this be a child of?

> +
> +- moddef0-gpio : phandle of the MOD-DEF0 (AKA Mod_ABS) module presence input
> +  gpio signal

mod-def0-gpios?

> +
> +- los-gpio : phandle of the Receiver Loss of Signal Indication input gpio
> +  signal
> +
> +- tx-fault-gpio : phandle of the Module Transmitter Fault input gpio signal
> +
> +- tx-disable-gpio : phandle of the Transmitter Disable output gpio signal
> +
> +- rate-select-gpio : phandle of the Rx Signaling Rate Select (AKA RS0) output
> +  gpio

-gpios is the preferred form for all of these.

> --
> 2.14.1
>
> --
> To unsubscribe from this list: send the line "unsubscribe devicetree" in
> the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC PATCH] dt-binding: net: sfp binding documentation

[Baruch Siach]

Hi Rob,

On Mon, Aug 21, 2017 at 02:10:33PM -0500, Rob Herring wrote:
> On Sun, Aug 20, 2017 at 5:28 AM, Baruch Siach <baruch@tkos.co.il> wrote:
> > Add device-tree binding documentation SFP transceivers. Support for SFP
> > transceivers has been recently introduced (drivers/net/phy/sfp.c).
> >
> > Signed-off-by: Baruch Siach <baruch@tkos.co.il>
> > ---
> >
> > The SFP driver is on net-next.

[...]

> > +Optional Properties:
> > +
> > +- i2c-bus : phandle of an I2C bus controller for the SFP two wire serial
> > +  interface
> 
> Why not a child of the i2c bus it is on? IOW, what should this be a child of?

As I understand form the code the ID of the SFP i2c slave is derived from the 
Ethernet PHY 'reg' property. The PHY node's 'sfp' property points to a phandle 
of the sff,sfp node.

It is also possible for the 'sfp' property to appear directly in the Ethernet 
device node.

Quoting RMK from merge commit 234709336b8 (net-next):

    To add to the complexity, SFP modules can be connected in at least
    two places:
    
    1. Directly to the serdes output of a MAC with no intervening PHY.
       For example:
    
         mvneta ----> SFP socket
    
    2. To a PHY, for example:
    
         mvpp2 ---> PHY ---> copper
                     |
                     `-----> SFP socket
    
    This code supports both setups, although it's not fully implemented
    with scenario (2).

baruch

-- 
     http://baruch.siach.name/blog/                  ~. .~   Tk Open Systems
=}------------------------------------------------ooO--U--Ooo------------{=
   - baruch@tkos.co.il - tel: +972.2.679.5364, http://www.tkos.co.il -

Re: [RFC PATCH] dt-binding: net: sfp binding documentation

[Andrew Lunn]

On Wed, Aug 23, 2017 at 03:16:53PM +0300, Baruch Siach wrote:
> Hi Rob,
> 
> On Mon, Aug 21, 2017 at 02:10:33PM -0500, Rob Herring wrote:
> > On Sun, Aug 20, 2017 at 5:28 AM, Baruch Siach <baruch@tkos.co.il> wrote:
> > > Add device-tree binding documentation SFP transceivers. Support for SFP
> > > transceivers has been recently introduced (drivers/net/phy/sfp.c).
> > >
> > > Signed-off-by: Baruch Siach <baruch@tkos.co.il>
> > > ---
> > >
> > > The SFP driver is on net-next.
> 
> [...]
> 
> > > +Optional Properties:
> > > +
> > > +- i2c-bus : phandle of an I2C bus controller for the SFP two wire serial
> > > +  interface
> > 
> > Why not a child of the i2c bus it is on? IOW, what should this be a child of?
> 
> As I understand form the code the ID of the SFP i2c slave is derived from the 
> Ethernet PHY 'reg' property. The PHY node's 'sfp' property points to a phandle 
> of the sff,sfp node.

Hi Rob

The SFP module uses multiple addresses on the i2c bus. 0x50 is
something like an EEPROM, but some of the content is
dynamic. Depending of the version of the standard, it can also use
0x51 for additional information. If the SPF module contains a copper
PHY, it also uses another address on the i2c bus for the standard
copper PHY registers.

An SFP module does not fit the usual I2C client model, since it is a
collection of interconnected i2c clients in one package.

	   Andrew

Re: [RFC PATCH] dt-binding: net: sfp binding documentation

[Baruch Siach]

Hi Rob,

On Mon, Aug 21, 2017 at 02:10:33PM -0500, Rob Herring wrote:
> On Sun, Aug 20, 2017 at 5:28 AM, Baruch Siach <baruch-NswTu9S1W3P6gbPvEgmw2w@public.gmane.org> wrote:
> > Add device-tree binding documentation SFP transceivers. Support for SFP
> > transceivers has been recently introduced (drivers/net/phy/sfp.c).
> >
> > Signed-off-by: Baruch Siach <baruch-NswTu9S1W3P6gbPvEgmw2w@public.gmane.org>
> > ---
> >
> > The SFP driver is on net-next.
> >
> > Not sure about the rate-select-gpio property name. The SFP+ standard
> > (not supported yet) uses two signals, RS0 and RS1. RS0 is compatible
> > with the SFP rate select signal, while RS1 controls the Tx rate.
> > ---
> >  Documentation/devicetree/bindings/net/sff-sfp.txt | 24 +++++++++++++++++++++++
> >  1 file changed, 24 insertions(+)
> >  create mode 100644 Documentation/devicetree/bindings/net/sff-sfp.txt
> >
> > diff --git a/Documentation/devicetree/bindings/net/sff-sfp.txt b/Documentation/devicetree/bindings/net/sff-sfp.txt
> > new file mode 100644
> > index 000000000000..f0c27bc3925e
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/net/sff-sfp.txt
> > @@ -0,0 +1,24 @@
> > +Small Form Factor (SFF) Committee Small Form-factor Pluggable (SFP)
> > +Transceiver
> > +
> > +Required properties:
> > +
> > +- compatible : must be "sff,sfp"
> 
> Need to document "sff" vendor prefix.

"sff" stands for Small Form Factor Committee, now under Storage Networking 
Industry Association (SNIA). Not really a vendor, but a standards body. Does 
that count? I could not find any other example in vendor-prefixes.txt, other 
than "linux" which is kind of special.

> Kind of a short name, but I guess it is sufficient. Are there
> revisions of the standard (not SFP+) or more than one form factor (I
> don't recall any)?

I'm not aware of any other revisions.

baruch

-- 
     http://baruch.siach.name/blog/                  ~. .~   Tk Open Systems
=}------------------------------------------------ooO--U--Ooo------------{=
   - baruch-NswTu9S1W3P6gbPvEgmw2w@public.gmane.org - tel: +972.2.679.5364, http://www.tkos.co.il -
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC PATCH] dt-binding: net: sfp binding documentation

[Rob Herring]

On Tue, Aug 22, 2017 at 07:49:01AM +0300, Baruch Siach wrote:
> Hi Rob,
> 
> On Mon, Aug 21, 2017 at 02:10:33PM -0500, Rob Herring wrote:
> > On Sun, Aug 20, 2017 at 5:28 AM, Baruch Siach <baruch-NswTu9S1W3P6gbPvEgmw2w@public.gmane.org> wrote:
> > > Add device-tree binding documentation SFP transceivers. Support for SFP
> > > transceivers has been recently introduced (drivers/net/phy/sfp.c).
> > >
> > > Signed-off-by: Baruch Siach <baruch-NswTu9S1W3P6gbPvEgmw2w@public.gmane.org>
> > > ---
> > >
> > > The SFP driver is on net-next.
> > >
> > > Not sure about the rate-select-gpio property name. The SFP+ standard
> > > (not supported yet) uses two signals, RS0 and RS1. RS0 is compatible
> > > with the SFP rate select signal, while RS1 controls the Tx rate.
> > > ---
> > >  Documentation/devicetree/bindings/net/sff-sfp.txt | 24 +++++++++++++++++++++++
> > >  1 file changed, 24 insertions(+)
> > >  create mode 100644 Documentation/devicetree/bindings/net/sff-sfp.txt
> > >
> > > diff --git a/Documentation/devicetree/bindings/net/sff-sfp.txt b/Documentation/devicetree/bindings/net/sff-sfp.txt
> > > new file mode 100644
> > > index 000000000000..f0c27bc3925e
> > > --- /dev/null
> > > +++ b/Documentation/devicetree/bindings/net/sff-sfp.txt
> > > @@ -0,0 +1,24 @@
> > > +Small Form Factor (SFF) Committee Small Form-factor Pluggable (SFP)
> > > +Transceiver
> > > +
> > > +Required properties:
> > > +
> > > +- compatible : must be "sff,sfp"
> > 
> > Need to document "sff" vendor prefix.
> 
> "sff" stands for Small Form Factor Committee, now under Storage Networking 
> Industry Association (SNIA). Not really a vendor, but a standards body. Does 
> that count? I could not find any other example in vendor-prefixes.txt, other 
> than "linux" which is kind of special.

sff is fine. I'd be fine with 'snia' too. Just need to add it to vendor 
prefixes.

One more thing, use "sff,sfp.txt" matching the compatible for the 
filename.

> 
> > Kind of a short name, but I guess it is sufficient. Are there
> > revisions of the standard (not SFP+) or more than one form factor (I
> > don't recall any)?
> 
> I'm not aware of any other revisions.

Okay.

Rob
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC PATCH] dt-binding: net: sfp binding documentation

[Russell King - ARM Linux]

On Mon, Aug 21, 2017 at 02:10:33PM -0500, Rob Herring wrote:
> On Sun, Aug 20, 2017 at 5:28 AM, Baruch Siach <baruch-NswTu9S1W3P6gbPvEgmw2w@public.gmane.org> wrote:
> > Add device-tree binding documentation SFP transceivers. Support for SFP
> > transceivers has been recently introduced (drivers/net/phy/sfp.c).
> >
> > Signed-off-by: Baruch Siach <baruch-NswTu9S1W3P6gbPvEgmw2w@public.gmane.org>
> > ---
> >
> > The SFP driver is on net-next.
> >
> > Not sure about the rate-select-gpio property name. The SFP+ standard
> > (not supported yet) uses two signals, RS0 and RS1. RS0 is compatible
> > with the SFP rate select signal, while RS1 controls the Tx rate.
> > ---
> >  Documentation/devicetree/bindings/net/sff-sfp.txt | 24 +++++++++++++++++++++++
> >  1 file changed, 24 insertions(+)
> >  create mode 100644 Documentation/devicetree/bindings/net/sff-sfp.txt
> >
> > diff --git a/Documentation/devicetree/bindings/net/sff-sfp.txt b/Documentation/devicetree/bindings/net/sff-sfp.txt
> > new file mode 100644
> > index 000000000000..f0c27bc3925e
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/net/sff-sfp.txt
> > @@ -0,0 +1,24 @@
> > +Small Form Factor (SFF) Committee Small Form-factor Pluggable (SFP)
> > +Transceiver
> > +
> > +Required properties:
> > +
> > +- compatible : must be "sff,sfp"
> 
> Need to document "sff" vendor prefix.
> 
> Kind of a short name, but I guess it is sufficient. Are there
> revisions of the standard (not SFP+) or more than one form factor (I
> don't recall any)?

The standards get revised and reorganised, so you can't really name any
particular standard.  SFP+ is a supplement to SFP, and I suspect that's
going to continue into the future.

> > +
> > +Optional Properties:
> > +
> > +- i2c-bus : phandle of an I2C bus controller for the SFP two wire serial
> > +  interface
> 
> Why not a child of the i2c bus it is on? IOW, what should this be a child of?

What reg= value would you use to identify it?  There's no particular
I2C bus address.  There's an EEPROM on the actual module, and there
may be a PHY on the I2C bus (some PHYs include I2C as an alternative
way to speak to them other than MDIO.)

I2C couldn't probe these as they are effectively hotplugged.

However, there's also the question about why it should be a child of
the I2C bus - the I2C bus is just a means of communicating with and
identifying the module.  You could equally argue that it should be
a child of the GPIO controller, because that's how it's controlled.
You could also argue that it should be a child of the ethernet
interface, since that's the main data path.

> > +
> > +- moddef0-gpio : phandle of the MOD-DEF0 (AKA Mod_ABS) module presence input
> > +  gpio signal
> 
> mod-def0-gpios?

It all depends on the standard you read.  Some call it MOD_DEF0, Mod-DEF0,
Mod_ABS, and some call it MOD-DEF0.  And confusingly, some standards call
the binary combination of the three MOD-DEF signals "MOD-DEF 0"...
"MOD-DEF 7".  These signals come from the GBIC module era.  It's something
of a mess.

> > +
> > +- los-gpio : phandle of the Receiver Loss of Signal Indication input gpio
> > +  signal
> > +
> > +- tx-fault-gpio : phandle of the Module Transmitter Fault input gpio signal
> > +
> > +- tx-disable-gpio : phandle of the Transmitter Disable output gpio signal
> > +
> > +- rate-select-gpio : phandle of the Rx Signaling Rate Select (AKA RS0) output
> > +  gpio
> 
> -gpios is the preferred form for all of these.

Even if there's only _one_ - using the plural leads one to think that
you can list many GPIOs, which is not correct here.

-- 
RMK's Patch system: http://www.armlinux.org.uk/developer/patches/
FTTC broadband for 0.8mile line in suburbia: sync at 8.8Mbps down 630kbps up
According to speedtest.net: 8.21Mbps down 510kbps up
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html