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 24 struct pid; 25 26 struct drm_i915_private; 27 struct drm_i915_file_private; 28 struct i915_address_space; 29 struct intel_timeline; 30 struct intel_ring; 31 32 /** 33 * struct i915_gem_engines - A set of engines 34 */ 35 struct 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 */ 60 struct 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 */ 71 enum 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 */ 107 struct 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 */ 189 struct 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 */ 227 struct 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