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 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, 54 struct fdtdec_phandle_args *args); 55 56 /** 57 * init - initialize the hardware. 58 * 59 * Hardware intialization should not be done in during probe() but 60 * should be implemented in this init() function. It could be starting 61 * PLL, taking a controller out of reset, routing, etc. This function 62 * is typically called only once per PHY port. 63 * If power_on() is not implemented, it must power up the phy. 64 * 65 * @phy: the PHY port to initialize 66 * @return 0 if OK, or a negative error code. 67 */ 68 int (*init)(struct phy *phy); 69 70 /** 71 * exit - de-initialize the PHY device 72 * 73 * Hardware de-intialization should be done here. Every step done in 74 * init() should be undone here. 75 * This could be used to suspend the phy to reduce power consumption or 76 * to put the phy in a known condition before booting the OS (though it 77 * is NOT called automatically before booting the OS) 78 * If power_off() is not implemented, it must power down the phy. 79 * 80 * @phy: PHY port to be de-initialized 81 * @return 0 if OK, or a negative error code 82 */ 83 int (*exit)(struct phy *phy); 84 85 /** 86 * reset - resets a PHY device without shutting down 87 * 88 * @phy: PHY port to be reset 89 * 90 * During runtime, the PHY may need to be reset in order to 91 * re-establish connection etc without being shut down or exit. 92 * 93 * @return 0 if OK, or a negative error code 94 */ 95 int (*reset)(struct phy *phy); 96 97 /** 98 * power_on - power on a PHY device 99 * 100 * @phy: PHY port to be powered on 101 * 102 * During runtime, the PHY may need to be powered on or off several 103 * times. This function is used to power on the PHY. It relies on the 104 * setup done in init(). If init() is not implemented, it must take care 105 * of setting up the context (PLLs, ...) 106 * 107 * @return 0 if OK, or a negative error code 108 */ 109 int (*power_on)(struct phy *phy); 110 111 /** 112 * power_off - power off a PHY device 113 * 114 * @phy: PHY port to be powered off 115 * 116 * During runtime, the PHY may need to be powered on or off several 117 * times. This function is used to power off the PHY. Except if 118 * init()/deinit() are not implemented, it must not de-initialize 119 * everything. 120 * 121 * @return 0 if OK, or a negative error code 122 */ 123 int (*power_off)(struct phy *phy); 124 }; 125 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 #endif /*__GENERIC_PHY_H */ 225