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