xref: /openbmc/u-boot/include/reset.h (revision 8797b2ca)
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 /**
11  * A reset is a hardware signal indicating that a HW module (or IP block, or
12  * sometimes an entire off-CPU chip) reset all of its internal state to some
13  * known-good initial state. Drivers will often reset HW modules when they
14  * begin execution to ensure that hardware correctly responds to all requests,
15  * or in response to some error condition. Reset signals are often controlled
16  * externally to the HW module being reset, by an entity this API calls a reset
17  * controller. This API provides a standard means for drivers to request that
18  * reset controllers set or clear reset signals.
19  *
20  * A driver that implements UCLASS_RESET is a reset controller or provider. A
21  * controller will often implement multiple separate reset signals, since the
22  * hardware it manages often has this capability. reset-uclass.h describes the
23  * interface which reset controllers must implement.
24  *
25  * Reset consumers/clients are the HW modules affected by reset signals. This
26  * header file describes the API used by drivers for those HW modules.
27  */
28 
29 struct udevice;
30 
31 /**
32  * struct reset_ctl - A handle to (allowing control of) a single reset signal.
33  *
34  * Clients provide storage for reset control handles. The content of the
35  * structure is managed solely by the reset API and reset drivers. A reset
36  * control struct is initialized by "get"ing the reset control struct. The
37  * reset control struct is passed to all other reset APIs to identify which
38  * reset signal to operate upon.
39  *
40  * @dev: The device which implements the reset signal.
41  * @id: The reset signal ID within the provider.
42  *
43  * Currently, the reset API assumes that a single integer ID is enough to
44  * identify and configure any reset signal for any reset provider. If this
45  * assumption becomes invalid in the future, the struct could be expanded to
46  * either (a) add more fields to allow reset providers to store additional
47  * information, or (b) replace the id field with an opaque pointer, which the
48  * provider would dynamically allocated during its .of_xlate op, and process
49  * during is .request op. This may require the addition of an extra op to clean
50  * up the allocation.
51  */
52 struct reset_ctl {
53 	struct udevice *dev;
54 	/*
55 	 * Written by of_xlate. We assume a single id is enough for now. In the
56 	 * future, we might add more fields here.
57 	 */
58 	unsigned long id;
59 };
60 
61 /**
62  * reset_get_by_index - Get/request a reset signal by integer index.
63  *
64  * This looks up and requests a reset signal. The index is relative to the
65  * client device; each device is assumed to have n reset signals associated
66  * with it somehow, and this function finds and requests one of them. The
67  * mapping of client device reset signal indices to provider reset signals may
68  * be via device-tree properties, board-provided mapping tables, or some other
69  * mechanism.
70  *
71  * @dev:	The client device.
72  * @index:	The index of the reset signal to request, within the client's
73  *		list of reset signals.
74  * @reset_ctl	A pointer to a reset control struct to initialize.
75  * @return 0 if OK, or a negative error code.
76  */
77 int reset_get_by_index(struct udevice *dev, int index,
78 		       struct reset_ctl *reset_ctl);
79 
80 /**
81  * reset_get_by_name - Get/request a reset signal by name.
82  *
83  * This looks up and requests a reset signal. The name is relative to the
84  * client device; each device is assumed to have n reset signals associated
85  * with it somehow, and this function finds and requests one of them. The
86  * mapping of client device reset signal names to provider reset signal may be
87  * via device-tree properties, board-provided mapping tables, or some other
88  * mechanism.
89  *
90  * @dev:	The client device.
91  * @name:	The name of the reset signal to request, within the client's
92  *		list of reset signals.
93  * @reset_ctl:	A pointer to a reset control struct to initialize.
94  * @return 0 if OK, or a negative error code.
95  */
96 int reset_get_by_name(struct udevice *dev, const char *name,
97 		      struct reset_ctl *reset_ctl);
98 
99 /**
100  * reset_free - Free a previously requested reset signal.
101  *
102  * @reset_ctl:	A reset control struct that was previously successfully
103  *		requested by reset_get_by_*().
104  * @return 0 if OK, or a negative error code.
105  */
106 int reset_free(struct reset_ctl *reset_ctl);
107 
108 /**
109  * reset_assert - Assert a reset signal.
110  *
111  * This function will assert the specified reset signal, thus resetting the
112  * affected HW module(s). Depending on the reset controller hardware, the reset
113  * signal will either stay asserted until reset_deassert() is called, or the
114  * hardware may autonomously clear the reset signal itself.
115  *
116  * @reset_ctl:	A reset control struct that was previously successfully
117  *		requested by reset_get_by_*().
118  * @return 0 if OK, or a negative error code.
119  */
120 int reset_assert(struct reset_ctl *reset_ctl);
121 
122 /**
123  * reset_deassert - Deassert a reset signal.
124  *
125  * This function will deassert the specified reset signal, thus releasing the
126  * affected HW modules() from reset, and allowing them to continue normal
127  * operation.
128  *
129  * @reset_ctl:	A reset control struct that was previously successfully
130  *		requested by reset_get_by_*().
131  * @return 0 if OK, or a negative error code.
132  */
133 int reset_deassert(struct reset_ctl *reset_ctl);
134 
135 #endif
136