blob: 0aa994bd9a917664fa34e8c5f481ec3e05fc986d
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), NULL, THIS_MODULE, (xlate)) |
35 | |
36 | #define devm_of_phy_provider_register(dev, xlate) \ |
37 | __devm_of_phy_provider_register((dev), NULL, 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 | Often the device tree nodes associated with a PHY provider will contain a set |
45 | of children that each represent a single PHY. Some bindings may nest the child |
46 | nodes within extra levels for context and extensibility, in which case the low |
47 | level of_phy_provider_register_full() and devm_of_phy_provider_register_full() |
48 | macros can be used to override the node containing the children. |
49 | |
50 | #define of_phy_provider_register_full(dev, children, xlate) \ |
51 | __of_phy_provider_register(dev, children, THIS_MODULE, xlate) |
52 | |
53 | #define devm_of_phy_provider_register_full(dev, children, xlate) \ |
54 | __devm_of_phy_provider_register_full(dev, children, THIS_MODULE, xlate) |
55 | |
56 | void devm_of_phy_provider_unregister(struct device *dev, |
57 | struct phy_provider *phy_provider); |
58 | void of_phy_provider_unregister(struct phy_provider *phy_provider); |
59 | |
60 | devm_of_phy_provider_unregister and of_phy_provider_unregister can be used to |
61 | unregister the PHY. |
62 | |
63 | 3. Creating the PHY |
64 | |
65 | The PHY driver should create the PHY in order for other peripheral controllers |
66 | to make use of it. The PHY framework provides 2 APIs to create the PHY. |
67 | |
68 | struct phy *phy_create(struct device *dev, struct device_node *node, |
69 | const struct phy_ops *ops); |
70 | struct phy *devm_phy_create(struct device *dev, struct device_node *node, |
71 | const struct phy_ops *ops); |
72 | |
73 | The PHY drivers can use one of the above 2 APIs to create the PHY by passing |
74 | the device pointer and phy ops. |
75 | phy_ops is a set of function pointers for performing PHY operations such as |
76 | init, exit, power_on and power_off. |
77 | |
78 | Inorder to dereference the private data (in phy_ops), the phy provider driver |
79 | can use phy_set_drvdata() after creating the PHY and use phy_get_drvdata() in |
80 | phy_ops to get back the private data. |
81 | |
82 | 4. Getting a reference to the PHY |
83 | |
84 | Before the controller can make use of the PHY, it has to get a reference to |
85 | it. This framework provides the following APIs to get a reference to the PHY. |
86 | |
87 | struct phy *phy_get(struct device *dev, const char *string); |
88 | struct phy *phy_optional_get(struct device *dev, const char *string); |
89 | struct phy *devm_phy_get(struct device *dev, const char *string); |
90 | struct phy *devm_phy_optional_get(struct device *dev, const char *string); |
91 | struct phy *devm_of_phy_get_by_index(struct device *dev, struct device_node *np, |
92 | int index); |
93 | |
94 | phy_get, phy_optional_get, devm_phy_get and devm_phy_optional_get can |
95 | be used to get the PHY. In the case of dt boot, the string arguments |
96 | should contain the phy name as given in the dt data and in the case of |
97 | non-dt boot, it should contain the label of the PHY. The two |
98 | devm_phy_get associates the device with the PHY using devres on |
99 | successful PHY get. On driver detach, release function is invoked on |
100 | the the devres data and devres data is freed. phy_optional_get and |
101 | devm_phy_optional_get should be used when the phy is optional. These |
102 | two functions will never return -ENODEV, but instead returns NULL when |
103 | the phy cannot be found.Some generic drivers, such as ehci, may use multiple |
104 | phys and for such drivers referencing phy(s) by name(s) does not make sense. In |
105 | this case, devm_of_phy_get_by_index can be used to get a phy reference based on |
106 | the index. |
107 | |
108 | It should be noted that NULL is a valid phy reference. All phy |
109 | consumer calls on the NULL phy become NOPs. That is the release calls, |
110 | the phy_init() and phy_exit() calls, and phy_power_on() and |
111 | phy_power_off() calls are all NOP when applied to a NULL phy. The NULL |
112 | phy is useful in devices for handling optional phy devices. |
113 | |
114 | 5. Releasing a reference to the PHY |
115 | |
116 | When the controller no longer needs the PHY, it has to release the reference |
117 | to the PHY it has obtained using the APIs mentioned in the above section. The |
118 | PHY framework provides 2 APIs to release a reference to the PHY. |
119 | |
120 | void phy_put(struct phy *phy); |
121 | void devm_phy_put(struct device *dev, struct phy *phy); |
122 | |
123 | Both these APIs are used to release a reference to the PHY and devm_phy_put |
124 | destroys the devres associated with this PHY. |
125 | |
126 | 6. Destroying the PHY |
127 | |
128 | When the driver that created the PHY is unloaded, it should destroy the PHY it |
129 | created using one of the following 2 APIs. |
130 | |
131 | void phy_destroy(struct phy *phy); |
132 | void devm_phy_destroy(struct device *dev, struct phy *phy); |
133 | |
134 | Both these APIs destroy the PHY and devm_phy_destroy destroys the devres |
135 | associated with this PHY. |
136 | |
137 | 7. PM Runtime |
138 | |
139 | This subsystem is pm runtime enabled. So while creating the PHY, |
140 | pm_runtime_enable of the phy device created by this subsystem is called and |
141 | while destroying the PHY, pm_runtime_disable is called. Note that the phy |
142 | device created by this subsystem will be a child of the device that calls |
143 | phy_create (PHY provider device). |
144 | |
145 | So pm_runtime_get_sync of the phy_device created by this subsystem will invoke |
146 | pm_runtime_get_sync of PHY provider device because of parent-child relationship. |
147 | It should also be noted that phy_power_on and phy_power_off performs |
148 | phy_pm_runtime_get_sync and phy_pm_runtime_put respectively. |
149 | There are exported APIs like phy_pm_runtime_get, phy_pm_runtime_get_sync, |
150 | phy_pm_runtime_put, phy_pm_runtime_put_sync, phy_pm_runtime_allow and |
151 | phy_pm_runtime_forbid for performing PM operations. |
152 | |
153 | 8. PHY Mappings |
154 | |
155 | In order to get reference to a PHY without help from DeviceTree, the framework |
156 | offers lookups which can be compared to clkdev that allow clk structures to be |
157 | bound to devices. A lookup can be made be made during runtime when a handle to |
158 | the struct phy already exists. |
159 | |
160 | The framework offers the following API for registering and unregistering the |
161 | lookups. |
162 | |
163 | int phy_create_lookup(struct phy *phy, const char *con_id, const char *dev_id); |
164 | void phy_remove_lookup(struct phy *phy, const char *con_id, const char *dev_id); |
165 | |
166 | 9. DeviceTree Binding |
167 | |
168 | The documentation for PHY dt binding can be found @ |
169 | Documentation/devicetree/bindings/phy/phy-bindings.txt |
170 |