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 #ifdef CONFIG_DM_RESET
  64 /**
  65  * reset_get_by_index - Get/request a reset signal by integer index.
  66  *
  67  * This looks up and requests a reset signal. The index is relative to the
  68  * client device; each device is assumed to have n reset signals associated
  69  * with it somehow, and this function finds and requests one of them. The
  70  * mapping of client device reset signal indices to provider reset signals may
  71  * be via device-tree properties, board-provided mapping tables, or some other
  72  * mechanism.
  73  *
  74  * @dev:        The client device.
  75  * @index:      The index of the reset signal to request, within the client's
  76  *              list of reset signals.
  77  * @reset_ctl   A pointer to a reset control struct to initialize.
  78  * @return 0 if OK, or a negative error code.
  79  */
  80 int reset_get_by_index(struct udevice *dev, int index,
  81                        struct reset_ctl *reset_ctl);
  82
  83 /**
  84  * reset_get_by_name - Get/request a reset signal by name.
  85  *
  86  * This looks up and requests a reset signal. The name 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 names to provider reset signal may be
  90  * via device-tree properties, board-provided mapping tables, or some other
  91  * mechanism.
  92  *
  93  * @dev:        The client device.
  94  * @name:       The name 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_name(struct udevice *dev, const char *name,
 100                       struct reset_ctl *reset_ctl);
 101
 102 /**
 103  * reset_free - Free a previously requested reset signal.
 104  *
 105  * @reset_ctl:  A reset control struct that was previously successfully
 106  *              requested by reset_get_by_*().
 107  * @return 0 if OK, or a negative error code.
 108  */
 109 int reset_free(struct reset_ctl *reset_ctl);
 110
 111 /**
 112  * reset_assert - Assert a reset signal.
 113  *
 114  * This function will assert the specified reset signal, thus resetting the
 115  * affected HW module(s). Depending on the reset controller hardware, the reset
 116  * signal will either stay asserted until reset_deassert() is called, or the
 117  * hardware may autonomously clear the reset signal itself.
 118  *
 119  * @reset_ctl:  A reset control struct that was previously successfully
 120  *              requested by reset_get_by_*().
 121  * @return 0 if OK, or a negative error code.
 122  */
 123 int reset_assert(struct reset_ctl *reset_ctl);
 124
 125 /**
 126  * reset_deassert - Deassert a reset signal.
 127  *
 128  * This function will deassert the specified reset signal, thus releasing the
 129  * affected HW modules() from reset, and allowing them to continue normal
 130  * operation.
 131  *
 132  * @reset_ctl:  A reset control struct that was previously successfully
 133  *              requested by reset_get_by_*().
 134  * @return 0 if OK, or a negative error code.
 135  */
 136 int reset_deassert(struct reset_ctl *reset_ctl);
 137
 138 #else
 139 static inline int reset_get_by_index(struct udevice *dev, int index,
 140                                      struct reset_ctl *reset_ctl)
 141 {
 142         return -ENOTSUPP;
 143 }
 144
 145 static inline int reset_get_by_name(struct udevice *dev, const char *name,
 146                                     struct reset_ctl *reset_ctl)
 147 {
 148         return -ENOTSUPP;
 149 }
 150
 151 static inline int reset_free(struct reset_ctl *reset_ctl)
 152 {
 153         return 0;
 154 }
 155
 156 static inline int reset_assert(struct reset_ctl *reset_ctl)
 157 {
 158         return 0;
 159 }
 160
 161 static inline int reset_deassert(struct reset_ctl *reset_ctl)
 162 {
 163         return 0;
 164 }
 165 #endif
 166
 167 #endif