1 /* SPDX-License-Identifier: GPL-2.0 */ 2 /* 3 * Copyright (c) 2016, NVIDIA CORPORATION. 4 */ 5 6 #ifndef _RESET_H 7 #define _RESET_H 8 9 #include <linux/errno.h> 10 11 /** 12 * A reset is a hardware signal indicating that a HW module (or IP block, or 13 * sometimes an entire off-CPU chip) reset all of its internal state to some 14 * known-good initial state. Drivers will often reset HW modules when they 15 * begin execution to ensure that hardware correctly responds to all requests, 16 * or in response to some error condition. Reset signals are often controlled 17 * externally to the HW module being reset, by an entity this API calls a reset 18 * controller. This API provides a standard means for drivers to request that 19 * reset controllers set or clear reset signals. 20 * 21 * A driver that implements UCLASS_RESET is a reset controller or provider. A 22 * controller will often implement multiple separate reset signals, since the 23 * hardware it manages often has this capability. reset-uclass.h describes the 24 * interface which reset controllers must implement. 25 * 26 * Reset consumers/clients are the HW modules affected by reset signals. This 27 * header file describes the API used by drivers for those HW modules. 28 */ 29 30 struct udevice; 31 32 /** 33 * struct reset_ctl - A handle to (allowing control of) a single reset signal. 34 * 35 * Clients provide storage for reset control handles. The content of the 36 * structure is managed solely by the reset API and reset drivers. A reset 37 * control struct is initialized by "get"ing the reset control struct. The 38 * reset control struct is passed to all other reset APIs to identify which 39 * reset signal to operate upon. 40 * 41 * @dev: The device which implements the reset signal. 42 * @id: The reset signal ID within the provider. 43 * 44 * Currently, the reset API assumes that a single integer ID is enough to 45 * identify and configure any reset signal for any reset provider. If this 46 * assumption becomes invalid in the future, the struct could be expanded to 47 * either (a) add more fields to allow reset providers to store additional 48 * information, or (b) replace the id field with an opaque pointer, which the 49 * provider would dynamically allocated during its .of_xlate op, and process 50 * during is .request op. This may require the addition of an extra op to clean 51 * up the allocation. 52 */ 53 struct reset_ctl { 54 struct udevice *dev; 55 /* 56 * Written by of_xlate. We assume a single id is enough for now. In the 57 * future, we might add more fields here. 58 */ 59 unsigned long id; 60 }; 61 62 /** 63 * struct reset_ctl_bulk - A handle to (allowing control of) a bulk of reset 64 * signals. 65 * 66 * Clients provide storage for the reset control bulk. The content of the 67 * structure is managed solely by the reset API. A reset control bulk struct is 68 * initialized by "get"ing the reset control bulk struct. 69 * The reset control bulk struct is passed to all other bulk reset APIs to apply 70 * the API to all the reset signals in the bulk struct. 71 * 72 * @resets: An array of reset signal handles handles. 73 * @count: The number of reset signal handles in the reset array. 74 */ 75 struct reset_ctl_bulk { 76 struct reset_ctl *resets; 77 unsigned int count; 78 }; 79 80 #if CONFIG_IS_ENABLED(DM_RESET) 81 /** 82 * reset_get_by_index - Get/request a reset signal by integer index. 83 * 84 * This looks up and requests a reset signal. The index is relative to the 85 * client device; each device is assumed to have n reset signals associated 86 * with it somehow, and this function finds and requests one of them. The 87 * mapping of client device reset signal indices to provider reset signals may 88 * be via device-tree properties, board-provided mapping tables, or some other 89 * mechanism. 90 * 91 * @dev: The client device. 92 * @index: The index of the reset signal to request, within the client's 93 * list of reset signals. 94 * @reset_ctl A pointer to a reset control struct to initialize. 95 * @return 0 if OK, or a negative error code. 96 */ 97 int reset_get_by_index(struct udevice *dev, int index, 98 struct reset_ctl *reset_ctl); 99 100 /** 101 * reset_get_bulk - Get/request all reset signals of a device. 102 * 103 * This looks up and requests all reset signals of the client device; each 104 * device is assumed to have n reset signals associated with it somehow, 105 * and this function finds and requests all of them in a separate structure. 106 * The mapping of client device reset signals indices to provider reset signals 107 * may be via device-tree properties, board-provided mapping tables, or some 108 * other mechanism. 109 * 110 * @dev: The client device. 111 * @bulk A pointer to a reset control bulk struct to initialize. 112 * @return 0 if OK, or a negative error code. 113 */ 114 int reset_get_bulk(struct udevice *dev, struct reset_ctl_bulk *bulk); 115 116 /** 117 * reset_get_by_name - Get/request a reset signal by name. 118 * 119 * This looks up and requests a reset signal. The name is relative to the 120 * client device; each device is assumed to have n reset signals associated 121 * with it somehow, and this function finds and requests one of them. The 122 * mapping of client device reset signal names to provider reset signal may be 123 * via device-tree properties, board-provided mapping tables, or some other 124 * mechanism. 125 * 126 * @dev: The client device. 127 * @name: The name of the reset signal to request, within the client's 128 * list of reset signals. 129 * @reset_ctl: A pointer to a reset control struct to initialize. 130 * @return 0 if OK, or a negative error code. 131 */ 132 int reset_get_by_name(struct udevice *dev, const char *name, 133 struct reset_ctl *reset_ctl); 134 135 /** 136 * reset_request - Request a reset signal. 137 * 138 * @reset_ctl: A reset control struct. 139 * 140 * @return 0 if OK, or a negative error code. 141 */ 142 int reset_request(struct reset_ctl *reset_ctl); 143 144 /** 145 * reset_free - Free a previously requested reset signal. 146 * 147 * @reset_ctl: A reset control struct that was previously successfully 148 * requested by reset_get_by_*(). 149 * @return 0 if OK, or a negative error code. 150 */ 151 int reset_free(struct reset_ctl *reset_ctl); 152 153 /** 154 * reset_assert - Assert a reset signal. 155 * 156 * This function will assert the specified reset signal, thus resetting the 157 * affected HW module(s). Depending on the reset controller hardware, the reset 158 * signal will either stay asserted until reset_deassert() is called, or the 159 * hardware may autonomously clear the reset signal itself. 160 * 161 * @reset_ctl: A reset control struct that was previously successfully 162 * requested by reset_get_by_*(). 163 * @return 0 if OK, or a negative error code. 164 */ 165 int reset_assert(struct reset_ctl *reset_ctl); 166 167 /** 168 * reset_assert_bulk - Assert all reset signals in a reset control bulk struct. 169 * 170 * This function will assert the specified reset signals in a reset control 171 * bulk struct, thus resetting the affected HW module(s). Depending on the 172 * reset controller hardware, the reset signals will either stay asserted 173 * until reset_deassert_bulk() is called, or the hardware may autonomously 174 * clear the reset signals itself. 175 * 176 * @bulk: A reset control bulk struct that was previously successfully 177 * requested by reset_get_bulk(). 178 * @return 0 if OK, or a negative error code. 179 */ 180 int reset_assert_bulk(struct reset_ctl_bulk *bulk); 181 182 /** 183 * reset_deassert - Deassert a reset signal. 184 * 185 * This function will deassert the specified reset signal, thus releasing the 186 * affected HW modules() from reset, and allowing them to continue normal 187 * operation. 188 * 189 * @reset_ctl: A reset control struct that was previously successfully 190 * requested by reset_get_by_*(). 191 * @return 0 if OK, or a negative error code. 192 */ 193 int reset_deassert(struct reset_ctl *reset_ctl); 194 195 /** 196 * reset_deassert_bulk - Deassert all reset signals in a reset control bulk 197 * struct. 198 * 199 * This function will deassert the specified reset signals in a reset control 200 * bulk struct, thus releasing the affected HW modules() from reset, and 201 * allowing them to continue normal operation. 202 * 203 * @bulk: A reset control bulk struct that was previously successfully 204 * requested by reset_get_bulk(). 205 * @return 0 if OK, or a negative error code. 206 */ 207 int reset_deassert_bulk(struct reset_ctl_bulk *bulk); 208 209 /** 210 * reset_release_all - Assert/Free an array of previously requested resets. 211 * 212 * For each reset contained in the reset array, this function will check if 213 * reset has been previously requested and then will assert and free it. 214 * 215 * @reset_ctl: A reset struct array that was previously successfully 216 * requested by reset_get_by_*(). 217 * @count Number of reset contained in the array 218 * @return 0 if OK, or a negative error code. 219 */ 220 int reset_release_all(struct reset_ctl *reset_ctl, int count); 221 222 /** 223 * reset_release_bulk - Assert/Free an array of previously requested reset 224 * signals in a reset control bulk struct. 225 * 226 * For each reset contained in the reset control bulk struct, this function 227 * will check if reset has been previously requested and then will assert 228 * and free it. 229 * 230 * @bulk: A reset control bulk struct that was previously successfully 231 * requested by reset_get_bulk(). 232 * @return 0 if OK, or a negative error code. 233 */ 234 static inline int reset_release_bulk(struct reset_ctl_bulk *bulk) 235 { 236 return reset_release_all(bulk->resets, bulk->count); 237 } 238 #else 239 static inline int reset_get_by_index(struct udevice *dev, int index, 240 struct reset_ctl *reset_ctl) 241 { 242 return -ENOTSUPP; 243 } 244 245 static inline int reset_get_bulk(struct udevice *dev, 246 struct reset_ctl_bulk *bulk) 247 { 248 return -ENOTSUPP; 249 } 250 251 static inline int reset_get_by_name(struct udevice *dev, const char *name, 252 struct reset_ctl *reset_ctl) 253 { 254 return -ENOTSUPP; 255 } 256 257 static inline int reset_free(struct reset_ctl *reset_ctl) 258 { 259 return 0; 260 } 261 262 static inline int reset_assert(struct reset_ctl *reset_ctl) 263 { 264 return 0; 265 } 266 267 static inline int reset_assert_bulk(struct reset_ctl_bulk *bulk) 268 { 269 return 0; 270 } 271 272 static inline int reset_deassert(struct reset_ctl *reset_ctl) 273 { 274 return 0; 275 } 276 277 static inline int reset_deassert_bulk(struct reset_ctl_bulk *bulk) 278 { 279 return 0; 280 } 281 282 static inline int reset_release_all(struct reset_ctl *reset_ctl, int count) 283 { 284 return 0; 285 } 286 287 static inline int reset_release_bulk(struct reset_ctl_bulk *bulk) 288 { 289 return 0; 290 } 291 #endif 292 293 #endif 294