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