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