include/reset.h

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