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_index_nodev() - Get a PHY device by integer index
 217  * without a device
 218  *
 219  * @node:       The client ofnode.
 220  * @index:      The index in the list of available PHYs
 221  * @phy:        A pointer to the PHY port
 222  *
 223  * This is a version of generic_phy_get_by_index() that does not use a device.
 224  *
 225  * This looks up a PHY device for a client device based on its ofnode and on
 226  * its position in the list of the possible PHYs.
 227  *
 228  * example:
 229  * usb1: usb_otg_ss@xxx {
 230  *       compatible = "xxx";
 231  *       reg = <xxx>;
 232  *   .
 233  *   .
 234  *   phys = <&usb2_phy>, <&usb3_phy>;
 235  *   .
 236  *   .
 237  * };
 238  * the USB2 phy can be accessed by passing index '0' and the USB3 phy can
 239  * be accessed by passing index '1'
 240  *
 241  * @return 0 if OK, or a negative error code
 242  */
 243 int generic_phy_get_by_index_nodev(ofnode node, int index, struct phy *phy);
 244
 245 /**
 246  * generic_phy_get_by_name() - Get a PHY device by its name.
 247  *
 248  * @user:       the client device
 249  * @phy_name:   The name of the PHY in the list of possible PHYs
 250  * @phy:        A pointer to the PHY port
 251  *
 252  * This looks up a PHY device for a client device in the
 253  * list of the possible PHYs based on its name.
 254  *
 255  * example:
 256  * usb1: usb_otg_ss@xxx {
 257  *       compatible = "xxx";
 258  *       reg = <xxx>;
 259  *   .
 260  *   .
 261  *   phys = <&usb2_phy>, <&usb3_phy>;
 262  *   phy-names = "usb2phy", "usb3phy";
 263  *   .
 264  *   .
 265  * };
 266  * the USB3 phy can be accessed using "usb3phy", and USB2 by using "usb2phy"
 267  *
 268  * @return 0 if OK, or a negative error code
 269  */
 270 int generic_phy_get_by_name(struct udevice *user, const char *phy_name,
 271                             struct phy *phy);
 272
 273 /**
 274  * generic_phy_get_bulk - Get all phys of a device.
 275  *
 276  * This looks up and gets all phys of the consumer device; each device is
 277  * assumed to have n phys associated with it somehow, and this function finds
 278  * and gets all of them in a separate structure.
 279  *
 280  * @dev:        The consumer device.
 281  * @bulk        A pointer to a phy bulk struct to initialize.
 282  * @return 0 if OK, or a negative error code.
 283  */
 284 int generic_phy_get_bulk(struct udevice *dev, struct phy_bulk *bulk);
 285
 286 /**
 287  * generic_phy_init_bulk() - Initialize all phys in a phy bulk struct.
 288  *
 289  * @bulk:       A phy bulk struct that was previously successfully requested
 290  *              by generic_phy_get_bulk().
 291  * @return 0 if OK, or negative error code.
 292  */
 293 int generic_phy_init_bulk(struct phy_bulk *bulk);
 294
 295 /**
 296  * generic_phy_exit_bulk() - de-initialize all phys in a phy bulk struct.
 297  *
 298  * @bulk:       A phy bulk struct that was previously successfully requested
 299  *              by generic_phy_get_bulk().
 300  * @return 0 if OK, or negative error code.
 301  */
 302 int generic_phy_exit_bulk(struct phy_bulk *bulk);
 303
 304 /**
 305  * generic_phy_power_on_bulk() - Power on all phys in a phy     bulk struct.
 306  *
 307  * @bulk:       A phy bulk struct that was previously successfully requested
 308  *              by generic_phy_get_bulk().
 309  * @return 0 if OK, or negative error code.
 310  */
 311 int generic_phy_power_on_bulk(struct phy_bulk *bulk);
 312
 313 /**
 314  * generic_phy_power_off_bulk() - Power off all phys in a phy bulk struct.
 315  *
 316  * @bulk:       A phy bulk struct that was previously successfully requested
 317  *              by generic_phy_get_bulk().
 318  * @return 0 if OK, or negative error code.
 319  */
 320 int generic_phy_power_off_bulk(struct phy_bulk *bulk);
 321
 322 #else /* CONFIG_PHY */
 323
 324 static inline int generic_phy_init(struct phy *phy)
 325 {
 326         return 0;
 327 }
 328
 329 static inline int generic_phy_exit(struct phy *phy)
 330 {
 331         return 0;
 332 }
 333
 334 static inline int generic_phy_reset(struct phy *phy)
 335 {
 336         return 0;
 337 }
 338
 339 static inline int generic_phy_power_on(struct phy *phy)
 340 {
 341         return 0;
 342 }
 343
 344 static inline int generic_phy_power_off(struct phy *phy)
 345 {
 346         return 0;
 347 }
 348
 349 static inline int generic_phy_get_by_index(struct udevice *user, int index,
 350                              struct phy *phy)
 351 {
 352         return 0;
 353 }
 354
 355 static inline int generic_phy_get_by_name(struct udevice *user, const char *phy_name,
 356                             struct phy *phy)
 357 {
 358         return 0;
 359 }
 360
 361 static inline int
 362 generic_phy_get_bulk(struct udevice *dev, struct phy_bulk *bulk)
 363 {
 364         return 0;
 365 }
 366
 367 static inline int generic_phy_init_bulk(struct phy_bulk *bulk)
 368 {
 369         return 0;
 370 }
 371
 372 static inline int generic_phy_exit_bulk(struct phy_bulk *bulk)
 373 {
 374         return 0;
 375 }
 376
 377 static inline int generic_phy_power_on_bulk(struct phy_bulk *bulk)
 378 {
 379         return 0;
 380 }
 381
 382 static inline int generic_phy_power_off_bulk(struct phy_bulk *bulk)
 383 {
 384         return 0;
 385 }
 386
 387 #endif /* CONFIG_PHY */
 388
 389 /**
 390  * generic_phy_valid() - check if PHY port is valid
 391  *
 392  * @phy:        the PHY port to check
 393  * @return TRUE if valid, or FALSE
 394  */
 395 static inline bool generic_phy_valid(struct phy *phy)
 396 {
 397         return phy && phy->dev;
 398 }
 399
 400 #endif /*__GENERIC_PHY_H */