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

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

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.

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

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:

quoted

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 -

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:

quoted

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