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