]>
Commit | Line | Data |
---|---|---|
ff764963 KVA |
1 | PHY SUBSYSTEM |
2 | Kishon Vijay Abraham I <kishon@ti.com> | |
3 | ||
4 | This document explains the Generic PHY Framework along with the APIs provided, | |
5 | and how-to-use. | |
6 | ||
7 | 1. Introduction | |
8 | ||
9 | *PHY* is the abbreviation for physical layer. It is used to connect a device | |
10 | to the physical medium e.g., the USB controller has a PHY to provide functions | |
11 | such as serialization, de-serialization, encoding, decoding and is responsible | |
12 | for obtaining the required data transmission rate. Note that some USB | |
13 | controllers have PHY functionality embedded into it and others use an external | |
14 | PHY. Other peripherals that use PHY include Wireless LAN, Ethernet, | |
15 | SATA etc. | |
16 | ||
17 | The intention of creating this framework is to bring the PHY drivers spread | |
18 | all over the Linux kernel to drivers/phy to increase code re-use and for | |
19 | better code maintainability. | |
20 | ||
21 | This framework will be of use only to devices that use external PHY (PHY | |
22 | functionality is not embedded within the controller). | |
23 | ||
24 | 2. Registering/Unregistering the PHY provider | |
25 | ||
26 | PHY provider refers to an entity that implements one or more PHY instances. | |
27 | For the simple case where the PHY provider implements only a single instance of | |
28 | the PHY, the framework provides its own implementation of of_xlate in | |
29 | of_phy_simple_xlate. If the PHY provider implements multiple instances, it | |
30 | should provide its own implementation of of_xlate. of_xlate is used only for | |
31 | dt boot case. | |
32 | ||
33 | #define of_phy_provider_register(dev, xlate) \ | |
34 | __of_phy_provider_register((dev), THIS_MODULE, (xlate)) | |
35 | ||
36 | #define devm_of_phy_provider_register(dev, xlate) \ | |
37 | __devm_of_phy_provider_register((dev), THIS_MODULE, (xlate)) | |
38 | ||
39 | of_phy_provider_register and devm_of_phy_provider_register macros can be used to | |
40 | register the phy_provider and it takes device and of_xlate as | |
41 | arguments. For the dt boot case, all PHY providers should use one of the above | |
42 | 2 macros to register the PHY provider. | |
43 | ||
44 | void devm_of_phy_provider_unregister(struct device *dev, | |
45 | struct phy_provider *phy_provider); | |
46 | void of_phy_provider_unregister(struct phy_provider *phy_provider); | |
47 | ||
48 | devm_of_phy_provider_unregister and of_phy_provider_unregister can be used to | |
49 | unregister the PHY. | |
50 | ||
51 | 3. Creating the PHY | |
52 | ||
53 | The PHY driver should create the PHY in order for other peripheral controllers | |
54 | to make use of it. The PHY framework provides 2 APIs to create the PHY. | |
55 | ||
56 | struct phy *phy_create(struct device *dev, const struct phy_ops *ops, | |
57 | struct phy_init_data *init_data); | |
58 | struct phy *devm_phy_create(struct device *dev, const struct phy_ops *ops, | |
59 | struct phy_init_data *init_data); | |
60 | ||
61 | The PHY drivers can use one of the above 2 APIs to create the PHY by passing | |
62 | the device pointer, phy ops and init_data. | |
63 | phy_ops is a set of function pointers for performing PHY operations such as | |
64 | init, exit, power_on and power_off. *init_data* is mandatory to get a reference | |
65 | to the PHY in the case of non-dt boot. See section *Board File Initialization* | |
66 | on how init_data should be used. | |
67 | ||
68 | Inorder to dereference the private data (in phy_ops), the phy provider driver | |
69 | can use phy_set_drvdata() after creating the PHY and use phy_get_drvdata() in | |
70 | phy_ops to get back the private data. | |
71 | ||
72 | 4. Getting a reference to the PHY | |
73 | ||
74 | Before the controller can make use of the PHY, it has to get a reference to | |
75 | it. This framework provides the following APIs to get a reference to the PHY. | |
76 | ||
77 | struct phy *phy_get(struct device *dev, const char *string); | |
78 | struct phy *devm_phy_get(struct device *dev, const char *string); | |
79 | ||
80 | phy_get and devm_phy_get can be used to get the PHY. In the case of dt boot, | |
81 | the string arguments should contain the phy name as given in the dt data and | |
82 | in the case of non-dt boot, it should contain the label of the PHY. | |
83 | The only difference between the two APIs is that devm_phy_get associates the | |
84 | device with the PHY using devres on successful PHY get. On driver detach, | |
85 | release function is invoked on the the devres data and devres data is freed. | |
86 | ||
87 | 5. Releasing a reference to the PHY | |
88 | ||
89 | When the controller no longer needs the PHY, it has to release the reference | |
90 | to the PHY it has obtained using the APIs mentioned in the above section. The | |
91 | PHY framework provides 2 APIs to release a reference to the PHY. | |
92 | ||
93 | void phy_put(struct phy *phy); | |
94 | void devm_phy_put(struct device *dev, struct phy *phy); | |
95 | ||
96 | Both these APIs are used to release a reference to the PHY and devm_phy_put | |
97 | destroys the devres associated with this PHY. | |
98 | ||
99 | 6. Destroying the PHY | |
100 | ||
101 | When the driver that created the PHY is unloaded, it should destroy the PHY it | |
102 | created using one of the following 2 APIs. | |
103 | ||
104 | void phy_destroy(struct phy *phy); | |
105 | void devm_phy_destroy(struct device *dev, struct phy *phy); | |
106 | ||
107 | Both these APIs destroy the PHY and devm_phy_destroy destroys the devres | |
108 | associated with this PHY. | |
109 | ||
110 | 7. PM Runtime | |
111 | ||
112 | This subsystem is pm runtime enabled. So while creating the PHY, | |
113 | pm_runtime_enable of the phy device created by this subsystem is called and | |
114 | while destroying the PHY, pm_runtime_disable is called. Note that the phy | |
115 | device created by this subsystem will be a child of the device that calls | |
116 | phy_create (PHY provider device). | |
117 | ||
118 | So pm_runtime_get_sync of the phy_device created by this subsystem will invoke | |
119 | pm_runtime_get_sync of PHY provider device because of parent-child relationship. | |
120 | It should also be noted that phy_power_on and phy_power_off performs | |
121 | phy_pm_runtime_get_sync and phy_pm_runtime_put respectively. | |
122 | There are exported APIs like phy_pm_runtime_get, phy_pm_runtime_get_sync, | |
123 | phy_pm_runtime_put, phy_pm_runtime_put_sync, phy_pm_runtime_allow and | |
124 | phy_pm_runtime_forbid for performing PM operations. | |
125 | ||
126 | 8. Board File Initialization | |
127 | ||
128 | Certain board file initialization is necessary in order to get a reference | |
129 | to the PHY in the case of non-dt boot. | |
130 | Say we have a single device that implements 3 PHYs that of USB, SATA and PCIe, | |
131 | then in the board file the following initialization should be done. | |
132 | ||
133 | struct phy_consumer consumers[] = { | |
134 | PHY_CONSUMER("dwc3.0", "usb"), | |
135 | PHY_CONSUMER("pcie.0", "pcie"), | |
136 | PHY_CONSUMER("sata.0", "sata"), | |
137 | }; | |
138 | PHY_CONSUMER takes 2 parameters, first is the device name of the controller | |
139 | (PHY consumer) and second is the port name. | |
140 | ||
141 | struct phy_init_data init_data = { | |
142 | .consumers = consumers, | |
143 | .num_consumers = ARRAY_SIZE(consumers), | |
144 | }; | |
145 | ||
146 | static const struct platform_device pipe3_phy_dev = { | |
147 | .name = "pipe3-phy", | |
148 | .id = -1, | |
149 | .dev = { | |
150 | .platform_data = { | |
151 | .init_data = &init_data, | |
152 | }, | |
153 | }, | |
154 | }; | |
155 | ||
156 | then, while doing phy_create, the PHY driver should pass this init_data | |
157 | phy_create(dev, ops, pdata->init_data); | |
158 | ||
159 | and the controller driver (phy consumer) should pass the port name along with | |
160 | the device to get a reference to the PHY | |
161 | phy_get(dev, "pcie"); | |
162 | ||
163 | 9. DeviceTree Binding | |
164 | ||
165 | The documentation for PHY dt binding can be found @ | |
166 | Documentation/devicetree/bindings/phy/phy-bindings.txt |