1 /* 2 * Copyright (C) 2017 Texas Instruments Incorporated - http://www.ti.com/ 3 * Written by Jean-Jacques Hiblot <jjhiblot@ti.com> 4 * 5 * SPDX-License-Identifier: GPL-2.0+ 6 */ 7 8 #ifndef __GENERIC_PHY_H 9 #define __GENERIC_PHY_H 10 11 12 /** 13 * struct phy - A handle to (allowing control of) a single phy port. 14 * 15 * Clients provide storage for phy handles. The content of the structure is 16 * managed solely by the PHY API and PHY drivers. A phy struct is 17 * initialized by "get"ing the phy struct. The phy struct is passed to all 18 * other phy APIs to identify which PHY port to operate upon. 19 * 20 * @dev: The device which implements the PHY port. 21 * @id: The PHY ID within the provider. 22 * 23 */ 24 struct phy { 25 struct udevice *dev; 26 unsigned long id; 27 }; 28 29 /* 30 * struct udevice_ops - set of function pointers for phy operations 31 * @init: operation to be performed for initializing phy (optional) 32 * @exit: operation to be performed while exiting (optional) 33 * @reset: reset the phy (optional). 34 * @power_on: powering on the phy (optional) 35 * @power_off: powering off the phy (optional) 36 */ 37 struct phy_ops { 38 /** 39 * of_xlate - Translate a client's device-tree (OF) phy specifier. 40 * 41 * The PHY core calls this function as the first step in implementing 42 * a client's generic_phy_get_by_*() call. 43 * 44 * If this function pointer is set to NULL, the PHY core will use a 45 * default implementation, which assumes #phy-cells = <0> or 46 * #phy-cells = <1>, and in the later case that the DT cell 47 * contains a simple integer PHY port ID. 48 * 49 * @phy: The phy struct to hold the translation result. 50 * @args: The phy specifier values from device tree. 51 * @return 0 if OK, or a negative error code. 52 */ 53 int (*of_xlate)(struct phy *phy, struct ofnode_phandle_args *args); 54 55 /** 56 * init - initialize the hardware. 57 * 58 * Hardware intialization should not be done in during probe() but 59 * should be implemented in this init() function. It could be starting 60 * PLL, taking a controller out of reset, routing, etc. This function 61 * is typically called only once per PHY port. 62 * If power_on() is not implemented, it must power up the phy. 63 * 64 * @phy: the PHY port to initialize 65 * @return 0 if OK, or a negative error code. 66 */ 67 int (*init)(struct phy *phy); 68 69 /** 70 * exit - de-initialize the PHY device 71 * 72 * Hardware de-intialization should be done here. Every step done in 73 * init() should be undone here. 74 * This could be used to suspend the phy to reduce power consumption or 75 * to put the phy in a known condition before booting the OS (though it 76 * is NOT called automatically before booting the OS) 77 * If power_off() is not implemented, it must power down the phy. 78 * 79 * @phy: PHY port to be de-initialized 80 * @return 0 if OK, or a negative error code 81 */ 82 int (*exit)(struct phy *phy); 83 84 /** 85 * reset - resets a PHY device without shutting down 86 * 87 * @phy: PHY port to be reset 88 * 89 * During runtime, the PHY may need to be reset in order to 90 * re-establish connection etc without being shut down or exit. 91 * 92 * @return 0 if OK, or a negative error code 93 */ 94 int (*reset)(struct phy *phy); 95 96 /** 97 * power_on - power on a PHY device 98 * 99 * @phy: PHY port to be powered on 100 * 101 * During runtime, the PHY may need to be powered on or off several 102 * times. This function is used to power on the PHY. It relies on the 103 * setup done in init(). If init() is not implemented, it must take care 104 * of setting up the context (PLLs, ...) 105 * 106 * @return 0 if OK, or a negative error code 107 */ 108 int (*power_on)(struct phy *phy); 109 110 /** 111 * power_off - power off a PHY device 112 * 113 * @phy: PHY port to be powered off 114 * 115 * During runtime, the PHY may need to be powered on or off several 116 * times. This function is used to power off the PHY. Except if 117 * init()/deinit() are not implemented, it must not de-initialize 118 * everything. 119 * 120 * @return 0 if OK, or a negative error code 121 */ 122 int (*power_off)(struct phy *phy); 123 }; 124 125 126 /** 127 * generic_phy_init() - initialize the PHY port 128 * 129 * @phy: the PHY port to initialize 130 * @return 0 if OK, or a negative error code 131 */ 132 int generic_phy_init(struct phy *phy); 133 134 /** 135 * generic_phy_init() - de-initialize the PHY device 136 * 137 * @phy: PHY port to be de-initialized 138 * @return 0 if OK, or a negative error code 139 */ 140 int generic_phy_exit(struct phy *phy); 141 142 /** 143 * generic_phy_reset() - resets a PHY device without shutting down 144 * 145 * @phy: PHY port to be reset 146 *@return 0 if OK, or a negative error code 147 */ 148 int generic_phy_reset(struct phy *phy); 149 150 /** 151 * generic_phy_power_on() - power on a PHY device 152 * 153 * @phy: PHY port to be powered on 154 * @return 0 if OK, or a negative error code 155 */ 156 int generic_phy_power_on(struct phy *phy); 157 158 /** 159 * generic_phy_power_off() - power off a PHY device 160 * 161 * @phy: PHY port to be powered off 162 * @return 0 if OK, or a negative error code 163 */ 164 int generic_phy_power_off(struct phy *phy); 165 166 167 /** 168 * generic_phy_get_by_index() - Get a PHY device by integer index. 169 * 170 * @user: the client device 171 * @index: The index in the list of available PHYs 172 * @phy: A pointer to the PHY port 173 * 174 * This looks up a PHY device for a client device based on its position in the 175 * list of the possible PHYs. 176 * 177 * example: 178 * usb1: usb_otg_ss@xxx { 179 * compatible = "xxx"; 180 * reg = <xxx>; 181 * . 182 * . 183 * phys = <&usb2_phy>, <&usb3_phy>; 184 * . 185 * . 186 * }; 187 * the USB2 phy can be accessed by passing index '0' and the USB3 phy can 188 * be accessed by passing index '1' 189 * 190 * @return 0 if OK, or a negative error code 191 */ 192 int generic_phy_get_by_index(struct udevice *user, int index, 193 struct phy *phy); 194 195 /** 196 * generic_phy_get_by_name() - Get a PHY device by its name. 197 * 198 * @user: the client device 199 * @phy_name: The name of the PHY in the list of possible PHYs 200 * @phy: A pointer to the PHY port 201 * 202 * This looks up a PHY device for a client device in the 203 * list of the possible PHYs based on its name. 204 * 205 * example: 206 * usb1: usb_otg_ss@xxx { 207 * compatible = "xxx"; 208 * reg = <xxx>; 209 * . 210 * . 211 * phys = <&usb2_phy>, <&usb3_phy>; 212 * phy-names = "usb2phy", "usb3phy"; 213 * . 214 * . 215 * }; 216 * the USB3 phy can be accessed using "usb3phy", and USB2 by using "usb2phy" 217 * 218 * @return 0 if OK, or a negative error code 219 */ 220 int generic_phy_get_by_name(struct udevice *user, const char *phy_name, 221 struct phy *phy); 222 223 #endif /*__GENERIC_PHY_H */ 224