Re: [PATCH v2 2/3] dt-binding: net: sfp binding documentation

On 08/30/2017 02:25 PM, Baruch Siach wrote:

quoted

quoted

quoted

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>
---
v2:
     Rename -gpio properties to -gpios
     Rename the rate-select-gpio property to rate-select0-gpios
     Add the rate-select1-gpios property
     Add examples
---
    Documentation/devicetree/bindings/net/sff,sfp.txt | 74 +++++++++++++++++++++++
    1 file changed, 74 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..1d9c786d6287
--- /dev/null
+++ b/Documentation/devicetree/bindings/net/sff,sfp.txt

@@ -0,0 +1,74 @@
+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-gpios : phandle of the MOD-DEF0 (AKA Mod_ABS) module presence input
+  gpio signal

     Your example shows there's GPIO phandle *and* specifier.

Would "GPIO specifier" be enough here?

    No, specifier is the cells following GPIO (or any other) phandle.

So this should be "GPIO phandle and specifier of ...", is that correct?

    Exactly. The length of the GPIO specifier is determined by the 
"#gpio-cells" prop of the GPIO node your phandle refers to.

I have found very few (< 4) occurrences of this language in (lots of) '-gpios'
property descriptions under Documentation/devicetree/bindings/.

    You better see Documentation/devicetree/bindings/gpio/gpio.txt.

Is this a new
requirement?

    Not at all, and it's not limited to GPIOs. Nobody reads the specs. :-)

baruch

MBR, Sergei