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/err.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 /**
  89  * devm_reset_control_get - resource managed reset_get_by_name()
  90  * @dev: device to be reset by the controller
  91  * @id: reset line name
  92  *
  93  * Managed reset_get_by_name(). For reset controllers returned
  94  * from this function, reset_free() is called automatically on driver
  95  * detach.
  96  *
  97  * Returns a struct reset_ctl or IS_ERR() condition containing errno.
  98  */
  99 struct reset_ctl *devm_reset_control_get(struct udevice *dev, const char *id);
 100
 101 /**
 102  * devm_reset_control_get_optional - resource managed reset_get_by_name() that
 103  *                                   can fail
 104  * @dev:        The client device.
 105  * @id:         reset line name
 106  *
 107  * Managed reset_get_by_name(). For reset controllers returned
 108  * from this function, reset_free() is called automatically on driver
 109  * detach.
 110  *
 111  * Returns a struct reset_ctl or a dummy reset controller if it failed.
 112  */
 113 struct reset_ctl *devm_reset_control_get_optional(struct udevice *dev,
 114                                                   const char *id);
 115
 116 /**
 117  * devm_reset_control_get - resource managed reset_get_by_index()
 118  * @dev:        The client device.
 119  * @index:      The index of the reset signal to request, within the client's
 120  *              list of reset signals.
 121  *
 122  * Managed reset_get_by_index(). For reset controllers returned
 123  * from this function, reset_free() is called automatically on driver
 124  * detach.
 125  *
 126  * Returns a struct reset_ctl or IS_ERR() condition containing errno.
 127  */
 128 struct reset_ctl *devm_reset_control_get_by_index(struct udevice *dev,
 129                                                   int index);
 130
 131 /**
 132  * devm_reset_bulk_get - resource managed reset_get_bulk()
 133  * @dev: device to be reset by the controller
 134  *
 135  * Managed reset_get_bulk(). For reset controllers returned
 136  * from this function, reset_free() is called automatically on driver
 137  * detach.
 138  *
 139  * Returns a struct reset_ctl or IS_ERR() condition containing errno.
 140  */
 141 struct reset_ctl_bulk *devm_reset_bulk_get(struct udevice *dev);
 142
 143 /**
 144  * devm_reset_bulk_get_optional - resource managed reset_get_bulk() that
 145  *                                can fail
 146  * @dev:        The client device.
 147  *
 148  * Managed reset_get_bulk(). For reset controllers returned
 149  * from this function, reset_free() is called automatically on driver
 150  * detach.
 151  *
 152  * Returns a struct reset_ctl or NULL if it failed.
 153  */
 154 struct reset_ctl_bulk *devm_reset_bulk_get_optional(struct udevice *dev);
 155
 156 /**
 157  * devm_reset_bulk_get_by_node - resource managed reset_get_bulk()
 158  * @dev: device to be reset by the controller
 159  * @node: ofnode where the "resets" property is. Usually a sub-node of
 160  *        the dev's node.
 161  *
 162  * see devm_reset_bulk_get()
 163  */
 164 struct reset_ctl_bulk *devm_reset_bulk_get_by_node(struct udevice *dev,
 165                                                    ofnode node);
 166
 167 /**
 168  * devm_reset_bulk_get_optional_by_node - resource managed reset_get_bulk()
 169  *                                        that can fail
 170  * @dev: device to be reset by the controller
 171  * @node: ofnode where the "resets" property is. Usually a sub-node of
 172  *        the dev's node.
 173  *
 174  * see devm_reset_bulk_get_optional()
 175  */
 176 struct reset_ctl_bulk *devm_reset_bulk_get_optional_by_node(struct udevice *dev,
 177                                                             ofnode node);
 178
 179 /**
 180  * reset_get_by_index - Get/request a reset signal by integer index.
 181  *
 182  * This looks up and requests a reset signal. The index is relative to the
 183  * client device; each device is assumed to have n reset signals associated
 184  * with it somehow, and this function finds and requests one of them. The
 185  * mapping of client device reset signal indices to provider reset signals may
 186  * be via device-tree properties, board-provided mapping tables, or some other
 187  * mechanism.
 188  *
 189  * @dev:        The client device.
 190  * @index:      The index of the reset signal to request, within the client's
 191  *              list of reset signals.
 192  * @reset_ctl   A pointer to a reset control struct to initialize.
 193  * Return: 0 if OK, or a negative error code.
 194  */
 195 int reset_get_by_index(struct udevice *dev, int index,
 196                        struct reset_ctl *reset_ctl);
 197
 198 /**
 199  * reset_get_by_index_nodev - Get/request a reset signal by integer index
 200  * without a device.
 201  *
 202  * This is a version of reset_get_by_index() that does not use a device.
 203  *
 204  * @node:       The client ofnode.
 205  * @index:      The index of the reset signal to request, within the client's
 206  *              list of reset signals.
 207  * @reset_ctl   A pointer to a reset control struct to initialize.
 208  * Return: 0 if OK, or a negative error code.
 209  */
 210 int reset_get_by_index_nodev(ofnode node, int index,
 211                              struct reset_ctl *reset_ctl);
 212
 213 /**
 214  * reset_get_bulk - Get/request all reset signals of a device.
 215  *
 216  * This looks up and requests all reset signals of the client device; each
 217  * device is assumed to have n reset signals associated with it somehow,
 218  * and this function finds and requests all of them in a separate structure.
 219  * The mapping of client device reset signals indices to provider reset signals
 220  * may be via device-tree properties, board-provided mapping tables, or some
 221  * other mechanism.
 222  *
 223  * @dev:        The client device.
 224  * @bulk        A pointer to a reset control bulk struct to initialize.
 225  * Return: 0 if OK, or a negative error code.
 226  */
 227 int reset_get_bulk(struct udevice *dev, struct reset_ctl_bulk *bulk);
 228
 229 /**
 230  * reset_get_by_name - Get/request a reset signal by name.
 231  *
 232  * This looks up and requests a reset signal. The name is relative to the
 233  * client device; each device is assumed to have n reset signals associated
 234  * with it somehow, and this function finds and requests one of them. The
 235  * mapping of client device reset signal names to provider reset signal may be
 236  * via device-tree properties, board-provided mapping tables, or some other
 237  * mechanism.
 238  *
 239  * @dev:        The client device.
 240  * @name:       The name of the reset signal to request, within the client's
 241  *              list of reset signals, or NULL to request the first reset
 242  *              signal in the list.
 243  * @reset_ctl:  A pointer to a reset control struct to initialize.
 244  * Return: 0 if OK, or a negative error code.
 245  */
 246 int reset_get_by_name(struct udevice *dev, const char *name,
 247                       struct reset_ctl *reset_ctl);
 248
 249 /**
 250  * reset_request - Request a reset signal.
 251  *
 252  * @reset_ctl:  A reset control struct.
 253  *
 254  * Return: 0 if OK, or a negative error code.
 255  */
 256 int reset_request(struct reset_ctl *reset_ctl);
 257
 258 /**
 259  * reset_free - Free a previously requested reset signal.
 260  *
 261  * @reset_ctl:  A reset control struct that was previously successfully
 262  *              requested by reset_get_by_*().
 263  * Return: 0 if OK, or a negative error code.
 264  */
 265 int reset_free(struct reset_ctl *reset_ctl);
 266
 267 /**
 268  * reset_assert - Assert a reset signal.
 269  *
 270  * This function will assert the specified reset signal, thus resetting the
 271  * affected HW module(s). Depending on the reset controller hardware, the reset
 272  * signal will either stay asserted until reset_deassert() is called, or the
 273  * hardware may autonomously clear the reset signal itself.
 274  *
 275  * @reset_ctl:  A reset control struct that was previously successfully
 276  *              requested by reset_get_by_*().
 277  * Return: 0 if OK, or a negative error code.
 278  */
 279 int reset_assert(struct reset_ctl *reset_ctl);
 280
 281 /**
 282  * reset_assert_bulk - Assert all reset signals in a reset control bulk struct.
 283  *
 284  * This function will assert the specified reset signals in a reset control
 285  * bulk struct, thus resetting the affected HW module(s). Depending on the
 286  * reset controller hardware, the reset signals will either stay asserted
 287  * until reset_deassert_bulk() is called, or the hardware may autonomously
 288  * clear the reset signals itself.
 289  *
 290  * @bulk:       A reset control bulk struct that was previously successfully
 291  *              requested by reset_get_bulk().
 292  * Return: 0 if OK, or a negative error code.
 293  */
 294 int reset_assert_bulk(struct reset_ctl_bulk *bulk);
 295
 296 /**
 297  * reset_deassert - Deassert a reset signal.
 298  *
 299  * This function will deassert the specified reset signal, thus releasing the
 300  * affected HW modules() from reset, and allowing them to continue normal
 301  * operation.
 302  *
 303  * @reset_ctl:  A reset control struct that was previously successfully
 304  *              requested by reset_get_by_*().
 305  * Return: 0 if OK, or a negative error code.
 306  */
 307 int reset_deassert(struct reset_ctl *reset_ctl);
 308
 309 /**
 310  * reset_deassert_bulk - Deassert all reset signals in a reset control bulk
 311  * struct.
 312  *
 313  * This function will deassert the specified reset signals in a reset control
 314  * bulk struct, thus releasing the affected HW modules() from reset, and
 315  * allowing them to continue normal operation.
 316  *
 317  * @bulk:       A reset control bulk struct that was previously successfully
 318  *              requested by reset_get_bulk().
 319  * Return: 0 if OK, or a negative error code.
 320  */
 321 int reset_deassert_bulk(struct reset_ctl_bulk *bulk);
 322
 323 /**
 324  * rst_status - Check reset signal status.
 325  *
 326  * @reset_ctl:  The reset signal to check.
 327  * Return: 0 if deasserted, positive if asserted, or a negative
 328  *           error code.
 329  */
 330 int reset_status(struct reset_ctl *reset_ctl);
 331
 332 /**
 333  * reset_release_all - Assert/Free an array of previously requested resets.
 334  *
 335  * For each reset contained in the reset array, this function will check if
 336  * reset has been previously requested and then will assert and free it.
 337  *
 338  * @reset_ctl:  A reset struct array that was previously successfully
 339  *              requested by reset_get_by_*().
 340  * @count       Number of reset contained in the array
 341  * Return: 0 if OK, or a negative error code.
 342  */
 343 int reset_release_all(struct reset_ctl *reset_ctl, int count);
 344
 345 /**
 346  * reset_release_bulk - Assert/Free an array of previously requested reset
 347  * signals in a reset control bulk struct.
 348  *
 349  * For each reset contained in the reset control bulk struct, this function
 350  * will check if reset has been previously requested and then will assert
 351  * and free it.
 352  *
 353  * @bulk:       A reset control bulk struct that was previously successfully
 354  *              requested by reset_get_bulk().
 355  * Return: 0 if OK, or a negative error code.
 356  */
 357 static inline int reset_release_bulk(struct reset_ctl_bulk *bulk)
 358 {
 359         return reset_release_all(bulk->resets, bulk->count);
 360 }
 361
 362 #else
 363 static inline struct reset_ctl *devm_reset_control_get(struct udevice *dev,
 364                                                        const char *id)
 365 {
 366         return ERR_PTR(-ENOTSUPP);
 367 }
 368
 369 static inline struct reset_ctl *devm_reset_control_get_optional(struct udevice *dev,
 370                                                                 const char *id)
 371 {
 372         return NULL;
 373 }
 374
 375 static inline struct reset_ctl *devm_reset_control_get_by_index(struct udevice *dev,
 376                                                                 int index)
 377 {
 378         return ERR_PTR(-ENOTSUPP);
 379 }
 380
 381 static inline struct reset_ctl_bulk *devm_reset_bulk_get(struct udevice *dev)
 382 {
 383         return ERR_PTR(-ENOTSUPP);
 384 }
 385
 386 static inline struct reset_ctl_bulk *devm_reset_bulk_get_optional(struct udevice *dev)
 387 {
 388         return NULL;
 389 }
 390
 391 static inline struct reset_ctl_bulk *devm_reset_bulk_get_by_node(struct udevice *dev,
 392                                                                  ofnode node)
 393 {
 394         return ERR_PTR(-ENOTSUPP);
 395 }
 396
 397 static inline struct reset_ctl_bulk *devm_reset_bulk_get_optional_by_node(struct udevice *dev,
 398                                                                           ofnode node)
 399 {
 400         return NULL;
 401 }
 402
 403 static inline int reset_get_by_index(struct udevice *dev, int index,
 404                                      struct reset_ctl *reset_ctl)
 405 {
 406         return -ENOTSUPP;
 407 }
 408
 409 static inline int reset_get_bulk(struct udevice *dev,
 410                                  struct reset_ctl_bulk *bulk)
 411 {
 412         return -ENOTSUPP;
 413 }
 414
 415 static inline int reset_get_by_name(struct udevice *dev, const char *name,
 416                                     struct reset_ctl *reset_ctl)
 417 {
 418         return -ENOTSUPP;
 419 }
 420
 421 static inline int reset_free(struct reset_ctl *reset_ctl)
 422 {
 423         return 0;
 424 }
 425
 426 static inline int reset_assert(struct reset_ctl *reset_ctl)
 427 {
 428         return 0;
 429 }
 430
 431 static inline int reset_assert_bulk(struct reset_ctl_bulk *bulk)
 432 {
 433         return 0;
 434 }
 435
 436 static inline int reset_deassert(struct reset_ctl *reset_ctl)
 437 {
 438         return 0;
 439 }
 440
 441 static inline int reset_deassert_bulk(struct reset_ctl_bulk *bulk)
 442 {
 443         return 0;
 444 }
 445
 446 static inline int reset_status(struct reset_ctl *reset_ctl)
 447 {
 448         return -ENOTSUPP;
 449 }
 450
 451 static inline int reset_release_all(struct reset_ctl *reset_ctl, int count)
 452 {
 453         return 0;
 454 }
 455
 456 static inline int reset_release_bulk(struct reset_ctl_bulk *bulk)
 457 {
 458         return 0;
 459 }
 460 #endif
 461
 462 /**
 463  * reset_valid() - check if reset is valid
 464  *
 465  * @reset_ctl:          the reset to check
 466  * Return: TRUE if valid, or FALSE
 467  */
 468 static inline bool reset_valid(struct reset_ctl *reset_ctl)
 469 {
 470         return !!reset_ctl->dev;
 471 }
 472
 473 #endif