Documentation/gpu/rfc/i915_parallel_execbuf.h

   1 /* SPDX-License-Identifier: MIT */
   2 /*
   3  * Copyright © 2021 Intel Corporation
   4  */
   5
   6 #define I915_CONTEXT_ENGINES_EXT_PARALLEL_SUBMIT 2 /* see i915_context_engines_parallel_submit */
   7
   8 /**
   9  * struct drm_i915_context_engines_parallel_submit - Configure engine for
  10  * parallel submission.
  11  *
  12  * Setup a slot in the context engine map to allow multiple BBs to be submitted
  13  * in a single execbuf IOCTL. Those BBs will then be scheduled to run on the GPU
  14  * in parallel. Multiple hardware contexts are created internally in the i915
  15  * run these BBs. Once a slot is configured for N BBs only N BBs can be
  16  * submitted in each execbuf IOCTL and this is implicit behavior e.g. The user
  17  * doesn't tell the execbuf IOCTL there are N BBs, the execbuf IOCTL knows how
  18  * many BBs there are based on the slot's configuration. The N BBs are the last
  19  * N buffer objects or first N if I915_EXEC_BATCH_FIRST is set.
  20  *
  21  * The default placement behavior is to create implicit bonds between each
  22  * context if each context maps to more than 1 physical engine (e.g. context is
  23  * a virtual engine). Also we only allow contexts of same engine class and these
  24  * contexts must be in logically contiguous order. Examples of the placement
  25  * behavior described below. Lastly, the default is to not allow BBs to
  26  * preempted mid BB rather insert coordinated preemption on all hardware
  27  * contexts between each set of BBs. Flags may be added in the future to change
  28  * both of these default behaviors.
  29  *
  30  * Returns -EINVAL if hardware context placement configuration is invalid or if
  31  * the placement configuration isn't supported on the platform / submission
  32  * interface.
  33  * Returns -ENODEV if extension isn't supported on the platform / submission
  34  * interface.
  35  *
  36  * .. code-block:: none
  37  *
  38  *      Example 1 pseudo code:
  39  *      CS[X] = generic engine of same class, logical instance X
  40  *      INVALID = I915_ENGINE_CLASS_INVALID, I915_ENGINE_CLASS_INVALID_NONE
  41  *      set_engines(INVALID)
  42  *      set_parallel(engine_index=0, width=2, num_siblings=1,
  43  *                   engines=CS[0],CS[1])
  44  *
  45  *      Results in the following valid placement:
  46  *      CS[0], CS[1]
  47  *
  48  *      Example 2 pseudo code:
  49  *      CS[X] = generic engine of same class, logical instance X
  50  *      INVALID = I915_ENGINE_CLASS_INVALID, I915_ENGINE_CLASS_INVALID_NONE
  51  *      set_engines(INVALID)
  52  *      set_parallel(engine_index=0, width=2, num_siblings=2,
  53  *                   engines=CS[0],CS[2],CS[1],CS[3])
  54  *
  55  *      Results in the following valid placements:
  56  *      CS[0], CS[1]
  57  *      CS[2], CS[3]
  58  *
  59  *      This can also be thought of as 2 virtual engines described by 2-D array
  60  *      in the engines the field with bonds placed between each index of the
  61  *      virtual engines. e.g. CS[0] is bonded to CS[1], CS[2] is bonded to
  62  *      CS[3].
  63  *      VE[0] = CS[0], CS[2]
  64  *      VE[1] = CS[1], CS[3]
  65  *
  66  *      Example 3 pseudo code:
  67  *      CS[X] = generic engine of same class, logical instance X
  68  *      INVALID = I915_ENGINE_CLASS_INVALID, I915_ENGINE_CLASS_INVALID_NONE
  69  *      set_engines(INVALID)
  70  *      set_parallel(engine_index=0, width=2, num_siblings=2,
  71  *                   engines=CS[0],CS[1],CS[1],CS[3])
  72  *
  73  *      Results in the following valid and invalid placements:
  74  *      CS[0], CS[1]
  75  *      CS[1], CS[3] - Not logical contiguous, return -EINVAL
  76  */
  77 struct drm_i915_context_engines_parallel_submit {
  78         /**
  79          * @base: base user extension.
  80          */
  81         struct i915_user_extension base;
  82
  83         /**
  84          * @engine_index: slot for parallel engine
  85          */
  86         __u16 engine_index;
  87
  88         /**
  89          * @width: number of contexts per parallel engine
  90          */
  91         __u16 width;
  92
  93         /**
  94          * @num_siblings: number of siblings per context
  95          */
  96         __u16 num_siblings;
  97
  98         /**
  99          * @mbz16: reserved for future use; must be zero
 100          */
 101         __u16 mbz16;
 102
 103         /**
 104          * @flags: all undefined flags must be zero, currently not defined flags
 105          */
 106         __u64 flags;
 107
 108         /**
 109          * @mbz64: reserved for future use; must be zero
 110          */
 111         __u64 mbz64[3];
 112
 113         /**
 114          * @engines: 2-d array of engine instances to configure parallel engine
 115          *
 116          * length = width (i) * num_siblings (j)
 117          * index = j + i * num_siblings
 118          */
 119         struct i915_engine_class_instance engines[0];
 120
 121 } __packed;
 122