1 /*
2 * Copyright (C) 2017 Texas Instruments Incorporated - http://www.ti.com/
3 * Written by Jean-Jacques Hiblot <jjhiblot@ti.com>
4 *
5 * SPDX-License-Identifier: GPL-2.0+
6 */
7
8 #ifndef __GENERIC_PHY_H
9 #define __GENERIC_PHY_H
10
11 #include <generic-phy-dp.h>
12 #include <generic-phy-mipi-dphy.h>
13 #include <generic-phy-pcie.h>
14
15 enum phy_mode {
16 PHY_MODE_INVALID,
17 PHY_MODE_DP,
18 };
19
20 /**
21 * union phy_configure_opts - Opaque generic phy configuration
22 *
23 * @mipi_dphy: Configuration set applicable for phys supporting
24 * the MIPI_DPHY phy mode.
25 * @dp: Configuration set applicable for phys supporting
26 * the DisplayPort protocol.
27 */
28 union phy_configure_opts {
29 struct phy_configure_opts_mipi_dphy mipi_dphy;
30 struct phy_configure_opts_dp dp;
31 struct phy_configure_opts_pcie pcie;
32 };
33
34 /**
35 * struct phy_attrs - represents phy attributes
36 * @bus_width: Data path width implemented by PHY
37 * @max_link_rate: Maximum link rate supported by PHY (in Mbps)
38 * @mode: PHY mode
39 */
40 struct phy_attrs {
41 u32 bus_width;
42 u32 max_link_rate;
43 enum phy_mode mode;
44 };
45
46 /**
47 * struct phy - A handle to (allowing control of) a single phy port.
48 *
49 * Clients provide storage for phy handles. The content of the structure is
50 * managed solely by the PHY API and PHY drivers. A phy struct is
51 * initialized by "get"ing the phy struct. The phy struct is passed to all
52 * other phy APIs to identify which PHY port to operate upon.
53 *
54 * @dev: The device which implements the PHY port.
55 * @id: The PHY ID within the provider.
56 *
57 */
58 struct phy {
59 struct udevice *dev;
60 unsigned long id;
61 struct phy_attrs attrs;
62 };
63
64 /*
65 * struct udevice_ops - set of function pointers for phy operations
66 * @init: operation to be performed for initializing phy (optional)
67 * @exit: operation to be performed while exiting (optional)
68 * @reset: reset the phy (optional).
69 * @power_on: powering on the phy (optional)
70 * @power_off: powering off the phy (optional)
71 * @set_mode: set the mode of the phy
72 */
73 struct phy_ops {
74 /**
75 * of_xlate - Translate a client's device-tree (OF) phy specifier.
76 *
77 * The PHY core calls this function as the first step in implementing
78 * a client's generic_phy_get_by_*() call.
79 *
80 * If this function pointer is set to NULL, the PHY core will use a
81 * default implementation, which assumes #phy-cells = <0> or
82 * #phy-cells = <1>, and in the later case that the DT cell
83 * contains a simple integer PHY port ID.
84 *
85 * @phy: The phy struct to hold the translation result.
86 * @args: The phy specifier values from device tree.
87 * @return 0 if OK, or a negative error code.
88 */
89 int (*of_xlate)(struct phy *phy, struct ofnode_phandle_args *args);
90
91 /**
92 * init - initialize the hardware.
93 *
94 * Hardware intialization should not be done in during probe() but
95 * should be implemented in this init() function. It could be starting
96 * PLL, taking a controller out of reset, routing, etc. This function
97 * is typically called only once per PHY port.
98 * If power_on() is not implemented, it must power up the phy.
99 *
100 * @phy: the PHY port to initialize
101 * @return 0 if OK, or a negative error code.
102 */
103 int (*init)(struct phy *phy);
104
105 /**
106 * exit - de-initialize the PHY device
107 *
108 * Hardware de-intialization should be done here. Every step done in
109 * init() should be undone here.
110 * This could be used to suspend the phy to reduce power consumption or
111 * to put the phy in a known condition before booting the OS (though it
112 * is NOT called automatically before booting the OS)
113 * If power_off() is not implemented, it must power down the phy.
114 *
115 * @phy: PHY port to be de-initialized
116 * @return 0 if OK, or a negative error code
117 */
118 int (*exit)(struct phy *phy);
119
120 /**
121 * reset - resets a PHY device without shutting down
122 *
123 * @phy: PHY port to be reset
124 *
125 * During runtime, the PHY may need to be reset in order to
126 * re-establish connection etc without being shut down or exit.
127 *
128 * @return 0 if OK, or a negative error code
129 */
130 int (*reset)(struct phy *phy);
131
132 /**
133 * @configure:
134 *
135 * Optional.
136 *
137 * Used to change the PHY parameters. phy_init() must have
138 * been called on the phy.
139 *
140 * Returns: 0 if successful, an negative error code otherwise
141 */
142 int (*configure)(struct phy *phy, union phy_configure_opts *opts);
143
144 /**
145 * @validate:
146 *
147 * Optional.
148 *
149 * Used to check that the current set of parameters can be
150 * handled by the phy. Implementations are free to tune the
151 * parameters passed as arguments if needed by some
152 * implementation detail or constraints. It must not change
153 * any actual configuration of the PHY, so calling it as many
154 * times as deemed fit by the consumer must have no side
155 * effect.
156 *
157 * Returns: 0 if the configuration can be applied, an negative
158 * error code otherwise
159 */
160 int (*validate)(struct phy *phy, enum phy_mode mode, int submode,
161 union phy_configure_opts *opts);
162
163 /**
164 * power_on - power on a PHY device
165 *
166 * @phy: PHY port to be powered on
167 *
168 * During runtime, the PHY may need to be powered on or off several
169 * times. This function is used to power on the PHY. It relies on the
170 * setup done in init(). If init() is not implemented, it must take care
171 * of setting up the context (PLLs, ...)
172 *
173 * @return 0 if OK, or a negative error code
174 */
175 int (*power_on)(struct phy *phy);
176
177 /**
178 * power_off - power off a PHY device
179 *
180 * @phy: PHY port to be powered off
181 *
182 * During runtime, the PHY may need to be powered on or off several
183 * times. This function is used to power off the PHY. Except if
184 * init()/deinit() are not implemented, it must not de-initialize
185 * everything.
186 *
187 * @return 0 if OK, or a negative error code
188 */
189 int (*power_off)(struct phy *phy);
190
191 int (*set_mode)(struct phy *phy, enum phy_mode mode, int submode);
192 };
193
194 #ifdef CONFIG_PHY
195
196 /**
197 * generic_phy_init() - initialize the PHY port
198 *
199 * @phy: the PHY port to initialize
200 * @return 0 if OK, or a negative error code
201 */
202 int generic_phy_init(struct phy *phy);
203
204 /**
205 * generic_phy_init() - de-initialize the PHY device
206 *
207 * @phy: PHY port to be de-initialized
208 * @return 0 if OK, or a negative error code
209 */
210 int generic_phy_exit(struct phy *phy);
211
212 /**
213 * generic_phy_reset() - resets a PHY device without shutting down
214 *
215 * @phy: PHY port to be reset
216 *@return 0 if OK, or a negative error code
217 */
218 int generic_phy_reset(struct phy *phy);
219
220 /**
221 * generic_phy_configure() - change the PHY parameters
222 *
223 * @phy: PHY port to be configure
224 * @return 0 if OK, or a negative error code
225 */
226 int generic_phy_configure(struct phy *phy, union phy_configure_opts *opts);
227
228 /**
229 * generic_phy_validate() - validate the PHY parameters
230 *
231 * @phy: PHY port to be validate
232 * @return 0 if OK, or a negative error code
233 */
234 int generic_phy_validate(struct phy *phy, enum phy_mode mode, int submode,
235 union phy_configure_opts *opts);
236
237 /**
238 * generic_phy_power_on() - power on a PHY device
239 *
240 * @phy: PHY port to be powered on
241 * @return 0 if OK, or a negative error code
242 */
243 int generic_phy_power_on(struct phy *phy);
244
245 /**
246 * generic_phy_power_off() - power off a PHY device
247 *
248 * @phy: PHY port to be powered off
249 * @return 0 if OK, or a negative error code
250 */
251 int generic_phy_power_off(struct phy *phy);
252
253 int generic_phy_set_mode_ext(struct phy *phy, enum phy_mode mode, int submode);
254 #define generic_phy_set_mode(phy, mode) \
255 generic_phy_set_mode_ext(phy, mode, 0)
256
generic_phy_get_mode(struct phy * phy)257 static inline enum phy_mode generic_phy_get_mode(struct phy *phy)
258 {
259 return phy->attrs.mode;
260 }
261
262 /**
263 * generic_phy_get_by_index() - Get a PHY device by integer index.
264 *
265 * @user: the client device
266 * @index: The index in the list of available PHYs
267 * @phy: A pointer to the PHY port
268 *
269 * This looks up a PHY device for a client device based on its position in the
270 * list of the possible PHYs.
271 *
272 * example:
273 * usb1: usb_otg_ss@xxx {
274 * compatible = "xxx";
275 * reg = <xxx>;
276 * .
277 * .
278 * phys = <&usb2_phy>, <&usb3_phy>;
279 * .
280 * .
281 * };
282 * the USB2 phy can be accessed by passing index '0' and the USB3 phy can
283 * be accessed by passing index '1'
284 *
285 * @return 0 if OK, or a negative error code
286 */
287 int generic_phy_get_by_index(struct udevice *user, int index,
288 struct phy *phy);
289
290 /**
291 * generic_phy_get_by_name() - Get a PHY device by its name.
292 *
293 * @user: the client device
294 * @phy_name: The name of the PHY in the list of possible PHYs
295 * @phy: A pointer to the PHY port
296 *
297 * This looks up a PHY device for a client device in the
298 * list of the possible PHYs based on its name.
299 *
300 * example:
301 * usb1: usb_otg_ss@xxx {
302 * compatible = "xxx";
303 * reg = <xxx>;
304 * .
305 * .
306 * phys = <&usb2_phy>, <&usb3_phy>;
307 * phy-names = "usb2phy", "usb3phy";
308 * .
309 * .
310 * };
311 * the USB3 phy can be accessed using "usb3phy", and USB2 by using "usb2phy"
312 *
313 * @return 0 if OK, or a negative error code
314 */
315 int generic_phy_get_by_name(struct udevice *user, const char *phy_name,
316 struct phy *phy);
317
318 #else /* CONFIG_PHY */
319
generic_phy_init(struct phy * phy)320 static inline int generic_phy_init(struct phy *phy)
321 {
322 return 0;
323 }
324
generic_phy_exit(struct phy * phy)325 static inline int generic_phy_exit(struct phy *phy)
326 {
327 return 0;
328 }
329
generic_phy_reset(struct phy * phy)330 static inline int generic_phy_reset(struct phy *phy)
331 {
332 return 0;
333 }
334
generic_phy_configure(struct phy * phy,union phy_configure_opts * opts)335 static inline int generic_phy_configure(struct phy *phy,
336 union phy_configure_opts *opts)
337 {
338 return 0;
339 }
340
generic_phy_validate(struct phy * phy,enum phy_mode mode,int submode,union phy_configure_opts * opts)341 static inline int generic_phy_validate(struct phy *phy, enum phy_mode mode,
342 int submode,
343 union phy_configure_opts *opts)
344 {
345 return 0;
346 }
347
generic_phy_power_on(struct phy * phy)348 static inline int generic_phy_power_on(struct phy *phy)
349 {
350 return 0;
351 }
352
generic_phy_power_off(struct phy * phy)353 static inline int generic_phy_power_off(struct phy *phy)
354 {
355 return 0;
356 }
357
generic_phy_get_by_index(struct udevice * user,int index,struct phy * phy)358 static inline int generic_phy_get_by_index(struct udevice *user, int index,
359 struct phy *phy)
360 {
361 return 0;
362 }
363
generic_phy_get_by_name(struct udevice * user,const char * phy_name,struct phy * phy)364 static inline int generic_phy_get_by_name(struct udevice *user, const char *phy_name,
365 struct phy *phy)
366 {
367 return 0;
368 }
369
generic_phy_set_mode_ext(struct phy * phy,enum phy_mode mode,int submode)370 static inline int generic_phy_set_mode_ext(struct phy *phy, enum phy_mode mode,
371 int submode)
372 {
373 return 0;
374 }
375
376 #define generic_phy_set_mode(phy, mode) \
377 generic_phy_set_mode_ext(phy, mode, 0)
378
379 #endif /* CONFIG_PHY */
380
381 /**
382 * generic_phy_valid() - check if PHY port is valid
383 *
384 * @phy: the PHY port to check
385 * @return TRUE if valid, or FALSE
386 */
generic_phy_valid(struct phy * phy)387 static inline bool generic_phy_valid(struct phy *phy)
388 {
389 return phy && phy->dev;
390 }
391
392 #endif /*__GENERIC_PHY_H */
393