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 11 /** 12 * struct phy - A handle to (allowing control of) a single phy port. 13 * 14 * Clients provide storage for phy handles. The content of the structure is 15 * managed solely by the PHY API and PHY drivers. A phy struct is 16 * initialized by "get"ing the phy struct. The phy struct is passed to all 17 * other phy APIs to identify which PHY port to operate upon. 18 * 19 * @dev: The device which implements the PHY port. 20 * @id: The PHY ID within the provider. 21 * 22 */ 23 struct phy { 24 struct udevice *dev; 25 unsigned long id; 26 }; 27 28 /* 29 * struct udevice_ops - set of function pointers for phy operations 30 * @init: operation to be performed for initializing phy (optional) 31 * @exit: operation to be performed while exiting (optional) 32 * @reset: reset the phy (optional). 33 * @power_on: powering on the phy (optional) 34 * @power_off: powering off the phy (optional) 35 */ 36 struct phy_ops { 37 /** 38 * of_xlate - Translate a client's device-tree (OF) phy specifier. 39 * 40 * The PHY core calls this function as the first step in implementing 41 * a client's generic_phy_get_by_*() call. 42 * 43 * If this function pointer is set to NULL, the PHY core will use a 44 * default implementation, which assumes #phy-cells = <0> or 45 * #phy-cells = <1>, and in the later case that the DT cell 46 * contains a simple integer PHY port ID. 47 * 48 * @phy: The phy struct to hold the translation result. 49 * @args: The phy specifier values from device tree. 50 * @return 0 if OK, or a negative error code. 51 */ 52 int (*of_xlate)(struct phy *phy, struct ofnode_phandle_args *args); 53 54 /** 55 * init - initialize the hardware. 56 * 57 * Hardware intialization should not be done in during probe() but 58 * should be implemented in this init() function. It could be starting 59 * PLL, taking a controller out of reset, routing, etc. This function 60 * is typically called only once per PHY port. 61 * If power_on() is not implemented, it must power up the phy. 62 * 63 * @phy: the PHY port to initialize 64 * @return 0 if OK, or a negative error code. 65 */ 66 int (*init)(struct phy *phy); 67 68 /** 69 * exit - de-initialize the PHY device 70 * 71 * Hardware de-intialization should be done here. Every step done in 72 * init() should be undone here. 73 * This could be used to suspend the phy to reduce power consumption or 74 * to put the phy in a known condition before booting the OS (though it 75 * is NOT called automatically before booting the OS) 76 * If power_off() is not implemented, it must power down the phy. 77 * 78 * @phy: PHY port to be de-initialized 79 * @return 0 if OK, or a negative error code 80 */ 81 int (*exit)(struct phy *phy); 82 83 /** 84 * reset - resets a PHY device without shutting down 85 * 86 * @phy: PHY port to be reset 87 * 88 * During runtime, the PHY may need to be reset in order to 89 * re-establish connection etc without being shut down or exit. 90 * 91 * @return 0 if OK, or a negative error code 92 */ 93 int (*reset)(struct phy *phy); 94 95 /** 96 * power_on - power on a PHY device 97 * 98 * @phy: PHY port to be powered on 99 * 100 * During runtime, the PHY may need to be powered on or off several 101 * times. This function is used to power on the PHY. It relies on the 102 * setup done in init(). If init() is not implemented, it must take care 103 * of setting up the context (PLLs, ...) 104 * 105 * @return 0 if OK, or a negative error code 106 */ 107 int (*power_on)(struct phy *phy); 108 109 /** 110 * power_off - power off a PHY device 111 * 112 * @phy: PHY port to be powered off 113 * 114 * During runtime, the PHY may need to be powered on or off several 115 * times. This function is used to power off the PHY. Except if 116 * init()/deinit() are not implemented, it must not de-initialize 117 * everything. 118 * 119 * @return 0 if OK, or a negative error code 120 */ 121 int (*power_off)(struct phy *phy); 122 }; 123 124 #ifdef CONFIG_PHY 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 #else /* CONFIG_PHY */ 224 225 static inline int generic_phy_init(struct phy *phy) 226 { 227 return 0; 228 } 229 230 static inline int generic_phy_exit(struct phy *phy) 231 { 232 return 0; 233 } 234 235 static inline int generic_phy_reset(struct phy *phy) 236 { 237 return 0; 238 } 239 240 static inline int generic_phy_power_on(struct phy *phy) 241 { 242 return 0; 243 } 244 245 static inline int generic_phy_power_off(struct phy *phy) 246 { 247 return 0; 248 } 249 250 static inline int generic_phy_get_by_index(struct udevice *user, int index, 251 struct phy *phy) 252 { 253 return 0; 254 } 255 256 static inline int generic_phy_get_by_name(struct udevice *user, const char *phy_name, 257 struct phy *phy) 258 { 259 return 0; 260 } 261 262 #endif /* CONFIG_PHY */ 263 264 /** 265 * generic_phy_valid() - check if PHY port is valid 266 * 267 * @phy: the PHY port to check 268 * @return TRUE if valid, or FALSE 269 */ 270 static inline bool generic_phy_valid(struct phy *phy) 271 { 272 return phy->dev != NULL; 273 } 274 275 #endif /*__GENERIC_PHY_H */ 276