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 /** 64 * struct reset_ctl_bulk - A handle to (allowing control of) a bulk of reset 65 * signals. 66 * 67 * Clients provide storage for the reset control bulk. The content of the 68 * structure is managed solely by the reset API. A reset control bulk struct is 69 * initialized by "get"ing the reset control bulk struct. 70 * The reset control bulk struct is passed to all other bulk reset APIs to apply 71 * the API to all the reset signals in the bulk struct. 72 * 73 * @resets: An array of reset signal handles handles. 74 * @count: The number of reset signal handles in the reset array. 75 */ 76 struct reset_ctl_bulk { 77 struct reset_ctl *resets; 78 unsigned int count; 79 }; 80 81 #ifdef CONFIG_DM_RESET 82 /** 83 * reset_get_by_index - Get/request a reset signal by integer index. 84 * 85 * This looks up and requests a reset signal. The index is relative to the 86 * client device; each device is assumed to have n reset signals associated 87 * with it somehow, and this function finds and requests one of them. The 88 * mapping of client device reset signal indices to provider reset signals may 89 * be via device-tree properties, board-provided mapping tables, or some other 90 * mechanism. 91 * 92 * @dev: The client device. 93 * @index: The index of the reset signal to request, within the client's 94 * list of reset signals. 95 * @reset_ctl A pointer to a reset control struct to initialize. 96 * @return 0 if OK, or a negative error code. 97 */ 98 int reset_get_by_index(struct udevice *dev, int index, 99 struct reset_ctl *reset_ctl); 100 101 /** 102 * reset_get_bulk - Get/request all reset signals of a device. 103 * 104 * This looks up and requests all reset signals of the client device; each 105 * device is assumed to have n reset signals associated with it somehow, 106 * and this function finds and requests all of them in a separate structure. 107 * The mapping of client device reset signals indices to provider reset signals 108 * may be via device-tree properties, board-provided mapping tables, or some 109 * other mechanism. 110 * 111 * @dev: The client device. 112 * @bulk A pointer to a reset control bulk struct to initialize. 113 * @return 0 if OK, or a negative error code. 114 */ 115 int reset_get_bulk(struct udevice *dev, struct reset_ctl_bulk *bulk); 116 117 /** 118 * reset_get_by_name - Get/request a reset signal by name. 119 * 120 * This looks up and requests a reset signal. The name is relative to the 121 * client device; each device is assumed to have n reset signals associated 122 * with it somehow, and this function finds and requests one of them. The 123 * mapping of client device reset signal names to provider reset signal may be 124 * via device-tree properties, board-provided mapping tables, or some other 125 * mechanism. 126 * 127 * @dev: The client device. 128 * @name: The name of the reset signal to request, within the client's 129 * list of reset signals. 130 * @reset_ctl: A pointer to a reset control struct to initialize. 131 * @return 0 if OK, or a negative error code. 132 */ 133 int reset_get_by_name(struct udevice *dev, const char *name, 134 struct reset_ctl *reset_ctl); 135 136 /** 137 * reset_request - Request a reset signal. 138 * 139 * @reset_ctl: A reset control struct. 140 * 141 * @return 0 if OK, or a negative error code. 142 */ 143 int reset_request(struct reset_ctl *reset_ctl); 144 145 /** 146 * reset_free - Free a previously requested reset signal. 147 * 148 * @reset_ctl: A reset control struct that was previously successfully 149 * requested by reset_get_by_*(). 150 * @return 0 if OK, or a negative error code. 151 */ 152 int reset_free(struct reset_ctl *reset_ctl); 153 154 /** 155 * reset_assert - Assert a reset signal. 156 * 157 * This function will assert the specified reset signal, thus resetting the 158 * affected HW module(s). Depending on the reset controller hardware, the reset 159 * signal will either stay asserted until reset_deassert() is called, or the 160 * hardware may autonomously clear the reset signal itself. 161 * 162 * @reset_ctl: A reset control struct that was previously successfully 163 * requested by reset_get_by_*(). 164 * @return 0 if OK, or a negative error code. 165 */ 166 int reset_assert(struct reset_ctl *reset_ctl); 167 168 /** 169 * reset_assert_bulk - Assert all reset signals in a reset control bulk struct. 170 * 171 * This function will assert the specified reset signals in a reset control 172 * bulk struct, thus resetting the affected HW module(s). Depending on the 173 * reset controller hardware, the reset signals will either stay asserted 174 * until reset_deassert_bulk() is called, or the hardware may autonomously 175 * clear the reset signals itself. 176 * 177 * @bulk: A reset control bulk struct that was previously successfully 178 * requested by reset_get_bulk(). 179 * @return 0 if OK, or a negative error code. 180 */ 181 int reset_assert_bulk(struct reset_ctl_bulk *bulk); 182 183 /** 184 * reset_deassert - Deassert a reset signal. 185 * 186 * This function will deassert the specified reset signal, thus releasing the 187 * affected HW modules() from reset, and allowing them to continue normal 188 * operation. 189 * 190 * @reset_ctl: A reset control struct that was previously successfully 191 * requested by reset_get_by_*(). 192 * @return 0 if OK, or a negative error code. 193 */ 194 int reset_deassert(struct reset_ctl *reset_ctl); 195 196 /** 197 * reset_deassert_bulk - Deassert all reset signals in a reset control bulk 198 * struct. 199 * 200 * This function will deassert the specified reset signals in a reset control 201 * bulk struct, thus releasing the affected HW modules() from reset, and 202 * allowing them to continue normal operation. 203 * 204 * @bulk: A reset control bulk struct that was previously successfully 205 * requested by reset_get_bulk(). 206 * @return 0 if OK, or a negative error code. 207 */ 208 int reset_deassert_bulk(struct reset_ctl_bulk *bulk); 209 210 /** 211 * reset_release_all - Assert/Free an array of previously requested resets. 212 * 213 * For each reset contained in the reset array, this function will check if 214 * reset has been previously requested and then will assert and free it. 215 * 216 * @reset_ctl: A reset struct array that was previously successfully 217 * requested by reset_get_by_*(). 218 * @count Number of reset contained in the array 219 * @return 0 if OK, or a negative error code. 220 */ 221 int reset_release_all(struct reset_ctl *reset_ctl, int count); 222 223 /** 224 * reset_release_bulk - Assert/Free an array of previously requested reset 225 * signals in a reset control bulk struct. 226 * 227 * For each reset contained in the reset control bulk struct, this function 228 * will check if reset has been previously requested and then will assert 229 * and free it. 230 * 231 * @bulk: A reset control bulk struct that was previously successfully 232 * requested by reset_get_bulk(). 233 * @return 0 if OK, or a negative error code. 234 */ 235 static inline int reset_release_bulk(struct reset_ctl_bulk *bulk) 236 { 237 return reset_release_all(bulk->resets, bulk->count); 238 } 239 #else 240 static inline int reset_get_by_index(struct udevice *dev, int index, 241 struct reset_ctl *reset_ctl) 242 { 243 return -ENOTSUPP; 244 } 245 246 static inline int reset_get_bulk(struct udevice *dev, 247 struct reset_ctl_bulk *bulk) 248 { 249 return -ENOTSUPP; 250 } 251 252 static inline int reset_get_by_name(struct udevice *dev, const char *name, 253 struct reset_ctl *reset_ctl) 254 { 255 return -ENOTSUPP; 256 } 257 258 static inline int reset_free(struct reset_ctl *reset_ctl) 259 { 260 return 0; 261 } 262 263 static inline int reset_assert(struct reset_ctl *reset_ctl) 264 { 265 return 0; 266 } 267 268 static inline int reset_assert_bulk(struct reset_ctl_bulk *bulk) 269 { 270 return 0; 271 } 272 273 static inline int reset_deassert(struct reset_ctl *reset_ctl) 274 { 275 return 0; 276 } 277 278 static inline int reset_deassert_bulk(struct reset_ctl_bulk *bulk) 279 { 280 return 0; 281 } 282 283 static inline int reset_release_all(struct reset_ctl *reset_ctl, int count) 284 { 285 return 0; 286 } 287 288 static inline int reset_release_bulk(struct reset_ctl_bulk *bulk) 289 { 290 return 0; 291 } 292 #endif 293 294 #endif 295