1 =============
2 PHY subsystem
3 =============
4
5 :Author: Kishon Vijay Abraham I <kishon@ti.com>
6
7 This document explains the Generic PHY Framewo
8 and how-to-use.
9
10 Introduction
11 ============
12
13 *PHY* is the abbreviation for physical layer.
14 to the physical medium e.g., the USB controlle
15 such as serialization, de-serialization, encod
16 for obtaining the required data transmission r
17 controllers have PHY functionality embedded in
18 PHY. Other peripherals that use PHY include Wi
19 SATA etc.
20
21 The intention of creating this framework is to
22 all over the Linux kernel to drivers/phy to in
23 better code maintainability.
24
25 This framework will be of use only to devices
26 functionality is not embedded within the contr
27
28 Registering/Unregistering the PHY provider
29 ==========================================
30
31 PHY provider refers to an entity that implemen
32 For the simple case where the PHY provider imp
33 the PHY, the framework provides its own implem
34 of_phy_simple_xlate. If the PHY provider imple
35 should provide its own implementation of of_xl
36 dt boot case.
37
38 ::
39
40 #define of_phy_provider_register(dev,
41 __of_phy_provider_register((de
42
43 #define devm_of_phy_provider_register(
44 __devm_of_phy_provider_registe
45
46
47 of_phy_provider_register and devm_of_phy_provi
48 register the phy_provider and it takes device
49 arguments. For the dt boot case, all PHY provi
50 2 macros to register the PHY provider.
51
52 Often the device tree nodes associated with a
53 of children that each represent a single PHY.
54 nodes within extra levels for context and exte
55 level of_phy_provider_register_full() and devm
56 macros can be used to override the node contai
57
58 ::
59
60 #define of_phy_provider_register_full(
61 __of_phy_provider_register(dev
62
63 #define devm_of_phy_provider_register_
64 __devm_of_phy_provider_registe
65
66
67 void devm_of_phy_provider_unregister(s
68 struct phy_provider *phy_provi
69 void of_phy_provider_unregister(struct
70
71 devm_of_phy_provider_unregister and of_phy_pro
72 unregister the PHY.
73
74 Creating the PHY
75 ================
76
77 The PHY driver should create the PHY in order
78 to make use of it. The PHY framework provides
79
80 ::
81
82 struct phy *phy_create(struct device *
83 const struct ph
84 struct phy *devm_phy_create(struct dev
85 struct dev
86 const stru
87
88 The PHY drivers can use one of the above 2 API
89 the device pointer and phy ops.
90 phy_ops is a set of function pointers for perf
91 init, exit, power_on and power_off.
92
93 Inorder to dereference the private data (in ph
94 can use phy_set_drvdata() after creating the P
95 phy_ops to get back the private data.
96
97 Getting a reference to the PHY
98 ==============================
99
100 Before the controller can make use of the PHY,
101 it. This framework provides the following APIs
102
103 ::
104
105 struct phy *phy_get(struct device *dev
106 struct phy *devm_phy_get(struct device
107 struct phy *devm_phy_optional_get(stru
108 cons
109 struct phy *devm_of_phy_get(struct dev
110 const char
111 struct phy *devm_of_phy_optional_get(s
112 s
113 c
114 struct phy *devm_of_phy_get_by_index(s
115 s
116 i
117
118 phy_get, devm_phy_get and devm_phy_optional_ge
119 In the case of dt boot, the string arguments
120 should contain the phy name as given in the dt
121 non-dt boot, it should contain the label of th
122 devm_phy_get associates the device with the PH
123 successful PHY get. On driver detach, release
124 the devres data and devres data is freed.
125 The _optional_get variants should be used when
126 functions will never return -ENODEV, but inste
127 the phy cannot be found.
128 Some generic drivers, such as ehci, may use mu
129 devm_of_phy_get or devm_of_phy_get_by_index ca
130 reference based on name or index.
131
132 It should be noted that NULL is a valid phy re
133 consumer calls on the NULL phy become NOPs. Th
134 the phy_init() and phy_exit() calls, and phy_p
135 phy_power_off() calls are all NOP when applied
136 phy is useful in devices for handling optional
137
138 Order of API calls
139 ==================
140
141 The general order of calls should be::
142
143 [devm_][of_]phy_get()
144 phy_init()
145 phy_power_on()
146 [phy_set_mode[_ext]()]
147 ...
148 phy_power_off()
149 phy_exit()
150 [[of_]phy_put()]
151
152 Some PHY drivers may not implement :c:func:`ph
153 but controllers should always call these funct
154 PHYs. Some PHYs may require :c:func:`phy_set_m
155 others may use a default mode (typically confi
156 firmware). For compatibility, you should alway
157 what mode you will be using. Generally, this f
158 :c:func:`phy_power_on`, although some PHY driv
159
160 Releasing a reference to the PHY
161 ================================
162
163 When the controller no longer needs the PHY, i
164 to the PHY it has obtained using the APIs ment
165 PHY framework provides 2 APIs to release a ref
166
167 ::
168
169 void phy_put(struct phy *phy);
170 void devm_phy_put(struct device *dev,
171
172 Both these APIs are used to release a referenc
173 destroys the devres associated with this PHY.
174
175 Destroying the PHY
176 ==================
177
178 When the driver that created the PHY is unload
179 created using one of the following 2 APIs::
180
181 void phy_destroy(struct phy *phy);
182 void devm_phy_destroy(struct device *d
183
184 Both these APIs destroy the PHY and devm_phy_d
185 associated with this PHY.
186
187 PM Runtime
188 ==========
189
190 This subsystem is pm runtime enabled. So while
191 pm_runtime_enable of the phy device created by
192 while destroying the PHY, pm_runtime_disable i
193 device created by this subsystem will be a chi
194 phy_create (PHY provider device).
195
196 So pm_runtime_get_sync of the phy_device creat
197 pm_runtime_get_sync of PHY provider device bec
198 It should also be noted that phy_power_on and
199 phy_pm_runtime_get_sync and phy_pm_runtime_put
200 There are exported APIs like phy_pm_runtime_ge
201 phy_pm_runtime_put, phy_pm_runtime_put_sync, p
202 phy_pm_runtime_forbid for performing PM operat
203
204 PHY Mappings
205 ============
206
207 In order to get reference to a PHY without hel
208 offers lookups which can be compared to clkdev
209 bound to devices. A lookup can be made during
210 struct phy already exists.
211
212 The framework offers the following API for reg
213 lookups::
214
215 int phy_create_lookup(struct phy *phy,
216 const char *dev_
217 void phy_remove_lookup(struct phy *phy
218 const char *dev
219
220 DeviceTree Binding
221 ==================
222
223 The documentation for PHY dt binding can be fo
224 Documentation/devicetree/bindings/phy/phy-bind
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.