]>
git.ipfire.org Git - thirdparty/u-boot.git/blob - include/reset.h
1 /* SPDX-License-Identifier: GPL-2.0 */
3 * Copyright (c) 2016, NVIDIA CORPORATION.
10 #include <linux/err.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.
47 * @polarity: An optional polarity field for drivers that support
48 * different reset polarities.
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
61 * Written by of_xlate. In the future, we might add more fields here.
65 unsigned long polarity
;
69 * struct reset_ctl_bulk - A handle to (allowing control of) a bulk of reset
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.
78 * @resets: An array of reset signal handles handles.
79 * @count: The number of reset signal handles in the reset array.
81 struct reset_ctl_bulk
{
82 struct reset_ctl
*resets
;
86 #if CONFIG_IS_ENABLED(DM_RESET)
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
93 * Managed reset_get_by_name(). For reset controllers returned
94 * from this function, reset_free() is called automatically on driver
97 * Returns a struct reset_ctl or IS_ERR() condition containing errno.
99 struct reset_ctl
*devm_reset_control_get(struct udevice
*dev
, const char *id
);
102 * devm_reset_control_get_optional - resource managed reset_get_by_name() that
104 * @dev: The client device.
105 * @id: reset line name
107 * Managed reset_get_by_name(). For reset controllers returned
108 * from this function, reset_free() is called automatically on driver
111 * Returns a struct reset_ctl or a dummy reset controller if it failed.
113 struct reset_ctl
*devm_reset_control_get_optional(struct udevice
*dev
,
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.
122 * Managed reset_get_by_index(). For reset controllers returned
123 * from this function, reset_free() is called automatically on driver
126 * Returns a struct reset_ctl or IS_ERR() condition containing errno.
128 struct reset_ctl
*devm_reset_control_get_by_index(struct udevice
*dev
,
132 * devm_reset_bulk_get - resource managed reset_get_bulk()
133 * @dev: device to be reset by the controller
135 * Managed reset_get_bulk(). For reset controllers returned
136 * from this function, reset_free() is called automatically on driver
139 * Returns a struct reset_ctl or IS_ERR() condition containing errno.
141 struct reset_ctl_bulk
*devm_reset_bulk_get(struct udevice
*dev
);
144 * devm_reset_bulk_get_optional - resource managed reset_get_bulk() that
146 * @dev: The client device.
148 * Managed reset_get_bulk(). For reset controllers returned
149 * from this function, reset_free() is called automatically on driver
152 * Returns a struct reset_ctl or NULL if it failed.
154 struct reset_ctl_bulk
*devm_reset_bulk_get_optional(struct udevice
*dev
);
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
162 * see devm_reset_bulk_get()
164 struct reset_ctl_bulk
*devm_reset_bulk_get_by_node(struct udevice
*dev
,
168 * devm_reset_bulk_get_optional_by_node - resource managed reset_get_bulk()
170 * @dev: device to be reset by the controller
171 * @node: ofnode where the "resets" property is. Usually a sub-node of
174 * see devm_reset_bulk_get_optional()
176 struct reset_ctl_bulk
*devm_reset_bulk_get_optional_by_node(struct udevice
*dev
,
180 * reset_get_by_index - Get/request a reset signal by integer index.
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
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.
195 int reset_get_by_index(struct udevice
*dev
, int index
,
196 struct reset_ctl
*reset_ctl
);
199 * reset_get_by_index_nodev - Get/request a reset signal by integer index
202 * This is a version of reset_get_by_index() that does not use a device.
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.
210 int reset_get_by_index_nodev(ofnode node
, int index
,
211 struct reset_ctl
*reset_ctl
);
214 * reset_get_bulk - Get/request all reset signals of a device.
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
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.
227 int reset_get_bulk(struct udevice
*dev
, struct reset_ctl_bulk
*bulk
);
230 * reset_get_by_name - Get/request a reset signal by name.
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
239 * @dev: The client device.
240 * @name: The name of the reset signal to request, within the client's
241 * list of reset signals, or NULL to request the first reset
242 * signal in the list.
243 * @reset_ctl: A pointer to a reset control struct to initialize.
244 * Return: 0 if OK, or a negative error code.
246 int reset_get_by_name(struct udevice
*dev
, const char *name
,
247 struct reset_ctl
*reset_ctl
);
250 * reset_request - Request a reset signal.
252 * @reset_ctl: A reset control struct.
254 * Return: 0 if OK, or a negative error code.
256 int reset_request(struct reset_ctl
*reset_ctl
);
259 * reset_free - Free a previously requested reset signal.
261 * @reset_ctl: A reset control struct that was previously successfully
262 * requested by reset_get_by_*().
263 * Return: 0 if OK, or a negative error code.
265 int reset_free(struct reset_ctl
*reset_ctl
);
268 * reset_assert - Assert a reset signal.
270 * This function will assert the specified reset signal, thus resetting the
271 * affected HW module(s). Depending on the reset controller hardware, the reset
272 * signal will either stay asserted until reset_deassert() is called, or the
273 * hardware may autonomously clear the reset signal itself.
275 * @reset_ctl: A reset control struct that was previously successfully
276 * requested by reset_get_by_*().
277 * Return: 0 if OK, or a negative error code.
279 int reset_assert(struct reset_ctl
*reset_ctl
);
282 * reset_assert_bulk - Assert all reset signals in a reset control bulk struct.
284 * This function will assert the specified reset signals in a reset control
285 * bulk struct, thus resetting the affected HW module(s). Depending on the
286 * reset controller hardware, the reset signals will either stay asserted
287 * until reset_deassert_bulk() is called, or the hardware may autonomously
288 * clear the reset signals itself.
290 * @bulk: A reset control bulk struct that was previously successfully
291 * requested by reset_get_bulk().
292 * Return: 0 if OK, or a negative error code.
294 int reset_assert_bulk(struct reset_ctl_bulk
*bulk
);
297 * reset_deassert - Deassert a reset signal.
299 * This function will deassert the specified reset signal, thus releasing the
300 * affected HW modules() from reset, and allowing them to continue normal
303 * @reset_ctl: A reset control struct that was previously successfully
304 * requested by reset_get_by_*().
305 * Return: 0 if OK, or a negative error code.
307 int reset_deassert(struct reset_ctl
*reset_ctl
);
310 * reset_deassert_bulk - Deassert all reset signals in a reset control bulk
313 * This function will deassert the specified reset signals in a reset control
314 * bulk struct, thus releasing the affected HW modules() from reset, and
315 * allowing them to continue normal operation.
317 * @bulk: A reset control bulk struct that was previously successfully
318 * requested by reset_get_bulk().
319 * Return: 0 if OK, or a negative error code.
321 int reset_deassert_bulk(struct reset_ctl_bulk
*bulk
);
324 * rst_status - Check reset signal status.
326 * @reset_ctl: The reset signal to check.
327 * Return: 0 if deasserted, positive if asserted, or a negative
330 int reset_status(struct reset_ctl
*reset_ctl
);
333 * reset_release_all - Assert/Free an array of previously requested resets.
335 * For each reset contained in the reset array, this function will check if
336 * reset has been previously requested and then will assert and free it.
338 * @reset_ctl: A reset struct array that was previously successfully
339 * requested by reset_get_by_*().
340 * @count Number of reset contained in the array
341 * Return: 0 if OK, or a negative error code.
343 int reset_release_all(struct reset_ctl
*reset_ctl
, int count
);
346 * reset_release_bulk - Assert/Free an array of previously requested reset
347 * signals in a reset control bulk struct.
349 * For each reset contained in the reset control bulk struct, this function
350 * will check if reset has been previously requested and then will assert
353 * @bulk: A reset control bulk struct that was previously successfully
354 * requested by reset_get_bulk().
355 * Return: 0 if OK, or a negative error code.
357 static inline int reset_release_bulk(struct reset_ctl_bulk
*bulk
)
359 return reset_release_all(bulk
->resets
, bulk
->count
);
363 static inline struct reset_ctl
*devm_reset_control_get(struct udevice
*dev
,
366 return ERR_PTR(-ENOTSUPP
);
369 static inline struct reset_ctl
*devm_reset_control_get_optional(struct udevice
*dev
,
375 static inline struct reset_ctl
*devm_reset_control_get_by_index(struct udevice
*dev
,
378 return ERR_PTR(-ENOTSUPP
);
381 static inline struct reset_ctl_bulk
*devm_reset_bulk_get(struct udevice
*dev
)
383 return ERR_PTR(-ENOTSUPP
);
386 static inline struct reset_ctl_bulk
*devm_reset_bulk_get_optional(struct udevice
*dev
)
391 static inline struct reset_ctl_bulk
*devm_reset_bulk_get_by_node(struct udevice
*dev
,
394 return ERR_PTR(-ENOTSUPP
);
397 static inline struct reset_ctl_bulk
*devm_reset_bulk_get_optional_by_node(struct udevice
*dev
,
403 static inline int reset_get_by_index(struct udevice
*dev
, int index
,
404 struct reset_ctl
*reset_ctl
)
409 static inline int reset_get_bulk(struct udevice
*dev
,
410 struct reset_ctl_bulk
*bulk
)
415 static inline int reset_get_by_name(struct udevice
*dev
, const char *name
,
416 struct reset_ctl
*reset_ctl
)
421 static inline int reset_free(struct reset_ctl
*reset_ctl
)
426 static inline int reset_assert(struct reset_ctl
*reset_ctl
)
431 static inline int reset_assert_bulk(struct reset_ctl_bulk
*bulk
)
436 static inline int reset_deassert(struct reset_ctl
*reset_ctl
)
441 static inline int reset_deassert_bulk(struct reset_ctl_bulk
*bulk
)
446 static inline int reset_status(struct reset_ctl
*reset_ctl
)
451 static inline int reset_release_all(struct reset_ctl
*reset_ctl
, int count
)
456 static inline int reset_release_bulk(struct reset_ctl_bulk
*bulk
)
463 * reset_valid() - check if reset is valid
465 * @reset_ctl: the reset to check
466 * Return: TRUE if valid, or FALSE
468 static inline bool reset_valid(struct reset_ctl
*reset_ctl
)
470 return !!reset_ctl
->dev
;