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