generic-phy.h 10 KB

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