[4/4] dt-bindings: Document the DT bindings for lan78xx

[4/4] dt-bindings: Document the DT bindings for lan78xx

[Phil Elwell]

The Microchip LAN78XX family of devices are Ethernet controllers with
a USB interface. Despite being discoverable devices it can be useful to
be able to configure them from Device Tree, particularly in low-cost
applications without an EEPROM or programmed OTP.

Document the supported properties in a bindings file, adding it to
MAINTAINERS at the same time.

Signed-off-by: Phil Elwell <phil@raspberrypi.org>
---
 .../devicetree/bindings/net/microchip,lan78xx.txt  | 44 ++++++++++++++++++++++
 MAINTAINERS                                        |  1 +
 2 files changed, 45 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/net/microchip,lan78xx.txt

diff --git a/Documentation/devicetree/bindings/net/microchip,lan78xx.txt b/Documentation/devicetree/bindings/net/microchip,lan78xx.txt
new file mode 100644
index 0000000..e7d7850
--- /dev/null
+++ b/Documentation/devicetree/bindings/net/microchip,lan78xx.txt
@@ -0,0 +1,44 @@
+Microchip LAN78xx Gigabit Ethernet controller
+
+The LAN78XX devices are usually configured by programming their OTP or with
+an external EEPROM, but some platforms (e.g. Raspberry Pi 3 B+) have neither.
+
+Please refer to ethernet.txt for a description of common Ethernet bindings.
+
+Optional properties:
+- microchip,eee-enabled: if present, enable Energy Efficient Ethernet support;
+- microchip,led-modes: a two-element vector, with each element configuring
+  the operating mode of an LED. The values supported by the device are;
+  0: Link/Activity
+  1: Link1000/Activity
+  2: Link100/Activity
+  3: Link10/Activity
+  4: Link100/1000/Activity
+  5: Link10/1000/Activity
+  6: Link10/100/Activity
+  7: RESERVED
+  8: Duplex/Collision
+  9: Collision
+  10: Activity
+  11: RESERVED
+  12: Auto-negotiation Fault
+  13: RESERVED
+  14: Off
+  15: On
+- microchip,tx-lpi-timer: the delay (in microseconds) between the TX fifo
+  becoming empty and invoking Low Power Idles (default 600).
+
+Example:
+
+	/* Standard configuration for a Raspberry Pi 3 B+ */
+	ethernet: usbether@1 {
+		compatible = "usb424,7800";
+		reg = <1>;
+		microchip,eee-enabled;
+		microchip,tx-lpi-timer = <600>;
+		/*
+		 * led0 = 1:link1000/activity
+		 * led1 = 6:link10/100/activity
+		 */
+		microchip,led-modes = <1 6>;
+	};
diff --git a/MAINTAINERS b/MAINTAINERS
index 2328eed..b637aad 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -14482,6 +14482,7 @@ M:	Microchip Linux Driver Support <UNGLinuxDriver@microchip.com>
 L:	netdev@vger.kernel.org
 S:	Maintained
 F:	drivers/net/usb/lan78xx.*
+F:	Documentation/devicetree/bindings/net/microchip,lan78xx.txt
 
 USB MASS STORAGE DRIVER
 M:	Alan Stern <stern@rowland.harvard.edu>

[4/4] dt-bindings: Document the DT bindings for lan78xx

[Andrew Lunn]

On Thu, Apr 12, 2018 at 02:55:36PM +0100, Phil Elwell wrote:
> The Microchip LAN78XX family of devices are Ethernet controllers with
> a USB interface. Despite being discoverable devices it can be useful to
> be able to configure them from Device Tree, particularly in low-cost
> applications without an EEPROM or programmed OTP.
> 
> Document the supported properties in a bindings file, adding it to
> MAINTAINERS at the same time.

Hi Phil

How you link an OF node to a USB device is not obvious. Could you
please include either a pointer to some binding documentation, or make
your example show it.

Thanks
	Andrew
---
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[4/4] dt-bindings: Document the DT bindings for lan78xx

[Phil Elwell]

Hi Andrew,

On 12/04/2018 15:04, Andrew Lunn wrote:
> On Thu, Apr 12, 2018 at 02:55:36PM +0100, Phil Elwell wrote:
>> The Microchip LAN78XX family of devices are Ethernet controllers with
>> a USB interface. Despite being discoverable devices it can be useful to
>> be able to configure them from Device Tree, particularly in low-cost
>> applications without an EEPROM or programmed OTP.
>>
>> Document the supported properties in a bindings file, adding it to
>> MAINTAINERS at the same time.
> 
> Hi Phil
> 
> How you link an OF node to a USB device is not obvious. Could you
> please include either a pointer to some binding documentation, or make
> your example show it.

Thanks for the feedback. Would you consider this (lifted from the Pi 3B+ Device Tree)
a sufficient example?

&usb {
	usb1@1 {
		compatible = "usb424,2514";
		reg = <1>;
		#address-cells = <1>;
		#size-cells = <0>;

		usb1_1@1 {
			compatible = "usb424,2514";
			reg = <1>;
			#address-cells = <1>;
			#size-cells = <0>;

			ethernet: usbether@1 {
				compatible = "usb424,7800";
				reg = <1>;
				microchip,eee-enabled;
				microchip,tx-lpi-timer = <600>; /* non-aggressive*/
				/*
				 * led0 = 1:link1000/activity
				 * led1 = 6:link10/100/activity
				 */
				microchip,led-modes = <1 6>;
			};
		};
	};
};

Phil
---
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[4/4] dt-bindings: Document the DT bindings for lan78xx

[Andrew Lunn]

On Thu, Apr 12, 2018 at 03:10:57PM +0100, Phil Elwell wrote:
> Hi Andrew,
> 
> On 12/04/2018 15:04, Andrew Lunn wrote:
> > On Thu, Apr 12, 2018 at 02:55:36PM +0100, Phil Elwell wrote:
> >> The Microchip LAN78XX family of devices are Ethernet controllers with
> >> a USB interface. Despite being discoverable devices it can be useful to
> >> be able to configure them from Device Tree, particularly in low-cost
> >> applications without an EEPROM or programmed OTP.
> >>
> >> Document the supported properties in a bindings file, adding it to
> >> MAINTAINERS at the same time.
> > 
> > Hi Phil
> > 
> > How you link an OF node to a USB device is not obvious. Could you
> > please include either a pointer to some binding documentation, or make
> > your example show it.
> 
> Thanks for the feedback. Would you consider this (lifted from the Pi 3B+ Device Tree)
> a sufficient example?

Yes, this is good.

Thanks
     Andrew
---
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[4/4] dt-bindings: Document the DT bindings for lan78xx

[Andrew Lunn]

On Thu, Apr 12, 2018 at 02:55:36PM +0100, Phil Elwell wrote:
> The Microchip LAN78XX family of devices are Ethernet controllers with
> a USB interface. Despite being discoverable devices it can be useful to
> be able to configure them from Device Tree, particularly in low-cost
> applications without an EEPROM or programmed OTP.

It would be good to document what happens when there is an EEPROM. Is
OF used in preference to the EEPROM?
   
Andrew
---
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[4/4] dt-bindings: Document the DT bindings for lan78xx

[Phil Elwell]

Hi Andrew,

On 12/04/2018 15:30, Andrew Lunn wrote:
> On Thu, Apr 12, 2018 at 02:55:36PM +0100, Phil Elwell wrote:
>> The Microchip LAN78XX family of devices are Ethernet controllers with
>> a USB interface. Despite being discoverable devices it can be useful to
>> be able to configure them from Device Tree, particularly in low-cost
>> applications without an EEPROM or programmed OTP.
> 
> It would be good to document what happens when there is an EEPROM. Is
> OF used in preference to the EEPROM?

Yes it is. I'll mention it in V2.

Phil
---
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[4/4] dt-bindings: Document the DT bindings for lan78xx

[Rob Herring]

On Thu, Apr 12, 2018 at 02:55:36PM +0100, Phil Elwell wrote:
> The Microchip LAN78XX family of devices are Ethernet controllers with
> a USB interface. Despite being discoverable devices it can be useful to
> be able to configure them from Device Tree, particularly in low-cost
> applications without an EEPROM or programmed OTP.
> 
> Document the supported properties in a bindings file, adding it to
> MAINTAINERS at the same time.
> 
> Signed-off-by: Phil Elwell <phil@raspberrypi.org>
> ---
>  .../devicetree/bindings/net/microchip,lan78xx.txt  | 44 ++++++++++++++++++++++
>  MAINTAINERS                                        |  1 +
>  2 files changed, 45 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/net/microchip,lan78xx.txt
> 
> diff --git a/Documentation/devicetree/bindings/net/microchip,lan78xx.txt b/Documentation/devicetree/bindings/net/microchip,lan78xx.txt
> new file mode 100644
> index 0000000..e7d7850
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/net/microchip,lan78xx.txt
> @@ -0,0 +1,44 @@
> +Microchip LAN78xx Gigabit Ethernet controller
> +
> +The LAN78XX devices are usually configured by programming their OTP or with
> +an external EEPROM, but some platforms (e.g. Raspberry Pi 3 B+) have neither.
> +
> +Please refer to ethernet.txt for a description of common Ethernet bindings.
> +
> +Optional properties:
> +- microchip,eee-enabled: if present, enable Energy Efficient Ethernet support;

I see we have some flags for broken EEE, but nothing already defined to 
enable EEE. Seems like this should either be a user option (therefore 
not in DT) or we should use the broken EEE properties if this is h/w 
dependent.

> +- microchip,led-modes: a two-element vector, with each element configuring
> +  the operating mode of an LED. The values supported by the device are;
> +  0: Link/Activity
> +  1: Link1000/Activity
> +  2: Link100/Activity
> +  3: Link10/Activity
> +  4: Link100/1000/Activity
> +  5: Link10/1000/Activity
> +  6: Link10/100/Activity
> +  7: RESERVED
> +  8: Duplex/Collision
> +  9: Collision
> +  10: Activity
> +  11: RESERVED
> +  12: Auto-negotiation Fault
> +  13: RESERVED
> +  14: Off
> +  15: On
> +- microchip,tx-lpi-timer: the delay (in microseconds) between the TX fifo
> +  becoming empty and invoking Low Power Idles (default 600).

Needs a unit suffix as defined in property-units.txt.

> +
> +Example:
> +
> +	/* Standard configuration for a Raspberry Pi 3 B+ */
> +	ethernet: usbether@1 {
> +		compatible = "usb424,7800";
> +		reg = <1>;
> +		microchip,eee-enabled;
> +		microchip,tx-lpi-timer = <600>;
> +		/*
> +		 * led0 = 1:link1000/activity
> +		 * led1 = 6:link10/100/activity
> +		 */
> +		microchip,led-modes = <1 6>;
> +	};
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 2328eed..b637aad 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -14482,6 +14482,7 @@ M:	Microchip Linux Driver Support <UNGLinuxDriver@microchip.com>
>  L:	netdev@vger.kernel.org
>  S:	Maintained
>  F:	drivers/net/usb/lan78xx.*
> +F:	Documentation/devicetree/bindings/net/microchip,lan78xx.txt
>  
>  USB MASS STORAGE DRIVER
>  M:	Alan Stern <stern@rowland.harvard.edu>
> -- 
> 2.7.4
>
---
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[4/4] dt-bindings: Document the DT bindings for lan78xx

[Phil Elwell]

On 16/04/2018 20:22, Rob Herring wrote:
> On Thu, Apr 12, 2018 at 02:55:36PM +0100, Phil Elwell wrote:
>> The Microchip LAN78XX family of devices are Ethernet controllers with
>> a USB interface. Despite being discoverable devices it can be useful to
>> be able to configure them from Device Tree, particularly in low-cost
>> applications without an EEPROM or programmed OTP.
>>
>> Document the supported properties in a bindings file, adding it to
>> MAINTAINERS at the same time.
>>
>> Signed-off-by: Phil Elwell <phil@raspberrypi.org>
>> ---
>>  .../devicetree/bindings/net/microchip,lan78xx.txt  | 44 ++++++++++++++++++++++
>>  MAINTAINERS                                        |  1 +
>>  2 files changed, 45 insertions(+)
>>  create mode 100644 Documentation/devicetree/bindings/net/microchip,lan78xx.txt
>>
>> diff --git a/Documentation/devicetree/bindings/net/microchip,lan78xx.txt b/Documentation/devicetree/bindings/net/microchip,lan78xx.txt
>> new file mode 100644
>> index 0000000..e7d7850
>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/net/microchip,lan78xx.txt
>> @@ -0,0 +1,44 @@
>> +Microchip LAN78xx Gigabit Ethernet controller
>> +
>> +The LAN78XX devices are usually configured by programming their OTP or with
>> +an external EEPROM, but some platforms (e.g. Raspberry Pi 3 B+) have neither.
>> +
>> +Please refer to ethernet.txt for a description of common Ethernet bindings.
>> +
>> +Optional properties:
>> +- microchip,eee-enabled: if present, enable Energy Efficient Ethernet support;
> 
> I see we have some flags for broken EEE, but nothing already defined to 
> enable EEE. Seems like this should either be a user option (therefore 
> not in DT) or we should use the broken EEE properties if this is h/w 
> dependent.

In the downstream Raspberry Pi kernel we use DT as a way of passing user settings
to drivers - it's more powerful than the command line. I understand that this is
not the done thing here so I'm withdrawing this element of the patch series.

Apologies for the noise.

>> +- microchip,led-modes: a two-element vector, with each element configuring
>> +  the operating mode of an LED. The values supported by the device are;
>> +  0: Link/Activity
>> +  1: Link1000/Activity
>> +  2: Link100/Activity
>> +  3: Link10/Activity
>> +  4: Link100/1000/Activity
>> +  5: Link10/1000/Activity
>> +  6: Link10/100/Activity
>> +  7: RESERVED
>> +  8: Duplex/Collision
>> +  9: Collision
>> +  10: Activity
>> +  11: RESERVED
>> +  12: Auto-negotiation Fault
>> +  13: RESERVED
>> +  14: Off
>> +  15: On
>> +- microchip,tx-lpi-timer: the delay (in microseconds) between the TX fifo
>> +  becoming empty and invoking Low Power Idles (default 600).
> 
> Needs a unit suffix as defined in property-units.txt.
> 
>> +
>> +Example:
>> +
>> +	/* Standard configuration for a Raspberry Pi 3 B+ */
>> +	ethernet: usbether@1 {
>> +		compatible = "usb424,7800";
>> +		reg = <1>;
>> +		microchip,eee-enabled;
>> +		microchip,tx-lpi-timer = <600>;
>> +		/*
>> +		 * led0 = 1:link1000/activity
>> +		 * led1 = 6:link10/100/activity
>> +		 */
>> +		microchip,led-modes = <1 6>;
>> +	};
>> diff --git a/MAINTAINERS b/MAINTAINERS
>> index 2328eed..b637aad 100644
>> --- a/MAINTAINERS
>> +++ b/MAINTAINERS
>> @@ -14482,6 +14482,7 @@ M:	Microchip Linux Driver Support <UNGLinuxDriver@microchip.com>
>>  L:	netdev@vger.kernel.org
>>  S:	Maintained
>>  F:	drivers/net/usb/lan78xx.*
>> +F:	Documentation/devicetree/bindings/net/microchip,lan78xx.txt
>>  
>>  USB MASS STORAGE DRIVER
>>  M:	Alan Stern <stern@rowland.harvard.edu>
>> -- 
>> 2.7.4
>>
---
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html