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 #ifdef CONFIG_PHY
 128
 129 /**
 130  * generic_phy_init() - initialize the PHY port
 131  *
 132  * @phy:        the PHY port to initialize
 133  * @return 0 if OK, or a negative error code
 134  */
 135 int generic_phy_init(struct phy *phy);
 136
 137 /**
 138  * generic_phy_init() - de-initialize the PHY device
 139  *
 140  * @phy:        PHY port to be de-initialized
 141  * @return 0 if OK, or a negative error code
 142  */
 143 int generic_phy_exit(struct phy *phy);
 144
 145 /**
 146  * generic_phy_reset() - resets a PHY device without shutting down
 147  *
 148  * @phy:        PHY port to be reset
 149  *@return 0 if OK, or a negative error code
 150  */
 151 int generic_phy_reset(struct phy *phy);
 152
 153 /**
 154  * generic_phy_power_on() - power on a PHY device
 155  *
 156  * @phy:        PHY port to be powered on
 157  * @return 0 if OK, or a negative error code
 158  */
 159 int generic_phy_power_on(struct phy *phy);
 160
 161 /**
 162  * generic_phy_power_off() - power off a PHY device
 163  *
 164  * @phy:        PHY port to be powered off
 165  * @return 0 if OK, or a negative error code
 166  */
 167 int generic_phy_power_off(struct phy *phy);
 168
 169
 170 /**
 171  * generic_phy_get_by_index() - Get a PHY device by integer index.
 172  *
 173  * @user:       the client device
 174  * @index:      The index in the list of available PHYs
 175  * @phy:        A pointer to the PHY port
 176  *
 177  * This looks up a PHY device for a client device based on its position in the
 178  * list of the possible PHYs.
 179  *
 180  * example:
 181  * usb1: usb_otg_ss@xxx {
 182  *       compatible = "xxx";
 183  *       reg = <xxx>;
 184  *   .
 185  *   .
 186  *   phys = <&usb2_phy>, <&usb3_phy>;
 187  *   .
 188  *   .
 189  * };
 190  * the USB2 phy can be accessed by passing index '0' and the USB3 phy can
 191  * be accessed by passing index '1'
 192  *
 193  * @return 0 if OK, or a negative error code
 194  */
 195 int generic_phy_get_by_index(struct udevice *user, int index,
 196                              struct phy *phy);
 197
 198 /**
 199  * generic_phy_get_by_node() - Get a PHY device by integer index on ofnode
 200  *
 201  * @node:       the device node
 202  * @index:      The index in the list of available PHYs
 203  * @phy:        A pointer to the PHY port
 204  *
 205  * This looks up a PHY device for a client device based on its ofnode and on
 206  * its position in the list of the possible PHYs.
 207  *
 208  * example:
 209  * usb1: usb_otg_ss@xxx {
 210  *       compatible = "xxx";
 211  *       reg = <xxx>;
 212  *   .
 213  *   .
 214  *   phys = <&usb2_phy>, <&usb3_phy>;
 215  *   .
 216  *   .
 217  * };
 218  * the USB2 phy can be accessed by passing index '0' and the USB3 phy can
 219  * be accessed by passing index '1'
 220  *
 221  * @return 0 if OK, or a negative error code
 222  */
 223 int generic_phy_get_by_node(ofnode node, int index, struct phy *phy);
 224
 225 /**
 226  * generic_phy_get_by_name() - Get a PHY device by its name.
 227  *
 228  * @user:       the client device
 229  * @phy_name:   The name of the PHY in the list of possible PHYs
 230  * @phy:        A pointer to the PHY port
 231  *
 232  * This looks up a PHY device for a client device in the
 233  * list of the possible PHYs based on its name.
 234  *
 235  * example:
 236  * usb1: usb_otg_ss@xxx {
 237  *       compatible = "xxx";
 238  *       reg = <xxx>;
 239  *   .
 240  *   .
 241  *   phys = <&usb2_phy>, <&usb3_phy>;
 242  *   phy-names = "usb2phy", "usb3phy";
 243  *   .
 244  *   .
 245  * };
 246  * the USB3 phy can be accessed using "usb3phy", and USB2 by using "usb2phy"
 247  *
 248  * @return 0 if OK, or a negative error code
 249  */
 250 int generic_phy_get_by_name(struct udevice *user, const char *phy_name,
 251                             struct phy *phy);
 252
 253 #else /* CONFIG_PHY */
 254
 255 static inline int generic_phy_init(struct phy *phy)
 256 {
 257         return 0;
 258 }
 259
 260 static inline int generic_phy_exit(struct phy *phy)
 261 {
 262         return 0;
 263 }
 264
 265 static inline int generic_phy_reset(struct phy *phy)
 266 {
 267         return 0;
 268 }
 269
 270 static inline int generic_phy_power_on(struct phy *phy)
 271 {
 272         return 0;
 273 }
 274
 275 static inline int generic_phy_power_off(struct phy *phy)
 276 {
 277         return 0;
 278 }
 279
 280 static inline int generic_phy_get_by_index(struct udevice *user, int index,
 281                              struct phy *phy)
 282 {
 283         return 0;
 284 }
 285
 286 static inline int generic_phy_get_by_name(struct udevice *user, const char *phy_name,
 287                             struct phy *phy)
 288 {
 289         return 0;
 290 }
 291
 292 #endif /* CONFIG_PHY */
 293
 294 /**
 295  * generic_phy_valid() - check if PHY port is valid
 296  *
 297  * @phy:        the PHY port to check
 298  * @return TRUE if valid, or FALSE
 299  */
 300 static inline bool generic_phy_valid(struct phy *phy)
 301 {
 302         return phy && phy->dev;
 303 }
 304
 305 #endif /*__GENERIC_PHY_H */