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