xref: /openbmc/u-boot/include/reset.h (revision 5d89b37f)
1 /*
2  * Copyright (c) 2016, NVIDIA CORPORATION.
3  *
4  * SPDX-License-Identifier: GPL-2.0
5  */
6 
7 #ifndef _RESET_H
8 #define _RESET_H
9 
10 #include <linux/errno.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  *
45  * Currently, the reset API assumes that a single integer ID is enough to
46  * identify and configure any reset signal for any reset provider. If this
47  * assumption becomes invalid in the future, the struct could be expanded to
48  * either (a) add more fields to allow reset providers to store additional
49  * information, or (b) replace the id field with an opaque pointer, which the
50  * provider would dynamically allocated during its .of_xlate op, and process
51  * during is .request op. This may require the addition of an extra op to clean
52  * up the allocation.
53  */
54 struct reset_ctl {
55 	struct udevice *dev;
56 	/*
57 	 * Written by of_xlate. We assume a single id is enough for now. In the
58 	 * future, we might add more fields here.
59 	 */
60 	unsigned long id;
61 };
62 
63 #ifdef CONFIG_DM_RESET
64 /**
65  * reset_get_by_index - Get/request a reset signal by integer index.
66  *
67  * This looks up and requests a reset signal. The index is relative to the
68  * client device; each device is assumed to have n reset signals associated
69  * with it somehow, and this function finds and requests one of them. The
70  * mapping of client device reset signal indices to provider reset signals may
71  * be via device-tree properties, board-provided mapping tables, or some other
72  * mechanism.
73  *
74  * @dev:	The client device.
75  * @index:	The index of the reset signal to request, within the client's
76  *		list of reset signals.
77  * @reset_ctl	A pointer to a reset control struct to initialize.
78  * @return 0 if OK, or a negative error code.
79  */
80 int reset_get_by_index(struct udevice *dev, int index,
81 		       struct reset_ctl *reset_ctl);
82 
83 /**
84  * reset_get_by_name - Get/request a reset signal by name.
85  *
86  * This looks up and requests a reset signal. The name is relative to the
87  * client device; each device is assumed to have n reset signals associated
88  * with it somehow, and this function finds and requests one of them. The
89  * mapping of client device reset signal names to provider reset signal may be
90  * via device-tree properties, board-provided mapping tables, or some other
91  * mechanism.
92  *
93  * @dev:	The client device.
94  * @name:	The name of the reset signal to request, within the client's
95  *		list of reset signals.
96  * @reset_ctl:	A pointer to a reset control struct to initialize.
97  * @return 0 if OK, or a negative error code.
98  */
99 int reset_get_by_name(struct udevice *dev, const char *name,
100 		      struct reset_ctl *reset_ctl);
101 
102 /**
103  * reset_request - Request a reset signal.
104  *
105  * @reset_ctl:	A reset control struct.
106  *
107  * @return 0 if OK, or a negative error code.
108  */
109 int reset_request(struct reset_ctl *reset_ctl);
110 
111 /**
112  * reset_free - Free a previously requested reset signal.
113  *
114  * @reset_ctl:	A reset control struct that was previously successfully
115  *		requested by reset_get_by_*().
116  * @return 0 if OK, or a negative error code.
117  */
118 int reset_free(struct reset_ctl *reset_ctl);
119 
120 /**
121  * reset_assert - Assert a reset signal.
122  *
123  * This function will assert the specified reset signal, thus resetting the
124  * affected HW module(s). Depending on the reset controller hardware, the reset
125  * signal will either stay asserted until reset_deassert() is called, or the
126  * hardware may autonomously clear the reset signal itself.
127  *
128  * @reset_ctl:	A reset control struct that was previously successfully
129  *		requested by reset_get_by_*().
130  * @return 0 if OK, or a negative error code.
131  */
132 int reset_assert(struct reset_ctl *reset_ctl);
133 
134 /**
135  * reset_deassert - Deassert a reset signal.
136  *
137  * This function will deassert the specified reset signal, thus releasing the
138  * affected HW modules() from reset, and allowing them to continue normal
139  * operation.
140  *
141  * @reset_ctl:	A reset control struct that was previously successfully
142  *		requested by reset_get_by_*().
143  * @return 0 if OK, or a negative error code.
144  */
145 int reset_deassert(struct reset_ctl *reset_ctl);
146 
147 /**
148  * reset_release_all - Assert/Free an array of previously requested resets.
149  *
150  * For each reset contained in the reset array, this function will check if
151  * reset has been previously requested and then will assert and free it.
152  *
153  * @reset_ctl:	A reset struct array that was previously successfully
154  *		requested by reset_get_by_*().
155  * @count	Number of reset contained in the array
156  * @return 0 if OK, or a negative error code.
157  */
158 int reset_release_all(struct reset_ctl *reset_ctl, int count);
159 #else
160 static inline int reset_get_by_index(struct udevice *dev, int index,
161 				     struct reset_ctl *reset_ctl)
162 {
163 	return -ENOTSUPP;
164 }
165 
166 static inline int reset_get_by_name(struct udevice *dev, const char *name,
167 				    struct reset_ctl *reset_ctl)
168 {
169 	return -ENOTSUPP;
170 }
171 
172 static inline int reset_free(struct reset_ctl *reset_ctl)
173 {
174 	return 0;
175 }
176 
177 static inline int reset_assert(struct reset_ctl *reset_ctl)
178 {
179 	return 0;
180 }
181 
182 static inline int reset_deassert(struct reset_ctl *reset_ctl)
183 {
184 	return 0;
185 }
186 
187 static inline int reset_release_all(struct reset_ctl *reset_ctl, int count)
188 {
189 	return 0;
190 }
191 
192 #endif
193 
194 #endif
195