From mboxrd@z Thu Jan 1 00:00:00 1970 From: Sergei Shtylyov Subject: Re: [PATCH v2] DT: net: document Ethernet bindings in one place Date: Fri, 31 Jan 2014 01:56:43 +0300 Message-ID: <52EAD8AB.6060905@cogentembedded.com> References: <201401280150.32456.sergei.shtylyov@cogentembedded.com> <52E7D31A.4090107@cogentembedded.com> Mime-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit Return-path: In-Reply-To: Sender: linux-doc-owner@vger.kernel.org To: Rob Herring Cc: Rob Herring , Pawel Moll , Mark Rutland , Ian Campbell , Kumar Gala , "devicetree@vger.kernel.org" , Rob Landley , "linux-doc@vger.kernel.org" , Max Filippov List-Id: devicetree@vger.kernel.org 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