Commit | Line | Data |
---|---|---|
ecc5fe7d IC |
1 | .. SPDX-License-Identifier: GPL-2.0 |
2 | .. include:: <isonum.txt> | |
3 | ||
4 | ======================= | |
5 | DPAA2 MAC / PHY support | |
6 | ======================= | |
7 | ||
8 | :Copyright: |copy| 2019 NXP | |
9 | ||
10 | Overview | |
11 | -------- | |
12 | ||
13 | The DPAA2 MAC / PHY support consists of a set of APIs that help DPAA2 network | |
a266ef69 | 14 | drivers (dpaa2-eth, dpaa2-ethsw) interact with the PHY library. |
ecc5fe7d IC |
15 | |
16 | DPAA2 Software Architecture | |
17 | --------------------------- | |
18 | ||
19 | Among other DPAA2 objects, the fsl-mc bus exports DPNI objects (abstracting a | |
20 | network interface) and DPMAC objects (abstracting a MAC). The dpaa2-eth driver | |
21 | probes on the DPNI object and connects to and configures a DPMAC object with | |
22 | the help of phylink. | |
23 | ||
24 | Data connections may be established between a DPNI and a DPMAC, or between two | |
25 | DPNIs. Depending on the connection type, the netif_carrier_[on/off] is handled | |
26 | directly by the dpaa2-eth driver or by phylink. | |
27 | ||
28 | .. code-block:: none | |
29 | ||
30 | Sources of abstracted link state information presented by the MC firmware | |
31 | ||
32 | +--------------------------------------+ | |
33 | +------------+ +---------+ | xgmac_mdio | | |
34 | | net_device | | phylink |--| +-----+ +-----+ +-----+ +-----+ | | |
35 | +------------+ +---------+ | | PHY | | PHY | | PHY | | PHY | | | |
36 | | | | +-----+ +-----+ +-----+ +-----+ | | |
37 | +------------------------------------+ | External MDIO bus | | |
38 | | dpaa2-eth | +--------------------------------------+ | |
39 | +------------------------------------+ | |
40 | | | Linux | |
41 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
42 | | | MC firmware | |
43 | | /| V | |
44 | +----------+ / | +----------+ | |
45 | | | / | | | | |
46 | | | | | | | | |
47 | | DPNI |<------| |<------| DPMAC | | |
48 | | | | | | | | |
49 | | | \ |<---+ | | | |
50 | +----------+ \ | | +----------+ | |
51 | \| | | |
52 | | | |
53 | +--------------------------------------+ | |
54 | | MC firmware polling MAC PCS for link | | |
55 | | +-----+ +-----+ +-----+ +-----+ | | |
56 | | | PCS | | PCS | | PCS | | PCS | | | |
57 | | +-----+ +-----+ +-----+ +-----+ | | |
58 | | Internal MDIO bus | | |
59 | +--------------------------------------+ | |
60 | ||
61 | ||
62 | Depending on an MC firmware configuration setting, each MAC may be in one of two modes: | |
63 | ||
64 | - DPMAC_LINK_TYPE_FIXED: the link state management is handled exclusively by | |
65 | the MC firmware by polling the MAC PCS. Without the need to register a | |
66 | phylink instance, the dpaa2-eth driver will not bind to the connected dpmac | |
67 | object at all. | |
68 | ||
69 | - DPMAC_LINK_TYPE_PHY: The MC firmware is left waiting for link state update | |
70 | events, but those are in fact passed strictly between the dpaa2-mac (based on | |
71 | phylink) and its attached net_device driver (dpaa2-eth, dpaa2-ethsw), | |
72 | effectively bypassing the firmware. | |
73 | ||
74 | Implementation | |
75 | -------------- | |
76 | ||
77 | At probe time or when a DPNI's endpoint is dynamically changed, the dpaa2-eth | |
78 | is responsible to find out if the peer object is a DPMAC and if this is the | |
79 | case, to integrate it with PHYLINK using the dpaa2_mac_connect() API, which | |
80 | will do the following: | |
81 | ||
82 | - look up the device tree for PHYLINK-compatible of binding (phy-handle) | |
83 | - will create a PHYLINK instance associated with the received net_device | |
84 | - connect to the PHY using phylink_of_phy_connect() | |
85 | ||
86 | The following phylink_mac_ops callback are implemented: | |
87 | ||
88 | - .validate() will populate the supported linkmodes with the MAC capabilities | |
89 | only when the phy_interface_t is RGMII_* (at the moment, this is the only | |
90 | link type supported by the driver). | |
91 | ||
92 | - .mac_config() will configure the MAC in the new configuration using the | |
93 | dpmac_set_link_state() MC firmware API. | |
94 | ||
95 | - .mac_link_up() / .mac_link_down() will update the MAC link using the same | |
96 | API described above. | |
97 | ||
98 | At driver unbind() or when the DPNI object is disconnected from the DPMAC, the | |
99 | dpaa2-eth driver calls dpaa2_mac_disconnect() which will, in turn, disconnect | |
100 | from the PHY and destroy the PHYLINK instance. | |
101 | ||
102 | In case of a DPNI-DPMAC connection, an 'ip link set dev eth0 up' would start | |
103 | the following sequence of operations: | |
104 | ||
105 | (1) phylink_start() called from .dev_open(). | |
106 | (2) The .mac_config() and .mac_link_up() callbacks are called by PHYLINK. | |
107 | (3) In order to configure the HW MAC, the MC Firmware API | |
108 | dpmac_set_link_state() is called. | |
109 | (4) The firmware will eventually setup the HW MAC in the new configuration. | |
110 | (5) A netif_carrier_on() call is made directly from PHYLINK on the associated | |
111 | net_device. | |
112 | (6) The dpaa2-eth driver handles the LINK_STATE_CHANGE irq in order to | |
113 | enable/disable Rx taildrop based on the pause frame settings. | |
114 | ||
115 | .. code-block:: none | |
116 | ||
117 | +---------+ +---------+ | |
118 | | PHYLINK |-------------->| eth0 | | |
119 | +---------+ (5) +---------+ | |
120 | (1) ^ | | |
121 | | | | |
122 | | v (2) | |
123 | +-----------------------------------+ | |
124 | | dpaa2-eth | | |
125 | +-----------------------------------+ | |
126 | | ^ (6) | |
127 | | | | |
128 | v (3) | | |
129 | +---------+---------------+---------+ | |
130 | | DPMAC | | DPNI | | |
131 | +---------+ +---------+ | |
132 | | MC Firmware | | |
133 | +-----------------------------------+ | |
134 | | | |
135 | | | |
136 | v (4) | |
137 | +-----------------------------------+ | |
138 | | HW MAC | | |
139 | +-----------------------------------+ | |
140 | ||
141 | In case of a DPNI-DPNI connection, a usual sequence of operations looks like | |
142 | the following: | |
143 | ||
144 | (1) ip link set dev eth0 up | |
145 | (2) The dpni_enable() MC API called on the associated fsl_mc_device. | |
146 | (3) ip link set dev eth1 up | |
147 | (4) The dpni_enable() MC API called on the associated fsl_mc_device. | |
148 | (5) The LINK_STATE_CHANGED irq is received by both instances of the dpaa2-eth | |
149 | driver because now the operational link state is up. | |
150 | (6) The netif_carrier_on() is called on the exported net_device from | |
151 | link_state_update(). | |
152 | ||
153 | .. code-block:: none | |
154 | ||
155 | +---------+ +---------+ | |
156 | | eth0 | | eth1 | | |
157 | +---------+ +---------+ | |
158 | | ^ ^ | | |
159 | | | | | | |
160 | (1) v | (6) (6) | v (3) | |
161 | +---------+ +---------+ | |
162 | |dpaa2-eth| |dpaa2-eth| | |
163 | +---------+ +---------+ | |
164 | | ^ ^ | | |
165 | | | | | | |
166 | (2) v | (5) (5) | v (4) | |
167 | +---------+---------------+---------+ | |
168 | | DPNI | | DPNI | | |
169 | +---------+ +---------+ | |
170 | | MC Firmware | | |
171 | +-----------------------------------+ | |
172 | ||
173 | ||
174 | Exported API | |
175 | ------------ | |
176 | ||
177 | Any DPAA2 driver that drivers endpoints of DPMAC objects should service its | |
178 | _EVENT_ENDPOINT_CHANGED irq and connect/disconnect from the associated DPMAC | |
179 | when necessary using the below listed API:: | |
180 | ||
181 | - int dpaa2_mac_connect(struct dpaa2_mac *mac); | |
182 | - void dpaa2_mac_disconnect(struct dpaa2_mac *mac); | |
183 | ||
320fefa9 VO |
184 | A phylink integration is necessary only when the partner DPMAC is not of |
185 | ``TYPE_FIXED``. This means it is either of ``TYPE_PHY``, or of | |
186 | ``TYPE_BACKPLANE`` (the difference being the two that in the ``TYPE_BACKPLANE`` | |
187 | mode, the MC firmware does not access the PCS registers). One can check for | |
188 | this condition using the following helper:: | |
ecc5fe7d | 189 | |
320fefa9 | 190 | - static inline bool dpaa2_mac_is_type_phy(struct dpaa2_mac *mac); |
ecc5fe7d IC |
191 | |
192 | Before connection to a MAC, the caller must allocate and populate the | |
193 | dpaa2_mac structure with the associated net_device, a pointer to the MC portal | |
194 | to be used and the actual fsl_mc_device structure of the DPMAC. |