0001 .. SPDX-License-Identifier: GPL-2.0-only
0002
0003 ====================
0004 Reset controller API
0005 ====================
0006
0007 Introduction
0008 ============
0009
0010 Reset controllers are central units that control the reset signals to multiple
0011 peripherals.
0012 The reset controller API is split into two parts:
0013 the `consumer driver interface <#consumer-driver-interface>`__ (`API reference
0014 <#reset-consumer-api>`__), which allows peripheral drivers to request control
0015 over their reset input signals, and the `reset controller driver interface
0016 <#reset-controller-driver-interface>`__ (`API reference
0017 <#reset-controller-driver-api>`__), which is used by drivers for reset
0018 controller devices to register their reset controls to provide them to the
0019 consumers.
0020
0021 While some reset controller hardware units also implement system restart
0022 functionality, restart handlers are out of scope for the reset controller API.
0023
0024 Glossary
0025 --------
0026
0027 The reset controller API uses these terms with a specific meaning:
0028
0029 Reset line
0030
0031 Physical reset line carrying a reset signal from a reset controller
0032 hardware unit to a peripheral module.
0033
0034 Reset control
0035
0036 Control method that determines the state of one or multiple reset lines.
0037 Most commonly this is a single bit in reset controller register space that
0038 either allows direct control over the physical state of the reset line, or
0039 is self-clearing and can be used to trigger a predetermined pulse on the
0040 reset line.
0041 In more complicated reset controls, a single trigger action can launch a
0042 carefully timed sequence of pulses on multiple reset lines.
0043
0044 Reset controller
0045
0046 A hardware module that provides a number of reset controls to control a
0047 number of reset lines.
0048
0049 Reset consumer
0050
0051 Peripheral module or external IC that is put into reset by the signal on a
0052 reset line.
0053
0054 Consumer driver interface
0055 =========================
0056
0057 This interface provides an API that is similar to the kernel clock framework.
0058 Consumer drivers use get and put operations to acquire and release reset
0059 controls.
0060 Functions are provided to assert and deassert the controlled reset lines,
0061 trigger reset pulses, or to query reset line status.
0062
0063 When requesting reset controls, consumers can use symbolic names for their
0064 reset inputs, which are mapped to an actual reset control on an existing reset
0065 controller device by the core.
0066
0067 A stub version of this API is provided when the reset controller framework is
0068 not in use in order to minimize the need to use ifdefs.
0069
0070 Shared and exclusive resets
0071 ---------------------------
0072
0073 The reset controller API provides either reference counted deassertion and
0074 assertion or direct, exclusive control.
0075 The distinction between shared and exclusive reset controls is made at the time
0076 the reset control is requested, either via devm_reset_control_get_shared() or
0077 via devm_reset_control_get_exclusive().
0078 This choice determines the behavior of the API calls made with the reset
0079 control.
0080
0081 Shared resets behave similarly to clocks in the kernel clock framework.
0082 They provide reference counted deassertion, where only the first deassert,
0083 which increments the deassertion reference count to one, and the last assert
0084 which decrements the deassertion reference count back to zero, have a physical
0085 effect on the reset line.
0086
0087 Exclusive resets on the other hand guarantee direct control.
0088 That is, an assert causes the reset line to be asserted immediately, and a
0089 deassert causes the reset line to be deasserted immediately.
0090
0091 Assertion and deassertion
0092 -------------------------
0093
0094 Consumer drivers use the reset_control_assert() and reset_control_deassert()
0095 functions to assert and deassert reset lines.
0096 For shared reset controls, calls to the two functions must be balanced.
0097
0098 Note that since multiple consumers may be using a shared reset control, there
0099 is no guarantee that calling reset_control_assert() on a shared reset control
0100 will actually cause the reset line to be asserted.
0101 Consumer drivers using shared reset controls should assume that the reset line
0102 may be kept deasserted at all times.
0103 The API only guarantees that the reset line can not be asserted as long as any
0104 consumer has requested it to be deasserted.
0105
0106 Triggering
0107 ----------
0108
0109 Consumer drivers use reset_control_reset() to trigger a reset pulse on a
0110 self-deasserting reset control.
0111 In general, these resets can not be shared between multiple consumers, since
0112 requesting a pulse from any consumer driver will reset all connected
0113 peripherals.
0114
0115 The reset controller API allows requesting self-deasserting reset controls as
0116 shared, but for those only the first trigger request causes an actual pulse to
0117 be issued on the reset line.
0118 All further calls to this function have no effect until all consumers have
0119 called reset_control_rearm().
0120 For shared reset controls, calls to the two functions must be balanced.
0121 This allows devices that only require an initial reset at any point before the
0122 driver is probed or resumed to share a pulsed reset line.
0123
0124 Querying
0125 --------
0126
0127 Only some reset controllers support querying the current status of a reset
0128 line, via reset_control_status().
0129 If supported, this function returns a positive non-zero value if the given
0130 reset line is asserted.
0131 The reset_control_status() function does not accept a
0132 `reset control array <#reset-control-arrays>`__ handle as its input parameter.
0133
0134 Optional resets
0135 ---------------
0136
0137 Often peripherals require a reset line on some platforms but not on others.
0138 For this, reset controls can be requested as optional using
0139 devm_reset_control_get_optional_exclusive() or
0140 devm_reset_control_get_optional_shared().
0141 These functions return a NULL pointer instead of an error when the requested
0142 reset control is not specified in the device tree.
0143 Passing a NULL pointer to the reset_control functions causes them to return
0144 quietly without an error.
0145
0146 Reset control arrays
0147 --------------------
0148
0149 Some drivers need to assert a bunch of reset lines in no particular order.
0150 devm_reset_control_array_get() returns an opaque reset control handle that can
0151 be used to assert, deassert, or trigger all specified reset controls at once.
0152 The reset control API does not guarantee the order in which the individual
0153 controls therein are handled.
0154
0155 Reset controller driver interface
0156 =================================
0157
0158 Drivers for reset controller modules provide the functionality necessary to
0159 assert or deassert reset signals, to trigger a reset pulse on a reset line, or
0160 to query its current state.
0161 All functions are optional.
0162
0163 Initialization
0164 --------------
0165
0166 Drivers fill a struct :c:type:`reset_controller_dev` and register it with
0167 reset_controller_register() in their probe function.
0168 The actual functionality is implemented in callback functions via a struct
0169 :c:type:`reset_control_ops`.
0170
0171 API reference
0172 =============
0173
0174 The reset controller API is documented here in two parts:
0175 the `reset consumer API <#reset-consumer-api>`__ and the `reset controller
0176 driver API <#reset-controller-driver-api>`__.
0177
0178 Reset consumer API
0179 ------------------
0180
0181 Reset consumers can control a reset line using an opaque reset control handle,
0182 which can be obtained from devm_reset_control_get_exclusive() or
0183 devm_reset_control_get_shared().
0184 Given the reset control, consumers can call reset_control_assert() and
0185 reset_control_deassert(), trigger a reset pulse using reset_control_reset(), or
0186 query the reset line status using reset_control_status().
0187
0188 .. kernel-doc:: include/linux/reset.h
0189 :internal:
0190
0191 .. kernel-doc:: drivers/reset/core.c
0192 :functions: reset_control_reset
0193 reset_control_assert
0194 reset_control_deassert
0195 reset_control_status
0196 reset_control_acquire
0197 reset_control_release
0198 reset_control_rearm
0199 reset_control_put
0200 of_reset_control_get_count
0201 of_reset_control_array_get
0202 devm_reset_control_array_get
0203 reset_control_get_count
0204
0205 Reset controller driver API
0206 ---------------------------
0207
0208 Reset controller drivers are supposed to implement the necessary functions in
0209 a static constant structure :c:type:`reset_control_ops`, allocate and fill out
0210 a struct :c:type:`reset_controller_dev`, and register it using
0211 devm_reset_controller_register().
0212
0213 .. kernel-doc:: include/linux/reset-controller.h
0214 :internal:
0215
0216 .. kernel-doc:: drivers/reset/core.c
0217 :functions: of_reset_simple_xlate
0218 reset_controller_register
0219 reset_controller_unregister
0220 devm_reset_controller_register
0221 reset_controller_add_lookup
