Root/
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 |
167 |
Branches:
ben-wpan
ben-wpan-stefan
javiroman/ks7010
jz-2.6.34
jz-2.6.34-rc5
jz-2.6.34-rc6
jz-2.6.34-rc7
jz-2.6.35
jz-2.6.36
jz-2.6.37
jz-2.6.38
jz-2.6.39
jz-3.0
jz-3.1
jz-3.11
jz-3.12
jz-3.13
jz-3.15
jz-3.16
jz-3.18-dt
jz-3.2
jz-3.3
jz-3.4
jz-3.5
jz-3.6
jz-3.6-rc2-pwm
jz-3.9
jz-3.9-clk
jz-3.9-rc8
jz47xx
jz47xx-2.6.38
master
Tags:
od-2011-09-04
od-2011-09-18
v2.6.34-rc5
v2.6.34-rc6
v2.6.34-rc7
v3.9