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. 242 * @reset_ctl: A pointer to a reset control struct to initialize. 243 * @return 0 if OK, or a negative error code. 244 */ 245int reset_get_by_name(struct udevice *dev, const char *name, 246 struct reset_ctl *reset_ctl); 247 248/** 249 * reset_request - Request a reset signal. 250 * 251 * @reset_ctl: A reset control struct. 252 * 253 * @return 0 if OK, or a negative error code. 254 */ 255int reset_request(struct reset_ctl *reset_ctl); 256 257/** 258 * reset_free - Free a previously requested reset signal. 259 * 260 * @reset_ctl: A reset control struct that was previously successfully 261 * requested by reset_get_by_*(). 262 * @return 0 if OK, or a negative error code. 263 */ 264int reset_free(struct reset_ctl *reset_ctl); 265 266/** 267 * reset_assert - Assert a reset signal. 268 * 269 * This function will assert the specified reset signal, thus resetting the 270 * affected HW module(s). Depending on the reset controller hardware, the reset 271 * signal will either stay asserted until reset_deassert() is called, or the 272 * hardware may autonomously clear the reset signal itself. 273 * 274 * @reset_ctl: A reset control struct that was previously successfully 275 * requested by reset_get_by_*(). 276 * @return 0 if OK, or a negative error code. 277 */ 278int reset_assert(struct reset_ctl *reset_ctl); 279 280/** 281 * reset_assert_bulk - Assert all reset signals in a reset control bulk struct. 282 * 283 * This function will assert the specified reset signals in a reset control 284 * bulk struct, thus resetting the affected HW module(s). Depending on the 285 * reset controller hardware, the reset signals will either stay asserted 286 * until reset_deassert_bulk() is called, or the hardware may autonomously 287 * clear the reset signals itself. 288 * 289 * @bulk: A reset control bulk struct that was previously successfully 290 * requested by reset_get_bulk(). 291 * @return 0 if OK, or a negative error code. 292 */ 293int reset_assert_bulk(struct reset_ctl_bulk *bulk); 294 295/** 296 * reset_deassert - Deassert a reset signal. 297 * 298 * This function will deassert the specified reset signal, thus releasing the 299 * affected HW modules() from reset, and allowing them to continue normal 300 * operation. 301 * 302 * @reset_ctl: A reset control struct that was previously successfully 303 * requested by reset_get_by_*(). 304 * @return 0 if OK, or a negative error code. 305 */ 306int reset_deassert(struct reset_ctl *reset_ctl); 307 308/** 309 * reset_deassert_bulk - Deassert all reset signals in a reset control bulk 310 * struct. 311 * 312 * This function will deassert the specified reset signals in a reset control 313 * bulk struct, thus releasing the affected HW modules() from reset, and 314 * allowing them to continue normal operation. 315 * 316 * @bulk: A reset control bulk struct that was previously successfully 317 * requested by reset_get_bulk(). 318 * @return 0 if OK, or a negative error code. 319 */ 320int reset_deassert_bulk(struct reset_ctl_bulk *bulk); 321 322/** 323 * rst_status - Check reset signal status. 324 * 325 * @reset_ctl: The reset signal to check. 326 * @return 0 if deasserted, positive if asserted, or a negative 327 * error code. 328 */ 329int reset_status(struct reset_ctl *reset_ctl); 330 331/** 332 * reset_release_all - Assert/Free an array of previously requested resets. 333 * 334 * For each reset contained in the reset array, this function will check if 335 * reset has been previously requested and then will assert and free it. 336 * 337 * @reset_ctl: A reset struct array that was previously successfully 338 * requested by reset_get_by_*(). 339 * @count Number of reset contained in the array 340 * @return 0 if OK, or a negative error code. 341 */ 342int reset_release_all(struct reset_ctl *reset_ctl, int count); 343 344/** 345 * reset_release_bulk - Assert/Free an array of previously requested reset 346 * signals in a reset control bulk struct. 347 * 348 * For each reset contained in the reset control bulk struct, this function 349 * will check if reset has been previously requested and then will assert 350 * and free it. 351 * 352 * @bulk: A reset control bulk struct that was previously successfully 353 * requested by reset_get_bulk(). 354 * @return 0 if OK, or a negative error code. 355 */ 356static inline int reset_release_bulk(struct reset_ctl_bulk *bulk) 357{ 358 return reset_release_all(bulk->resets, bulk->count); 359} 360 361#else 362static inline struct reset_ctl *devm_reset_control_get(struct udevice *dev, 363 const char *id) 364{ 365 return ERR_PTR(-ENOTSUPP); 366} 367 368static inline struct reset_ctl *devm_reset_control_get_optional(struct udevice *dev, 369 const char *id) 370{ 371 return NULL; 372} 373 374static inline struct reset_ctl *devm_reset_control_get_by_index(struct udevice *dev, 375 int index) 376{ 377 return ERR_PTR(-ENOTSUPP); 378} 379 380static inline struct reset_ctl_bulk *devm_reset_bulk_get(struct udevice *dev) 381{ 382 return ERR_PTR(-ENOTSUPP); 383} 384 385static inline struct reset_ctl_bulk *devm_reset_bulk_get_optional(struct udevice *dev) 386{ 387 return NULL; 388} 389 390static inline struct reset_ctl_bulk *devm_reset_bulk_get_by_node(struct udevice *dev, 391 ofnode node) 392{ 393 return ERR_PTR(-ENOTSUPP); 394} 395 396static inline struct reset_ctl_bulk *devm_reset_bulk_get_optional_by_node(struct udevice *dev, 397 ofnode node) 398{ 399 return NULL; 400} 401 402static inline int reset_get_by_index(struct udevice *dev, int index, 403 struct reset_ctl *reset_ctl) 404{ 405 return -ENOTSUPP; 406} 407 408static inline int reset_get_bulk(struct udevice *dev, 409 struct reset_ctl_bulk *bulk) 410{ 411 return -ENOTSUPP; 412} 413 414static inline int reset_get_by_name(struct udevice *dev, const char *name, 415 struct reset_ctl *reset_ctl) 416{ 417 return -ENOTSUPP; 418} 419 420static inline int reset_free(struct reset_ctl *reset_ctl) 421{ 422 return 0; 423} 424 425static inline int reset_assert(struct reset_ctl *reset_ctl) 426{ 427 return 0; 428} 429 430static inline int reset_assert_bulk(struct reset_ctl_bulk *bulk) 431{ 432 return 0; 433} 434 435static inline int reset_deassert(struct reset_ctl *reset_ctl) 436{ 437 return 0; 438} 439 440static inline int reset_deassert_bulk(struct reset_ctl_bulk *bulk) 441{ 442 return 0; 443} 444 445static inline int reset_status(struct reset_ctl *reset_ctl) 446{ 447 return -ENOTSUPP; 448} 449 450static inline int reset_release_all(struct reset_ctl *reset_ctl, int count) 451{ 452 return 0; 453} 454 455static inline int reset_release_bulk(struct reset_ctl_bulk *bulk) 456{ 457 return 0; 458} 459#endif 460 461/** 462 * reset_valid() - check if reset is valid 463 * 464 * @reset_ctl: the reset to check 465 * @return TRUE if valid, or FALSE 466 */ 467static inline bool reset_valid(struct reset_ctl *reset_ctl) 468{ 469 return !!reset_ctl->dev; 470} 471 472#endif 473