Commit | Line | Data |
---|---|---|
907d1f14 PZ |
1 | .. SPDX-License-Identifier: GPL-2.0-only |
2 | ||
3 | ==================== | |
4 | Reset controller API | |
5 | ==================== | |
6 | ||
7 | Introduction | |
8 | ============ | |
9 | ||
10 | Reset controllers are central units that control the reset signals to multiple | |
11 | peripherals. | |
12 | The reset controller API is split into two parts: | |
13 | the `consumer driver interface <#consumer-driver-interface>`__ (`API reference | |
14 | <#reset-consumer-api>`__), which allows peripheral drivers to request control | |
15 | over their reset input signals, and the `reset controller driver interface | |
16 | <#reset-controller-driver-interface>`__ (`API reference | |
17 | <#reset-controller-driver-api>`__), which is used by drivers for reset | |
18 | controller devices to register their reset controls to provide them to the | |
19 | consumers. | |
20 | ||
21 | While some reset controller hardware units also implement system restart | |
22 | functionality, restart handlers are out of scope for the reset controller API. | |
23 | ||
24 | Glossary | |
25 | -------- | |
26 | ||
27 | The reset controller API uses these terms with a specific meaning: | |
28 | ||
29 | Reset line | |
30 | ||
31 | Physical reset line carrying a reset signal from a reset controller | |
32 | hardware unit to a peripheral module. | |
33 | ||
34 | Reset control | |
35 | ||
36 | Control method that determines the state of one or multiple reset lines. | |
37 | Most commonly this is a single bit in reset controller register space that | |
38 | either allows direct control over the physical state of the reset line, or | |
39 | is self-clearing and can be used to trigger a predetermined pulse on the | |
40 | reset line. | |
41 | In more complicated reset controls, a single trigger action can launch a | |
42 | carefully timed sequence of pulses on multiple reset lines. | |
43 | ||
44 | Reset controller | |
45 | ||
46 | A hardware module that provides a number of reset controls to control a | |
47 | number of reset lines. | |
48 | ||
49 | Reset consumer | |
50 | ||
51 | Peripheral module or external IC that is put into reset by the signal on a | |
52 | reset line. | |
53 | ||
54 | Consumer driver interface | |
55 | ========================= | |
56 | ||
57 | This interface provides an API that is similar to the kernel clock framework. | |
58 | Consumer drivers use get and put operations to acquire and release reset | |
59 | controls. | |
60 | Functions are provided to assert and deassert the controlled reset lines, | |
61 | trigger reset pulses, or to query reset line status. | |
62 | ||
63 | When requesting reset controls, consumers can use symbolic names for their | |
64 | reset inputs, which are mapped to an actual reset control on an existing reset | |
65 | controller device by the core. | |
66 | ||
67 | A stub version of this API is provided when the reset controller framework is | |
68 | not in use in order to minimize the need to use ifdefs. | |
69 | ||
70 | Shared and exclusive resets | |
71 | --------------------------- | |
72 | ||
73 | The reset controller API provides either reference counted deassertion and | |
74 | assertion or direct, exclusive control. | |
75 | The distinction between shared and exclusive reset controls is made at the time | |
76 | the reset control is requested, either via devm_reset_control_get_shared() or | |
77 | via devm_reset_control_get_exclusive(). | |
78 | This choice determines the behavior of the API calls made with the reset | |
79 | control. | |
80 | ||
81 | Shared resets behave similarly to clocks in the kernel clock framework. | |
82 | They provide reference counted deassertion, where only the first deassert, | |
83 | which increments the deassertion reference count to one, and the last assert | |
84 | which decrements the deassertion reference count back to zero, have a physical | |
85 | effect on the reset line. | |
86 | ||
87 | Exclusive resets on the other hand guarantee direct control. | |
88 | That is, an assert causes the reset line to be asserted immediately, and a | |
89 | deassert causes the reset line to be deasserted immediately. | |
90 | ||
91 | Assertion and deassertion | |
92 | ------------------------- | |
93 | ||
94 | Consumer drivers use the reset_control_assert() and reset_control_deassert() | |
95 | functions to assert and deassert reset lines. | |
96 | For shared reset controls, calls to the two functions must be balanced. | |
97 | ||
98 | Note that since multiple consumers may be using a shared reset control, there | |
99 | is no guarantee that calling reset_control_assert() on a shared reset control | |
100 | will actually cause the reset line to be asserted. | |
101 | Consumer drivers using shared reset controls should assume that the reset line | |
102 | may be kept deasserted at all times. | |
103 | The API only guarantees that the reset line can not be asserted as long as any | |
104 | consumer has requested it to be deasserted. | |
105 | ||
106 | Triggering | |
107 | ---------- | |
108 | ||
109 | Consumer drivers use reset_control_reset() to trigger a reset pulse on a | |
110 | self-deasserting reset control. | |
111 | In general, these resets can not be shared between multiple consumers, since | |
112 | requesting a pulse from any consumer driver will reset all connected | |
113 | peripherals. | |
114 | ||
115 | The reset controller API allows requesting self-deasserting reset controls as | |
116 | shared, but for those only the first trigger request causes an actual pulse to | |
117 | be issued on the reset line. | |
118 | All further calls to this function have no effect until all consumers have | |
119 | called reset_control_rearm(). | |
120 | For shared reset controls, calls to the two functions must be balanced. | |
121 | This allows devices that only require an initial reset at any point before the | |
122 | driver is probed or resumed to share a pulsed reset line. | |
123 | ||
124 | Querying | |
125 | -------- | |
126 | ||
127 | Only some reset controllers support querying the current status of a reset | |
128 | line, via reset_control_status(). | |
129 | If supported, this function returns a positive non-zero value if the given | |
130 | reset line is asserted. | |
131 | The reset_control_status() function does not accept a | |
132 | `reset control array <#reset-control-arrays>`__ handle as its input parameter. | |
133 | ||
134 | Optional resets | |
135 | --------------- | |
136 | ||
137 | Often peripherals require a reset line on some platforms but not on others. | |
138 | For this, reset controls can be requested as optional using | |
139 | devm_reset_control_get_optional_exclusive() or | |
140 | devm_reset_control_get_optional_shared(). | |
141 | These functions return a NULL pointer instead of an error when the requested | |
142 | reset control is not specified in the device tree. | |
143 | Passing a NULL pointer to the reset_control functions causes them to return | |
144 | quietly without an error. | |
145 | ||
146 | Reset control arrays | |
147 | -------------------- | |
148 | ||
149 | Some drivers need to assert a bunch of reset lines in no particular order. | |
150 | devm_reset_control_array_get() returns an opaque reset control handle that can | |
151 | be used to assert, deassert, or trigger all specified reset controls at once. | |
152 | The reset control API does not guarantee the order in which the individual | |
153 | controls therein are handled. | |
154 | ||
155 | Reset controller driver interface | |
156 | ================================= | |
157 | ||
158 | Drivers for reset controller modules provide the functionality necessary to | |
159 | assert or deassert reset signals, to trigger a reset pulse on a reset line, or | |
160 | to query its current state. | |
161 | All functions are optional. | |
162 | ||
163 | Initialization | |
164 | -------------- | |
165 | ||
166 | Drivers fill a struct :c:type:`reset_controller_dev` and register it with | |
167 | reset_controller_register() in their probe function. | |
168 | The actual functionality is implemented in callback functions via a struct | |
169 | :c:type:`reset_control_ops`. | |
170 | ||
171 | API reference | |
172 | ============= | |
173 | ||
174 | The reset controller API is documented here in two parts: | |
175 | the `reset consumer API <#reset-consumer-api>`__ and the `reset controller | |
176 | driver API <#reset-controller-driver-api>`__. | |
177 | ||
178 | Reset consumer API | |
179 | ------------------ | |
180 | ||
181 | Reset consumers can control a reset line using an opaque reset control handle, | |
182 | which can be obtained from devm_reset_control_get_exclusive() or | |
183 | devm_reset_control_get_shared(). | |
184 | Given the reset control, consumers can call reset_control_assert() and | |
185 | reset_control_deassert(), trigger a reset pulse using reset_control_reset(), or | |
186 | query the reset line status using reset_control_status(). | |
187 | ||
188 | .. kernel-doc:: include/linux/reset.h | |
189 | :internal: | |
190 | ||
191 | .. kernel-doc:: drivers/reset/core.c | |
192 | :functions: reset_control_reset | |
193 | reset_control_assert | |
194 | reset_control_deassert | |
195 | reset_control_status | |
196 | reset_control_acquire | |
197 | reset_control_release | |
198 | reset_control_rearm | |
199 | reset_control_put | |
200 | of_reset_control_get_count | |
201 | of_reset_control_array_get | |
202 | devm_reset_control_array_get | |
203 | reset_control_get_count | |
204 | ||
205 | Reset controller driver API | |
206 | --------------------------- | |
207 | ||
208 | Reset controller drivers are supposed to implement the necessary functions in | |
209 | a static constant structure :c:type:`reset_control_ops`, allocate and fill out | |
210 | a struct :c:type:`reset_controller_dev`, and register it using | |
211 | devm_reset_controller_register(). | |
212 | ||
213 | .. kernel-doc:: include/linux/reset-controller.h | |
214 | :internal: | |
215 | ||
216 | .. kernel-doc:: drivers/reset/core.c | |
217 | :functions: of_reset_simple_xlate | |
218 | reset_controller_register | |
219 | reset_controller_unregister | |
220 | devm_reset_controller_register | |
221 | reset_controller_add_lookup |