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 /**
 128  * struct phy_bulk - A handle to (allowing control of) a bulk of phys.
 129  *
 130  * Consumers provide storage for the phy bulk. The content of the structure is
 131  * managed solely by the phy API. A phy bulk struct is initialized
 132  * by "get"ing the phy bulk struct.
 133  * The phy bulk struct is passed to all other bulk phy APIs to apply
 134  * the API to all the phy in the bulk struct.
 135  *
 136  * @phys: An array of phy handles.
 137  * @count: The number of phy handles in the phys array.
 138  */
 139 struct phy_bulk {
 140         struct phy *phys;
 141         unsigned int count;
 142 };
 143
 144 #ifdef CONFIG_PHY
 145
 146 /**
 147  * generic_phy_init() - initialize the PHY port
 148  *
 149  * @phy:        the PHY port to initialize
 150  * @return 0 if OK, or a negative error code
 151  */
 152 int generic_phy_init(struct phy *phy);
 153
 154 /**
 155  * generic_phy_init() - de-initialize the PHY device
 156  *
 157  * @phy:        PHY port to be de-initialized
 158  * @return 0 if OK, or a negative error code
 159  */
 160 int generic_phy_exit(struct phy *phy);
 161
 162 /**
 163  * generic_phy_reset() - resets a PHY device without shutting down
 164  *
 165  * @phy:        PHY port to be reset
 166  *@return 0 if OK, or a negative error code
 167  */
 168 int generic_phy_reset(struct phy *phy);
 169
 170 /**
 171  * generic_phy_power_on() - power on a PHY device
 172  *
 173  * @phy:        PHY port to be powered on
 174  * @return 0 if OK, or a negative error code
 175  */
 176 int generic_phy_power_on(struct phy *phy);
 177
 178 /**
 179  * generic_phy_power_off() - power off a PHY device
 180  *
 181  * @phy:        PHY port to be powered off
 182  * @return 0 if OK, or a negative error code
 183  */
 184 int generic_phy_power_off(struct phy *phy);
 185
 186
 187 /**
 188  * generic_phy_get_by_index() - Get a PHY device by integer index.
 189  *
 190  * @user:       the client device
 191  * @index:      The index in the list of available PHYs
 192  * @phy:        A pointer to the PHY port
 193  *
 194  * This looks up a PHY device for a client device based on its position in the
 195  * list of the possible PHYs.
 196  *
 197  * example:
 198  * usb1: usb_otg_ss@xxx {
 199  *       compatible = "xxx";
 200  *       reg = <xxx>;
 201  *   .
 202  *   .
 203  *   phys = <&usb2_phy>, <&usb3_phy>;
 204  *   .
 205  *   .
 206  * };
 207  * the USB2 phy can be accessed by passing index '0' and the USB3 phy can
 208  * be accessed by passing index '1'
 209  *
 210  * @return 0 if OK, or a negative error code
 211  */
 212 int generic_phy_get_by_index(struct udevice *user, int index,
 213                              struct phy *phy);
 214
 215 /**
 216  * generic_phy_get_by_node() - Get a PHY device by integer index on ofnode
 217  *
 218  * @node:       the device node
 219  * @index:      The index in the list of available PHYs
 220  * @phy:        A pointer to the PHY port
 221  *
 222  * This looks up a PHY device for a client device based on its ofnode and on
 223  * its position in the list of the possible PHYs.
 224  *
 225  * example:
 226  * usb1: usb_otg_ss@xxx {
 227  *       compatible = "xxx";
 228  *       reg = <xxx>;
 229  *   .
 230  *   .
 231  *   phys = <&usb2_phy>, <&usb3_phy>;
 232  *   .
 233  *   .
 234  * };
 235  * the USB2 phy can be accessed by passing index '0' and the USB3 phy can
 236  * be accessed by passing index '1'
 237  *
 238  * @return 0 if OK, or a negative error code
 239  */
 240 int generic_phy_get_by_node(ofnode node, int index, struct phy *phy);
 241
 242 /**
 243  * generic_phy_get_by_name() - Get a PHY device by its name.
 244  *
 245  * @user:       the client device
 246  * @phy_name:   The name of the PHY in the list of possible PHYs
 247  * @phy:        A pointer to the PHY port
 248  *
 249  * This looks up a PHY device for a client device in the
 250  * list of the possible PHYs based on its name.
 251  *
 252  * example:
 253  * usb1: usb_otg_ss@xxx {
 254  *       compatible = "xxx";
 255  *       reg = <xxx>;
 256  *   .
 257  *   .
 258  *   phys = <&usb2_phy>, <&usb3_phy>;
 259  *   phy-names = "usb2phy", "usb3phy";
 260  *   .
 261  *   .
 262  * };
 263  * the USB3 phy can be accessed using "usb3phy", and USB2 by using "usb2phy"
 264  *
 265  * @return 0 if OK, or a negative error code
 266  */
 267 int generic_phy_get_by_name(struct udevice *user, const char *phy_name,
 268                             struct phy *phy);
 269
 270 /**
 271  * generic_phy_get_bulk - Get all phys of a device.
 272  *
 273  * This looks up and gets all phys of the consumer device; each device is
 274  * assumed to have n phys associated with it somehow, and this function finds
 275  * and gets all of them in a separate structure.
 276  *
 277  * @dev:        The consumer device.
 278  * @bulk        A pointer to a phy bulk struct to initialize.
 279  * @return 0 if OK, or a negative error code.
 280  */
 281 int generic_phy_get_bulk(struct udevice *dev, struct phy_bulk *bulk);
 282
 283 /**
 284  * generic_phy_init_bulk() - Initialize all phys in a phy bulk struct.
 285  *
 286  * @bulk:       A phy bulk struct that was previously successfully requested
 287  *              by generic_phy_get_bulk().
 288  * @return 0 if OK, or negative error code.
 289  */
 290 int generic_phy_init_bulk(struct phy_bulk *bulk);
 291
 292 /**
 293  * generic_phy_exit_bulk() - de-initialize all phys in a phy bulk struct.
 294  *
 295  * @bulk:       A phy bulk struct that was previously successfully requested
 296  *              by generic_phy_get_bulk().
 297  * @return 0 if OK, or negative error code.
 298  */
 299 int generic_phy_exit_bulk(struct phy_bulk *bulk);
 300
 301 /**
 302  * generic_phy_power_on_bulk() - Power on all phys in a phy     bulk struct.
 303  *
 304  * @bulk:       A phy bulk struct that was previously successfully requested
 305  *              by generic_phy_get_bulk().
 306  * @return 0 if OK, or negative error code.
 307  */
 308 int generic_phy_power_on_bulk(struct phy_bulk *bulk);
 309
 310 /**
 311  * generic_phy_power_off_bulk() - Power off all phys in a phy bulk struct.
 312  *
 313  * @bulk:       A phy bulk struct that was previously successfully requested
 314  *              by generic_phy_get_bulk().
 315  * @return 0 if OK, or negative error code.
 316  */
 317 int generic_phy_power_off_bulk(struct phy_bulk *bulk);
 318
 319 #else /* CONFIG_PHY */
 320
 321 static inline int generic_phy_init(struct phy *phy)
 322 {
 323         return 0;
 324 }
 325
 326 static inline int generic_phy_exit(struct phy *phy)
 327 {
 328         return 0;
 329 }
 330
 331 static inline int generic_phy_reset(struct phy *phy)
 332 {
 333         return 0;
 334 }
 335
 336 static inline int generic_phy_power_on(struct phy *phy)
 337 {
 338         return 0;
 339 }
 340
 341 static inline int generic_phy_power_off(struct phy *phy)
 342 {
 343         return 0;
 344 }
 345
 346 static inline int generic_phy_get_by_index(struct udevice *user, int index,
 347                              struct phy *phy)
 348 {
 349         return 0;
 350 }
 351
 352 static inline int generic_phy_get_by_name(struct udevice *user, const char *phy_name,
 353                             struct phy *phy)
 354 {
 355         return 0;
 356 }
 357
 358 static inline int
 359 generic_phy_get_bulk(struct udevice *dev, struct phy_bulk *bulk)
 360 {
 361         return 0;
 362 }
 363
 364 static inline int generic_phy_init_bulk(struct phy_bulk *bulk)
 365 {
 366         return 0;
 367 }
 368
 369 static inline int generic_phy_exit_bulk(struct phy_bulk *bulk)
 370 {
 371         return 0;
 372 }
 373
 374 static inline int generic_phy_power_on_bulk(struct phy_bulk *bulk)
 375 {
 376         return 0;
 377 }
 378
 379 static inline int generic_phy_power_off_bulk(struct phy_bulk *bulk)
 380 {
 381         return 0;
 382 }
 383
 384 #endif /* CONFIG_PHY */
 385
 386 /**
 387  * generic_phy_valid() - check if PHY port is valid
 388  *
 389  * @phy:        the PHY port to check
 390  * @return TRUE if valid, or FALSE
 391  */
 392 static inline bool generic_phy_valid(struct phy *phy)
 393 {
 394         return phy && phy->dev;
 395 }
 396
 397 #endif /*__GENERIC_PHY_H */