include/reset.h

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