Synopsys DWC Ethernet QoS 4.10

요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.

1. 요약·해설

원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.

요약과 해설

snps,dwc-qos-ethernet.txt:1-168

Deprecated binding의 compatible별 필수 resource를 표로 정리합니다.

2. 영어 원문 전체

번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.

원문 전체 펼치기

1 * Synopsys DWC Ethernet QoS IP version 4.10 driver (GMAC)

3 This binding is deprecated, but it continues to be supported, but new

4 features should be preferably added to the stmmac binding document.

6 This binding supports the Synopsys Designware Ethernet QoS (Quality Of Service)

7 IP block. The IP supports multiple options for bus type, clocking and reset

8 structure, and feature list. Consequently, a number of properties and list

9 entries in properties are marked as optional, or only required in specific HW

10 configurations.

12 Required properties:

13 - compatible: One of:

14 - "axis,artpec6-eqos", "snps,dwc-qos-ethernet-4.10"

15 Represents the IP core when integrated into the Axis ARTPEC-6 SoC.

16 - "nvidia,tegra186-eqos", "snps,dwc-qos-ethernet-4.10"

17 Represents the IP core when integrated into the NVIDIA Tegra186 SoC.

18 - "snps,dwc-qos-ethernet-4.10"

19 This combination is deprecated. It should be treated as equivalent to

20 "axis,artpec6-eqos", "snps,dwc-qos-ethernet-4.10". It is supported to be

21 compatible with earlier revisions of this binding.

22 - reg: Address and length of the register set for the device

23 - clocks: Phandle and clock specifiers for each entry in clock-names, in the

24 same order. See ../clock/clock-bindings.txt.

25 - clock-names: May contain any/all of the following depending on the IP

26 configuration, in any order:

27 - "tx"

28 The EQOS transmit path clock. The HW signal name is clk_tx_i.

29 In some configurations (e.g. GMII/RGMII), this clock also drives the PHY TX

30 path. In other configurations, other clocks (such as tx_125, rmii) may

31 drive the PHY TX path.

32 - "rx"

33 The EQOS receive path clock. The HW signal name is clk_rx_i.

34 In some configurations (e.g. GMII/RGMII), this clock is derived from the

35 PHY's RX clock output. In other configurations, other clocks (such as

36 rx_125, rmii) may drive the EQOS RX path.

37 In cases where the PHY clock is directly fed into the EQOS receive path

38 without intervening logic, the DT need not represent this clock, since it

39 is assumed to be fully under the control of the PHY device/driver. In

40 cases where SoC integration adds additional logic to this path, such as a

41 SW-controlled clock gate, this clock should be represented in DT.

42 - "slave_bus"

43 The CPU/slave-bus (CSR) interface clock. This applies to any bus type;

44 APB, AHB, AXI, etc. The HW signal name is hclk_i (AHB) or clk_csr_i (other

45 buses).

46 - "master_bus"

47 The master bus interface clock. Only required in configurations that use a

48 separate clock for the master and slave bus interfaces. The HW signal name

49 is hclk_i (AHB) or aclk_i (AXI).

50 - "ptp_ref"

51 The PTP reference clock. The HW signal name is clk_ptp_ref_i.

52 - "phy_ref_clk"

53 This clock is deprecated and should not be used by new compatible values.

54 It is equivalent to "tx".

55 - "apb_pclk"

56 This clock is deprecated and should not be used by new compatible values.

57 It is equivalent to "slave_bus".

59 Note: Support for additional IP configurations may require adding the

60 following clocks to this list in the future: clk_rx_125_i, clk_tx_125_i,

61 clk_pmarx_0_i, clk_pmarx1_i, clk_rmii_i, clk_revmii_rx_i, clk_revmii_tx_i.

62 Configurations exist where multiple similar clocks are used at once, e.g. all

63 of clk_rx_125_i, clk_pmarx_0_i, clk_pmarx1_i. For this reason it is best to

64 extend the binding with a separate clock-names entry for each of those RX

65 clocks, rather than repurposing the existing "rx" clock-names entry as a

66 generic/logical clock in a similar fashion to "master_bus" and "slave_bus".

67 This will allow easy support for configurations that support multiple PHY

68 interfaces using a mux, and hence need to have explicit control over

69 specific RX clocks.

71 The following compatible values require the following set of clocks:

72 - "nvidia,tegra186-eqos", "snps,dwc-qos-ethernet-4.10":

73 - "slave_bus"

74 - "master_bus"

75 - "rx"

76 - "tx"

77 - "ptp_ref"

78 - "axis,artpec6-eqos", "snps,dwc-qos-ethernet-4.10":

79 - "slave_bus"

80 - "master_bus"

81 - "tx"

82 - "ptp_ref"

83 - "snps,dwc-qos-ethernet-4.10" (deprecated):

84 - "phy_ref_clk"

85 - "apb_clk"

86 - interrupts: Should contain the core's combined interrupt signal

87 - phy-mode: See ethernet.txt file in the same directory

88 - resets: Phandle and reset specifiers for each entry in reset-names, in the

89 same order. See ../reset/reset.txt.

90 - reset-names: May contain any/all of the following depending on the IP

91 configuration, in any order:

92 - "eqos". The reset to the entire module. The HW signal name is hreset_n

93 (AHB) or aresetn_i (AXI).

95 The following compatible values require the following set of resets:

96 (the reset properties may be omitted if empty)

97 - "nvidia,tegra186-eqos", "snps,dwc-qos-ethernet-4.10":

98 - "eqos".

99 - "axis,artpec6-eqos", "snps,dwc-qos-ethernet-4.10":

100 - None.

101 - "snps,dwc-qos-ethernet-4.10" (deprecated):

102 - None.

103

104 Optional properties:

105 - dma-coherent: Present if dma operations are coherent

106 - phy-reset-gpios: Phandle and specifier for any GPIO used to reset the PHY.

107 See ../gpio/gpio.txt.

108 - snps,en-lpi: If present it enables use of the AXI low-power interface

109 - snps,write-requests: Number of write requests that the AXI port can issue.

110 It depends on the SoC configuration.

111 - snps,read-requests: Number of read requests that the AXI port can issue.

112 It depends on the SoC configuration.

113 - snps,burst-map: Bitmap of allowed AXI burst lengths, with the LSB

114 representing 4, then 8 etc.

115 - snps,txpbl: DMA Programmable burst length for the TX DMA

116 - snps,rxpbl: DMA Programmable burst length for the RX DMA

117 - snps,en-tx-lpi-clockgating: Enable gating of the MAC TX clock during

118 TX low-power mode.

119 - phy-handle: See ethernet.txt file in the same directory

120 - mdio device tree subnode: When the GMAC has a phy connected to its local

121 mdio, there must be device tree subnode with the following

122 required properties:

123 - compatible: Must be "snps,dwc-qos-ethernet-mdio".

124 - #address-cells: Must be <1>.

125 - #size-cells: Must be <0>.

126

127 For each phy on the mdio bus, there must be a node with the following

128 fields:

129

130 - reg: phy id used to communicate to phy.

131 - device_type: Must be "ethernet-phy".

132 - fixed-mode device tree subnode: see fixed-link.txt in the same directory

133

134 The MAC address will be determined using the optional properties

135 defined in ethernet.txt.

136

137 Examples:

138 ethernet2@40010000 {

139 clock-names = "phy_ref_clk", "apb_pclk";

140 clocks = <&clkc 17>, <&clkc 15>;

141 compatible = "snps,dwc-qos-ethernet-4.10";

142 interrupt-parent = <&intc>;

143 interrupts = <0x0 0x1e 0x4>;

144 reg = <0x40010000 0x4000>;

145 phy-handle = <&phy2>;

146 phy-mode = "gmii";

147 phy-reset-gpios = <&gpioctlr 43 GPIO_ACTIVE_LOW>;

148

149 snps,en-tx-lpi-clockgating;

150 snps,en-lpi;

151 snps,write-requests = <2>;

152 snps,read-requests = <16>;

153 snps,burst-map = <0x7>;

154 snps,txpbl = <8>;

155 snps,rxpbl = <2>;

156

157 dma-coherent;

158

159 mdio {

160 #address-cells = <0x1>;

161 #size-cells = <0x0>;

162 phy2: phy@1 {

163 compatible = "ethernet-phy-ieee802.3-c22";

164 device_type = "ethernet-phy";

165 reg = <0x1>;

166 };

167 };

168 };

169

3. 한국어 전문 번역

영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.

1-11

이 binding은 deprecated지만 계속 지원됩니다. 새 기능은 가급적 STMMAC binding 문서에 추가해야 합니다.

Synopsys DesignWare Ethernet QoS IP는 bus type, clock/reset 구조와 feature 구성이 다양하므로 여러 속성이나 목록 항목이 선택이거나 특정 hardware 구성에서만 필수입니다.

DWC QoS compatible

12-21

Axis ARTPEC-6에서는 `axis,artpec6-eqos`와 `snps,dwc-qos-ethernet-4.10`, NVIDIA Tegra186에서는 `nvidia,tegra186-eqos`와 `snps,dwc-qos-ethernet-4.10`을 함께 사용합니다.

`snps,dwc-qos-ethernet-4.10` 단독 조합은 deprecated이며 이전 binding revision 호환을 위해 지원합니다. 이는 Axis ARTPEC-6 조합과 동등하게 처리합니다.

Register와 clock 이름

22-70

`reg`는 장치 register 주소와 길이입니다. `clocks`는 `clock-names` 각 항목과 같은 순서의 phandle/clock specifier이며 `../clock/clock-bindings.txt`를 따릅니다.

`tx`는 `clk_tx_i`인 EQOS transmit path clock입니다. GMII/RGMII에서는 PHY TX path도 구동할 수 있고 다른 구성에서는 `tx_125`, `rmii` 같은 clock이 PHY TX path를 구동할 수 있습니다.

`rx`는 `clk_rx_i`인 receive path clock입니다. GMII/RGMII에서는 PHY RX output에서 파생될 수 있습니다. PHY clock이 중간 logic 없이 EQOS에 직접 들어가면 DT에 표현하지 않아도 되지만 SoC가 software-controlled gate 같은 logic을 추가하면 표현해야 합니다.

`slave_bus`는 CPU/slave-bus CSR interface clock으로 APB, AHB, AXI 등에 적용하며 `hclk_i` 또는 `clk_csr_i`입니다. `master_bus`는 master/slave bus clock이 분리된 경우의 master interface clock으로 `hclk_i` 또는 `aclk_i`입니다. `ptp_ref`는 `clk_ptp_ref_i` PTP reference clock입니다.

Deprecated `phy_ref_clk`는 `tx`, deprecated `apb_pclk`는 `slave_bus`와 동등합니다. 향후 `clk_rx_125_i`, `clk_tx_125_i`, `clk_pmarx_0_i`, `clk_pmarx1_i`, `clk_rmii_i`, `clk_revmii_rx_i`, `clk_revmii_tx_i`를 별도 이름으로 추가해야 할 수 있습니다. 여러 PHY interface mux 구성에서 각 RX clock을 명시적으로 제어할 수 있도록 이름을 재사용하지 않고 각각 추가해야 합니다.

Compatible별 clock과 reset

71-103

DWC QoS clock and reset requirements

CompatibleRequired clocksRequired resets

nvidia,tegra186-eqos + snps,dwc-qos-ethernet-4.10slave_bus, master_bus, rx, tx, ptp_refeqos

axis,artpec6-eqos + snps,dwc-qos-ethernet-4.10slave_bus, master_bus, tx, ptp_refNone

snps,dwc-qos-ethernet-4.10 (deprecated)phy_ref_clk, apb_clkNone

원문의 compatible별 필수 clock과 reset 집합을 구조화했습니다.

`interrupts`는 core combined interrupt, `phy-mode`는 `ethernet.txt` 정의입니다. `resets`는 `reset-names`와 같은 순서의 reset phandle/specifier이며 `../reset/reset.txt`를 따릅니다. `eqos` reset은 전체 module의 `hreset_n`(AHB) 또는 `aresetn_i`(AXI)입니다. 빈 reset 집합이면 reset 속성을 생략할 수 있습니다.

DWC QoS 선택 속성

104-136

`dma-coherent`는 coherent DMA, `phy-reset-gpios`는 PHY reset GPIO입니다. `snps,en-lpi`는 AXI low-power interface, `snps,en-tx-lpi-clockgating`은 TX low-power mode의 MAC TX clock gating을 enable합니다.

`snps,write-requests`, `snps,read-requests`는 AXI port가 issue할 수 있는 write/read request 수입니다. `snps,burst-map`은 LSB가 4, 다음이 8인 허용 AXI burst length bitmap입니다. `snps,txpbl`, `snps,rxpbl`은 TX/RX DMA Programmable Burst Length입니다.

Local MDIO에 PHY가 연결되면 `compatible = "snps,dwc-qos-ethernet-mdio"`, `#address-cells = <1>`, `#size-cells = <0>`인 subnode가 필요합니다. 각 PHY node는 통신에 쓰는 PHY ID `reg`, `device_type = "ethernet-phy"`를 가지며 fixed mode는 `fixed-link.txt`를 따릅니다.

`phy-handle`과 MAC address 속성은 `ethernet.txt`를 따릅니다.

DWC QoS 예제

137-168

예제는 deprecated clock 이름 두 개, GMII mode, active-low PHY reset GPIO 43, AXI LPI와 TX clock gating을 사용합니다. Write/read request는 2/16, burst map은 `0x7`, TX/RX PBL은 8/2이며 MDIO 주소 1의 Clause 22 PHY를 연결합니다.

ethernet2@40010000 {
        clock-names = "phy_ref_clk", "apb_pclk";
        clocks = <&clkc 17>, <&clkc 15>;
        compatible = "snps,dwc-qos-ethernet-4.10";
        interrupt-parent = <&intc>;
        interrupts = <0x0 0x1e 0x4>;
        reg = <0x40010000 0x4000>;
        phy-handle = <&phy2>;
        phy-mode = "gmii";
        phy-reset-gpios = <&gpioctlr 43 GPIO_ACTIVE_LOW>;

        snps,en-tx-lpi-clockgating;
        snps,en-lpi;
        snps,write-requests = <2>;
        snps,read-requests = <16>;
        snps,burst-map = <0x7>;
        snps,txpbl = <8>;
        snps,rxpbl = <2>;

        dma-coherent;

        mdio {
                #address-cells = <0x1>;
                #size-cells = <0x0>;
                phy2: phy@1 {
                        compatible = "ethernet-phy-ieee802.3-c22";
                        device_type = "ethernet-phy";
                        reg = <0x1>;
                };
        };
};