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 #ifdef CONFIG_DM_RESET 64 /** 65 * reset_get_by_index - Get/request a reset signal by integer index. 66 * 67 * This looks up and requests a reset signal. The index is relative to the 68 * client device; each device is assumed to have n reset signals associated 69 * with it somehow, and this function finds and requests one of them. The 70 * mapping of client device reset signal indices to provider reset signals may 71 * be via device-tree properties, board-provided mapping tables, or some other 72 * mechanism. 73 * 74 * @dev: The client device. 75 * @index: The index of the reset signal to request, within the client's 76 * list of reset signals. 77 * @reset_ctl A pointer to a reset control struct to initialize. 78 * @return 0 if OK, or a negative error code. 79 */ 80 int reset_get_by_index(struct udevice *dev, int index, 81 struct reset_ctl *reset_ctl); 82 83 /** 84 * reset_get_by_name - Get/request a reset signal by name. 85 * 86 * This looks up and requests a reset signal. The name 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 names to provider reset signal may be 90 * via device-tree properties, board-provided mapping tables, or some other 91 * mechanism. 92 * 93 * @dev: The client device. 94 * @name: The name 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_name(struct udevice *dev, const char *name, 100 struct reset_ctl *reset_ctl); 101 102 /** 103 * reset_request - Request a reset signal. 104 * 105 * @reset_ctl: A reset control struct. 106 * 107 * @return 0 if OK, or a negative error code. 108 */ 109 int reset_request(struct reset_ctl *reset_ctl); 110 111 /** 112 * reset_free - Free a previously requested reset signal. 113 * 114 * @reset_ctl: A reset control struct that was previously successfully 115 * requested by reset_get_by_*(). 116 * @return 0 if OK, or a negative error code. 117 */ 118 int reset_free(struct reset_ctl *reset_ctl); 119 120 /** 121 * reset_assert - Assert a reset signal. 122 * 123 * This function will assert the specified reset signal, thus resetting the 124 * affected HW module(s). Depending on the reset controller hardware, the reset 125 * signal will either stay asserted until reset_deassert() is called, or the 126 * hardware may autonomously clear the reset signal itself. 127 * 128 * @reset_ctl: A reset control struct that was previously successfully 129 * requested by reset_get_by_*(). 130 * @return 0 if OK, or a negative error code. 131 */ 132 int reset_assert(struct reset_ctl *reset_ctl); 133 134 /** 135 * reset_deassert - Deassert a reset signal. 136 * 137 * This function will deassert the specified reset signal, thus releasing the 138 * affected HW modules() from reset, and allowing them to continue normal 139 * operation. 140 * 141 * @reset_ctl: A reset control struct that was previously successfully 142 * requested by reset_get_by_*(). 143 * @return 0 if OK, or a negative error code. 144 */ 145 int reset_deassert(struct reset_ctl *reset_ctl); 146 147 /** 148 * reset_release_all - Assert/Free an array of previously requested resets. 149 * 150 * For each reset contained in the reset array, this function will check if 151 * reset has been previously requested and then will assert and free it. 152 * 153 * @reset_ctl: A reset struct array that was previously successfully 154 * requested by reset_get_by_*(). 155 * @count Number of reset contained in the array 156 * @return 0 if OK, or a negative error code. 157 */ 158 int reset_release_all(struct reset_ctl *reset_ctl, int count); 159 #else 160 static inline int reset_get_by_index(struct udevice *dev, int index, 161 struct reset_ctl *reset_ctl) 162 { 163 return -ENOTSUPP; 164 } 165 166 static inline int reset_get_by_name(struct udevice *dev, const char *name, 167 struct reset_ctl *reset_ctl) 168 { 169 return -ENOTSUPP; 170 } 171 172 static inline int reset_free(struct reset_ctl *reset_ctl) 173 { 174 return 0; 175 } 176 177 static inline int reset_assert(struct reset_ctl *reset_ctl) 178 { 179 return 0; 180 } 181 182 static inline int reset_deassert(struct reset_ctl *reset_ctl) 183 { 184 return 0; 185 } 186 187 static inline int reset_release_all(struct reset_ctl *reset_ctl, int count) 188 { 189 return 0; 190 } 191 192 #endif 193 194 #endif 195