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_free - Free a previously requested reset signal. 104 * 105 * @reset_ctl: A reset control struct that was previously successfully 106 * requested by reset_get_by_*(). 107 * @return 0 if OK, or a negative error code. 108 */ 109 int reset_free(struct reset_ctl *reset_ctl); 110 111 /** 112 * reset_assert - Assert a reset signal. 113 * 114 * This function will assert the specified reset signal, thus resetting the 115 * affected HW module(s). Depending on the reset controller hardware, the reset 116 * signal will either stay asserted until reset_deassert() is called, or the 117 * hardware may autonomously clear the reset signal itself. 118 * 119 * @reset_ctl: A reset control struct that was previously successfully 120 * requested by reset_get_by_*(). 121 * @return 0 if OK, or a negative error code. 122 */ 123 int reset_assert(struct reset_ctl *reset_ctl); 124 125 /** 126 * reset_deassert - Deassert a reset signal. 127 * 128 * This function will deassert the specified reset signal, thus releasing the 129 * affected HW modules() from reset, and allowing them to continue normal 130 * operation. 131 * 132 * @reset_ctl: A reset control struct that was previously successfully 133 * requested by reset_get_by_*(). 134 * @return 0 if OK, or a negative error code. 135 */ 136 int reset_deassert(struct reset_ctl *reset_ctl); 137 138 #else 139 static inline int reset_get_by_index(struct udevice *dev, int index, 140 struct reset_ctl *reset_ctl) 141 { 142 return -ENOTSUPP; 143 } 144 145 static inline int reset_get_by_name(struct udevice *dev, const char *name, 146 struct reset_ctl *reset_ctl) 147 { 148 return -ENOTSUPP; 149 } 150 151 static inline int reset_free(struct reset_ctl *reset_ctl) 152 { 153 return 0; 154 } 155 156 static inline int reset_assert(struct reset_ctl *reset_ctl) 157 { 158 return 0; 159 } 160 161 static inline int reset_deassert(struct reset_ctl *reset_ctl) 162 { 163 return 0; 164 } 165 #endif 166 167 #endif 168