]>
Commit | Line | Data |
---|---|---|
1 | ============= | |
2 | PHY subsystem | |
3 | ============= | |
4 | ||
5 | :Author: Kishon Vijay Abraham I <kishon@ti.com> | |
6 | ||
7 | This document explains the Generic PHY Framework along with the APIs provided, | |
8 | and how-to-use. | |
9 | ||
10 | Introduction | |
11 | ============ | |
12 | ||
13 | *PHY* is the abbreviation for physical layer. It is used to connect a device | |
14 | to the physical medium e.g., the USB controller has a PHY to provide functions | |
15 | such as serialization, de-serialization, encoding, decoding and is responsible | |
16 | for obtaining the required data transmission rate. Note that some USB | |
17 | controllers have PHY functionality embedded into it and others use an external | |
18 | PHY. Other peripherals that use PHY include Wireless LAN, Ethernet, | |
19 | SATA etc. | |
20 | ||
21 | The intention of creating this framework is to bring the PHY drivers spread | |
22 | all over the Linux kernel to drivers/phy to increase code re-use and for | |
23 | better code maintainability. | |
24 | ||
25 | This framework will be of use only to devices that use external PHY (PHY | |
26 | functionality is not embedded within the controller). | |
27 | ||
28 | Registering/Unregistering the PHY provider | |
29 | ========================================== | |
30 | ||
31 | PHY provider refers to an entity that implements one or more PHY instances. | |
32 | For the simple case where the PHY provider implements only a single instance of | |
33 | the PHY, the framework provides its own implementation of of_xlate in | |
34 | of_phy_simple_xlate. If the PHY provider implements multiple instances, it | |
35 | should provide its own implementation of of_xlate. of_xlate is used only for | |
36 | dt boot case. | |
37 | ||
38 | :: | |
39 | ||
40 | #define of_phy_provider_register(dev, xlate) \ | |
41 | __of_phy_provider_register((dev), NULL, THIS_MODULE, (xlate)) | |
42 | ||
43 | #define devm_of_phy_provider_register(dev, xlate) \ | |
44 | __devm_of_phy_provider_register((dev), NULL, THIS_MODULE, | |
45 | (xlate)) | |
46 | ||
47 | of_phy_provider_register and devm_of_phy_provider_register macros can be used to | |
48 | register the phy_provider and it takes device and of_xlate as | |
49 | arguments. For the dt boot case, all PHY providers should use one of the above | |
50 | 2 macros to register the PHY provider. | |
51 | ||
52 | Often the device tree nodes associated with a PHY provider will contain a set | |
53 | of children that each represent a single PHY. Some bindings may nest the child | |
54 | nodes within extra levels for context and extensibility, in which case the low | |
55 | level of_phy_provider_register_full() and devm_of_phy_provider_register_full() | |
56 | macros can be used to override the node containing the children. | |
57 | ||
58 | :: | |
59 | ||
60 | #define of_phy_provider_register_full(dev, children, xlate) \ | |
61 | __of_phy_provider_register(dev, children, THIS_MODULE, xlate) | |
62 | ||
63 | #define devm_of_phy_provider_register_full(dev, children, xlate) \ | |
64 | __devm_of_phy_provider_register_full(dev, children, | |
65 | THIS_MODULE, xlate) | |
66 | ||
67 | void devm_of_phy_provider_unregister(struct device *dev, | |
68 | struct phy_provider *phy_provider); | |
69 | void of_phy_provider_unregister(struct phy_provider *phy_provider); | |
70 | ||
71 | devm_of_phy_provider_unregister and of_phy_provider_unregister can be used to | |
72 | unregister the PHY. | |
73 | ||
74 | Creating the PHY | |
75 | ================ | |
76 | ||
77 | The PHY driver should create the PHY in order for other peripheral controllers | |
78 | to make use of it. The PHY framework provides 2 APIs to create the PHY. | |
79 | ||
80 | :: | |
81 | ||
82 | struct phy *phy_create(struct device *dev, struct device_node *node, | |
83 | const struct phy_ops *ops); | |
84 | struct phy *devm_phy_create(struct device *dev, | |
85 | struct device_node *node, | |
86 | const struct phy_ops *ops); | |
87 | ||
88 | The PHY drivers can use one of the above 2 APIs to create the PHY by passing | |
89 | the device pointer and phy ops. | |
90 | phy_ops is a set of function pointers for performing PHY operations such as | |
91 | init, exit, power_on and power_off. | |
92 | ||
93 | Inorder to dereference the private data (in phy_ops), the phy provider driver | |
94 | can use phy_set_drvdata() after creating the PHY and use phy_get_drvdata() in | |
95 | phy_ops to get back the private data. | |
96 | ||
97 | 4. Getting a reference to the PHY | |
98 | ||
99 | Before the controller can make use of the PHY, it has to get a reference to | |
100 | it. This framework provides the following APIs to get a reference to the PHY. | |
101 | ||
102 | :: | |
103 | ||
104 | struct phy *phy_get(struct device *dev, const char *string); | |
105 | struct phy *phy_optional_get(struct device *dev, const char *string); | |
106 | struct phy *devm_phy_get(struct device *dev, const char *string); | |
107 | struct phy *devm_phy_optional_get(struct device *dev, | |
108 | const char *string); | |
109 | struct phy *devm_of_phy_get_by_index(struct device *dev, | |
110 | struct device_node *np, | |
111 | int index); | |
112 | ||
113 | phy_get, phy_optional_get, devm_phy_get and devm_phy_optional_get can | |
114 | be used to get the PHY. In the case of dt boot, the string arguments | |
115 | should contain the phy name as given in the dt data and in the case of | |
116 | non-dt boot, it should contain the label of the PHY. The two | |
117 | devm_phy_get associates the device with the PHY using devres on | |
118 | successful PHY get. On driver detach, release function is invoked on | |
119 | the devres data and devres data is freed. phy_optional_get and | |
120 | devm_phy_optional_get should be used when the phy is optional. These | |
121 | two functions will never return -ENODEV, but instead returns NULL when | |
122 | the phy cannot be found.Some generic drivers, such as ehci, may use multiple | |
123 | phys and for such drivers referencing phy(s) by name(s) does not make sense. In | |
124 | this case, devm_of_phy_get_by_index can be used to get a phy reference based on | |
125 | the index. | |
126 | ||
127 | It should be noted that NULL is a valid phy reference. All phy | |
128 | consumer calls on the NULL phy become NOPs. That is the release calls, | |
129 | the phy_init() and phy_exit() calls, and phy_power_on() and | |
130 | phy_power_off() calls are all NOP when applied to a NULL phy. The NULL | |
131 | phy is useful in devices for handling optional phy devices. | |
132 | ||
133 | Releasing a reference to the PHY | |
134 | ================================ | |
135 | ||
136 | When the controller no longer needs the PHY, it has to release the reference | |
137 | to the PHY it has obtained using the APIs mentioned in the above section. The | |
138 | PHY framework provides 2 APIs to release a reference to the PHY. | |
139 | ||
140 | :: | |
141 | ||
142 | void phy_put(struct phy *phy); | |
143 | void devm_phy_put(struct device *dev, struct phy *phy); | |
144 | ||
145 | Both these APIs are used to release a reference to the PHY and devm_phy_put | |
146 | destroys the devres associated with this PHY. | |
147 | ||
148 | Destroying the PHY | |
149 | ================== | |
150 | ||
151 | When the driver that created the PHY is unloaded, it should destroy the PHY it | |
152 | created using one of the following 2 APIs:: | |
153 | ||
154 | void phy_destroy(struct phy *phy); | |
155 | void devm_phy_destroy(struct device *dev, struct phy *phy); | |
156 | ||
157 | Both these APIs destroy the PHY and devm_phy_destroy destroys the devres | |
158 | associated with this PHY. | |
159 | ||
160 | PM Runtime | |
161 | ========== | |
162 | ||
163 | This subsystem is pm runtime enabled. So while creating the PHY, | |
164 | pm_runtime_enable of the phy device created by this subsystem is called and | |
165 | while destroying the PHY, pm_runtime_disable is called. Note that the phy | |
166 | device created by this subsystem will be a child of the device that calls | |
167 | phy_create (PHY provider device). | |
168 | ||
169 | So pm_runtime_get_sync of the phy_device created by this subsystem will invoke | |
170 | pm_runtime_get_sync of PHY provider device because of parent-child relationship. | |
171 | It should also be noted that phy_power_on and phy_power_off performs | |
172 | phy_pm_runtime_get_sync and phy_pm_runtime_put respectively. | |
173 | There are exported APIs like phy_pm_runtime_get, phy_pm_runtime_get_sync, | |
174 | phy_pm_runtime_put, phy_pm_runtime_put_sync, phy_pm_runtime_allow and | |
175 | phy_pm_runtime_forbid for performing PM operations. | |
176 | ||
177 | PHY Mappings | |
178 | ============ | |
179 | ||
180 | In order to get reference to a PHY without help from DeviceTree, the framework | |
181 | offers lookups which can be compared to clkdev that allow clk structures to be | |
182 | bound to devices. A lookup can be made be made during runtime when a handle to | |
183 | the struct phy already exists. | |
184 | ||
185 | The framework offers the following API for registering and unregistering the | |
186 | lookups:: | |
187 | ||
188 | int phy_create_lookup(struct phy *phy, const char *con_id, | |
189 | const char *dev_id); | |
190 | void phy_remove_lookup(struct phy *phy, const char *con_id, | |
191 | const char *dev_id); | |
192 | ||
193 | DeviceTree Binding | |
194 | ================== | |
195 | ||
196 | The documentation for PHY dt binding can be found @ | |
197 | Documentation/devicetree/bindings/phy/phy-bindings.txt |