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 <dm/ofnode.h> 10#include <linux/err.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 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 * @data: An optional data field for scenarios where a single integer ID is not 45 * sufficient. If used, it can be populated through an .of_xlate op and 46 * processed during the various reset ops. 47 * @polarity: An optional polarity field for drivers that support 48 * different reset polarities. 49 * 50 * Should additional information to identify and configure any reset signal 51 * for any provider be required in the future, the struct could be expanded to 52 * either (a) add more fields to allow reset providers to store additional 53 * information, or (b) replace the id field with an opaque pointer, which the 54 * provider would dynamically allocated during its .of_xlate op, and process 55 * during is .request op. This may require the addition of an extra op to clean 56 * up the allocation. 57 */ 58struct reset_ctl { 59 struct udevice *dev; 60 /* 61 * Written by of_xlate. In the future, we might add more fields here. 62 */ 63 unsigned long id; 64 unsigned long data; 65 unsigned long polarity; 66}; 67 68/** 69 * struct reset_ctl_bulk - A handle to (allowing control of) a bulk of reset 70 * signals. 71 * 72 * Clients provide storage for the reset control bulk. The content of the 73 * structure is managed solely by the reset API. A reset control bulk struct is 74 * initialized by "get"ing the reset control bulk struct. 75 * The reset control bulk struct is passed to all other bulk reset APIs to apply 76 * the API to all the reset signals in the bulk struct. 77 * 78 * @resets: An array of reset signal handles handles. 79 * @count: The number of reset signal handles in the reset array. 80 */ 81struct reset_ctl_bulk { 82 struct reset_ctl *resets; 83 unsigned int count; 84}; 85 86#if CONFIG_IS_ENABLED(DM_RESET) 87 88/** 89 * devm_reset_control_get - resource managed reset_get_by_name() 90 * @dev: device to be reset by the controller 91 * @id: reset line name 92 * 93 * Managed reset_get_by_name(). For reset controllers returned 94 * from this function, reset_free() is called automatically on driver 95 * detach. 96 * 97 * Returns a struct reset_ctl or IS_ERR() condition containing errno. 98 */ 99struct reset_ctl *devm_reset_control_get(struct udevice *dev, const char *id); 100 101/** 102 * devm_reset_control_get_optional - resource managed reset_get_by_name() that 103 * can fail 104 * @dev: The client device. 105 * @id: reset line name 106 * 107 * Managed reset_get_by_name(). For reset controllers returned 108 * from this function, reset_free() is called automatically on driver 109 * detach. 110 * 111 * Returns a struct reset_ctl or a dummy reset controller if it failed. 112 */ 113struct reset_ctl *devm_reset_control_get_optional(struct udevice *dev, 114 const char *id); 115 116/** 117 * devm_reset_control_get - resource managed reset_get_by_index() 118 * @dev: The client device. 119 * @index: The index of the reset signal to request, within the client's 120 * list of reset signals. 121 * 122 * Managed reset_get_by_index(). For reset controllers returned 123 * from this function, reset_free() is called automatically on driver 124 * detach. 125 * 126 * Returns a struct reset_ctl or IS_ERR() condition containing errno. 127 */ 128struct reset_ctl *devm_reset_control_get_by_index(struct udevice *dev, 129 int index); 130 131/** 132 * devm_reset_bulk_get - resource managed reset_get_bulk() 133 * @dev: device to be reset by the controller 134 * 135 * Managed reset_get_bulk(). For reset controllers returned 136 * from this function, reset_free() is called automatically on driver 137 * detach. 138 * 139 * Returns a struct reset_ctl or IS_ERR() condition containing errno. 140 */ 141struct reset_ctl_bulk *devm_reset_bulk_get(struct udevice *dev); 142 143/** 144 * devm_reset_bulk_get_optional - resource managed reset_get_bulk() that 145 * can fail 146 * @dev: The client device. 147 * 148 * Managed reset_get_bulk(). For reset controllers returned 149 * from this function, reset_free() is called automatically on driver 150 * detach. 151 * 152 * Returns a struct reset_ctl or NULL if it failed. 153 */ 154struct reset_ctl_bulk *devm_reset_bulk_get_optional(struct udevice *dev); 155 156/** 157 * devm_reset_bulk_get_by_node - resource managed reset_get_bulk() 158 * @dev: device to be reset by the controller 159 * @node: ofnode where the "resets" property is. Usually a sub-node of 160 * the dev's node. 161 * 162 * see devm_reset_bulk_get() 163 */ 164struct reset_ctl_bulk *devm_reset_bulk_get_by_node(struct udevice *dev, 165 ofnode node); 166 167/** 168 * devm_reset_bulk_get_optional_by_node - resource managed reset_get_bulk() 169 * that can fail 170 * @dev: device to be reset by the controller 171 * @node: ofnode where the "resets" property is. Usually a sub-node of 172 * the dev's node. 173 * 174 * see devm_reset_bulk_get_optional() 175 */ 176struct reset_ctl_bulk *devm_reset_bulk_get_optional_by_node(struct udevice *dev, 177 ofnode node); 178 179/** 180 * reset_get_by_index - Get/request a reset signal by integer index. 181 * 182 * This looks up and requests a reset signal. The index is relative to the 183 * client device; each device is assumed to have n reset signals associated 184 * with it somehow, and this function finds and requests one of them. The 185 * mapping of client device reset signal indices to provider reset signals may 186 * be via device-tree properties, board-provided mapping tables, or some other 187 * mechanism. 188 * 189 * @dev: The client device. 190 * @index: The index of the reset signal to request, within the client's 191 * list of reset signals. 192 * @reset_ctl A pointer to a reset control struct to initialize. 193 * Return: 0 if OK, or a negative error code. 194 */ 195int reset_get_by_index(struct udevice *dev, int index, 196 struct reset_ctl *reset_ctl); 197 198/** 199 * reset_get_by_index_nodev - Get/request a reset signal by integer index 200 * without a device. 201 * 202 * This is a version of reset_get_by_index() that does not use a device. 203 * 204 * @node: The client ofnode. 205 * @index: The index of the reset signal to request, within the client's 206 * list of reset signals. 207 * @reset_ctl A pointer to a reset control struct to initialize. 208 * Return: 0 if OK, or a negative error code. 209 */ 210int reset_get_by_index_nodev(ofnode node, int index, 211 struct reset_ctl *reset_ctl); 212 213/** 214 * reset_get_bulk - Get/request all reset signals of a device. 215 * 216 * This looks up and requests all reset signals of the client device; each 217 * device is assumed to have n reset signals associated with it somehow, 218 * and this function finds and requests all of them in a separate structure. 219 * The mapping of client device reset signals indices to provider reset signals 220 * may be via device-tree properties, board-provided mapping tables, or some 221 * other mechanism. 222 * 223 * @dev: The client device. 224 * @bulk A pointer to a reset control bulk struct to initialize. 225 * Return: 0 if OK, or a negative error code. 226 */ 227int reset_get_bulk(struct udevice *dev, struct reset_ctl_bulk *bulk); 228 229/** 230 * reset_get_by_name - Get/request a reset signal by name. 231 * 232 * This looks up and requests a reset signal. The name is relative to the 233 * client device; each device is assumed to have n reset signals associated 234 * with it somehow, and this function finds and requests one of them. The 235 * mapping of client device reset signal names to provider reset signal may be 236 * via device-tree properties, board-provided mapping tables, or some other 237 * mechanism. 238 * 239 * @dev: The client device. 240 * @name: The name of the reset signal to request, within the client's 241 * list of reset signals, or NULL to request the first reset 242 * signal in the list. 243 * @reset_ctl: A pointer to a reset control struct to initialize. 244 * Return: 0 if OK, or a negative error code. 245 */ 246int reset_get_by_name(struct udevice *dev, const char *name, 247 struct reset_ctl *reset_ctl); 248 249/** 250 * reset_request - Request a reset signal. 251 * 252 * @reset_ctl: A reset control struct. 253 * 254 * Return: 0 if OK, or a negative error code. 255 */ 256int reset_request(struct reset_ctl *reset_ctl); 257 258/** 259 * reset_free - Free a previously requested reset signal. 260 * 261 * @reset_ctl: A reset control struct that was previously successfully 262 * requested by reset_get_by_*(). 263 * Return: 0 if OK, or a negative error code. 264 */ 265int reset_free(struct reset_ctl *reset_ctl); 266 267/** 268 * reset_assert - Assert a reset signal. 269 * 270 * This function will assert the specified reset signal, thus resetting the 271 * affected HW module(s). Depending on the reset controller hardware, the reset 272 * signal will either stay asserted until reset_deassert() is called, or the 273 * hardware may autonomously clear the reset signal itself. 274 * 275 * @reset_ctl: A reset control struct that was previously successfully 276 * requested by reset_get_by_*(). 277 * Return: 0 if OK, or a negative error code. 278 */ 279int reset_assert(struct reset_ctl *reset_ctl); 280 281/** 282 * reset_assert_bulk - Assert all reset signals in a reset control bulk struct. 283 * 284 * This function will assert the specified reset signals in a reset control 285 * bulk struct, thus resetting the affected HW module(s). Depending on the 286 * reset controller hardware, the reset signals will either stay asserted 287 * until reset_deassert_bulk() is called, or the hardware may autonomously 288 * clear the reset signals itself. 289 * 290 * @bulk: A reset control bulk struct that was previously successfully 291 * requested by reset_get_bulk(). 292 * Return: 0 if OK, or a negative error code. 293 */ 294int reset_assert_bulk(struct reset_ctl_bulk *bulk); 295 296/** 297 * reset_deassert - Deassert a reset signal. 298 * 299 * This function will deassert the specified reset signal, thus releasing the 300 * affected HW modules() from reset, and allowing them to continue normal 301 * operation. 302 * 303 * @reset_ctl: A reset control struct that was previously successfully 304 * requested by reset_get_by_*(). 305 * Return: 0 if OK, or a negative error code. 306 */ 307int reset_deassert(struct reset_ctl *reset_ctl); 308 309/** 310 * reset_deassert_bulk - Deassert all reset signals in a reset control bulk 311 * struct. 312 * 313 * This function will deassert the specified reset signals in a reset control 314 * bulk struct, thus releasing the affected HW modules() from reset, and 315 * allowing them to continue normal operation. 316 * 317 * @bulk: A reset control bulk struct that was previously successfully 318 * requested by reset_get_bulk(). 319 * Return: 0 if OK, or a negative error code. 320 */ 321int reset_deassert_bulk(struct reset_ctl_bulk *bulk); 322 323/** 324 * rst_status - Check reset signal status. 325 * 326 * @reset_ctl: The reset signal to check. 327 * Return: 0 if deasserted, positive if asserted, or a negative 328 * error code. 329 */ 330int reset_status(struct reset_ctl *reset_ctl); 331 332/** 333 * reset_release_all - Assert/Free an array of previously requested resets. 334 * 335 * For each reset contained in the reset array, this function will check if 336 * reset has been previously requested and then will assert and free it. 337 * 338 * @reset_ctl: A reset struct array that was previously successfully 339 * requested by reset_get_by_*(). 340 * @count Number of reset contained in the array 341 * Return: 0 if OK, or a negative error code. 342 */ 343int reset_release_all(struct reset_ctl *reset_ctl, int count); 344 345/** 346 * reset_release_bulk - Assert/Free an array of previously requested reset 347 * signals in a reset control bulk struct. 348 * 349 * For each reset contained in the reset control bulk struct, this function 350 * will check if reset has been previously requested and then will assert 351 * and free it. 352 * 353 * @bulk: A reset control bulk struct that was previously successfully 354 * requested by reset_get_bulk(). 355 * Return: 0 if OK, or a negative error code. 356 */ 357static inline int reset_release_bulk(struct reset_ctl_bulk *bulk) 358{ 359 return reset_release_all(bulk->resets, bulk->count); 360} 361 362#else 363static inline struct reset_ctl *devm_reset_control_get(struct udevice *dev, 364 const char *id) 365{ 366 return ERR_PTR(-ENOTSUPP); 367} 368 369static inline struct reset_ctl *devm_reset_control_get_optional(struct udevice *dev, 370 const char *id) 371{ 372 return NULL; 373} 374 375static inline struct reset_ctl *devm_reset_control_get_by_index(struct udevice *dev, 376 int index) 377{ 378 return ERR_PTR(-ENOTSUPP); 379} 380 381static inline struct reset_ctl_bulk *devm_reset_bulk_get(struct udevice *dev) 382{ 383 return ERR_PTR(-ENOTSUPP); 384} 385 386static inline struct reset_ctl_bulk *devm_reset_bulk_get_optional(struct udevice *dev) 387{ 388 return NULL; 389} 390 391static inline struct reset_ctl_bulk *devm_reset_bulk_get_by_node(struct udevice *dev, 392 ofnode node) 393{ 394 return ERR_PTR(-ENOTSUPP); 395} 396 397static inline struct reset_ctl_bulk *devm_reset_bulk_get_optional_by_node(struct udevice *dev, 398 ofnode node) 399{ 400 return NULL; 401} 402 403static inline int reset_get_by_index(struct udevice *dev, int index, 404 struct reset_ctl *reset_ctl) 405{ 406 return -ENOTSUPP; 407} 408 409static inline int reset_get_bulk(struct udevice *dev, 410 struct reset_ctl_bulk *bulk) 411{ 412 return -ENOTSUPP; 413} 414 415static inline int reset_get_by_name(struct udevice *dev, const char *name, 416 struct reset_ctl *reset_ctl) 417{ 418 return -ENOTSUPP; 419} 420 421static inline int reset_free(struct reset_ctl *reset_ctl) 422{ 423 return 0; 424} 425 426static inline int reset_assert(struct reset_ctl *reset_ctl) 427{ 428 return 0; 429} 430 431static inline int reset_assert_bulk(struct reset_ctl_bulk *bulk) 432{ 433 return 0; 434} 435 436static inline int reset_deassert(struct reset_ctl *reset_ctl) 437{ 438 return 0; 439} 440 441static inline int reset_deassert_bulk(struct reset_ctl_bulk *bulk) 442{ 443 return 0; 444} 445 446static inline int reset_status(struct reset_ctl *reset_ctl) 447{ 448 return -ENOTSUPP; 449} 450 451static inline int reset_release_all(struct reset_ctl *reset_ctl, int count) 452{ 453 return 0; 454} 455 456static inline int reset_release_bulk(struct reset_ctl_bulk *bulk) 457{ 458 return 0; 459} 460#endif 461 462/** 463 * reset_valid() - check if reset is valid 464 * 465 * @reset_ctl: the reset to check 466 * Return: TRUE if valid, or FALSE 467 */ 468static inline bool reset_valid(struct reset_ctl *reset_ctl) 469{ 470 return !!reset_ctl->dev; 471} 472 473#endif 474