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 struct ofnode_phandle_args; 11 12 /** 13 * struct phy - A handle to (allowing control of) a single phy port. 14 * 15 * Clients provide storage for phy handles. The content of the structure is 16 * managed solely by the PHY API and PHY drivers. A phy struct is 17 * initialized by "get"ing the phy struct. The phy struct is passed to all 18 * other phy APIs to identify which PHY port to operate upon. 19 * 20 * @dev: The device which implements the PHY port. 21 * @id: The PHY ID within the provider. 22 * 23 */ 24 struct phy { 25 struct udevice *dev; 26 unsigned long id; 27 }; 28 29 /* 30 * struct udevice_ops - set of function pointers for phy operations 31 * @init: operation to be performed for initializing phy (optional) 32 * @exit: operation to be performed while exiting (optional) 33 * @reset: reset the phy (optional). 34 * @power_on: powering on the phy (optional) 35 * @power_off: powering off the phy (optional) 36 */ 37 struct phy_ops { 38 /** 39 * of_xlate - Translate a client's device-tree (OF) phy specifier. 40 * 41 * The PHY core calls this function as the first step in implementing 42 * a client's generic_phy_get_by_*() call. 43 * 44 * If this function pointer is set to NULL, the PHY core will use a 45 * default implementation, which assumes #phy-cells = <0> or 46 * #phy-cells = <1>, and in the later case that the DT cell 47 * contains a simple integer PHY port ID. 48 * 49 * @phy: The phy struct to hold the translation result. 50 * @args: The phy specifier values from device tree. 51 * @return 0 if OK, or a negative error code. 52 */ 53 int (*of_xlate)(struct phy *phy, struct ofnode_phandle_args *args); 54 55 /** 56 * init - initialize the hardware. 57 * 58 * Hardware intialization should not be done in during probe() but 59 * should be implemented in this init() function. It could be starting 60 * PLL, taking a controller out of reset, routing, etc. This function 61 * is typically called only once per PHY port. 62 * If power_on() is not implemented, it must power up the phy. 63 * 64 * @phy: the PHY port to initialize 65 * @return 0 if OK, or a negative error code. 66 */ 67 int (*init)(struct phy *phy); 68 69 /** 70 * exit - de-initialize the PHY device 71 * 72 * Hardware de-intialization should be done here. Every step done in 73 * init() should be undone here. 74 * This could be used to suspend the phy to reduce power consumption or 75 * to put the phy in a known condition before booting the OS (though it 76 * is NOT called automatically before booting the OS) 77 * If power_off() is not implemented, it must power down the phy. 78 * 79 * @phy: PHY port to be de-initialized 80 * @return 0 if OK, or a negative error code 81 */ 82 int (*exit)(struct phy *phy); 83 84 /** 85 * reset - resets a PHY device without shutting down 86 * 87 * @phy: PHY port to be reset 88 * 89 * During runtime, the PHY may need to be reset in order to 90 * re-establish connection etc without being shut down or exit. 91 * 92 * @return 0 if OK, or a negative error code 93 */ 94 int (*reset)(struct phy *phy); 95 96 /** 97 * power_on - power on a PHY device 98 * 99 * @phy: PHY port to be powered on 100 * 101 * During runtime, the PHY may need to be powered on or off several 102 * times. This function is used to power on the PHY. It relies on the 103 * setup done in init(). If init() is not implemented, it must take care 104 * of setting up the context (PLLs, ...) 105 * 106 * @return 0 if OK, or a negative error code 107 */ 108 int (*power_on)(struct phy *phy); 109 110 /** 111 * power_off - power off a PHY device 112 * 113 * @phy: PHY port to be powered off 114 * 115 * During runtime, the PHY may need to be powered on or off several 116 * times. This function is used to power off the PHY. Except if 117 * init()/deinit() are not implemented, it must not de-initialize 118 * everything. 119 * 120 * @return 0 if OK, or a negative error code 121 */ 122 int (*power_off)(struct phy *phy); 123 }; 124 125 #ifdef CONFIG_PHY 126 127 /** 128 * generic_phy_init() - initialize the PHY port 129 * 130 * @phy: the PHY port to initialize 131 * @return 0 if OK, or a negative error code 132 */ 133 int generic_phy_init(struct phy *phy); 134 135 /** 136 * generic_phy_init() - de-initialize the PHY device 137 * 138 * @phy: PHY port to be de-initialized 139 * @return 0 if OK, or a negative error code 140 */ 141 int generic_phy_exit(struct phy *phy); 142 143 /** 144 * generic_phy_reset() - resets a PHY device without shutting down 145 * 146 * @phy: PHY port to be reset 147 *@return 0 if OK, or a negative error code 148 */ 149 int generic_phy_reset(struct phy *phy); 150 151 /** 152 * generic_phy_power_on() - power on a PHY device 153 * 154 * @phy: PHY port to be powered on 155 * @return 0 if OK, or a negative error code 156 */ 157 int generic_phy_power_on(struct phy *phy); 158 159 /** 160 * generic_phy_power_off() - power off a PHY device 161 * 162 * @phy: PHY port to be powered off 163 * @return 0 if OK, or a negative error code 164 */ 165 int generic_phy_power_off(struct phy *phy); 166 167 168 /** 169 * generic_phy_get_by_index() - Get a PHY device by integer index. 170 * 171 * @user: the client device 172 * @index: The index in the list of available PHYs 173 * @phy: A pointer to the PHY port 174 * 175 * This looks up a PHY device for a client device based on its position in the 176 * list of the possible PHYs. 177 * 178 * example: 179 * usb1: usb_otg_ss@xxx { 180 * compatible = "xxx"; 181 * reg = <xxx>; 182 * . 183 * . 184 * phys = <&usb2_phy>, <&usb3_phy>; 185 * . 186 * . 187 * }; 188 * the USB2 phy can be accessed by passing index '0' and the USB3 phy can 189 * be accessed by passing index '1' 190 * 191 * @return 0 if OK, or a negative error code 192 */ 193 int generic_phy_get_by_index(struct udevice *user, int index, 194 struct phy *phy); 195 196 /** 197 * generic_phy_get_by_name() - Get a PHY device by its name. 198 * 199 * @user: the client device 200 * @phy_name: The name of the PHY in the list of possible PHYs 201 * @phy: A pointer to the PHY port 202 * 203 * This looks up a PHY device for a client device in the 204 * list of the possible PHYs based on its name. 205 * 206 * example: 207 * usb1: usb_otg_ss@xxx { 208 * compatible = "xxx"; 209 * reg = <xxx>; 210 * . 211 * . 212 * phys = <&usb2_phy>, <&usb3_phy>; 213 * phy-names = "usb2phy", "usb3phy"; 214 * . 215 * . 216 * }; 217 * the USB3 phy can be accessed using "usb3phy", and USB2 by using "usb2phy" 218 * 219 * @return 0 if OK, or a negative error code 220 */ 221 int generic_phy_get_by_name(struct udevice *user, const char *phy_name, 222 struct phy *phy); 223 224 #else /* CONFIG_PHY */ 225 226 static inline int generic_phy_init(struct phy *phy) 227 { 228 return 0; 229 } 230 231 static inline int generic_phy_exit(struct phy *phy) 232 { 233 return 0; 234 } 235 236 static inline int generic_phy_reset(struct phy *phy) 237 { 238 return 0; 239 } 240 241 static inline int generic_phy_power_on(struct phy *phy) 242 { 243 return 0; 244 } 245 246 static inline int generic_phy_power_off(struct phy *phy) 247 { 248 return 0; 249 } 250 251 static inline int generic_phy_get_by_index(struct udevice *user, int index, 252 struct phy *phy) 253 { 254 return 0; 255 } 256 257 static inline int generic_phy_get_by_name(struct udevice *user, const char *phy_name, 258 struct phy *phy) 259 { 260 return 0; 261 } 262 263 #endif /* CONFIG_PHY */ 264 265 /** 266 * generic_phy_valid() - check if PHY port is valid 267 * 268 * @phy: the PHY port to check 269 * @return TRUE if valid, or FALSE 270 */ 271 static inline bool generic_phy_valid(struct phy *phy) 272 { 273 return phy->dev != NULL; 274 } 275 276 #endif /*__GENERIC_PHY_H */ 277