1/* SPDX-License-Identifier: MIT */
  2/*
  3 * Copyright © 2019 Intel Corporation
  4 */
  5
  6#ifndef __INTEL_RUNTIME_PM_H__
  7#define __INTEL_RUNTIME_PM_H__
  8
  9#include <linux/types.h>
 10
 11#include "display/intel_display.h"
 12
 13#include "intel_wakeref.h"
 14
 15#include "i915_utils.h"
 16
 17struct device;
 18struct drm_i915_private;
 19struct drm_printer;
 20
 21enum i915_drm_suspend_mode {
 22	I915_DRM_SUSPEND_IDLE,
 23	I915_DRM_SUSPEND_MEM,
 24	I915_DRM_SUSPEND_HIBERNATE,
 25};
 26
 27/*
 28 * This struct helps tracking the state needed for runtime PM, which puts the
 29 * device in PCI D3 state. Notice that when this happens, nothing on the
 30 * graphics device works, even register access, so we don't get interrupts nor
 31 * anything else.
 32 *
 33 * Every piece of our code that needs to actually touch the hardware needs to
 34 * either call intel_runtime_pm_get or call intel_display_power_get with the
 35 * appropriate power domain.
 36 *
 37 * Our driver uses the autosuspend delay feature, which means we'll only really
 38 * suspend if we stay with zero refcount for a certain amount of time. The
 39 * default value is currently very conservative (see intel_runtime_pm_enable), but
 40 * it can be changed with the standard runtime PM files from sysfs.
 41 *
 42 * The irqs_disabled variable becomes true exactly after we disable the IRQs and
 43 * goes back to false exactly before we reenable the IRQs. We use this variable
 44 * to check if someone is trying to enable/disable IRQs while they're supposed
 45 * to be disabled. This shouldn't happen and we'll print some error messages in
 46 * case it happens.
 47 *
 48 * For more, read the Documentation/power/runtime_pm.rst.
 49 */
 50struct intel_runtime_pm {
 51	atomic_t wakeref_count;
 52	struct device *kdev; /* points to i915->drm.pdev->dev */
 53	bool available;
 54	bool suspended;
 55	bool irqs_enabled;
 56
 57#if IS_ENABLED(CONFIG_DRM_I915_DEBUG_RUNTIME_PM)
 58	/*
 59	 * To aide detection of wakeref leaks and general misuse, we
 60	 * track all wakeref holders. With manual markup (i.e. returning
 61	 * a cookie to each rpm_get caller which they then supply to their
 62	 * paired rpm_put) we can remove corresponding pairs of and keep
 63	 * the array trimmed to active wakerefs.
 64	 */
 65	struct intel_runtime_pm_debug {
 66		spinlock_t lock;
 67
 68		depot_stack_handle_t last_acquire;
 69		depot_stack_handle_t last_release;
 70
 71		depot_stack_handle_t *owners;
 72		unsigned long count;
 73	} debug;
 74#endif
 75};
 76
 77#define BITS_PER_WAKEREF	\
 78	BITS_PER_TYPE(struct_member(struct intel_runtime_pm, wakeref_count))
 79#define INTEL_RPM_WAKELOCK_SHIFT	(BITS_PER_WAKEREF / 2)
 80#define INTEL_RPM_WAKELOCK_BIAS		(1 << INTEL_RPM_WAKELOCK_SHIFT)
 81#define INTEL_RPM_RAW_WAKEREF_MASK	(INTEL_RPM_WAKELOCK_BIAS - 1)
 82
 83static inline int
 84intel_rpm_raw_wakeref_count(int wakeref_count)
 85{
 86	return wakeref_count & INTEL_RPM_RAW_WAKEREF_MASK;
 87}
 88
 89static inline int
 90intel_rpm_wakelock_count(int wakeref_count)
 91{
 92	return wakeref_count >> INTEL_RPM_WAKELOCK_SHIFT;
 93}
 94
 95static inline void
 96assert_rpm_device_not_suspended(struct intel_runtime_pm *rpm)
 97{
 98	WARN_ONCE(rpm->suspended,
 99		  "Device suspended during HW access\n");
100}
101
102static inline void
103__assert_rpm_raw_wakeref_held(struct intel_runtime_pm *rpm, int wakeref_count)
104{
105	assert_rpm_device_not_suspended(rpm);
106	WARN_ONCE(!intel_rpm_raw_wakeref_count(wakeref_count),
107		  "RPM raw-wakeref not held\n");
108}
109
110static inline void
111__assert_rpm_wakelock_held(struct intel_runtime_pm *rpm, int wakeref_count)
112{
113	__assert_rpm_raw_wakeref_held(rpm, wakeref_count);
114	WARN_ONCE(!intel_rpm_wakelock_count(wakeref_count),
115		  "RPM wakelock ref not held during HW access\n");
116}
117
118static inline void
119assert_rpm_raw_wakeref_held(struct intel_runtime_pm *rpm)
120{
121	__assert_rpm_raw_wakeref_held(rpm, atomic_read(&rpm->wakeref_count));
122}
123
124static inline void
125assert_rpm_wakelock_held(struct intel_runtime_pm *rpm)
126{
127	__assert_rpm_wakelock_held(rpm, atomic_read(&rpm->wakeref_count));
128}
129
130/**
131 * disable_rpm_wakeref_asserts - disable the RPM assert checks
132 * @rpm: the intel_runtime_pm structure
133 *
134 * This function disable asserts that check if we hold an RPM wakelock
135 * reference, while keeping the device-not-suspended checks still enabled.
136 * It's meant to be used only in special circumstances where our rule about
137 * the wakelock refcount wrt. the device power state doesn't hold. According
138 * to this rule at any point where we access the HW or want to keep the HW in
139 * an active state we must hold an RPM wakelock reference acquired via one of
140 * the intel_runtime_pm_get() helpers. Currently there are a few special spots
141 * where this rule doesn't hold: the IRQ and suspend/resume handlers, the
142 * forcewake release timer, and the GPU RPS and hangcheck works. All other
143 * users should avoid using this function.
144 *
145 * Any calls to this function must have a symmetric call to
146 * enable_rpm_wakeref_asserts().
147 */
148static inline void
149disable_rpm_wakeref_asserts(struct intel_runtime_pm *rpm)
150{
151	atomic_add(INTEL_RPM_WAKELOCK_BIAS + 1,
152		   &rpm->wakeref_count);
153}
154
155/**
156 * enable_rpm_wakeref_asserts - re-enable the RPM assert checks
157 * @rpm: the intel_runtime_pm structure
158 *
159 * This function re-enables the RPM assert checks after disabling them with
160 * disable_rpm_wakeref_asserts. It's meant to be used only in special
161 * circumstances otherwise its use should be avoided.
162 *
163 * Any calls to this function must have a symmetric call to
164 * disable_rpm_wakeref_asserts().
165 */
166static inline void
167enable_rpm_wakeref_asserts(struct intel_runtime_pm *rpm)
168{
169	atomic_sub(INTEL_RPM_WAKELOCK_BIAS + 1,
170		   &rpm->wakeref_count);
171}
172
173void intel_runtime_pm_init_early(struct intel_runtime_pm *rpm);
174void intel_runtime_pm_enable(struct intel_runtime_pm *rpm);
175void intel_runtime_pm_disable(struct intel_runtime_pm *rpm);
176void intel_runtime_pm_driver_release(struct intel_runtime_pm *rpm);
177
178intel_wakeref_t intel_runtime_pm_get(struct intel_runtime_pm *rpm);
179intel_wakeref_t intel_runtime_pm_get_if_in_use(struct intel_runtime_pm *rpm);
180intel_wakeref_t intel_runtime_pm_get_noresume(struct intel_runtime_pm *rpm);
181intel_wakeref_t intel_runtime_pm_get_raw(struct intel_runtime_pm *rpm);
182
183#define with_intel_runtime_pm(rpm, wf) \
184	for ((wf) = intel_runtime_pm_get(rpm); (wf); \
185	     intel_runtime_pm_put((rpm), (wf)), (wf) = 0)
186
187#define with_intel_runtime_pm_if_in_use(rpm, wf) \
188	for ((wf) = intel_runtime_pm_get_if_in_use(rpm); (wf); \
189	     intel_runtime_pm_put((rpm), (wf)), (wf) = 0)
190
191void intel_runtime_pm_put_unchecked(struct intel_runtime_pm *rpm);
192#if IS_ENABLED(CONFIG_DRM_I915_DEBUG_RUNTIME_PM)
193void intel_runtime_pm_put(struct intel_runtime_pm *rpm, intel_wakeref_t wref);
194#else
195static inline void
196intel_runtime_pm_put(struct intel_runtime_pm *rpm, intel_wakeref_t wref)
197{
198	intel_runtime_pm_put_unchecked(rpm);
199}
200#endif
201void intel_runtime_pm_put_raw(struct intel_runtime_pm *rpm, intel_wakeref_t wref);
202
203#if IS_ENABLED(CONFIG_DRM_I915_DEBUG_RUNTIME_PM)
204void print_intel_runtime_pm_wakeref(struct intel_runtime_pm *rpm,
205				    struct drm_printer *p);
206#else
207static inline void print_intel_runtime_pm_wakeref(struct intel_runtime_pm *rpm,
208						  struct drm_printer *p)
209{
210}
211#endif
212
213#endif /* __INTEL_RUNTIME_PM_H__ */