1 /* SPDX-License-Identifier: GPL-2.0 */
2 /*
3  * Copyright (c) 2016, NVIDIA CORPORATION.
4  */
5 
6 #ifndef _RESET_H
7 #define _RESET_H
8 
9 #include <dm/ofnode.h>
10 #include <linux/err.h>
11 
12 /**
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.
21  *
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.
26  *
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.
29  */
30 
31 struct udevice;
32 
33 /**
34  * struct reset_ctl - A handle to (allowing control of) a single reset signal.
35  *
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.
41  *
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.
47  * @polarity: An optional polarity field for drivers that support
48  *	  different reset polarities.
49  *
50  * Should additional information to identify and configure any reset signal
51  * for any provider be required in the future, the struct could be expanded to
52  * either (a) add more fields to allow reset providers to store additional
53  * information, or (b) replace the id field with an opaque pointer, which the
54  * provider would dynamically allocated during its .of_xlate op, and process
55  * during is .request op. This may require the addition of an extra op to clean
56  * up the allocation.
57  */
58 struct reset_ctl {
59 	struct udevice *dev;
60 	/*
61 	 * Written by of_xlate. In the future, we might add more fields here.
62 	 */
63 	unsigned long id;
64 	unsigned long data;
65 	unsigned long polarity;
66 };
67 
68 /**
69  * struct reset_ctl_bulk - A handle to (allowing control of) a bulk of reset
70  * signals.
71  *
72  * Clients provide storage for the reset control bulk. The content of the
73  * structure is managed solely by the reset API. A reset control bulk struct is
74  * initialized by "get"ing the reset control bulk struct.
75  * The reset control bulk struct is passed to all other bulk reset APIs to apply
76  * the API to all the reset signals in the bulk struct.
77  *
78  * @resets: An array of reset signal handles handles.
79  * @count: The number of reset signal handles in the reset array.
80  */
81 struct reset_ctl_bulk {
82 	struct reset_ctl *resets;
83 	unsigned int count;
84 };
85 
86 #if CONFIG_IS_ENABLED(DM_RESET)
87 
88 /**
89  * devm_reset_control_get - resource managed reset_get_by_name()
90  * @dev: device to be reset by the controller
91  * @id: reset line name
92  *
93  * Managed reset_get_by_name(). For reset controllers returned
94  * from this function, reset_free() is called automatically on driver
95  * detach.
96  *
97  * Returns a struct reset_ctl or IS_ERR() condition containing errno.
98  */
99 struct reset_ctl *devm_reset_control_get(struct udevice *dev, const char *id);
100 
101 /**
102  * devm_reset_control_get_optional - resource managed reset_get_by_name() that
103  *                                   can fail
104  * @dev:	The client device.
105  * @id:		reset line name
106  *
107  * Managed reset_get_by_name(). For reset controllers returned
108  * from this function, reset_free() is called automatically on driver
109  * detach.
110  *
111  * Returns a struct reset_ctl or a dummy reset controller if it failed.
112  */
113 struct reset_ctl *devm_reset_control_get_optional(struct udevice *dev,
114 						  const char *id);
115 
116 /**
117  * devm_reset_control_get - resource managed reset_get_by_index()
118  * @dev:	The client device.
119  * @index:	The index of the reset signal to request, within the client's
120  *		list of reset signals.
121  *
122  * Managed reset_get_by_index(). For reset controllers returned
123  * from this function, reset_free() is called automatically on driver
124  * detach.
125  *
126  * Returns a struct reset_ctl or IS_ERR() condition containing errno.
127  */
128 struct reset_ctl *devm_reset_control_get_by_index(struct udevice *dev,
129 						  int index);
130 
131 /**
132  * devm_reset_bulk_get - resource managed reset_get_bulk()
133  * @dev: device to be reset by the controller
134  *
135  * Managed reset_get_bulk(). For reset controllers returned
136  * from this function, reset_free() is called automatically on driver
137  * detach.
138  *
139  * Returns a struct reset_ctl or IS_ERR() condition containing errno.
140  */
141 struct reset_ctl_bulk *devm_reset_bulk_get(struct udevice *dev);
142 
143 /**
144  * devm_reset_bulk_get_optional - resource managed reset_get_bulk() that
145  *                                can fail
146  * @dev:	The client device.
147  *
148  * Managed reset_get_bulk(). For reset controllers returned
149  * from this function, reset_free() is called automatically on driver
150  * detach.
151  *
152  * Returns a struct reset_ctl or NULL if it failed.
153  */
154 struct reset_ctl_bulk *devm_reset_bulk_get_optional(struct udevice *dev);
155 
156 /**
157  * devm_reset_bulk_get_by_node - resource managed reset_get_bulk()
158  * @dev: device to be reset by the controller
159  * @node: ofnode where the "resets" property is. Usually a sub-node of
160  *        the dev's node.
161  *
162  * see devm_reset_bulk_get()
163  */
164 struct reset_ctl_bulk *devm_reset_bulk_get_by_node(struct udevice *dev,
165 						   ofnode node);
166 
167 /**
168  * devm_reset_bulk_get_optional_by_node - resource managed reset_get_bulk()
169  *                                        that can fail
170  * @dev: device to be reset by the controller
171  * @node: ofnode where the "resets" property is. Usually a sub-node of
172  *        the dev's node.
173  *
174  * see devm_reset_bulk_get_optional()
175  */
176 struct reset_ctl_bulk *devm_reset_bulk_get_optional_by_node(struct udevice *dev,
177 							    ofnode node);
178 
179 /**
180  * reset_get_by_index - Get/request a reset signal by integer index.
181  *
182  * This looks up and requests a reset signal. The index is relative to the
183  * client device; each device is assumed to have n reset signals associated
184  * with it somehow, and this function finds and requests one of them. The
185  * mapping of client device reset signal indices to provider reset signals may
186  * be via device-tree properties, board-provided mapping tables, or some other
187  * mechanism.
188  *
189  * @dev:	The client device.
190  * @index:	The index of the reset signal to request, within the client's
191  *		list of reset signals.
192  * @reset_ctl	A pointer to a reset control struct to initialize.
193  * @return 0 if OK, or a negative error code.
194  */
195 int reset_get_by_index(struct udevice *dev, int index,
196 		       struct reset_ctl *reset_ctl);
197 
198 /**
199  * reset_get_by_index_nodev - Get/request a reset signal by integer index
200  * without a device.
201  *
202  * This is a version of reset_get_by_index() that does not use a device.
203  *
204  * @node:	The client ofnode.
205  * @index:	The index of the reset signal to request, within the client's
206  *		list of reset signals.
207  * @reset_ctl	A pointer to a reset control struct to initialize.
208  * @return 0 if OK, or a negative error code.
209  */
210 int reset_get_by_index_nodev(ofnode node, int index,
211 			     struct reset_ctl *reset_ctl);
212 
213 /**
214  * reset_get_bulk - Get/request all reset signals of a device.
215  *
216  * This looks up and requests all reset signals of the client device; each
217  * device is assumed to have n reset signals associated with it somehow,
218  * and this function finds and requests all of them in a separate structure.
219  * The mapping of client device reset signals indices to provider reset signals
220  * may be via device-tree properties, board-provided mapping tables, or some
221  * other mechanism.
222  *
223  * @dev:	The client device.
224  * @bulk	A pointer to a reset control bulk struct to initialize.
225  * @return 0 if OK, or a negative error code.
226  */
227 int reset_get_bulk(struct udevice *dev, struct reset_ctl_bulk *bulk);
228 
229 /**
230  * reset_get_by_name - Get/request a reset signal by name.
231  *
232  * This looks up and requests a reset signal. The name is relative to the
233  * client device; each device is assumed to have n reset signals associated
234  * with it somehow, and this function finds and requests one of them. The
235  * mapping of client device reset signal names to provider reset signal may be
236  * via device-tree properties, board-provided mapping tables, or some other
237  * mechanism.
238  *
239  * @dev:	The client device.
240  * @name:	The name of the reset signal to request, within the client's
241  *		list of reset signals.
242  * @reset_ctl:	A pointer to a reset control struct to initialize.
243  * @return 0 if OK, or a negative error code.
244  */
245 int reset_get_by_name(struct udevice *dev, const char *name,
246 		      struct reset_ctl *reset_ctl);
247 
248 /**
249  * reset_request - Request a reset signal.
250  *
251  * @reset_ctl:	A reset control struct.
252  *
253  * @return 0 if OK, or a negative error code.
254  */
255 int reset_request(struct reset_ctl *reset_ctl);
256 
257 /**
258  * reset_free - Free a previously requested reset signal.
259  *
260  * @reset_ctl:	A reset control struct that was previously successfully
261  *		requested by reset_get_by_*().
262  * @return 0 if OK, or a negative error code.
263  */
264 int reset_free(struct reset_ctl *reset_ctl);
265 
266 /**
267  * reset_assert - Assert a reset signal.
268  *
269  * This function will assert the specified reset signal, thus resetting the
270  * affected HW module(s). Depending on the reset controller hardware, the reset
271  * signal will either stay asserted until reset_deassert() is called, or the
272  * hardware may autonomously clear the reset signal itself.
273  *
274  * @reset_ctl:	A reset control struct that was previously successfully
275  *		requested by reset_get_by_*().
276  * @return 0 if OK, or a negative error code.
277  */
278 int reset_assert(struct reset_ctl *reset_ctl);
279 
280 /**
281  * reset_assert_bulk - Assert all reset signals in a reset control bulk struct.
282  *
283  * This function will assert the specified reset signals in a reset control
284  * bulk struct, thus resetting the affected HW module(s). Depending on the
285  * reset controller hardware, the reset signals will either stay asserted
286  * until reset_deassert_bulk() is called, or the hardware may autonomously
287  * clear the reset signals itself.
288  *
289  * @bulk:	A reset control bulk struct that was previously successfully
290  *		requested by reset_get_bulk().
291  * @return 0 if OK, or a negative error code.
292  */
293 int reset_assert_bulk(struct reset_ctl_bulk *bulk);
294 
295 /**
296  * reset_deassert - Deassert a reset signal.
297  *
298  * This function will deassert the specified reset signal, thus releasing the
299  * affected HW modules() from reset, and allowing them to continue normal
300  * operation.
301  *
302  * @reset_ctl:	A reset control struct that was previously successfully
303  *		requested by reset_get_by_*().
304  * @return 0 if OK, or a negative error code.
305  */
306 int reset_deassert(struct reset_ctl *reset_ctl);
307 
308 /**
309  * reset_deassert_bulk - Deassert all reset signals in a reset control bulk
310  * struct.
311  *
312  * This function will deassert the specified reset signals in a reset control
313  * bulk struct, thus releasing the affected HW modules() from reset, and
314  * allowing them to continue normal operation.
315  *
316  * @bulk:	A reset control bulk struct that was previously successfully
317  *		requested by reset_get_bulk().
318  * @return 0 if OK, or a negative error code.
319  */
320 int reset_deassert_bulk(struct reset_ctl_bulk *bulk);
321 
322 /**
323  * rst_status - Check reset signal status.
324  *
325  * @reset_ctl:	The reset signal to check.
326  * @return 0 if deasserted, positive if asserted, or a negative
327  *           error code.
328  */
329 int reset_status(struct reset_ctl *reset_ctl);
330 
331 /**
332  * reset_release_all - Assert/Free an array of previously requested resets.
333  *
334  * For each reset contained in the reset array, this function will check if
335  * reset has been previously requested and then will assert and free it.
336  *
337  * @reset_ctl:	A reset struct array that was previously successfully
338  *		requested by reset_get_by_*().
339  * @count	Number of reset contained in the array
340  * @return 0 if OK, or a negative error code.
341  */
342 int reset_release_all(struct reset_ctl *reset_ctl, int count);
343 
344 /**
345  * reset_release_bulk - Assert/Free an array of previously requested reset
346  * signals in a reset control bulk struct.
347  *
348  * For each reset contained in the reset control bulk struct, this function
349  * will check if reset has been previously requested and then will assert
350  * and free it.
351  *
352  * @bulk:	A reset control bulk struct that was previously successfully
353  *		requested by reset_get_bulk().
354  * @return 0 if OK, or a negative error code.
355  */
reset_release_bulk(struct reset_ctl_bulk * bulk)356 static inline int reset_release_bulk(struct reset_ctl_bulk *bulk)
357 {
358 	return reset_release_all(bulk->resets, bulk->count);
359 }
360 
361 #else
devm_reset_control_get(struct udevice * dev,const char * id)362 static inline struct reset_ctl *devm_reset_control_get(struct udevice *dev,
363 						       const char *id)
364 {
365 	return ERR_PTR(-ENOTSUPP);
366 }
367 
devm_reset_control_get_optional(struct udevice * dev,const char * id)368 static inline struct reset_ctl *devm_reset_control_get_optional(struct udevice *dev,
369 								const char *id)
370 {
371 	return NULL;
372 }
373 
devm_reset_control_get_by_index(struct udevice * dev,int index)374 static inline struct reset_ctl *devm_reset_control_get_by_index(struct udevice *dev,
375 								int index)
376 {
377 	return ERR_PTR(-ENOTSUPP);
378 }
379 
devm_reset_bulk_get(struct udevice * dev)380 static inline struct reset_ctl_bulk *devm_reset_bulk_get(struct udevice *dev)
381 {
382 	return ERR_PTR(-ENOTSUPP);
383 }
384 
devm_reset_bulk_get_optional(struct udevice * dev)385 static inline struct reset_ctl_bulk *devm_reset_bulk_get_optional(struct udevice *dev)
386 {
387 	return NULL;
388 }
389 
devm_reset_bulk_get_by_node(struct udevice * dev,ofnode node)390 static inline struct reset_ctl_bulk *devm_reset_bulk_get_by_node(struct udevice *dev,
391 								 ofnode node)
392 {
393 	return ERR_PTR(-ENOTSUPP);
394 }
395 
devm_reset_bulk_get_optional_by_node(struct udevice * dev,ofnode node)396 static inline struct reset_ctl_bulk *devm_reset_bulk_get_optional_by_node(struct udevice *dev,
397 									  ofnode node)
398 {
399 	return NULL;
400 }
401 
reset_get_by_index(struct udevice * dev,int index,struct reset_ctl * reset_ctl)402 static inline int reset_get_by_index(struct udevice *dev, int index,
403 				     struct reset_ctl *reset_ctl)
404 {
405 	return -ENOTSUPP;
406 }
407 
reset_get_bulk(struct udevice * dev,struct reset_ctl_bulk * bulk)408 static inline int reset_get_bulk(struct udevice *dev,
409 				 struct reset_ctl_bulk *bulk)
410 {
411 	return -ENOTSUPP;
412 }
413 
reset_get_by_name(struct udevice * dev,const char * name,struct reset_ctl * reset_ctl)414 static inline int reset_get_by_name(struct udevice *dev, const char *name,
415 				    struct reset_ctl *reset_ctl)
416 {
417 	return -ENOTSUPP;
418 }
419 
reset_free(struct reset_ctl * reset_ctl)420 static inline int reset_free(struct reset_ctl *reset_ctl)
421 {
422 	return 0;
423 }
424 
reset_assert(struct reset_ctl * reset_ctl)425 static inline int reset_assert(struct reset_ctl *reset_ctl)
426 {
427 	return 0;
428 }
429 
reset_assert_bulk(struct reset_ctl_bulk * bulk)430 static inline int reset_assert_bulk(struct reset_ctl_bulk *bulk)
431 {
432 	return 0;
433 }
434 
reset_deassert(struct reset_ctl * reset_ctl)435 static inline int reset_deassert(struct reset_ctl *reset_ctl)
436 {
437 	return 0;
438 }
439 
reset_deassert_bulk(struct reset_ctl_bulk * bulk)440 static inline int reset_deassert_bulk(struct reset_ctl_bulk *bulk)
441 {
442 	return 0;
443 }
444 
reset_status(struct reset_ctl * reset_ctl)445 static inline int reset_status(struct reset_ctl *reset_ctl)
446 {
447 	return -ENOTSUPP;
448 }
449 
reset_release_all(struct reset_ctl * reset_ctl,int count)450 static inline int reset_release_all(struct reset_ctl *reset_ctl, int count)
451 {
452 	return 0;
453 }
454 
reset_release_bulk(struct reset_ctl_bulk * bulk)455 static inline int reset_release_bulk(struct reset_ctl_bulk *bulk)
456 {
457 	return 0;
458 }
459 #endif
460 
461 /**
462  * reset_valid() - check if reset is valid
463  *
464  * @reset_ctl:		the reset to check
465  * @return TRUE if valid, or FALSE
466  */
reset_valid(struct reset_ctl * reset_ctl)467 static inline bool reset_valid(struct reset_ctl *reset_ctl)
468 {
469 	return !!reset_ctl->dev;
470 }
471 
472 #endif
473