1 /* SPDX-License-Identifier: GPL-2.0 */
3 * Copyright (c) 2016, NVIDIA CORPORATION.
10 #include <linux/errno.h>
13 * A reset is a hardware signal indicating that a HW module (or IP block, or
14 * sometimes an entire off-CPU chip) reset all of its internal state to some
15 * known-good initial state. Drivers will often reset HW modules when they
16 * begin execution to ensure that hardware correctly responds to all requests,
17 * or in response to some error condition. Reset signals are often controlled
18 * externally to the HW module being reset, by an entity this API calls a reset
19 * controller. This API provides a standard means for drivers to request that
20 * reset controllers set or clear reset signals.
22 * A driver that implements UCLASS_RESET is a reset controller or provider. A
23 * controller will often implement multiple separate reset signals, since the
24 * hardware it manages often has this capability. reset-uclass.h describes the
25 * interface which reset controllers must implement.
27 * Reset consumers/clients are the HW modules affected by reset signals. This
28 * header file describes the API used by drivers for those HW modules.
34 * struct reset_ctl - A handle to (allowing control of) a single reset signal.
36 * Clients provide storage for reset control handles. The content of the
37 * structure is managed solely by the reset API and reset drivers. A reset
38 * control struct is initialized by "get"ing the reset control struct. The
39 * reset control struct is passed to all other reset APIs to identify which
40 * reset signal to operate upon.
42 * @dev: The device which implements the reset signal.
43 * @id: The reset signal ID within the provider.
44 * @data: An optional data field for scenarios where a single integer ID is not
45 * sufficient. If used, it can be populated through an .of_xlate op and
46 * processed during the various reset ops.
48 * Should additional information to identify and configure any reset signal
49 * for any provider be required in the future, the struct could be expanded to
50 * either (a) add more fields to allow reset providers to store additional
51 * information, or (b) replace the id field with an opaque pointer, which the
52 * provider would dynamically allocated during its .of_xlate op, and process
53 * during is .request op. This may require the addition of an extra op to clean
59 * Written by of_xlate. In the future, we might add more fields here.
66 * struct reset_ctl_bulk - A handle to (allowing control of) a bulk of reset
69 * Clients provide storage for the reset control bulk. The content of the
70 * structure is managed solely by the reset API. A reset control bulk struct is
71 * initialized by "get"ing the reset control bulk struct.
72 * The reset control bulk struct is passed to all other bulk reset APIs to apply
73 * the API to all the reset signals in the bulk struct.
75 * @resets: An array of reset signal handles handles.
76 * @count: The number of reset signal handles in the reset array.
78 struct reset_ctl_bulk {
79 struct reset_ctl *resets;
83 #if CONFIG_IS_ENABLED(DM_RESET)
85 * reset_get_by_index - Get/request a reset signal by integer index.
87 * This looks up and requests a reset signal. The index is relative to the
88 * client device; each device is assumed to have n reset signals associated
89 * with it somehow, and this function finds and requests one of them. The
90 * mapping of client device reset signal indices to provider reset signals may
91 * be via device-tree properties, board-provided mapping tables, or some other
94 * @dev: The client device.
95 * @index: The index of the reset signal to request, within the client's
96 * list of reset signals.
97 * @reset_ctl A pointer to a reset control struct to initialize.
98 * @return 0 if OK, or a negative error code.
100 int reset_get_by_index(struct udevice *dev, int index,
101 struct reset_ctl *reset_ctl);
104 * reset_get_by_index_nodev - Get/request a reset signal by integer index
107 * This is a version of reset_get_by_index() that does not use a device.
109 * @node: The client ofnode.
110 * @index: The index of the reset signal to request, within the client's
111 * list of reset signals.
112 * @reset_ctl A pointer to a reset control struct to initialize.
113 * @return 0 if OK, or a negative error code.
115 int reset_get_by_index_nodev(ofnode node, int index,
116 struct reset_ctl *reset_ctl);
119 * reset_get_bulk - Get/request all reset signals of a device.
121 * This looks up and requests all reset signals of the client device; each
122 * device is assumed to have n reset signals associated with it somehow,
123 * and this function finds and requests all of them in a separate structure.
124 * The mapping of client device reset signals indices to provider reset signals
125 * may be via device-tree properties, board-provided mapping tables, or some
128 * @dev: The client device.
129 * @bulk A pointer to a reset control bulk struct to initialize.
130 * @return 0 if OK, or a negative error code.
132 int reset_get_bulk(struct udevice *dev, struct reset_ctl_bulk *bulk);
135 * reset_get_by_name - Get/request a reset signal by name.
137 * This looks up and requests a reset signal. The name is relative to the
138 * client device; each device is assumed to have n reset signals associated
139 * with it somehow, and this function finds and requests one of them. The
140 * mapping of client device reset signal names to provider reset signal may be
141 * via device-tree properties, board-provided mapping tables, or some other
144 * @dev: The client device.
145 * @name: The name of the reset signal to request, within the client's
146 * list of reset signals.
147 * @reset_ctl: A pointer to a reset control struct to initialize.
148 * @return 0 if OK, or a negative error code.
150 int reset_get_by_name(struct udevice *dev, const char *name,
151 struct reset_ctl *reset_ctl);
154 * reset_request - Request a reset signal.
156 * @reset_ctl: A reset control struct.
158 * @return 0 if OK, or a negative error code.
160 int reset_request(struct reset_ctl *reset_ctl);
163 * reset_free - Free a previously requested reset signal.
165 * @reset_ctl: A reset control struct that was previously successfully
166 * requested by reset_get_by_*().
167 * @return 0 if OK, or a negative error code.
169 int reset_free(struct reset_ctl *reset_ctl);
172 * reset_assert - Assert a reset signal.
174 * This function will assert the specified reset signal, thus resetting the
175 * affected HW module(s). Depending on the reset controller hardware, the reset
176 * signal will either stay asserted until reset_deassert() is called, or the
177 * hardware may autonomously clear the reset signal itself.
179 * @reset_ctl: A reset control struct that was previously successfully
180 * requested by reset_get_by_*().
181 * @return 0 if OK, or a negative error code.
183 int reset_assert(struct reset_ctl *reset_ctl);
186 * reset_assert_bulk - Assert all reset signals in a reset control bulk struct.
188 * This function will assert the specified reset signals in a reset control
189 * bulk struct, thus resetting the affected HW module(s). Depending on the
190 * reset controller hardware, the reset signals will either stay asserted
191 * until reset_deassert_bulk() is called, or the hardware may autonomously
192 * clear the reset signals itself.
194 * @bulk: A reset control bulk struct that was previously successfully
195 * requested by reset_get_bulk().
196 * @return 0 if OK, or a negative error code.
198 int reset_assert_bulk(struct reset_ctl_bulk *bulk);
201 * reset_deassert - Deassert a reset signal.
203 * This function will deassert the specified reset signal, thus releasing the
204 * affected HW modules() from reset, and allowing them to continue normal
207 * @reset_ctl: A reset control struct that was previously successfully
208 * requested by reset_get_by_*().
209 * @return 0 if OK, or a negative error code.
211 int reset_deassert(struct reset_ctl *reset_ctl);
214 * reset_deassert_bulk - Deassert all reset signals in a reset control bulk
217 * This function will deassert the specified reset signals in a reset control
218 * bulk struct, thus releasing the affected HW modules() from reset, and
219 * allowing them to continue normal operation.
221 * @bulk: A reset control bulk struct that was previously successfully
222 * requested by reset_get_bulk().
223 * @return 0 if OK, or a negative error code.
225 int reset_deassert_bulk(struct reset_ctl_bulk *bulk);
228 * rst_status - Check reset signal status.
230 * @reset_ctl: The reset signal to check.
231 * @return 0 if deasserted, positive if asserted, or a negative
234 int reset_status(struct reset_ctl *reset_ctl);
237 * reset_release_all - Assert/Free an array of previously requested resets.
239 * For each reset contained in the reset array, this function will check if
240 * reset has been previously requested and then will assert and free it.
242 * @reset_ctl: A reset struct array that was previously successfully
243 * requested by reset_get_by_*().
244 * @count Number of reset contained in the array
245 * @return 0 if OK, or a negative error code.
247 int reset_release_all(struct reset_ctl *reset_ctl, int count);
250 * reset_release_bulk - Assert/Free an array of previously requested reset
251 * signals in a reset control bulk struct.
253 * For each reset contained in the reset control bulk struct, this function
254 * will check if reset has been previously requested and then will assert
257 * @bulk: A reset control bulk struct that was previously successfully
258 * requested by reset_get_bulk().
259 * @return 0 if OK, or a negative error code.
261 static inline int reset_release_bulk(struct reset_ctl_bulk *bulk)
263 return reset_release_all(bulk->resets, bulk->count);
266 static inline int reset_get_by_index(struct udevice *dev, int index,
267 struct reset_ctl *reset_ctl)
272 static inline int reset_get_bulk(struct udevice *dev,
273 struct reset_ctl_bulk *bulk)
278 static inline int reset_get_by_name(struct udevice *dev, const char *name,
279 struct reset_ctl *reset_ctl)
284 static inline int reset_free(struct reset_ctl *reset_ctl)
289 static inline int reset_assert(struct reset_ctl *reset_ctl)
294 static inline int reset_assert_bulk(struct reset_ctl_bulk *bulk)
299 static inline int reset_deassert(struct reset_ctl *reset_ctl)
304 static inline int reset_deassert_bulk(struct reset_ctl_bulk *bulk)
309 static inline int reset_status(struct reset_ctl *reset_ctl)
314 static inline int reset_release_all(struct reset_ctl *reset_ctl, int count)
319 static inline int reset_release_bulk(struct reset_ctl_bulk *bulk)
326 * reset_valid() - check if reset is valid
328 * @reset_ctl: the reset to check
329 * @return TRUE if valid, or FALSE
331 static inline bool reset_valid(struct reset_ctl *reset_ctl)
333 return !!reset_ctl->dev;