Re: [PATCH v2] DT: net: document Ethernet bindings in one place

[Sergei Shtylyov <sergei.shtylyov@cogentembedded.com>]

Hello.

On 01/29/2014 07:16 PM, Rob Herring wrote:

>>>> This patch is an attempt to gather the Ethernet related bindings in one
>>>> file,
>>>> like it's done in the MMC and some other subsystems. It should save some
>>>> of
>>>> the trouble of documenting several properties over and over in each
>>>> binding
>>>> document, instead only making reference to the main file.

> [snip]

>>>>    - compatible: should be "allwinner,sun4i-emac".
>>>>    - reg: address and length of the register set for the device.
>>>>    - interrupts: interrupt for the device
>>>> -- phy: A phandle to a phy node defining the PHY address (as the reg
>>>> -  property, a single integer).
>>>> +- phy: see ethernet.txt file in the same directory.
>>>>    - clocks: A phandle to the reference clock for this device
>>>>
>>>>    Optional properties:
>>>> -- (local-)mac-address: mac address to be used by this driver
>>>> +- [local-]mac-address: see ethernet.txt file in the same directory

>>> Sorry, but I meant you should just have a single statement like:

>>> This binding uses standard ethernet properties defined in ethernet.txt.

>>     This way it won't be clear which of the properties are used and which are
>> not, no?

> You're right. For the phy properties we need to specify which ones are
> used. This could be done only for bindings using the not recommended
> properties.

> For optional properties like local-mac-address, I don't think these
> need to be listed. They can be used for all devices and whether or not
> a given Linux driver supports using the property is not really the
> concern of the binding documentation. An exception could be a device
> that requires a optional property (i.e. a NIC with no eeprom to store
> a MAC address).

    So, to avoid any ambiguities, will this fragment be OK with you:

Index: net-next/Documentation/devicetree/bindings/net/allwinner,sun4i-emac.txt
===================================================================
--- net-next.orig/Documentation/devicetree/bindings/net/allwinner,sun4i-emac.txt
+++ net-next/Documentation/devicetree/bindings/net/allwinner,sun4i-emac.txt
@@ -4,13 +4,9 @@ Required properties:
  - compatible: should be "allwinner,sun4i-emac".
  - reg: address and length of the register set for the device.
  - interrupts: interrupt for the device
-- phy: A phandle to a phy node defining the PHY address (as the reg
-  property, a single integer).
+- phy: see ethernet.txt file in the same directory.
  - clocks: A phandle to the reference clock for this device

-Optional properties:
-- (local-)mac-address: mac address to be used by this driver
-
  Example:

  emac: ethernet@01c0b000 {

    Or do I still need to insert "this binding uses standard Ethernet 
properties defined in ethernet.txt in the same directory" somewhere?

> Rob

WBR, Sergei