1/* SPDX-License-Identifier: MIT */
2/*
3 * Copyright © 2019 Intel Corporation
4 */
5
6#ifndef __I915_GEM_CONTEXT_TYPES_H__
7#define __I915_GEM_CONTEXT_TYPES_H__
8
9#include <linux/atomic.h>
10#include <linux/list.h>
11#include <linux/llist.h>
12#include <linux/kref.h>
13#include <linux/mutex.h>
14#include <linux/radix-tree.h>
15#include <linux/rbtree.h>
16#include <linux/rcupdate.h>
17#include <linux/types.h>
18
19#include "gt/intel_context_types.h"
20
21#include "i915_scheduler.h"
22#include "i915_sw_fence.h"
23
24struct pid;
25
26struct drm_i915_private;
27struct drm_i915_file_private;
28struct i915_address_space;
29struct intel_timeline;
30struct intel_ring;
31
32/**
33 * struct i915_gem_engines - A set of engines
34 */
35struct i915_gem_engines {
36 union {
37 /** @link: Link in i915_gem_context::stale::engines */
38 struct list_head link;
39
40 /** @rcu: RCU to use when freeing */
41 struct rcu_head rcu;
42 };
43
44 /** @fence: Fence used for delayed destruction of engines */
45 struct i915_sw_fence fence;
46
47 /** @ctx: i915_gem_context backpointer */
48 struct i915_gem_context *ctx;
49
50 /** @num_engines: Number of engines in this set */
51 unsigned int num_engines;
52
53 /** @engines: Array of engines */
54 struct intel_context *engines[];
55};
56
57/**
58 * struct i915_gem_engines_iter - Iterator for an i915_gem_engines set
59 */
60struct i915_gem_engines_iter {
61 /** @idx: Index into i915_gem_engines::engines */
62 unsigned int idx;
63
64 /** @engines: Engine set being iterated */
65 const struct i915_gem_engines *engines;
66};
67
68/**
69 * enum i915_gem_engine_type - Describes the type of an i915_gem_proto_engine
70 */
71enum i915_gem_engine_type {
72 /** @I915_GEM_ENGINE_TYPE_INVALID: An invalid engine */
73 I915_GEM_ENGINE_TYPE_INVALID = 0,
74
75 /** @I915_GEM_ENGINE_TYPE_PHYSICAL: A single physical engine */
76 I915_GEM_ENGINE_TYPE_PHYSICAL,
77
78 /** @I915_GEM_ENGINE_TYPE_BALANCED: A load-balanced engine set */
79 I915_GEM_ENGINE_TYPE_BALANCED,
80
81 /** @I915_GEM_ENGINE_TYPE_PARALLEL: A parallel engine set */
82 I915_GEM_ENGINE_TYPE_PARALLEL,
83};
84
85/**
86 * struct i915_gem_proto_engine - prototype engine
87 *
88 * This struct describes an engine that a context may contain. Engines
89 * have four types:
90 *
91 * - I915_GEM_ENGINE_TYPE_INVALID: Invalid engines can be created but they
92 * show up as a NULL in i915_gem_engines::engines[i] and any attempt to
93 * use them by the user results in -EINVAL. They are also useful during
94 * proto-context construction because the client may create invalid
95 * engines and then set them up later as virtual engines.
96 *
97 * - I915_GEM_ENGINE_TYPE_PHYSICAL: A single physical engine, described by
98 * i915_gem_proto_engine::engine.
99 *
100 * - I915_GEM_ENGINE_TYPE_BALANCED: A load-balanced engine set, described
101 * i915_gem_proto_engine::num_siblings and i915_gem_proto_engine::siblings.
102 *
103 * - I915_GEM_ENGINE_TYPE_PARALLEL: A parallel submission engine set, described
104 * i915_gem_proto_engine::width, i915_gem_proto_engine::num_siblings, and
105 * i915_gem_proto_engine::siblings.
106 */
107struct i915_gem_proto_engine {
108 /** @type: Type of this engine */
109 enum i915_gem_engine_type type;
110
111 /** @engine: Engine, for physical */
112 struct intel_engine_cs *engine;
113
114 /** @num_siblings: Number of balanced or parallel siblings */
115 unsigned int num_siblings;
116
117 /** @width: Width of each sibling */
118 unsigned int width;
119
120 /** @siblings: Balanced siblings or num_siblings * width for parallel */
121 struct intel_engine_cs **siblings;
122
123 /** @sseu: Client-set SSEU parameters */
124 struct intel_sseu sseu;
125};
126
127/**
128 * struct i915_gem_proto_context - prototype context
129 *
130 * The struct i915_gem_proto_context represents the creation parameters for
131 * a struct i915_gem_context. This is used to gather parameters provided
132 * either through creation flags or via SET_CONTEXT_PARAM so that, when we
133 * create the final i915_gem_context, those parameters can be immutable.
134 *
135 * The context uAPI allows for two methods of setting context parameters:
136 * SET_CONTEXT_PARAM and CONTEXT_CREATE_EXT_SETPARAM. The former is
137 * allowed to be called at any time while the later happens as part of
138 * GEM_CONTEXT_CREATE. When these were initially added, Currently,
139 * everything settable via one is settable via the other. While some
140 * params are fairly simple and setting them on a live context is harmless
141 * such the context priority, others are far trickier such as the VM or the
142 * set of engines. To avoid some truly nasty race conditions, we don't
143 * allow setting the VM or the set of engines on live contexts.
144 *
145 * The way we dealt with this without breaking older userspace that sets
146 * the VM or engine set via SET_CONTEXT_PARAM is to delay the creation of
147 * the actual context until after the client is done configuring it with
148 * SET_CONTEXT_PARAM. From the perspective of the client, it has the same
149 * u32 context ID the whole time. From the perspective of i915, however,
150 * it's an i915_gem_proto_context right up until the point where we attempt
151 * to do something which the proto-context can't handle at which point the
152 * real context gets created.
153 *
154 * This is accomplished via a little xarray dance. When GEM_CONTEXT_CREATE
155 * is called, we create a proto-context, reserve a slot in context_xa but
156 * leave it NULL, the proto-context in the corresponding slot in
157 * proto_context_xa. Then, whenever we go to look up a context, we first
158 * check context_xa. If it's there, we return the i915_gem_context and
159 * we're done. If it's not, we look in proto_context_xa and, if we find it
160 * there, we create the actual context and kill the proto-context.
161 *
162 * At the time we made this change (April, 2021), we did a fairly complete
163 * audit of existing userspace to ensure this wouldn't break anything:
164 *
165 * - Mesa/i965 didn't use the engines or VM APIs at all
166 *
167 * - Mesa/ANV used the engines API but via CONTEXT_CREATE_EXT_SETPARAM and
168 * didn't use the VM API.
169 *
170 * - Mesa/iris didn't use the engines or VM APIs at all
171 *
172 * - The open-source compute-runtime didn't yet use the engines API but
173 * did use the VM API via SET_CONTEXT_PARAM. However, CONTEXT_SETPARAM
174 * was always the second ioctl on that context, immediately following
175 * GEM_CONTEXT_CREATE.
176 *
177 * - The media driver sets engines and bonding/balancing via
178 * SET_CONTEXT_PARAM. However, CONTEXT_SETPARAM to set the VM was
179 * always the second ioctl on that context, immediately following
180 * GEM_CONTEXT_CREATE and setting engines immediately followed that.
181 *
182 * In order for this dance to work properly, any modification to an
183 * i915_gem_proto_context that is exposed to the client via
184 * drm_i915_file_private::proto_context_xa must be guarded by
185 * drm_i915_file_private::proto_context_lock. The exception is when a
186 * proto-context has not yet been exposed such as when handling
187 * CONTEXT_CREATE_SET_PARAM during GEM_CONTEXT_CREATE.
188 */
189struct i915_gem_proto_context {
190 /** @fpriv: Client which creates the context */
191 struct drm_i915_file_private *fpriv;
192
193 /** @vm: See &i915_gem_context.vm */
194 struct i915_address_space *vm;
195
196 /** @user_flags: See &i915_gem_context.user_flags */
197 unsigned long user_flags;
198
199 /** @sched: See &i915_gem_context.sched */
200 struct i915_sched_attr sched;
201
202 /** @num_user_engines: Number of user-specified engines or -1 */
203 int num_user_engines;
204
205 /** @user_engines: User-specified engines */
206 struct i915_gem_proto_engine *user_engines;
207
208 /** @legacy_rcs_sseu: Client-set SSEU parameters for the legacy RCS */
209 struct intel_sseu legacy_rcs_sseu;
210
211 /** @single_timeline: See See &i915_gem_context.syncobj */
212 bool single_timeline;
213
214 /** @uses_protected_content: See &i915_gem_context.uses_protected_content */
215 bool uses_protected_content;
216
217 /** @pxp_wakeref: See &i915_gem_context.pxp_wakeref */
218 intel_wakeref_t pxp_wakeref;
219};
220
221/**
222 * struct i915_gem_context - client state
223 *
224 * The struct i915_gem_context represents the combined view of the driver and
225 * logical hardware state for a particular client.
226 */
227struct i915_gem_context {
228 /** @i915: i915 device backpointer */
229 struct drm_i915_private *i915;
230
231 /** @file_priv: owning file descriptor */
232 struct drm_i915_file_private *file_priv;
233
234 /**
235 * @engines: User defined engines for this context
236 *
237 * Various uAPI offer the ability to lookup up an
238 * index from this array to select an engine operate on.
239 *
240 * Multiple logically distinct instances of the same engine
241 * may be defined in the array, as well as composite virtual
242 * engines.
243 *
244 * Execbuf uses the I915_EXEC_RING_MASK as an index into this
245 * array to select which HW context + engine to execute on. For
246 * the default array, the user_ring_map[] is used to translate
247 * the legacy uABI onto the appropriate index (e.g. both
248 * I915_EXEC_DEFAULT and I915_EXEC_RENDER select the same
249 * context, and I915_EXEC_BSD is weird). For a user defined
250 * array, execbuf uses I915_EXEC_RING_MASK as a plain index.
251 *
252 * User defined by I915_CONTEXT_PARAM_ENGINE (when the
253 * CONTEXT_USER_ENGINES flag is set).
254 */
255 struct i915_gem_engines __rcu *engines;
256
257 /** @engines_mutex: guards writes to engines */
258 struct mutex engines_mutex;
259
260 /**
261 * @syncobj: Shared timeline syncobj
262 *
263 * When the SHARED_TIMELINE flag is set on context creation, we
264 * emulate a single timeline across all engines using this syncobj.
265 * For every execbuffer2 call, this syncobj is used as both an in-
266 * and out-fence. Unlike the real intel_timeline, this doesn't
267 * provide perfect atomic in-order guarantees if the client races
268 * with itself by calling execbuffer2 twice concurrently. However,
269 * if userspace races with itself, that's not likely to yield well-
270 * defined results anyway so we choose to not care.
271 */
272 struct drm_syncobj *syncobj;
273
274 /**
275 * @vm: unique address space (GTT)
276 *
277 * In full-ppgtt mode, each context has its own address space ensuring
278 * complete separation of one client from all others.
279 *
280 * In other modes, this is a NULL pointer with the expectation that
281 * the caller uses the shared global GTT.
282 */
283 struct i915_address_space *vm;
284
285 /**
286 * @pid: process id of creator
287 *
288 * Note that who created the context may not be the principle user,
289 * as the context may be shared across a local socket. However,
290 * that should only affect the default context, all contexts created
291 * explicitly by the client are expected to be isolated.
292 */
293 struct pid *pid;
294
295 /** @link: place with &drm_i915_private.context_list */
296 struct list_head link;
297
298 /** @client: struct i915_drm_client */
299 struct i915_drm_client *client;
300
301 /** @client_link: for linking onto &i915_drm_client.ctx_list */
302 struct list_head client_link;
303
304 /**
305 * @ref: reference count
306 *
307 * A reference to a context is held by both the client who created it
308 * and on each request submitted to the hardware using the request
309 * (to ensure the hardware has access to the state until it has
310 * finished all pending writes). See i915_gem_context_get() and
311 * i915_gem_context_put() for access.
312 */
313 struct kref ref;
314
315 /**
316 * @release_work:
317 *
318 * Work item for deferred cleanup, since i915_gem_context_put() tends to
319 * be called from hardirq context.
320 *
321 * FIXME: The only real reason for this is &i915_gem_engines.fence, all
322 * other callers are from process context and need at most some mild
323 * shuffling to pull the i915_gem_context_put() call out of a spinlock.
324 */
325 struct work_struct release_work;
326
327 /**
328 * @rcu: rcu_head for deferred freeing.
329 */
330 struct rcu_head rcu;
331
332 /**
333 * @user_flags: small set of booleans controlled by the user
334 */
335 unsigned long user_flags;
336#define UCONTEXT_NO_ERROR_CAPTURE 1
337#define UCONTEXT_BANNABLE 2
338#define UCONTEXT_RECOVERABLE 3
339#define UCONTEXT_PERSISTENCE 4
340#define UCONTEXT_LOW_LATENCY 5
341
342 /**
343 * @flags: small set of booleans
344 */
345 unsigned long flags;
346#define CONTEXT_CLOSED 0
347#define CONTEXT_USER_ENGINES 1
348
349 /**
350 * @uses_protected_content: context uses PXP-encrypted objects.
351 *
352 * This flag can only be set at ctx creation time and it's immutable for
353 * the lifetime of the context. See I915_CONTEXT_PARAM_PROTECTED_CONTENT
354 * in uapi/drm/i915_drm.h for more info on setting restrictions and
355 * expected behaviour of marked contexts.
356 */
357 bool uses_protected_content;
358
359 /**
360 * @pxp_wakeref: wakeref to keep the device awake when PXP is in use
361 *
362 * PXP sessions are invalidated when the device is suspended, which in
363 * turns invalidates all contexts and objects using it. To keep the
364 * flow simple, we keep the device awake when contexts using PXP objects
365 * are in use. It is expected that the userspace application only uses
366 * PXP when the display is on, so taking a wakeref here shouldn't worsen
367 * our power metrics.
368 */
369 intel_wakeref_t pxp_wakeref;
370
371 /** @mutex: guards everything that isn't engines or handles_vma */
372 struct mutex mutex;
373
374 /** @sched: scheduler parameters */
375 struct i915_sched_attr sched;
376
377 /** @guilty_count: How many times this context has caused a GPU hang. */
378 atomic_t guilty_count;
379 /**
380 * @active_count: How many times this context was active during a GPU
381 * hang, but did not cause it.
382 */
383 atomic_t active_count;
384
385 /**
386 * @hang_timestamp: The last time(s) this context caused a GPU hang
387 */
388 unsigned long hang_timestamp[2];
389#define CONTEXT_FAST_HANG_JIFFIES (120 * HZ) /* 3 hangs within 120s? Banned! */
390
391 /** @remap_slice: Bitmask of cache lines that need remapping */
392 u8 remap_slice;
393
394 /**
395 * @handles_vma: rbtree to look up our context specific obj/vma for
396 * the user handle. (user handles are per fd, but the binding is
397 * per vm, which may be one per context or shared with the global GTT)
398 */
399 struct radix_tree_root handles_vma;
400
401 /** @lut_mutex: Locks handles_vma */
402 struct mutex lut_mutex;
403
404 /**
405 * @name: arbitrary name, used for user debug
406 *
407 * A name is constructed for the context from the creator's process
408 * name, pid and user handle in order to uniquely identify the
409 * context in messages.
410 */
411 char name[TASK_COMM_LEN + 8];
412
413 /** @stale: tracks stale engines to be destroyed */
414 struct {
415 /** @stale.lock: guards engines */
416 spinlock_t lock;
417 /** @stale.engines: list of stale engines */
418 struct list_head engines;
419 } stale;
420};
421
422#endif /* __I915_GEM_CONTEXT_TYPES_H__ */
423

source code of linux/drivers/gpu/drm/i915/gem/i915_gem_context_types.h