blob: 7185ade7ac5e96a56b0c0e0d3d332641400310ec [file] [log] [blame]
Stephen Warren89c1e2d2016-06-17 09:43:58 -06001/*
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
Masahiro Yamada4815db82016-09-21 11:29:01 +090010#include <linux/errno.h>
11
Stephen Warren89c1e2d2016-06-17 09:43:58 -060012/**
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
31struct 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 */
54struct 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
Masahiro Yamada4815db82016-09-21 11:29:01 +090063#ifdef CONFIG_DM_RESET
Stephen Warren89c1e2d2016-06-17 09:43:58 -060064/**
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 */
80int 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 */
99int reset_get_by_name(struct udevice *dev, const char *name,
100 struct reset_ctl *reset_ctl);
101
102/**
Patrice Chotard9bd5cdf2017-07-18 11:57:05 +0200103 * 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 */
109int reset_request(struct reset_ctl *reset_ctl);
110
111/**
Stephen Warren89c1e2d2016-06-17 09:43:58 -0600112 * 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 */
118int 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 */
132int 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 */
145int reset_deassert(struct reset_ctl *reset_ctl);
146
Patrice Chotard3b9d1bd2017-07-18 11:57:06 +0200147/**
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 */
158int reset_release_all(struct reset_ctl *reset_ctl, int count);
Masahiro Yamada4815db82016-09-21 11:29:01 +0900159#else
160static inline int reset_get_by_index(struct udevice *dev, int index,
161 struct reset_ctl *reset_ctl)
162{
163 return -ENOTSUPP;
164}
165
166static inline int reset_get_by_name(struct udevice *dev, const char *name,
167 struct reset_ctl *reset_ctl)
168{
169 return -ENOTSUPP;
170}
171
172static inline int reset_free(struct reset_ctl *reset_ctl)
173{
174 return 0;
175}
176
177static inline int reset_assert(struct reset_ctl *reset_ctl)
178{
179 return 0;
180}
181
182static inline int reset_deassert(struct reset_ctl *reset_ctl)
183{
184 return 0;
185}
Patrice Chotard3b9d1bd2017-07-18 11:57:06 +0200186
187static inline int reset_release_all(struct reset_ctl *reset_ctl, int count)
188{
189 return 0;
190}
191
Masahiro Yamada4815db82016-09-21 11:29:01 +0900192#endif
193
Stephen Warren89c1e2d2016-06-17 09:43:58 -0600194#endif