1/* SPDX-License-Identifier: GPL-2.0+ */ 2/* 3 * Copyright (C) 2017 Texas Instruments Incorporated - http://www.ti.com/ 4 * Written by Jean-Jacques Hiblot <jjhiblot@ti.com> 5 */ 6 7#ifndef __GENERIC_PHY_H 8#define __GENERIC_PHY_H 9 10#include <dm/ofnode.h> 11 12struct ofnode_phandle_args; 13 14/** 15 * struct phy - A handle to (allowing control of) a single phy port. 16 * 17 * Clients provide storage for phy handles. The content of the structure is 18 * managed solely by the PHY API and PHY drivers. A phy struct is 19 * initialized by "get"ing the phy struct. The phy struct is passed to all 20 * other phy APIs to identify which PHY port to operate upon. 21 * 22 * @dev: The device which implements the PHY port. 23 * @id: The PHY ID within the provider. 24 * 25 */ 26struct phy { 27 struct udevice *dev; 28 unsigned long id; 29}; 30 31/* 32 * struct udevice_ops - set of function pointers for phy operations 33 * @init: operation to be performed for initializing phy (optional) 34 * @exit: operation to be performed while exiting (optional) 35 * @reset: reset the phy (optional). 36 * @power_on: powering on the phy (optional) 37 * @power_off: powering off the phy (optional) 38 */ 39struct phy_ops { 40 /** 41 * of_xlate - Translate a client's device-tree (OF) phy specifier. 42 * 43 * The PHY core calls this function as the first step in implementing 44 * a client's generic_phy_get_by_*() call. 45 * 46 * If this function pointer is set to NULL, the PHY core will use a 47 * default implementation, which assumes #phy-cells = <0> or 48 * #phy-cells = <1>, and in the later case that the DT cell 49 * contains a simple integer PHY port ID. 50 * 51 * @phy: The phy struct to hold the translation result. 52 * @args: The phy specifier values from device tree. 53 * @return 0 if OK, or a negative error code. 54 */ 55 int (*of_xlate)(struct phy *phy, struct ofnode_phandle_args *args); 56 57 /** 58 * init - initialize the hardware. 59 * 60 * Hardware intialization should not be done in during probe() but 61 * should be implemented in this init() function. It could be starting 62 * PLL, taking a controller out of reset, routing, etc. This function 63 * is typically called only once per PHY port. 64 * If power_on() is not implemented, it must power up the phy. 65 * 66 * @phy: the PHY port to initialize 67 * @return 0 if OK, or a negative error code. 68 */ 69 int (*init)(struct phy *phy); 70 71 /** 72 * exit - de-initialize the PHY device 73 * 74 * Hardware de-intialization should be done here. Every step done in 75 * init() should be undone here. 76 * This could be used to suspend the phy to reduce power consumption or 77 * to put the phy in a known condition before booting the OS (though it 78 * is NOT called automatically before booting the OS) 79 * If power_off() is not implemented, it must power down the phy. 80 * 81 * @phy: PHY port to be de-initialized 82 * @return 0 if OK, or a negative error code 83 */ 84 int (*exit)(struct phy *phy); 85 86 /** 87 * reset - resets a PHY device without shutting down 88 * 89 * @phy: PHY port to be reset 90 * 91 * During runtime, the PHY may need to be reset in order to 92 * re-establish connection etc without being shut down or exit. 93 * 94 * @return 0 if OK, or a negative error code 95 */ 96 int (*reset)(struct phy *phy); 97 98 /** 99 * power_on - power on a PHY device 100 * 101 * @phy: PHY port to be powered on 102 * 103 * During runtime, the PHY may need to be powered on or off several 104 * times. This function is used to power on the PHY. It relies on the 105 * setup done in init(). If init() is not implemented, it must take care 106 * of setting up the context (PLLs, ...) 107 * 108 * @return 0 if OK, or a negative error code 109 */ 110 int (*power_on)(struct phy *phy); 111 112 /** 113 * power_off - power off a PHY device 114 * 115 * @phy: PHY port to be powered off 116 * 117 * During runtime, the PHY may need to be powered on or off several 118 * times. This function is used to power off the PHY. Except if 119 * init()/deinit() are not implemented, it must not de-initialize 120 * everything. 121 * 122 * @return 0 if OK, or a negative error code 123 */ 124 int (*power_off)(struct phy *phy); 125 126 /** 127 * configure - configure a PHY device 128 * 129 * @phy: PHY port to be configured 130 * @params: PHY Parameters, underlying data is specific to the PHY function 131 * 132 * During runtime, the PHY may need to be configured for it's main function. 133 * This function configures the PHY for it's main function following 134 * power_on/off() after beeing initialized. 135 * 136 * @return 0 if OK, or a negative error code 137 */ 138 int (*configure)(struct phy *phy, void *params); 139}; 140 141/** 142 * struct phy_bulk - A handle to (allowing control of) a bulk of phys. 143 * 144 * Consumers provide storage for the phy bulk. The content of the structure is 145 * managed solely by the phy API. A phy bulk struct is initialized 146 * by "get"ing the phy bulk struct. 147 * The phy bulk struct is passed to all other bulk phy APIs to apply 148 * the API to all the phy in the bulk struct. 149 * 150 * @phys: An array of phy handles. 151 * @count: The number of phy handles in the phys array. 152 */ 153struct phy_bulk { 154 struct phy *phys; 155 unsigned int count; 156}; 157 158#ifdef CONFIG_PHY 159 160/** 161 * generic_phy_init() - initialize the PHY port 162 * 163 * @phy: the PHY port to initialize 164 * @return 0 if OK, or a negative error code 165 */ 166int generic_phy_init(struct phy *phy); 167 168/** 169 * generic_phy_init() - de-initialize the PHY device 170 * 171 * @phy: PHY port to be de-initialized 172 * @return 0 if OK, or a negative error code 173 */ 174int generic_phy_exit(struct phy *phy); 175 176/** 177 * generic_phy_reset() - resets a PHY device without shutting down 178 * 179 * @phy: PHY port to be reset 180 *@return 0 if OK, or a negative error code 181 */ 182int generic_phy_reset(struct phy *phy); 183 184/** 185 * generic_phy_power_on() - power on a PHY device 186 * 187 * @phy: PHY port to be powered on 188 * @return 0 if OK, or a negative error code 189 */ 190int generic_phy_power_on(struct phy *phy); 191 192/** 193 * generic_phy_power_off() - power off a PHY device 194 * 195 * @phy: PHY port to be powered off 196 * @return 0 if OK, or a negative error code 197 */ 198int generic_phy_power_off(struct phy *phy); 199 200/** 201 * generic_phy_configure() - configure a PHY device 202 * 203 * @phy: PHY port to be configured 204 * @params: PHY Parameters, underlying data is specific to the PHY function 205 * @return 0 if OK, or a negative error code 206 */ 207int generic_phy_configure(struct phy *phy, void *params); 208 209 210/** 211 * generic_phy_get_by_index() - Get a PHY device by integer index. 212 * 213 * @user: the client device 214 * @index: The index in the list of available PHYs 215 * @phy: A pointer to the PHY port 216 * 217 * This looks up a PHY device for a client device based on its position in the 218 * list of the possible PHYs. 219 * 220 * example: 221 * usb1: usb_otg_ss@xxx { 222 * compatible = "xxx"; 223 * reg = <xxx>; 224 * . 225 * . 226 * phys = <&usb2_phy>, <&usb3_phy>; 227 * . 228 * . 229 * }; 230 * the USB2 phy can be accessed by passing index '0' and the USB3 phy can 231 * be accessed by passing index '1' 232 * 233 * @return 0 if OK, or a negative error code 234 */ 235int generic_phy_get_by_index(struct udevice *user, int index, 236 struct phy *phy); 237 238/** 239 * generic_phy_get_by_index_nodev() - Get a PHY device by integer index 240 * without a device 241 * 242 * @node: The client ofnode. 243 * @index: The index in the list of available PHYs 244 * @phy: A pointer to the PHY port 245 * 246 * This is a version of generic_phy_get_by_index() that does not use a device. 247 * 248 * This looks up a PHY device for a client device based on its ofnode and on 249 * its position in the list of the possible PHYs. 250 * 251 * example: 252 * usb1: usb_otg_ss@xxx { 253 * compatible = "xxx"; 254 * reg = <xxx>; 255 * . 256 * . 257 * phys = <&usb2_phy>, <&usb3_phy>; 258 * . 259 * . 260 * }; 261 * the USB2 phy can be accessed by passing index '0' and the USB3 phy can 262 * be accessed by passing index '1' 263 * 264 * @return 0 if OK, or a negative error code 265 */ 266int generic_phy_get_by_index_nodev(ofnode node, int index, struct phy *phy); 267 268/** 269 * generic_phy_get_by_name() - Get a PHY device by its name. 270 * 271 * @user: the client device 272 * @phy_name: The name of the PHY in the list of possible PHYs 273 * @phy: A pointer to the PHY port 274 * 275 * This looks up a PHY device for a client device in the 276 * list of the possible PHYs based on its name. 277 * 278 * example: 279 * usb1: usb_otg_ss@xxx { 280 * compatible = "xxx"; 281 * reg = <xxx>; 282 * . 283 * . 284 * phys = <&usb2_phy>, <&usb3_phy>; 285 * phy-names = "usb2phy", "usb3phy"; 286 * . 287 * . 288 * }; 289 * the USB3 phy can be accessed using "usb3phy", and USB2 by using "usb2phy" 290 * 291 * @return 0 if OK, or a negative error code 292 */ 293int generic_phy_get_by_name(struct udevice *user, const char *phy_name, 294 struct phy *phy); 295 296/** 297 * generic_phy_get_bulk - Get all phys of a device. 298 * 299 * This looks up and gets all phys of the consumer device; each device is 300 * assumed to have n phys associated with it somehow, and this function finds 301 * and gets all of them in a separate structure. 302 * 303 * @dev: The consumer device. 304 * @bulk A pointer to a phy bulk struct to initialize. 305 * @return 0 if OK, or a negative error code. 306 */ 307int generic_phy_get_bulk(struct udevice *dev, struct phy_bulk *bulk); 308 309/** 310 * generic_phy_init_bulk() - Initialize all phys in a phy bulk struct. 311 * 312 * @bulk: A phy bulk struct that was previously successfully requested 313 * by generic_phy_get_bulk(). 314 * @return 0 if OK, or negative error code. 315 */ 316int generic_phy_init_bulk(struct phy_bulk *bulk); 317 318/** 319 * generic_phy_exit_bulk() - de-initialize all phys in a phy bulk struct. 320 * 321 * @bulk: A phy bulk struct that was previously successfully requested 322 * by generic_phy_get_bulk(). 323 * @return 0 if OK, or negative error code. 324 */ 325int generic_phy_exit_bulk(struct phy_bulk *bulk); 326 327/** 328 * generic_phy_power_on_bulk() - Power on all phys in a phy bulk struct. 329 * 330 * @bulk: A phy bulk struct that was previously successfully requested 331 * by generic_phy_get_bulk(). 332 * @return 0 if OK, or negative error code. 333 */ 334int generic_phy_power_on_bulk(struct phy_bulk *bulk); 335 336/** 337 * generic_phy_power_off_bulk() - Power off all phys in a phy bulk struct. 338 * 339 * @bulk: A phy bulk struct that was previously successfully requested 340 * by generic_phy_get_bulk(). 341 * @return 0 if OK, or negative error code. 342 */ 343int generic_phy_power_off_bulk(struct phy_bulk *bulk); 344 345#else /* CONFIG_PHY */ 346 347static inline int generic_phy_init(struct phy *phy) 348{ 349 return 0; 350} 351 352static inline int generic_phy_exit(struct phy *phy) 353{ 354 return 0; 355} 356 357static inline int generic_phy_reset(struct phy *phy) 358{ 359 return 0; 360} 361 362static inline int generic_phy_power_on(struct phy *phy) 363{ 364 return 0; 365} 366 367static inline int generic_phy_power_off(struct phy *phy) 368{ 369 return 0; 370} 371 372static inline int generic_phy_get_by_index(struct udevice *user, int index, 373 struct phy *phy) 374{ 375 return 0; 376} 377 378static inline int generic_phy_get_by_name(struct udevice *user, const char *phy_name, 379 struct phy *phy) 380{ 381 return 0; 382} 383 384static inline int 385generic_phy_get_bulk(struct udevice *dev, struct phy_bulk *bulk) 386{ 387 return 0; 388} 389 390static inline int generic_phy_init_bulk(struct phy_bulk *bulk) 391{ 392 return 0; 393} 394 395static inline int generic_phy_exit_bulk(struct phy_bulk *bulk) 396{ 397 return 0; 398} 399 400static inline int generic_phy_power_on_bulk(struct phy_bulk *bulk) 401{ 402 return 0; 403} 404 405static inline int generic_phy_power_off_bulk(struct phy_bulk *bulk) 406{ 407 return 0; 408} 409 410#endif /* CONFIG_PHY */ 411 412/** 413 * generic_phy_valid() - check if PHY port is valid 414 * 415 * @phy: the PHY port to check 416 * @return TRUE if valid, or FALSE 417 */ 418static inline bool generic_phy_valid(struct phy *phy) 419{ 420 return phy && phy->dev; 421} 422 423#endif /*__GENERIC_PHY_H */ 424