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 /** 11 * A reset is a hardware signal indicating that a HW module (or IP block, or 12 * sometimes an entire off-CPU chip) reset all of its internal state to some 13 * known-good initial state. Drivers will often reset HW modules when they 14 * begin execution to ensure that hardware correctly responds to all requests, 15 * or in response to some error condition. Reset signals are often controlled 16 * externally to the HW module being reset, by an entity this API calls a reset 17 * controller. This API provides a standard means for drivers to request that 18 * reset controllers set or clear reset signals. 19 * 20 * A driver that implements UCLASS_RESET is a reset controller or provider. A 21 * controller will often implement multiple separate reset signals, since the 22 * hardware it manages often has this capability. reset-uclass.h describes the 23 * interface which reset controllers must implement. 24 * 25 * Reset consumers/clients are the HW modules affected by reset signals. This 26 * header file describes the API used by drivers for those HW modules. 27 */ 28 29 struct udevice; 30 31 /** 32 * struct reset_ctl - A handle to (allowing control of) a single reset signal. 33 * 34 * Clients provide storage for reset control handles. The content of the 35 * structure is managed solely by the reset API and reset drivers. A reset 36 * control struct is initialized by "get"ing the reset control struct. The 37 * reset control struct is passed to all other reset APIs to identify which 38 * reset signal to operate upon. 39 * 40 * @dev: The device which implements the reset signal. 41 * @id: The reset signal ID within the provider. 42 * 43 * Currently, the reset API assumes that a single integer ID is enough to 44 * identify and configure any reset signal for any reset provider. If this 45 * assumption becomes invalid in the future, the struct could be expanded to 46 * either (a) add more fields to allow reset providers to store additional 47 * information, or (b) replace the id field with an opaque pointer, which the 48 * provider would dynamically allocated during its .of_xlate op, and process 49 * during is .request op. This may require the addition of an extra op to clean 50 * up the allocation. 51 */ 52 struct reset_ctl { 53 struct udevice *dev; 54 /* 55 * Written by of_xlate. We assume a single id is enough for now. In the 56 * future, we might add more fields here. 57 */ 58 unsigned long id; 59 }; 60 61 /** 62 * reset_get_by_index - Get/request a reset signal by integer index. 63 * 64 * This looks up and requests a reset signal. The index is relative to the 65 * client device; each device is assumed to have n reset signals associated 66 * with it somehow, and this function finds and requests one of them. The 67 * mapping of client device reset signal indices to provider reset signals may 68 * be via device-tree properties, board-provided mapping tables, or some other 69 * mechanism. 70 * 71 * @dev: The client device. 72 * @index: The index of the reset signal to request, within the client's 73 * list of reset signals. 74 * @reset_ctl A pointer to a reset control struct to initialize. 75 * @return 0 if OK, or a negative error code. 76 */ 77 int reset_get_by_index(struct udevice *dev, int index, 78 struct reset_ctl *reset_ctl); 79 80 /** 81 * reset_get_by_name - Get/request a reset signal by name. 82 * 83 * This looks up and requests a reset signal. The name is relative to the 84 * client device; each device is assumed to have n reset signals associated 85 * with it somehow, and this function finds and requests one of them. The 86 * mapping of client device reset signal names to provider reset signal may be 87 * via device-tree properties, board-provided mapping tables, or some other 88 * mechanism. 89 * 90 * @dev: The client device. 91 * @name: The name of the reset signal to request, within the client's 92 * list of reset signals. 93 * @reset_ctl: A pointer to a reset control struct to initialize. 94 * @return 0 if OK, or a negative error code. 95 */ 96 int reset_get_by_name(struct udevice *dev, const char *name, 97 struct reset_ctl *reset_ctl); 98 99 /** 100 * reset_free - Free a previously requested reset signal. 101 * 102 * @reset_ctl: A reset control struct that was previously successfully 103 * requested by reset_get_by_*(). 104 * @return 0 if OK, or a negative error code. 105 */ 106 int reset_free(struct reset_ctl *reset_ctl); 107 108 /** 109 * reset_assert - Assert a reset signal. 110 * 111 * This function will assert the specified reset signal, thus resetting the 112 * affected HW module(s). Depending on the reset controller hardware, the reset 113 * signal will either stay asserted until reset_deassert() is called, or the 114 * hardware may autonomously clear the reset signal itself. 115 * 116 * @reset_ctl: A reset control struct that was previously successfully 117 * requested by reset_get_by_*(). 118 * @return 0 if OK, or a negative error code. 119 */ 120 int reset_assert(struct reset_ctl *reset_ctl); 121 122 /** 123 * reset_deassert - Deassert a reset signal. 124 * 125 * This function will deassert the specified reset signal, thus releasing the 126 * affected HW modules() from reset, and allowing them to continue normal 127 * operation. 128 * 129 * @reset_ctl: A reset control struct that was previously successfully 130 * requested by reset_get_by_*(). 131 * @return 0 if OK, or a negative error code. 132 */ 133 int reset_deassert(struct reset_ctl *reset_ctl); 134 135 #endif 136