Difference between revisions of "Ethernet device tree configuration"

[quality revision] [pending revision]

1 Article purpose[edit]

This article explains how to configure the Ethernet when it is assigned to the Linux® OS. In that case, it is controlled by the Ethernet framework

The configuration is performed using the device tree mechanism that provides a hardware description of the Ethernet peripheral, used by the STM32 DWMAC driver

2 DT bindings documentation[edit]

The Ethernet is a multifunction device.

Each function is represented by a separate binding document:

  • "Generic" Ethernet device tree bindings [1]
  • specific STM32 ETH device tree bindings[2]

3 DT configuration[edit]

This hardware description is a combination of the STM32 microprocessor device tree files (.dtsi extension) and board device tree files (.dts extension). See the Device tree for an explanation of the device tree file split.

3.1 DT configuration (STM32 level)[edit]

Ethernet peripheral nodes are located in stm32mp157c.dtsi [3] file with a disabled status and some required properties such as:

  • Physical base address and size of the device register map
  • STMMAC interrupts
  • stmmaceth clock and Rx, Tx clocks

This is a set of properties that may not vary for a given STM32MP device, such as: register addresses, interrupts, clocks, ...

ethernet0: ethernet@5800a000 {
	compatible = "st,stm32mp1-dwmac", "snps,dwmac-4.20a";
	reg = <0x5800a000 0x2000>;
	reg-names = "stmmaceth";
	interrupts-extended = <&intc GIC_SPI 61 IRQ_TYPE_NONE>;
	interrupt-names = "macirq";
	clock-names = "stmmaceth",
		      "mac-clk-tx",
		      "mac-clk-rx",
		      "ethstp",
		      "syscfg-clk";
	clocks = <&rcc ETHMAC>,
		 <&rcc ETHTX>,
		 <&rcc ETHRX>,
		 <&rcc ETHSTP>,
		 <&rcc SYSCFG>;
	st,syscon = <&syscfg 0x4>;
	snps,mixed-burst;
	snps,pbl = <2>;
	snps,axi-config = <&stmmac_axi_config_0>;
	snps,tso;
	power-domains = <&pd_core>;
	status = "disabled";
};

The required and optional properties are fully described in the bindings files.

Warning.png This device tree part is related to STM32 microprocessors. It must be kept as is, without being modified by the end-user.

3.2 Ethernet DT configuration (board level)[edit]

The device tree board file (.dts) contains all hardware configurations related to board design. The DT node ("ethernet") should be updated to:

  • Enable the Ethernet block by setting status = "okay".
  • Configure the pins in use via pinctrl, through pinctrl-0 (default pins), pinctrl-1 (sleep pins) and pinctrl-names.
  • Configure Ethernet interface used phy-mode = "rgmii"., (rmii, mii, gmii).
  • Configure Ethernet max speed max-speed = <1000>"..
&ethernet0 {
	status = "okay";
	pinctrl-0 = <&ethernet0_rgmii_pins_a>;
	pinctrl-1 = <&ethernet0_rgmii_pins_sleep_a>;
	pinctrl-names = "default", "sleep";
	phy-mode = "rgmii";
	max-speed = <1000>;
	phy-handle = <&phy0>;

	mdio0 {
		#address-cells = <1>;
		#size-cells = <0>;
		compatible = "snps,dwmac-mdio";
		phy0: ethernet-phy@1 {
			reg = <1>;
		};
	};
};

3.3 DT configuration examples[edit]

The example below shows how to configure and enable an Ethernet instance at board level:

&ethernet0 {
   status = "okay";                             /* enable ethernet0 */ 
   pinctrl-0 = <&ethernet0_rmii_pins_a>;        /* configure pinctrl modes for ethernet0 */
   pinctrl-1 = <&ethernet0_rmii_pins_sleep_a>;  /* configure ethernet0_rmii_pins_sleep_a as sleep pinctrl configuration for ethernet0 */
   pinctrl-names = "default", "sleep";
   phy-mode = "rmii";                           /* configure ethernet phy mode for ethernet0 */
   max-speed = <100>;                           /* configure ethernet max speed for ethernet0 */
   phy-handle = <&phy0>;
   
   mdio0 {
       #address-cells = <1>;
       #size-cells = <0>;
       compatible = "snps,dwmac-mdio";
       phy0: ethernet-phy@1 {
           reg = <1>;                           /* configure ethernet phy @ for ethernet0 */
       };
   };
};

4 How to configure Ethernet using CubeMX[edit]

The STM32CubeMX tool can be used to configure the STM32MPU device and get the corresponding platform configuration device tree files.
The STM32CubeMX may not support all the properties described in the above DT bindings documentation paragraph. If so, the tool inserts user sections in the generated device tree. These sections can then be edited to add some properties and they are preserved from one generation to another. Refer to STM32CubeMX user manual for further information.

5 References[edit]


== Article purpose ==
This article explains how to configure the [[ETH internal peripheral|Ethernet]] when it is assigned to the Linux<sup>&reg;</sup> OS. In that case, it is controlled by the [[Ethernet overview|Ethernet framework]]

The configuration is performed using the [[Device tree|device tree]] mechanism that provides a hardware description of the Ethernet peripheral, used by the STM32 DWMAC driver

== DT bindings documentation ==
The ''Ethernet'' is a multifunction device.

Each function is represented by a separate binding document:
* "Generic" Ethernet device tree bindings <ref>{{CodeSource | Linux kernel | Documentation/devicetree/bindings/net/stmmac.txt}}</ref>

* specific STM32 ETH device tree bindings<ref>{{CodeSource | Linux kernel | Documentation/devicetree/bindings/net/stm32-dwmac.txt}}</ref>


== DT configuration ==
This hardware description is a combination of the '''STM32 microprocessor''' device tree files (''.dtsi'' extension) and '''board''' device tree files (''.dts'' extension). See the [[Device tree]] for an explanation of the device tree file split. 

=== DT configuration (STM32 level) ===

Ethernet peripheral nodes are located in stm32mp157c.dtsi <ref>{{CodeSource | Linux kernel | arch/arm/boot/dts/stm32mp157c.dtsi | arch/arm/boot/dts/stm32mp157c.dtsi}}, STM32MP157C device tree file</ref> file with a disabled status and some required properties such as:
* Physical base address and size of the device register map
* STMMAC interrupts
* stmmaceth clock and Rx, Tx clocks

This is a set of properties that may not vary for a given STM32MP device, such as: register addresses, interrupts, clocks, ...
<pre>

ethernet0: ethernet@5800a000 {
	compatible = "st,stm32mp1-dwmac", "snps,dwmac-4.20a";
	reg = <0x5800a000 0x2000>;
	reg-names = "stmmaceth";
	interrupts-extended = <&intc GIC_SPI 61 IRQ_TYPE_NONE>;
	interrupt-names = "macirq";
	clock-names = "stmmaceth",
		      "mac-clk-tx",
		      "mac-clk-rx",
		      "ethstp",
		      "syscfg-clk";
	clocks = <&rcc ETHMAC>,<&rcc ETHTX>,<&rcc ETHRX>,<&rcc ETHSTP>,<&rcc SYSCFG>;
	st,syscon = <&syscfg 0x4>;
	snps,mixed-burst;
	snps,pbl = <2>;
	snps,axi-config = <&stmmac_axi_config_0>;
	snps,tso;
	power-domains = <&pd_core>;
	status = "disabled";
};</pre>


The required and optional properties are fully described in the [[Ethernet device tree configuration#DT bindings documentation|bindings files]].
{{Warning|This device tree part is related to STM32 microprocessors. It must be kept as is, without being modified by the end-user.}}

=== Ethernet DT configuration (board level) ===

The device tree board file (.dts) contains all hardware configurations related to board design. The DT node ('''"ethernet"''') should be updated to:

* Enable the Ethernet block by setting '''status = "okay".'''
* Configure the pins in use via [[Pinctrl overview|pinctrl]], through '''pinctrl-0''' (default pins), '''pinctrl-1''' (sleep pins) and '''pinctrl-names'''.
* Configure Ethernet interface used '''phy-mode = "rgmii".''', (rmii, mii, gmii).
* Configure Ethernet max speed '''max-speed = <1000>".'''.
<pre>

&ethernet0 {
	status = "okay";
	pinctrl-0 = <&ethernet0_rgmii_pins_a>;
	pinctrl-1 = <&ethernet0_rgmii_pins_sleep_a>;
	pinctrl-names = "default", "sleep";
	phy-mode = "rgmii";
	max-speed = <1000>;
	phy-handle = <&phy0>;

	mdio0 {
		#address-cells = <1>;
		#size-cells = <0>;
		compatible = "snps,dwmac-mdio";
		phy0: ethernet-phy@1 {
			reg = <1>;
		};
	};
};</pre>


=== DT configuration examples ===
The example below shows how to configure and enable an Ethernet instance at board level:

 &ethernet0 {
    status = "okay";                             {{highlight|/* enable ethernet0 */}} 
    pinctrl-0 = <&ethernet0_rmii_pins_a>;        {{highlight|/* configure pinctrl modes for ethernet0 */}}
    pinctrl-1 = <&ethernet0_rmii_pins_sleep_a>;  {{highlight|/* configure ethernet0_rmii_pins_sleep_a as sleep pinctrl configuration for ethernet0 */}}
    pinctrl-names = "default", "sleep";
    phy-mode = "rmii";                           {{highlight|/* configure ethernet phy mode for ethernet0 */}}
    max-speed = <100>;                           {{highlight|/* configure ethernet max speed for ethernet0 */}}
    phy-handle = <&phy0>;

    mdio0 {
        #address-cells = <1>;
        #size-cells = <0>;
        compatible = "snps,dwmac-mdio";
        phy0: ethernet-phy@1 {
            reg = <1>;                           {{highlight|/* configure ethernet phy @ for ethernet0 */}}
        };
    };
 };

== {{ReviewsComments|-- ECO 26 March2020 : Many customers loose time to set-up the device tree configuration. Please add all the configuration including FSBL clock when PHY clock is comming from RCC.

For each case below (from AN5031) it would be efficient to list all the properties needed  (including the clock configuration, see the RMrv4 RCC figure 83).
	1 RMII with 25MHz Crystal on PHY
	2 RMII with 25MHz on ETH_CLK (no PHY Crystal), REF_CLK from PHY
	3 RMII with 50MHz on ETH_CLK (no PHY Crystal), internal REF_CLK from RCC
	4 RGMII with Crystal on PHY, CLK125 from PHY
	5 RGMII with 25MHz on ETH_CLK (no PHY Crystal), CLK125 from PHY
	6 RGMII with 25MHz Crystal on PHY, internal CLK125 from RCC

ex
-> RMII with 50MHz on ETH_CLK (no PHY Crystal), internal REF_CLK from RCC
In Uboot / kernel device tree, in node "ethernet" add
1/ ETHCK_K 
 clock-names = "stmmaceth","mac-clk-tx","mac-clk-rx","ethstp","syscfg-clk",'''"eth-ck";'''
 clocks = <&rcc ETHMAC>,<&rcc ETHTX>,<&rcc ETHRX>,<&rcc ETHSTP>,<&rcc SYSCFG>,'''''<&rcc ETHCK_K>;'''''

 2/st,eth_ref_clk_sel;

3/In TF-A device tree, check if Ethernet kernel source is enabled.

=>ensure in the 'st,pkcs' property to CLK_ETH_PLL4P or CLK_ETH_PLL3Q 
If st,pkcs contains CLK_ETH_DISABLE, it means  PLL4P or PLL3Q must be setup 
}}
== How to configure Ethernet using CubeMX ==
The [[STM32CubeMX]] tool can be used to configure the STM32MPU device and get the corresponding [[Device_tree#STM32|platform configuration device tree]] files.<br />

The STM32CubeMX may not support all the properties described in the above [[#DT bindings documentation|DT bindings documentation]] paragraph. If so, the tool inserts '''user sections''' in the generated device tree. These sections can then be edited to add some properties and they are preserved from one generation to another. Refer to [[STM32CubeMX]] user manual for further information.

==References==<references />

<noinclude>

[[Category:Device tree configuration]]
[[Category:Ethernet]]
{{PublicationRequestId | 10170 | 2019-01-02 | BrunoB}}
{{ArticleBasedOnModel | Peripheral or framework device tree configuration model}}</noinclude>
Line 104: Line 104:
 
     };
 
     };
 
  };
 
  };
  +
{{ReviewsComments|-- ECO 26 March2020 : Many customers loose time to set-up the device tree configuration. Please add all the configuration including FSBL clock when PHY clock is comming from RCC.
   
  +
For each case below (from AN5031) it would be efficient to list all the properties needed  (including the clock configuration, see the RMrv4 RCC figure 83).
  +
1 RMII with 25MHz Crystal on PHY
  +
2 RMII with 25MHz on ETH_CLK (no PHY Crystal), REF_CLK from PHY
  +
3 RMII with 50MHz on ETH_CLK (no PHY Crystal), internal REF_CLK from RCC
  +
4 RGMII with Crystal on PHY, CLK125 from PHY
  +
5 RGMII with 25MHz on ETH_CLK (no PHY Crystal), CLK125 from PHY
  +
6 RGMII with 25MHz Crystal on PHY, internal CLK125 from RCC
  +
  +
ex
  +
-> RMII with 50MHz on ETH_CLK (no PHY Crystal), internal REF_CLK from RCC
  +
In Uboot / kernel device tree, in node "ethernet" add
  +
1/ ETHCK_K
  +
clock-names = "stmmaceth","mac-clk-tx","mac-clk-rx","ethstp","syscfg-clk",'''"eth-ck";'''
  +
clocks = <&rcc ETHMAC>,<&rcc ETHTX>,<&rcc ETHRX>,<&rcc ETHSTP>,<&rcc SYSCFG>,'''''<&rcc ETHCK_K>;'''''
  +
  +
2/st,eth_ref_clk_sel;
  +
  +
3/In TF-A device tree, check if Ethernet kernel source is enabled.
  +
  +
=>ensure in the 'st,pkcs' property to CLK_ETH_PLL4P or CLK_ETH_PLL3Q
  +
If st,pkcs contains CLK_ETH_DISABLE, it means  PLL4P or PLL3Q must be setup
  +
}}
 
== How to configure Ethernet using CubeMX ==
 
== How to configure Ethernet using CubeMX ==
 
The [[STM32CubeMX]] tool can be used to configure the STM32MPU device and get the corresponding [[Device_tree#STM32|platform configuration device tree]] files.<br />
 
The [[STM32CubeMX]] tool can be used to configure the STM32MPU device and get the corresponding [[Device_tree#STM32|platform configuration device tree]] files.<br />

Attachments

Discussions