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

[Rob Herring <robherring2@gmail.com>]

On Tue, Jan 28, 2014 at 9:56 AM, Sergei Shtylyov
<sergei.shtylyov@cogentembedded.com> wrote:
> On 01/28/2014 04:38 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).

Rob