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