blob: f45fcf88c43cbe205177af0e46e2f5e7b610366c [file] [log] [blame]
Stephen Warren89c1e2d2016-06-17 09:43:58 -06001/*
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
Masahiro Yamada4815db82016-09-21 11:29:01 +090010#include <linux/errno.h>
11
Stephen Warren89c1e2d2016-06-17 09:43:58 -060012/**
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
31struct 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 */
54struct 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
Masahiro Yamada4815db82016-09-21 11:29:01 +090063#ifdef CONFIG_DM_RESET
Stephen Warren89c1e2d2016-06-17 09:43:58 -060064/**
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 */
80int 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 */
99int 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 */
109int 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 */
123int 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 */
136int reset_deassert(struct reset_ctl *reset_ctl);
137
Masahiro Yamada4815db82016-09-21 11:29:01 +0900138#else
139static inline int reset_get_by_index(struct udevice *dev, int index,
140 struct reset_ctl *reset_ctl)
141{
142 return -ENOTSUPP;
143}
144
145static inline int reset_get_by_name(struct udevice *dev, const char *name,
146 struct reset_ctl *reset_ctl)
147{
148 return -ENOTSUPP;
149}
150
151static inline int reset_free(struct reset_ctl *reset_ctl)
152{
153 return 0;
154}
155
156static inline int reset_assert(struct reset_ctl *reset_ctl)
157{
158 return 0;
159}
160
161static inline int reset_deassert(struct reset_ctl *reset_ctl)
162{
163 return 0;
164}
165#endif
166
Stephen Warren89c1e2d2016-06-17 09:43:58 -0600167#endif