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