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 * @data: An optional data field for scenarios where a single integer ID is not 44 * sufficient. If used, it can be populated through an .of_xlate op and 45 * processed during the various reset ops. 46 * 47 * Should additional information to identify and configure any reset signal 48 * for any provider be required in the future, the struct could be expanded to 49 * either (a) add more fields to allow reset providers to store additional 50 * information, or (b) replace the id field with an opaque pointer, which the 51 * provider would dynamically allocated during its .of_xlate op, and process 52 * during is .request op. This may require the addition of an extra op to clean 53 * up the allocation. 54 */ 55 struct reset_ctl { 56 struct udevice *dev; 57 /* 58 * Written by of_xlate. In the future, we might add more fields here. 59 */ 60 unsigned long id; 61 unsigned long data; 62 }; 63 64 /** 65 * struct reset_ctl_bulk - A handle to (allowing control of) a bulk of reset 66 * signals. 67 * 68 * Clients provide storage for the reset control bulk. The content of the 69 * structure is managed solely by the reset API. A reset control bulk struct is 70 * initialized by "get"ing the reset control bulk struct. 71 * The reset control bulk struct is passed to all other bulk reset APIs to apply 72 * the API to all the reset signals in the bulk struct. 73 * 74 * @resets: An array of reset signal handles handles. 75 * @count: The number of reset signal handles in the reset array. 76 */ 77 struct reset_ctl_bulk { 78 struct reset_ctl *resets; 79 unsigned int count; 80 }; 81 82 #if CONFIG_IS_ENABLED(DM_RESET) 83 /** 84 * reset_get_by_index - Get/request a reset signal by integer index. 85 * 86 * This looks up and requests a reset signal. The index 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 indices to provider reset signals may 90 * be via device-tree properties, board-provided mapping tables, or some other 91 * mechanism. 92 * 93 * @dev: The client device. 94 * @index: The index 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 */ 99 int reset_get_by_index(struct udevice *dev, int index, 100 struct reset_ctl *reset_ctl); 101 102 /** 103 * reset_get_bulk - Get/request all reset signals of a device. 104 * 105 * This looks up and requests all reset signals of the client device; each 106 * device is assumed to have n reset signals associated with it somehow, 107 * and this function finds and requests all of them in a separate structure. 108 * The mapping of client device reset signals indices to provider reset signals 109 * may be via device-tree properties, board-provided mapping tables, or some 110 * other mechanism. 111 * 112 * @dev: The client device. 113 * @bulk A pointer to a reset control bulk struct to initialize. 114 * @return 0 if OK, or a negative error code. 115 */ 116 int reset_get_bulk(struct udevice *dev, struct reset_ctl_bulk *bulk); 117 118 /** 119 * reset_get_by_name - Get/request a reset signal by name. 120 * 121 * This looks up and requests a reset signal. The name is relative to the 122 * client device; each device is assumed to have n reset signals associated 123 * with it somehow, and this function finds and requests one of them. The 124 * mapping of client device reset signal names to provider reset signal may be 125 * via device-tree properties, board-provided mapping tables, or some other 126 * mechanism. 127 * 128 * @dev: The client device. 129 * @name: The name of the reset signal to request, within the client's 130 * list of reset signals. 131 * @reset_ctl: A pointer to a reset control struct to initialize. 132 * @return 0 if OK, or a negative error code. 133 */ 134 int reset_get_by_name(struct udevice *dev, const char *name, 135 struct reset_ctl *reset_ctl); 136 137 /** 138 * reset_request - Request a reset signal. 139 * 140 * @reset_ctl: A reset control struct. 141 * 142 * @return 0 if OK, or a negative error code. 143 */ 144 int reset_request(struct reset_ctl *reset_ctl); 145 146 /** 147 * reset_free - Free a previously requested reset signal. 148 * 149 * @reset_ctl: A reset control struct that was previously successfully 150 * requested by reset_get_by_*(). 151 * @return 0 if OK, or a negative error code. 152 */ 153 int reset_free(struct reset_ctl *reset_ctl); 154 155 /** 156 * reset_assert - Assert a reset signal. 157 * 158 * This function will assert the specified reset signal, thus resetting the 159 * affected HW module(s). Depending on the reset controller hardware, the reset 160 * signal will either stay asserted until reset_deassert() is called, or the 161 * hardware may autonomously clear the reset signal itself. 162 * 163 * @reset_ctl: A reset control struct that was previously successfully 164 * requested by reset_get_by_*(). 165 * @return 0 if OK, or a negative error code. 166 */ 167 int reset_assert(struct reset_ctl *reset_ctl); 168 169 /** 170 * reset_assert_bulk - Assert all reset signals in a reset control bulk struct. 171 * 172 * This function will assert the specified reset signals in a reset control 173 * bulk struct, thus resetting the affected HW module(s). Depending on the 174 * reset controller hardware, the reset signals will either stay asserted 175 * until reset_deassert_bulk() is called, or the hardware may autonomously 176 * clear the reset signals itself. 177 * 178 * @bulk: A reset control bulk struct that was previously successfully 179 * requested by reset_get_bulk(). 180 * @return 0 if OK, or a negative error code. 181 */ 182 int reset_assert_bulk(struct reset_ctl_bulk *bulk); 183 184 /** 185 * reset_deassert - Deassert a reset signal. 186 * 187 * This function will deassert the specified reset signal, thus releasing the 188 * affected HW modules() from reset, and allowing them to continue normal 189 * operation. 190 * 191 * @reset_ctl: A reset control struct that was previously successfully 192 * requested by reset_get_by_*(). 193 * @return 0 if OK, or a negative error code. 194 */ 195 int reset_deassert(struct reset_ctl *reset_ctl); 196 197 /** 198 * reset_deassert_bulk - Deassert all reset signals in a reset control bulk 199 * struct. 200 * 201 * This function will deassert the specified reset signals in a reset control 202 * bulk struct, thus releasing the affected HW modules() from reset, and 203 * allowing them to continue normal operation. 204 * 205 * @bulk: A reset control bulk struct that was previously successfully 206 * requested by reset_get_bulk(). 207 * @return 0 if OK, or a negative error code. 208 */ 209 int reset_deassert_bulk(struct reset_ctl_bulk *bulk); 210 211 /** 212 * rst_status - Check reset signal status. 213 * 214 * @reset_ctl: The reset signal to check. 215 * @return 0 if deasserted, positive if asserted, or a negative 216 * error code. 217 */ 218 int reset_status(struct reset_ctl *reset_ctl); 219 220 /** 221 * reset_release_all - Assert/Free an array of previously requested resets. 222 * 223 * For each reset contained in the reset array, this function will check if 224 * reset has been previously requested and then will assert and free it. 225 * 226 * @reset_ctl: A reset struct array that was previously successfully 227 * requested by reset_get_by_*(). 228 * @count Number of reset contained in the array 229 * @return 0 if OK, or a negative error code. 230 */ 231 int reset_release_all(struct reset_ctl *reset_ctl, int count); 232 233 /** 234 * reset_release_bulk - Assert/Free an array of previously requested reset 235 * signals in a reset control bulk struct. 236 * 237 * For each reset contained in the reset control bulk struct, this function 238 * will check if reset has been previously requested and then will assert 239 * and free it. 240 * 241 * @bulk: A reset control bulk struct that was previously successfully 242 * requested by reset_get_bulk(). 243 * @return 0 if OK, or a negative error code. 244 */ 245 static inline int reset_release_bulk(struct reset_ctl_bulk *bulk) 246 { 247 return reset_release_all(bulk->resets, bulk->count); 248 } 249 #else 250 static inline int reset_get_by_index(struct udevice *dev, int index, 251 struct reset_ctl *reset_ctl) 252 { 253 return -ENOTSUPP; 254 } 255 256 static inline int reset_get_bulk(struct udevice *dev, 257 struct reset_ctl_bulk *bulk) 258 { 259 return -ENOTSUPP; 260 } 261 262 static inline int reset_get_by_name(struct udevice *dev, const char *name, 263 struct reset_ctl *reset_ctl) 264 { 265 return -ENOTSUPP; 266 } 267 268 static inline int reset_free(struct reset_ctl *reset_ctl) 269 { 270 return 0; 271 } 272 273 static inline int reset_assert(struct reset_ctl *reset_ctl) 274 { 275 return 0; 276 } 277 278 static inline int reset_assert_bulk(struct reset_ctl_bulk *bulk) 279 { 280 return 0; 281 } 282 283 static inline int reset_deassert(struct reset_ctl *reset_ctl) 284 { 285 return 0; 286 } 287 288 static inline int reset_deassert_bulk(struct reset_ctl_bulk *bulk) 289 { 290 return 0; 291 } 292 293 static inline int reset_status(struct reset_ctl *reset_ctl) 294 { 295 return -ENOTSUPP; 296 } 297 298 static inline int reset_release_all(struct reset_ctl *reset_ctl, int count) 299 { 300 return 0; 301 } 302 303 static inline int reset_release_bulk(struct reset_ctl_bulk *bulk) 304 { 305 return 0; 306 } 307 #endif 308 309 #endif 310