1 /* SPDX-License-Identifier: GPL-2.0+ */
2 /*
3 * Copyright (C) 2017 Texas Instruments Incorporated - https://www.ti.com/
4 * Written by Jean-Jacques Hiblot <jjhiblot@ti.com>
5 */
6
7 #ifndef __GENERIC_PHY_H
8 #define __GENERIC_PHY_H
9
10 #include <dm/ofnode.h>
11
12 struct ofnode_phandle_args;
13
14 enum phy_mode {
15 PHY_MODE_INVALID,
16 PHY_MODE_USB_HOST,
17 PHY_MODE_USB_HOST_LS,
18 PHY_MODE_USB_HOST_FS,
19 PHY_MODE_USB_HOST_HS,
20 PHY_MODE_USB_HOST_SS,
21 PHY_MODE_USB_DEVICE,
22 PHY_MODE_USB_DEVICE_LS,
23 PHY_MODE_USB_DEVICE_FS,
24 PHY_MODE_USB_DEVICE_HS,
25 PHY_MODE_USB_DEVICE_SS,
26 PHY_MODE_USB_OTG,
27 PHY_MODE_UFS_HS_A,
28 PHY_MODE_UFS_HS_B,
29 PHY_MODE_PCIE,
30 PHY_MODE_ETHERNET,
31 PHY_MODE_MIPI_DPHY,
32 PHY_MODE_SATA,
33 PHY_MODE_LVDS,
34 PHY_MODE_DP
35 };
36
37 /**
38 * struct phy - A handle to (allowing control of) a single phy port.
39 *
40 * Clients provide storage for phy handles. The content of the structure is
41 * managed solely by the PHY API and PHY drivers. A phy struct is
42 * initialized by "get"ing the phy struct. The phy struct is passed to all
43 * other phy APIs to identify which PHY port to operate upon.
44 *
45 * @dev: The device which implements the PHY port.
46 * @id: The PHY ID within the provider.
47 *
48 */
49 struct phy {
50 struct udevice *dev;
51 unsigned long id;
52 };
53
54 /*
55 * struct udevice_ops - set of function pointers for phy operations
56 * @init: operation to be performed for initializing phy (optional)
57 * @exit: operation to be performed while exiting (optional)
58 * @reset: reset the phy (optional).
59 * @power_on: powering on the phy (optional)
60 * @power_off: powering off the phy (optional)
61 */
62 struct phy_ops {
63 /**
64 * of_xlate - Translate a client's device-tree (OF) phy specifier.
65 *
66 * The PHY core calls this function as the first step in implementing
67 * a client's generic_phy_get_by_*() call.
68 *
69 * If this function pointer is set to NULL, the PHY core will use a
70 * default implementation, which assumes #phy-cells = <0> or
71 * #phy-cells = <1>, and in the later case that the DT cell
72 * contains a simple integer PHY port ID.
73 *
74 * @phy: The phy struct to hold the translation result.
75 * @args: The phy specifier values from device tree.
76 * @return 0 if OK, or a negative error code.
77 */
78 int (*of_xlate)(struct phy *phy, struct ofnode_phandle_args *args);
79
80 /**
81 * init - initialize the hardware.
82 *
83 * Hardware intialization should not be done in during probe() but
84 * should be implemented in this init() function. It could be starting
85 * PLL, taking a controller out of reset, routing, etc. This function
86 * is typically called only once per PHY port.
87 * If power_on() is not implemented, it must power up the phy.
88 *
89 * @phy: the PHY port to initialize
90 * @return 0 if OK, or a negative error code.
91 */
92 int (*init)(struct phy *phy);
93
94 /**
95 * exit - de-initialize the PHY device
96 *
97 * Hardware de-intialization should be done here. Every step done in
98 * init() should be undone here.
99 * This could be used to suspend the phy to reduce power consumption or
100 * to put the phy in a known condition before booting the OS (though it
101 * is NOT called automatically before booting the OS)
102 * If power_off() is not implemented, it must power down the phy.
103 *
104 * @phy: PHY port to be de-initialized
105 * Return: 0 if OK, or a negative error code
106 */
107 int (*exit)(struct phy *phy);
108
109 /**
110 * reset - resets a PHY device without shutting down
111 *
112 * @phy: PHY port to be reset
113 *
114 * During runtime, the PHY may need to be reset in order to
115 * re-establish connection etc without being shut down or exit.
116 *
117 * Return: 0 if OK, or a negative error code
118 */
119 int (*reset)(struct phy *phy);
120
121 /**
122 * power_on - power on a PHY device
123 *
124 * @phy: PHY port to be powered on
125 *
126 * During runtime, the PHY may need to be powered on or off several
127 * times. This function is used to power on the PHY. It relies on the
128 * setup done in init(). If init() is not implemented, it must take care
129 * of setting up the context (PLLs, ...)
130 *
131 * Return: 0 if OK, or a negative error code
132 */
133 int (*power_on)(struct phy *phy);
134
135 /**
136 * power_off - power off a PHY device
137 *
138 * @phy: PHY port to be powered off
139 *
140 * During runtime, the PHY may need to be powered on or off several
141 * times. This function is used to power off the PHY. Except if
142 * init()/deinit() are not implemented, it must not de-initialize
143 * everything.
144 *
145 * Return: 0 if OK, or a negative error code
146 */
147 int (*power_off)(struct phy *phy);
148
149 /**
150 * configure - configure a PHY device
151 *
152 * @phy: PHY port to be configured
153 * @params: PHY Parameters, underlying data is specific to the PHY function
154 *
155 * During runtime, the PHY may need to be configured for it's main function.
156 * This function configures the PHY for it's main function following
157 * power_on/off() after being initialized.
158 *
159 * Return: 0 if OK, or a negative error code
160 */
161 int (*configure)(struct phy *phy, void *params);
162
163 /**
164 * set_mode - set PHY device mode
165 *
166 * @phy: PHY port to be configured
167 * @mode: PHY mode
168 * @submode: PHY submode
169 *
170 * Configure PHY mode (e.g. USB, Ethernet, ...) and submode
171 * (e.g. for Ethernet this can be RGMII).
172 *
173 * Return: 0 if OK, or a negative error code
174 */
175 int (*set_mode)(struct phy *phy, enum phy_mode mode, int submode);
176
177 /**
178 * set_speed - set PHY device speed
179 *
180 * @phy: PHY port to be configured
181 * @speed: PHY speed
182 *
183 * Configure PHY speed (e.g. for Ethernet, this could be 10 or 100 ...).
184 *
185 * Return: 0 if OK, or a negative error code
186 */
187 int (*set_speed)(struct phy *phy, int speed);
188 };
189
190 /**
191 * struct phy_bulk - A handle to (allowing control of) a bulk of phys.
192 *
193 * Consumers provide storage for the phy bulk. The content of the structure is
194 * managed solely by the phy API. A phy bulk struct is initialized
195 * by "get"ing the phy bulk struct.
196 * The phy bulk struct is passed to all other bulk phy APIs to apply
197 * the API to all the phy in the bulk struct.
198 *
199 * @phys: An array of phy handles.
200 * @count: The number of phy handles in the phys array.
201 */
202 struct phy_bulk {
203 struct phy *phys;
204 unsigned int count;
205 };
206
207 #if CONFIG_IS_ENABLED(PHY)
208
209 /**
210 * generic_phy_init() - initialize the PHY port
211 *
212 * @phy: the PHY port to initialize
213 * Return: 0 if OK, or a negative error code
214 */
215 int generic_phy_init(struct phy *phy);
216
217 /**
218 * generic_phy_init() - de-initialize the PHY device
219 *
220 * @phy: PHY port to be de-initialized
221 * Return: 0 if OK, or a negative error code
222 */
223 int generic_phy_exit(struct phy *phy);
224
225 /**
226 * generic_phy_reset() - resets a PHY device without shutting down
227 *
228 * @phy: PHY port to be reset
229 *Return: 0 if OK, or a negative error code
230 */
231 int generic_phy_reset(struct phy *phy);
232
233 /**
234 * generic_phy_power_on() - power on a PHY device
235 *
236 * @phy: PHY port to be powered on
237 * Return: 0 if OK, or a negative error code
238 */
239 int generic_phy_power_on(struct phy *phy);
240
241 /**
242 * generic_phy_power_off() - power off a PHY device
243 *
244 * @phy: PHY port to be powered off
245 * Return: 0 if OK, or a negative error code
246 */
247 int generic_phy_power_off(struct phy *phy);
248
249 /**
250 * generic_phy_configure() - configure a PHY device
251 *
252 * @phy: PHY port to be configured
253 * @params: PHY Parameters, underlying data is specific to the PHY function
254 * Return: 0 if OK, or a negative error code
255 */
256 int generic_phy_configure(struct phy *phy, void *params);
257
258 /**
259 * generic_phy_set_mode() - set PHY device mode
260 *
261 * @phy: PHY port to be configured
262 * @mode: PHY mode
263 * @submode: PHY submode
264 * Return: 0 if OK, or a negative error code
265 */
266 int generic_phy_set_mode(struct phy *phy, enum phy_mode mode, int submode);
267
268 /**
269 * generic_phy_set_speed() - set PHY device speed
270 *
271 * @phy: PHY port to be configured
272 * @speed: PHY speed
273 * Return: 0 if OK, or a negative error code
274 */
275 int generic_phy_set_speed(struct phy *phy, int speed);
276
277 /**
278 * generic_phy_get_by_index() - Get a PHY device by integer index.
279 *
280 * @user: the client device
281 * @index: The index in the list of available PHYs
282 * @phy: A pointer to the PHY port
283 *
284 * This looks up a PHY device for a client device based on its position in the
285 * list of the possible PHYs.
286 *
287 * example:
288 * usb1: usb_otg_ss@xxx {
289 * compatible = "xxx";
290 * reg = <xxx>;
291 * .
292 * .
293 * phys = <&usb2_phy>, <&usb3_phy>;
294 * .
295 * .
296 * };
297 * the USB2 phy can be accessed by passing index '0' and the USB3 phy can
298 * be accessed by passing index '1'
299 *
300 * Return: 0 if OK, or a negative error code
301 */
302 int generic_phy_get_by_index(struct udevice *user, int index,
303 struct phy *phy);
304
305 /**
306 * generic_phy_get_by_index_nodev() - Get a PHY device by integer index
307 * without a device
308 *
309 * @node: The client ofnode.
310 * @index: The index in the list of available PHYs
311 * @phy: A pointer to the PHY port
312 *
313 * This is a version of generic_phy_get_by_index() that does not use a device.
314 *
315 * This looks up a PHY device for a client device based on its ofnode and on
316 * its position in the list of the possible PHYs.
317 *
318 * example:
319 * usb1: usb_otg_ss@xxx {
320 * compatible = "xxx";
321 * reg = <xxx>;
322 * .
323 * .
324 * phys = <&usb2_phy>, <&usb3_phy>;
325 * .
326 * .
327 * };
328 * the USB2 phy can be accessed by passing index '0' and the USB3 phy can
329 * be accessed by passing index '1'
330 *
331 * Return: 0 if OK, or a negative error code
332 */
333 int generic_phy_get_by_index_nodev(ofnode node, int index, struct phy *phy);
334
335 /**
336 * generic_phy_get_by_name() - Get a PHY device by its name.
337 *
338 * @user: the client device
339 * @phy_name: The name of the PHY in the list of possible PHYs
340 * @phy: A pointer to the PHY port
341 *
342 * This looks up a PHY device for a client device in the
343 * list of the possible PHYs based on its name.
344 *
345 * example:
346 * usb1: usb_otg_ss@xxx {
347 * compatible = "xxx";
348 * reg = <xxx>;
349 * .
350 * .
351 * phys = <&usb2_phy>, <&usb3_phy>;
352 * phy-names = "usb2phy", "usb3phy";
353 * .
354 * .
355 * };
356 * the USB3 phy can be accessed using "usb3phy", and USB2 by using "usb2phy"
357 *
358 * Return: 0 if OK, or a negative error code
359 */
360 int generic_phy_get_by_name(struct udevice *user, const char *phy_name,
361 struct phy *phy);
362
363 /**
364 * generic_phy_get_bulk - Get all phys of a device.
365 *
366 * This looks up and gets all phys of the consumer device; each device is
367 * assumed to have n phys associated with it somehow, and this function finds
368 * and gets all of them in a separate structure.
369 *
370 * @dev: The consumer device.
371 * @bulk A pointer to a phy bulk struct to initialize.
372 * Return: 0 if OK, or a negative error code.
373 */
374 int generic_phy_get_bulk(struct udevice *dev, struct phy_bulk *bulk);
375
376 /**
377 * generic_phy_init_bulk() - Initialize all phys in a phy bulk struct.
378 *
379 * @bulk: A phy bulk struct that was previously successfully requested
380 * by generic_phy_get_bulk().
381 * Return: 0 if OK, or negative error code.
382 */
383 int generic_phy_init_bulk(struct phy_bulk *bulk);
384
385 /**
386 * generic_phy_exit_bulk() - de-initialize all phys in a phy bulk struct.
387 *
388 * @bulk: A phy bulk struct that was previously successfully requested
389 * by generic_phy_get_bulk().
390 * Return: 0 if OK, or negative error code.
391 */
392 int generic_phy_exit_bulk(struct phy_bulk *bulk);
393
394 /**
395 * generic_phy_power_on_bulk() - Power on all phys in a phy bulk struct.
396 *
397 * @bulk: A phy bulk struct that was previously successfully requested
398 * by generic_phy_get_bulk().
399 * Return: 0 if OK, or negative error code.
400 */
401 int generic_phy_power_on_bulk(struct phy_bulk *bulk);
402
403 /**
404 * generic_phy_power_off_bulk() - Power off all phys in a phy bulk struct.
405 *
406 * @bulk: A phy bulk struct that was previously successfully requested
407 * by generic_phy_get_bulk().
408 * Return: 0 if OK, or negative error code.
409 */
410 int generic_phy_power_off_bulk(struct phy_bulk *bulk);
411
412 /**
413 * generic_setup_phy() - Get, initialize and power on phy.
414 *
415 * @dev: The consumer device.
416 * @phy: A pointer to the PHY port
417 * @index: The index in the list of available PHYs
418 * @mode: PHY mode
419 * @submode: PHY submode
420 *
421 * Return: 0 if OK, or negative error code.
422 */
423 int generic_setup_phy(struct udevice *dev, struct phy *phy, int index,
424 enum phy_mode mode, int submode);
425
426 /**
427 * generic_shutdown_phy() - Power off and de-initialize phy.
428 *
429 * @phy: A pointer to the PHY port.
430 *
431 * Return: 0 if OK, or negative error code.
432 */
433 int generic_shutdown_phy(struct phy *phy);
434
435 #else /* CONFIG_PHY */
436
generic_phy_init(struct phy * phy)437 static inline int generic_phy_init(struct phy *phy)
438 {
439 return 0;
440 }
441
generic_phy_exit(struct phy * phy)442 static inline int generic_phy_exit(struct phy *phy)
443 {
444 return 0;
445 }
446
generic_phy_reset(struct phy * phy)447 static inline int generic_phy_reset(struct phy *phy)
448 {
449 return 0;
450 }
451
generic_phy_power_on(struct phy * phy)452 static inline int generic_phy_power_on(struct phy *phy)
453 {
454 return 0;
455 }
456
generic_phy_power_off(struct phy * phy)457 static inline int generic_phy_power_off(struct phy *phy)
458 {
459 return 0;
460 }
461
generic_phy_configure(struct phy * phy,void * params)462 static inline int generic_phy_configure(struct phy *phy, void *params)
463 {
464 return 0;
465 }
466
generic_phy_set_mode(struct phy * phy,enum phy_mode mode,int submode)467 static inline int generic_phy_set_mode(struct phy *phy, enum phy_mode mode, int submode)
468 {
469 return 0;
470 }
471
generic_phy_set_speed(struct phy * phy,int speed)472 static inline int generic_phy_set_speed(struct phy *phy, int speed)
473 {
474 return 0;
475 }
476
generic_phy_get_by_index(struct udevice * user,int index,struct phy * phy)477 static inline int generic_phy_get_by_index(struct udevice *user, int index,
478 struct phy *phy)
479 {
480 return 0;
481 }
482
generic_phy_get_by_name(struct udevice * user,const char * phy_name,struct phy * phy)483 static inline int generic_phy_get_by_name(struct udevice *user, const char *phy_name,
484 struct phy *phy)
485 {
486 return 0;
487 }
488
489 static inline int
generic_phy_get_bulk(struct udevice * dev,struct phy_bulk * bulk)490 generic_phy_get_bulk(struct udevice *dev, struct phy_bulk *bulk)
491 {
492 return 0;
493 }
494
generic_phy_init_bulk(struct phy_bulk * bulk)495 static inline int generic_phy_init_bulk(struct phy_bulk *bulk)
496 {
497 return 0;
498 }
499
generic_phy_exit_bulk(struct phy_bulk * bulk)500 static inline int generic_phy_exit_bulk(struct phy_bulk *bulk)
501 {
502 return 0;
503 }
504
generic_phy_power_on_bulk(struct phy_bulk * bulk)505 static inline int generic_phy_power_on_bulk(struct phy_bulk *bulk)
506 {
507 return 0;
508 }
509
generic_phy_power_off_bulk(struct phy_bulk * bulk)510 static inline int generic_phy_power_off_bulk(struct phy_bulk *bulk)
511 {
512 return 0;
513 }
514
generic_setup_phy(struct udevice * dev,struct phy * phy,int index,enum phy_mode mode,int submode)515 static inline int generic_setup_phy(struct udevice *dev, struct phy *phy, int index,
516 enum phy_mode mode, int submode)
517 {
518 return 0;
519 }
520
generic_shutdown_phy(struct phy * phy)521 static inline int generic_shutdown_phy(struct phy *phy)
522 {
523 return 0;
524 }
525
526 #endif /* CONFIG_PHY */
527
528 /**
529 * generic_phy_valid() - check if PHY port is valid
530 *
531 * @phy: the PHY port to check
532 * Return: TRUE if valid, or FALSE
533 */
generic_phy_valid(struct phy * phy)534 static inline bool generic_phy_valid(struct phy *phy)
535 {
536 return phy && phy->dev;
537 }
538
539 #endif /*__GENERIC_PHY_H */
540