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