1 /* $NetBSD: i915_active.h,v 1.3 2021/12/19 11:59:04 riastradh Exp $ */
2
3 /*
4 * SPDX-License-Identifier: MIT
5 *
6 * Copyright © 2019 Intel Corporation
7 */
8
9 #ifndef _I915_ACTIVE_H_
10 #define _I915_ACTIVE_H_
11
12 #include <linux/lockdep.h>
13
14 #include "i915_active_types.h"
15 #include "i915_request.h"
16
17 struct i915_request;
18 struct intel_engine_cs;
19 struct intel_timeline;
20
21 /*
22 * We treat requests as fences. This is not be to confused with our
23 * "fence registers" but pipeline synchronisation objects ala GL_ARB_sync.
24 * We use the fences to synchronize access from the CPU with activity on the
25 * GPU, for example, we should not rewrite an object's PTE whilst the GPU
26 * is reading them. We also track fences at a higher level to provide
27 * implicit synchronisation around GEM objects, e.g. set-domain will wait
28 * for outstanding GPU rendering before marking the object ready for CPU
29 * access, or a pageflip will wait until the GPU is complete before showing
30 * the frame on the scanout.
31 *
32 * In order to use a fence, the object must track the fence it needs to
33 * serialise with. For example, GEM objects want to track both read and
34 * write access so that we can perform concurrent read operations between
35 * the CPU and GPU engines, as well as waiting for all rendering to
36 * complete, or waiting for the last GPU user of a "fence register". The
37 * object then embeds a #i915_active_fence to track the most recent (in
38 * retirement order) request relevant for the desired mode of access.
39 * The #i915_active_fence is updated with i915_active_fence_set() to
40 * track the most recent fence request, typically this is done as part of
41 * i915_vma_move_to_active().
42 *
43 * When the #i915_active_fence completes (is retired), it will
44 * signal its completion to the owner through a callback as well as mark
45 * itself as idle (i915_active_fence.request == NULL). The owner
46 * can then perform any action, such as delayed freeing of an active
47 * resource including itself.
48 */
49
50 void i915_active_noop(struct dma_fence *fence, struct dma_fence_cb *cb);
51
52 /**
53 * __i915_active_fence_init - prepares the activity tracker for use
54 * @active - the active tracker
55 * @fence - initial fence to track, can be NULL
56 * @func - a callback when then the tracker is retired (becomes idle),
57 * can be NULL
58 *
59 * i915_active_fence_init() prepares the embedded @active struct for use as
60 * an activity tracker, that is for tracking the last known active fence
61 * associated with it. When the last fence becomes idle, when it is retired
62 * after completion, the optional callback @func is invoked.
63 */
64 static inline void
__i915_active_fence_init(struct i915_active_fence * active,void * fence,dma_fence_func_t fn)65 __i915_active_fence_init(struct i915_active_fence *active,
66 void *fence,
67 dma_fence_func_t fn)
68 {
69 RCU_INIT_POINTER(active->fence, fence);
70 active->cb.func = fn ?: i915_active_noop;
71 }
72
73 #define INIT_ACTIVE_FENCE(A) \
74 __i915_active_fence_init((A), NULL, NULL)
75
76 struct dma_fence *
77 __i915_active_fence_set(struct i915_active_fence *active,
78 struct dma_fence *fence);
79
80 /**
81 * i915_active_fence_set - updates the tracker to watch the current fence
82 * @active - the active tracker
83 * @rq - the request to watch
84 *
85 * i915_active_fence_set() watches the given @rq for completion. While
86 * that @rq is busy, the @active reports busy. When that @rq is signaled
87 * (or else retired) the @active tracker is updated to report idle.
88 */
89 int __must_check
90 i915_active_fence_set(struct i915_active_fence *active,
91 struct i915_request *rq);
92 /**
93 * i915_active_fence_get - return a reference to the active fence
94 * @active - the active tracker
95 *
96 * i915_active_fence_get() returns a reference to the active fence,
97 * or NULL if the active tracker is idle. The reference is obtained under RCU,
98 * so no locking is required by the caller.
99 *
100 * The reference should be freed with dma_fence_put().
101 */
102 static inline struct dma_fence *
i915_active_fence_get(struct i915_active_fence * active)103 i915_active_fence_get(struct i915_active_fence *active)
104 {
105 struct dma_fence *fence;
106
107 rcu_read_lock();
108 fence = dma_fence_get_rcu_safe(&active->fence);
109 rcu_read_unlock();
110
111 return fence;
112 }
113
114 /**
115 * i915_active_fence_isset - report whether the active tracker is assigned
116 * @active - the active tracker
117 *
118 * i915_active_fence_isset() returns true if the active tracker is currently
119 * assigned to a fence. Due to the lazy retiring, that fence may be idle
120 * and this may report stale information.
121 */
122 static inline bool
i915_active_fence_isset(const struct i915_active_fence * active)123 i915_active_fence_isset(const struct i915_active_fence *active)
124 {
125 return rcu_access_pointer(active->fence);
126 }
127
128 /*
129 * GPU activity tracking
130 *
131 * Each set of commands submitted to the GPU compromises a single request that
132 * signals a fence upon completion. struct i915_request combines the
133 * command submission, scheduling and fence signaling roles. If we want to see
134 * if a particular task is complete, we need to grab the fence (struct
135 * i915_request) for that task and check or wait for it to be signaled. More
136 * often though we want to track the status of a bunch of tasks, for example
137 * to wait for the GPU to finish accessing some memory across a variety of
138 * different command pipelines from different clients. We could choose to
139 * track every single request associated with the task, but knowing that
140 * each request belongs to an ordered timeline (later requests within a
141 * timeline must wait for earlier requests), we need only track the
142 * latest request in each timeline to determine the overall status of the
143 * task.
144 *
145 * struct i915_active provides this tracking across timelines. It builds a
146 * composite shared-fence, and is updated as new work is submitted to the task,
147 * forming a snapshot of the current status. It should be embedded into the
148 * different resources that need to track their associated GPU activity to
149 * provide a callback when that GPU activity has ceased, or otherwise to
150 * provide a serialisation point either for request submission or for CPU
151 * synchronisation.
152 */
153
154 void __i915_active_init(struct i915_active *ref,
155 int (*active)(struct i915_active *ref),
156 void (*retire)(struct i915_active *ref),
157 struct lock_class_key *mkey,
158 struct lock_class_key *wkey);
159
160 /* Specialise each class of i915_active to avoid impossible lockdep cycles. */
161 #define i915_active_init(ref, active, retire) do { \
162 static struct lock_class_key __mkey; \
163 static struct lock_class_key __wkey; \
164 \
165 __i915_active_init(ref, active, retire, &__mkey, &__wkey); \
166 } while (0)
167
168 int i915_active_ref(struct i915_active *ref,
169 struct intel_timeline *tl,
170 struct dma_fence *fence);
171
172 static inline int
i915_active_add_request(struct i915_active * ref,struct i915_request * rq)173 i915_active_add_request(struct i915_active *ref, struct i915_request *rq)
174 {
175 return i915_active_ref(ref, i915_request_timeline(rq), &rq->fence);
176 }
177
178 void i915_active_set_exclusive(struct i915_active *ref, struct dma_fence *f);
179
i915_active_has_exclusive(struct i915_active * ref)180 static inline bool i915_active_has_exclusive(struct i915_active *ref)
181 {
182 return rcu_access_pointer(ref->excl.fence);
183 }
184
185 int i915_active_wait(struct i915_active *ref);
186
187 int i915_request_await_active(struct i915_request *rq, struct i915_active *ref);
188
189 int i915_active_acquire(struct i915_active *ref);
190 bool i915_active_acquire_if_busy(struct i915_active *ref);
191 void i915_active_release(struct i915_active *ref);
192
__i915_active_acquire(struct i915_active * ref)193 static inline void __i915_active_acquire(struct i915_active *ref)
194 {
195 GEM_BUG_ON(!atomic_read(&ref->count));
196 atomic_inc(&ref->count);
197 }
198
199 static inline bool
i915_active_is_idle(const struct i915_active * ref)200 i915_active_is_idle(const struct i915_active *ref)
201 {
202 return !atomic_read(&ref->count);
203 }
204
205 void i915_active_fini(struct i915_active *ref);
206
207 int i915_active_acquire_preallocate_barrier(struct i915_active *ref,
208 struct intel_engine_cs *engine);
209 void i915_active_acquire_barrier(struct i915_active *ref);
210 void i915_request_add_active_barriers(struct i915_request *rq);
211
212 void i915_active_print(struct i915_active *ref, struct drm_printer *m);
213 void i915_active_unlock_wait(struct i915_active *ref);
214
215 #endif /* _I915_ACTIVE_H_ */
216