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 12struct ofnode_phandle_args; 13 14enum 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 */ 49struct 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 */ 62struct 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 */ 202struct 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 */ 215int 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 */ 223int 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 */ 231int 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 */ 239int 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 */ 247int 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 */ 256int 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 */ 266int 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 */ 275int 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 */ 302int 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 */ 333int 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 */ 360int 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 */ 374int 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 */ 383int 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 */ 392int 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 */ 401int 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 */ 410int 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 * 419 * Return: 0 if OK, or negative error code. 420 */ 421int generic_setup_phy(struct udevice *dev, struct phy *phy, int index); 422 423/** 424 * generic_shutdown_phy() - Power off and de-initialize phy. 425 * 426 * @phy: A pointer to the PHY port. 427 * 428 * Return: 0 if OK, or negative error code. 429 */ 430int generic_shutdown_phy(struct phy *phy); 431 432#else /* CONFIG_PHY */ 433 434static inline int generic_phy_init(struct phy *phy) 435{ 436 return 0; 437} 438 439static inline int generic_phy_exit(struct phy *phy) 440{ 441 return 0; 442} 443 444static inline int generic_phy_reset(struct phy *phy) 445{ 446 return 0; 447} 448 449static inline int generic_phy_power_on(struct phy *phy) 450{ 451 return 0; 452} 453 454static inline int generic_phy_power_off(struct phy *phy) 455{ 456 return 0; 457} 458 459static inline int generic_phy_configure(struct phy *phy, void *params) 460{ 461 return 0; 462} 463 464static inline int generic_phy_set_mode(struct phy *phy, enum phy_mode mode, int submode) 465{ 466 return 0; 467} 468 469static inline int generic_phy_set_speed(struct phy *phy, int speed) 470{ 471 return 0; 472} 473 474static inline int generic_phy_get_by_index(struct udevice *user, int index, 475 struct phy *phy) 476{ 477 return 0; 478} 479 480static inline int generic_phy_get_by_name(struct udevice *user, const char *phy_name, 481 struct phy *phy) 482{ 483 return 0; 484} 485 486static inline int 487generic_phy_get_bulk(struct udevice *dev, struct phy_bulk *bulk) 488{ 489 return 0; 490} 491 492static inline int generic_phy_init_bulk(struct phy_bulk *bulk) 493{ 494 return 0; 495} 496 497static inline int generic_phy_exit_bulk(struct phy_bulk *bulk) 498{ 499 return 0; 500} 501 502static inline int generic_phy_power_on_bulk(struct phy_bulk *bulk) 503{ 504 return 0; 505} 506 507static inline int generic_phy_power_off_bulk(struct phy_bulk *bulk) 508{ 509 return 0; 510} 511 512static inline int generic_setup_phy(struct udevice *dev, struct phy *phy, int index) 513{ 514 return 0; 515} 516 517static inline int generic_shutdown_phy(struct phy *phy) 518{ 519 return 0; 520} 521 522#endif /* CONFIG_PHY */ 523 524/** 525 * generic_phy_valid() - check if PHY port is valid 526 * 527 * @phy: the PHY port to check 528 * Return: TRUE if valid, or FALSE 529 */ 530static inline bool generic_phy_valid(struct phy *phy) 531{ 532 return phy && phy->dev; 533} 534 535#endif /*__GENERIC_PHY_H */ 536