drivers/gpu/drm/i915/gem/i915_gem_context_types.h

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