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/** 128 * struct phy_bulk - A handle to (allowing control of) a bulk of phys. 129 * 130 * Consumers provide storage for the phy bulk. The content of the structure is 131 * managed solely by the phy API. A phy bulk struct is initialized 132 * by "get"ing the phy bulk struct. 133 * The phy bulk struct is passed to all other bulk phy APIs to apply 134 * the API to all the phy in the bulk struct. 135 * 136 * @phys: An array of phy handles. 137 * @count: The number of phy handles in the phys array. 138 */ 139struct phy_bulk { 140 struct phy *phys; 141 unsigned int count; 142}; 143 144#ifdef CONFIG_PHY 145 146/** 147 * generic_phy_init() - initialize the PHY port 148 * 149 * @phy: the PHY port to initialize 150 * @return 0 if OK, or a negative error code 151 */ 152int generic_phy_init(struct phy *phy); 153 154/** 155 * generic_phy_init() - de-initialize the PHY device 156 * 157 * @phy: PHY port to be de-initialized 158 * @return 0 if OK, or a negative error code 159 */ 160int generic_phy_exit(struct phy *phy); 161 162/** 163 * generic_phy_reset() - resets a PHY device without shutting down 164 * 165 * @phy: PHY port to be reset 166 *@return 0 if OK, or a negative error code 167 */ 168int generic_phy_reset(struct phy *phy); 169 170/** 171 * generic_phy_power_on() - power on a PHY device 172 * 173 * @phy: PHY port to be powered on 174 * @return 0 if OK, or a negative error code 175 */ 176int generic_phy_power_on(struct phy *phy); 177 178/** 179 * generic_phy_power_off() - power off a PHY device 180 * 181 * @phy: PHY port to be powered off 182 * @return 0 if OK, or a negative error code 183 */ 184int generic_phy_power_off(struct phy *phy); 185 186 187/** 188 * generic_phy_get_by_index() - Get a PHY device by integer index. 189 * 190 * @user: the client device 191 * @index: The index in the list of available PHYs 192 * @phy: A pointer to the PHY port 193 * 194 * This looks up a PHY device for a client device based on its position in the 195 * list of the possible PHYs. 196 * 197 * example: 198 * usb1: usb_otg_ss@xxx { 199 * compatible = "xxx"; 200 * reg = <xxx>; 201 * . 202 * . 203 * phys = <&usb2_phy>, <&usb3_phy>; 204 * . 205 * . 206 * }; 207 * the USB2 phy can be accessed by passing index '0' and the USB3 phy can 208 * be accessed by passing index '1' 209 * 210 * @return 0 if OK, or a negative error code 211 */ 212int generic_phy_get_by_index(struct udevice *user, int index, 213 struct phy *phy); 214 215/** 216 * generic_phy_get_by_index_nodev() - Get a PHY device by integer index 217 * without a device 218 * 219 * @node: The client ofnode. 220 * @index: The index in the list of available PHYs 221 * @phy: A pointer to the PHY port 222 * 223 * This is a version of generic_phy_get_by_index() that does not use a device. 224 * 225 * This looks up a PHY device for a client device based on its ofnode and on 226 * its position in the list of the possible PHYs. 227 * 228 * example: 229 * usb1: usb_otg_ss@xxx { 230 * compatible = "xxx"; 231 * reg = <xxx>; 232 * . 233 * . 234 * phys = <&usb2_phy>, <&usb3_phy>; 235 * . 236 * . 237 * }; 238 * the USB2 phy can be accessed by passing index '0' and the USB3 phy can 239 * be accessed by passing index '1' 240 * 241 * @return 0 if OK, or a negative error code 242 */ 243int generic_phy_get_by_index_nodev(ofnode node, int index, struct phy *phy); 244 245/** 246 * generic_phy_get_by_name() - Get a PHY device by its name. 247 * 248 * @user: the client device 249 * @phy_name: The name of the PHY in the list of possible PHYs 250 * @phy: A pointer to the PHY port 251 * 252 * This looks up a PHY device for a client device in the 253 * list of the possible PHYs based on its name. 254 * 255 * example: 256 * usb1: usb_otg_ss@xxx { 257 * compatible = "xxx"; 258 * reg = <xxx>; 259 * . 260 * . 261 * phys = <&usb2_phy>, <&usb3_phy>; 262 * phy-names = "usb2phy", "usb3phy"; 263 * . 264 * . 265 * }; 266 * the USB3 phy can be accessed using "usb3phy", and USB2 by using "usb2phy" 267 * 268 * @return 0 if OK, or a negative error code 269 */ 270int generic_phy_get_by_name(struct udevice *user, const char *phy_name, 271 struct phy *phy); 272 273/** 274 * generic_phy_get_bulk - Get all phys of a device. 275 * 276 * This looks up and gets all phys of the consumer device; each device is 277 * assumed to have n phys associated with it somehow, and this function finds 278 * and gets all of them in a separate structure. 279 * 280 * @dev: The consumer device. 281 * @bulk A pointer to a phy bulk struct to initialize. 282 * @return 0 if OK, or a negative error code. 283 */ 284int generic_phy_get_bulk(struct udevice *dev, struct phy_bulk *bulk); 285 286/** 287 * generic_phy_init_bulk() - Initialize all phys in a phy bulk struct. 288 * 289 * @bulk: A phy bulk struct that was previously successfully requested 290 * by generic_phy_get_bulk(). 291 * @return 0 if OK, or negative error code. 292 */ 293int generic_phy_init_bulk(struct phy_bulk *bulk); 294 295/** 296 * generic_phy_exit_bulk() - de-initialize all phys in a phy bulk struct. 297 * 298 * @bulk: A phy bulk struct that was previously successfully requested 299 * by generic_phy_get_bulk(). 300 * @return 0 if OK, or negative error code. 301 */ 302int generic_phy_exit_bulk(struct phy_bulk *bulk); 303 304/** 305 * generic_phy_power_on_bulk() - Power on all phys in a phy bulk struct. 306 * 307 * @bulk: A phy bulk struct that was previously successfully requested 308 * by generic_phy_get_bulk(). 309 * @return 0 if OK, or negative error code. 310 */ 311int generic_phy_power_on_bulk(struct phy_bulk *bulk); 312 313/** 314 * generic_phy_power_off_bulk() - Power off all phys in a phy bulk struct. 315 * 316 * @bulk: A phy bulk struct that was previously successfully requested 317 * by generic_phy_get_bulk(). 318 * @return 0 if OK, or negative error code. 319 */ 320int generic_phy_power_off_bulk(struct phy_bulk *bulk); 321 322#else /* CONFIG_PHY */ 323 324static inline int generic_phy_init(struct phy *phy) 325{ 326 return 0; 327} 328 329static inline int generic_phy_exit(struct phy *phy) 330{ 331 return 0; 332} 333 334static inline int generic_phy_reset(struct phy *phy) 335{ 336 return 0; 337} 338 339static inline int generic_phy_power_on(struct phy *phy) 340{ 341 return 0; 342} 343 344static inline int generic_phy_power_off(struct phy *phy) 345{ 346 return 0; 347} 348 349static inline int generic_phy_get_by_index(struct udevice *user, int index, 350 struct phy *phy) 351{ 352 return 0; 353} 354 355static inline int generic_phy_get_by_name(struct udevice *user, const char *phy_name, 356 struct phy *phy) 357{ 358 return 0; 359} 360 361static inline int 362generic_phy_get_bulk(struct udevice *dev, struct phy_bulk *bulk) 363{ 364 return 0; 365} 366 367static inline int generic_phy_init_bulk(struct phy_bulk *bulk) 368{ 369 return 0; 370} 371 372static inline int generic_phy_exit_bulk(struct phy_bulk *bulk) 373{ 374 return 0; 375} 376 377static inline int generic_phy_power_on_bulk(struct phy_bulk *bulk) 378{ 379 return 0; 380} 381 382static inline int generic_phy_power_off_bulk(struct phy_bulk *bulk) 383{ 384 return 0; 385} 386 387#endif /* CONFIG_PHY */ 388 389/** 390 * generic_phy_valid() - check if PHY port is valid 391 * 392 * @phy: the PHY port to check 393 * @return TRUE if valid, or FALSE 394 */ 395static inline bool generic_phy_valid(struct phy *phy) 396{ 397 return phy && phy->dev; 398} 399 400#endif /*__GENERIC_PHY_H */ 401