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 enum phy_mode { 12 PHY_MODE_INVALID, 13 }; 14 15 /** 16 * union phy_configure_opts - Opaque generic phy configuration 17 */ 18 union phy_configure_opts { 19 }; 20 21 /** 22 * struct phy - A handle to (allowing control of) a single phy port. 23 * 24 * Clients provide storage for phy handles. The content of the structure is 25 * managed solely by the PHY API and PHY drivers. A phy struct is 26 * initialized by "get"ing the phy struct. The phy struct is passed to all 27 * other phy APIs to identify which PHY port to operate upon. 28 * 29 * @dev: The device which implements the PHY port. 30 * @id: The PHY ID within the provider. 31 * 32 */ 33 struct phy { 34 struct udevice *dev; 35 unsigned long id; 36 }; 37 38 /* 39 * struct udevice_ops - set of function pointers for phy operations 40 * @init: operation to be performed for initializing phy (optional) 41 * @exit: operation to be performed while exiting (optional) 42 * @reset: reset the phy (optional). 43 * @power_on: powering on the phy (optional) 44 * @power_off: powering off the phy (optional) 45 */ 46 struct phy_ops { 47 /** 48 * of_xlate - Translate a client's device-tree (OF) phy specifier. 49 * 50 * The PHY core calls this function as the first step in implementing 51 * a client's generic_phy_get_by_*() call. 52 * 53 * If this function pointer is set to NULL, the PHY core will use a 54 * default implementation, which assumes #phy-cells = <0> or 55 * #phy-cells = <1>, and in the later case that the DT cell 56 * contains a simple integer PHY port ID. 57 * 58 * @phy: The phy struct to hold the translation result. 59 * @args: The phy specifier values from device tree. 60 * @return 0 if OK, or a negative error code. 61 */ 62 int (*of_xlate)(struct phy *phy, struct ofnode_phandle_args *args); 63 64 /** 65 * init - initialize the hardware. 66 * 67 * Hardware intialization should not be done in during probe() but 68 * should be implemented in this init() function. It could be starting 69 * PLL, taking a controller out of reset, routing, etc. This function 70 * is typically called only once per PHY port. 71 * If power_on() is not implemented, it must power up the phy. 72 * 73 * @phy: the PHY port to initialize 74 * @return 0 if OK, or a negative error code. 75 */ 76 int (*init)(struct phy *phy); 77 78 /** 79 * exit - de-initialize the PHY device 80 * 81 * Hardware de-intialization should be done here. Every step done in 82 * init() should be undone here. 83 * This could be used to suspend the phy to reduce power consumption or 84 * to put the phy in a known condition before booting the OS (though it 85 * is NOT called automatically before booting the OS) 86 * If power_off() is not implemented, it must power down the phy. 87 * 88 * @phy: PHY port to be de-initialized 89 * @return 0 if OK, or a negative error code 90 */ 91 int (*exit)(struct phy *phy); 92 93 /** 94 * reset - resets a PHY device without shutting down 95 * 96 * @phy: PHY port to be reset 97 * 98 * During runtime, the PHY may need to be reset in order to 99 * re-establish connection etc without being shut down or exit. 100 * 101 * @return 0 if OK, or a negative error code 102 */ 103 int (*reset)(struct phy *phy); 104 105 /** 106 * @configure: 107 * 108 * Optional. 109 * 110 * Used to change the PHY parameters. phy_init() must have 111 * been called on the phy. 112 * 113 * Returns: 0 if successful, an negative error code otherwise 114 */ 115 int (*configure)(struct phy *phy, union phy_configure_opts *opts); 116 117 /** 118 * @validate: 119 * 120 * Optional. 121 * 122 * Used to check that the current set of parameters can be 123 * handled by the phy. Implementations are free to tune the 124 * parameters passed as arguments if needed by some 125 * implementation detail or constraints. It must not change 126 * any actual configuration of the PHY, so calling it as many 127 * times as deemed fit by the consumer must have no side 128 * effect. 129 * 130 * Returns: 0 if the configuration can be applied, an negative 131 * error code otherwise 132 */ 133 int (*validate)(struct phy *phy, enum phy_mode mode, int submode, 134 union phy_configure_opts *opts); 135 136 /** 137 * power_on - power on a PHY device 138 * 139 * @phy: PHY port to be powered on 140 * 141 * During runtime, the PHY may need to be powered on or off several 142 * times. This function is used to power on the PHY. It relies on the 143 * setup done in init(). If init() is not implemented, it must take care 144 * of setting up the context (PLLs, ...) 145 * 146 * @return 0 if OK, or a negative error code 147 */ 148 int (*power_on)(struct phy *phy); 149 150 /** 151 * power_off - power off a PHY device 152 * 153 * @phy: PHY port to be powered off 154 * 155 * During runtime, the PHY may need to be powered on or off several 156 * times. This function is used to power off the PHY. Except if 157 * init()/deinit() are not implemented, it must not de-initialize 158 * everything. 159 * 160 * @return 0 if OK, or a negative error code 161 */ 162 int (*power_off)(struct phy *phy); 163 }; 164 165 #ifdef CONFIG_PHY 166 167 /** 168 * generic_phy_init() - initialize the PHY port 169 * 170 * @phy: the PHY port to initialize 171 * @return 0 if OK, or a negative error code 172 */ 173 int generic_phy_init(struct phy *phy); 174 175 /** 176 * generic_phy_init() - de-initialize the PHY device 177 * 178 * @phy: PHY port to be de-initialized 179 * @return 0 if OK, or a negative error code 180 */ 181 int generic_phy_exit(struct phy *phy); 182 183 /** 184 * generic_phy_reset() - resets a PHY device without shutting down 185 * 186 * @phy: PHY port to be reset 187 *@return 0 if OK, or a negative error code 188 */ 189 int generic_phy_reset(struct phy *phy); 190 191 /** 192 * generic_phy_configure() - change the PHY parameters 193 * 194 * @phy: PHY port to be configure 195 * @return 0 if OK, or a negative error code 196 */ 197 int generic_phy_configure(struct phy *phy, union phy_configure_opts *opts); 198 199 /** 200 * generic_phy_validate() - validate the PHY parameters 201 * 202 * @phy: PHY port to be validate 203 * @return 0 if OK, or a negative error code 204 */ 205 int generic_phy_validate(struct phy *phy, enum phy_mode mode, int submode, 206 union phy_configure_opts *opts); 207 208 /** 209 * generic_phy_power_on() - power on a PHY device 210 * 211 * @phy: PHY port to be powered on 212 * @return 0 if OK, or a negative error code 213 */ 214 int generic_phy_power_on(struct phy *phy); 215 216 /** 217 * generic_phy_power_off() - power off a PHY device 218 * 219 * @phy: PHY port to be powered off 220 * @return 0 if OK, or a negative error code 221 */ 222 int generic_phy_power_off(struct phy *phy); 223 224 225 /** 226 * generic_phy_get_by_index() - Get a PHY device by integer index. 227 * 228 * @user: the client device 229 * @index: The index in the list of available PHYs 230 * @phy: A pointer to the PHY port 231 * 232 * This looks up a PHY device for a client device based on its position in the 233 * list of the possible PHYs. 234 * 235 * example: 236 * usb1: usb_otg_ss@xxx { 237 * compatible = "xxx"; 238 * reg = <xxx>; 239 * . 240 * . 241 * phys = <&usb2_phy>, <&usb3_phy>; 242 * . 243 * . 244 * }; 245 * the USB2 phy can be accessed by passing index '0' and the USB3 phy can 246 * be accessed by passing index '1' 247 * 248 * @return 0 if OK, or a negative error code 249 */ 250 int generic_phy_get_by_index(struct udevice *user, int index, 251 struct phy *phy); 252 253 /** 254 * generic_phy_get_by_name() - Get a PHY device by its name. 255 * 256 * @user: the client device 257 * @phy_name: The name of the PHY in the list of possible PHYs 258 * @phy: A pointer to the PHY port 259 * 260 * This looks up a PHY device for a client device in the 261 * list of the possible PHYs based on its name. 262 * 263 * example: 264 * usb1: usb_otg_ss@xxx { 265 * compatible = "xxx"; 266 * reg = <xxx>; 267 * . 268 * . 269 * phys = <&usb2_phy>, <&usb3_phy>; 270 * phy-names = "usb2phy", "usb3phy"; 271 * . 272 * . 273 * }; 274 * the USB3 phy can be accessed using "usb3phy", and USB2 by using "usb2phy" 275 * 276 * @return 0 if OK, or a negative error code 277 */ 278 int generic_phy_get_by_name(struct udevice *user, const char *phy_name, 279 struct phy *phy); 280 281 #else /* CONFIG_PHY */ 282 283 static inline int generic_phy_init(struct phy *phy) 284 { 285 return 0; 286 } 287 288 static inline int generic_phy_exit(struct phy *phy) 289 { 290 return 0; 291 } 292 293 static inline int generic_phy_reset(struct phy *phy) 294 { 295 return 0; 296 } 297 298 static inline int generic_phy_configure(struct phy *phy, 299 union phy_configure_opts *opts) 300 { 301 return 0; 302 } 303 304 static inline int generic_phy_validate(struct phy *phy, enum phy_mode mode, 305 int submode, 306 union phy_configure_opts *opts) 307 { 308 return 0; 309 } 310 311 static inline int generic_phy_power_on(struct phy *phy) 312 { 313 return 0; 314 } 315 316 static inline int generic_phy_power_off(struct phy *phy) 317 { 318 return 0; 319 } 320 321 static inline int generic_phy_get_by_index(struct udevice *user, int index, 322 struct phy *phy) 323 { 324 return 0; 325 } 326 327 static inline int generic_phy_get_by_name(struct udevice *user, const char *phy_name, 328 struct phy *phy) 329 { 330 return 0; 331 } 332 333 #endif /* CONFIG_PHY */ 334 335 /** 336 * generic_phy_valid() - check if PHY port is valid 337 * 338 * @phy: the PHY port to check 339 * @return TRUE if valid, or FALSE 340 */ 341 static inline bool generic_phy_valid(struct phy *phy) 342 { 343 return phy && phy->dev; 344 } 345 346 #endif /*__GENERIC_PHY_H */ 347