include/generic-phy.h

   1 /* SPDX-License-Identifier: GPL-2.0+ */
   2 /*
   3  * Copyright (C) 2017 Texas Instruments Incorporated - http://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  *
 419  * Return: 0 if OK, or negative error code.
 420  */
 421 int 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  */
 430 int generic_shutdown_phy(struct phy *phy);
 431
 432 #else /* CONFIG_PHY */
 433
 434 static inline int generic_phy_init(struct phy *phy)
 435 {
 436         return 0;
 437 }
 438
 439 static inline int generic_phy_exit(struct phy *phy)
 440 {
 441         return 0;
 442 }
 443
 444 static inline int generic_phy_reset(struct phy *phy)
 445 {
 446         return 0;
 447 }
 448
 449 static inline int generic_phy_power_on(struct phy *phy)
 450 {
 451         return 0;
 452 }
 453
 454 static inline int generic_phy_power_off(struct phy *phy)
 455 {
 456         return 0;
 457 }
 458
 459 static inline int generic_phy_configure(struct phy *phy, void *params)
 460 {
 461         return 0;
 462 }
 463
 464 static inline int generic_phy_set_mode(struct phy *phy, enum phy_mode mode, int submode)
 465 {
 466         return 0;
 467 }
 468
 469 static inline int generic_phy_set_speed(struct phy *phy, int speed)
 470 {
 471         return 0;
 472 }
 473
 474 static inline int generic_phy_get_by_index(struct udevice *user, int index,
 475                              struct phy *phy)
 476 {
 477         return 0;
 478 }
 479
 480 static inline int generic_phy_get_by_name(struct udevice *user, const char *phy_name,
 481                             struct phy *phy)
 482 {
 483         return 0;
 484 }
 485
 486 static inline int
 487 generic_phy_get_bulk(struct udevice *dev, struct phy_bulk *bulk)
 488 {
 489         return 0;
 490 }
 491
 492 static inline int generic_phy_init_bulk(struct phy_bulk *bulk)
 493 {
 494         return 0;
 495 }
 496
 497 static inline int generic_phy_exit_bulk(struct phy_bulk *bulk)
 498 {
 499         return 0;
 500 }
 501
 502 static inline int generic_phy_power_on_bulk(struct phy_bulk *bulk)
 503 {
 504         return 0;
 505 }
 506
 507 static inline int generic_phy_power_off_bulk(struct phy_bulk *bulk)
 508 {
 509         return 0;
 510 }
 511
 512 static inline int generic_setup_phy(struct udevice *dev, struct phy *phy, int index)
 513 {
 514         return 0;
 515 }
 516
 517 static 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  */
 530 static inline bool generic_phy_valid(struct phy *phy)
 531 {
 532         return phy && phy->dev;
 533 }
 534
 535 #endif /*__GENERIC_PHY_H */