Documentation/gpu/rfc/i915_small_bar.h

   1 /**
   2  * struct __drm_i915_memory_region_info - Describes one region as known to the
   3  * driver.
   4  *
   5  * Note this is using both struct drm_i915_query_item and struct drm_i915_query.
   6  * For this new query we are adding the new query id DRM_I915_QUERY_MEMORY_REGIONS
   7  * at &drm_i915_query_item.query_id.
   8  */
   9 struct __drm_i915_memory_region_info {
  10         /** @region: The class:instance pair encoding */
  11         struct drm_i915_gem_memory_class_instance region;
  12
  13         /** @rsvd0: MBZ */
  14         __u32 rsvd0;
  15
  16         /**
  17          * @probed_size: Memory probed by the driver
  18          *
  19          * Note that it should not be possible to ever encounter a zero value
  20          * here, also note that no current region type will ever return -1 here.
  21          * Although for future region types, this might be a possibility. The
  22          * same applies to the other size fields.
  23          */
  24         __u64 probed_size;
  25
  26         /**
  27          * @unallocated_size: Estimate of memory remaining
  28          *
  29          * Requires CAP_PERFMON or CAP_SYS_ADMIN to get reliable accounting.
  30          * Without this (or if this is an older kernel) the value here will
  31          * always equal the @probed_size. Note this is only currently tracked
  32          * for I915_MEMORY_CLASS_DEVICE regions (for other types the value here
  33          * will always equal the @probed_size).
  34          */
  35         __u64 unallocated_size;
  36
  37         union {
  38                 /** @rsvd1: MBZ */
  39                 __u64 rsvd1[8];
  40                 struct {
  41                         /**
  42                          * @probed_cpu_visible_size: Memory probed by the driver
  43                          * that is CPU accessible.
  44                          *
  45                          * This will be always be <= @probed_size, and the
  46                          * remainder (if there is any) will not be CPU
  47                          * accessible.
  48                          *
  49                          * On systems without small BAR, the @probed_size will
  50                          * always equal the @probed_cpu_visible_size, since all
  51                          * of it will be CPU accessible.
  52                          *
  53                          * Note this is only tracked for
  54                          * I915_MEMORY_CLASS_DEVICE regions (for other types the
  55                          * value here will always equal the @probed_size).
  56                          *
  57                          * Note that if the value returned here is zero, then
  58                          * this must be an old kernel which lacks the relevant
  59                          * small-bar uAPI support (including
  60                          * I915_GEM_CREATE_EXT_FLAG_NEEDS_CPU_ACCESS), but on
  61                          * such systems we should never actually end up with a
  62                          * small BAR configuration, assuming we are able to load
  63                          * the kernel module. Hence it should be safe to treat
  64                          * this the same as when @probed_cpu_visible_size ==
  65                          * @probed_size.
  66                          */
  67                         __u64 probed_cpu_visible_size;
  68
  69                         /**
  70                          * @unallocated_cpu_visible_size: Estimate of CPU
  71                          * visible memory remaining
  72                          *
  73                          * Note this is only tracked for
  74                          * I915_MEMORY_CLASS_DEVICE regions (for other types the
  75                          * value here will always equal the
  76                          * @probed_cpu_visible_size).
  77                          *
  78                          * Requires CAP_PERFMON or CAP_SYS_ADMIN to get reliable
  79                          * accounting.  Without this the value here will always
  80                          * equal the @probed_cpu_visible_size. Note this is only
  81                          * currently tracked for I915_MEMORY_CLASS_DEVICE
  82                          * regions (for other types the value here will also
  83                          * always equal the @probed_cpu_visible_size).
  84                          *
  85                          * If this is an older kernel the value here will be
  86                          * zero, see also @probed_cpu_visible_size.
  87                          */
  88                         __u64 unallocated_cpu_visible_size;
  89                 };
  90         };
  91 };
  92
  93 /**
  94  * struct __drm_i915_gem_create_ext - Existing gem_create behaviour, with added
  95  * extension support using struct i915_user_extension.
  96  *
  97  * Note that new buffer flags should be added here, at least for the stuff that
  98  * is immutable. Previously we would have two ioctls, one to create the object
  99  * with gem_create, and another to apply various parameters, however this
 100  * creates some ambiguity for the params which are considered immutable. Also in
 101  * general we're phasing out the various SET/GET ioctls.
 102  */
 103 struct __drm_i915_gem_create_ext {
 104         /**
 105          * @size: Requested size for the object.
 106          *
 107          * The (page-aligned) allocated size for the object will be returned.
 108          *
 109          * Note that for some devices we have might have further minimum
 110          * page-size restrictions (larger than 4K), like for device local-memory.
 111          * However in general the final size here should always reflect any
 112          * rounding up, if for example using the I915_GEM_CREATE_EXT_MEMORY_REGIONS
 113          * extension to place the object in device local-memory. The kernel will
 114          * always select the largest minimum page-size for the set of possible
 115          * placements as the value to use when rounding up the @size.
 116          */
 117         __u64 size;
 118
 119         /**
 120          * @handle: Returned handle for the object.
 121          *
 122          * Object handles are nonzero.
 123          */
 124         __u32 handle;
 125
 126         /**
 127          * @flags: Optional flags.
 128          *
 129          * Supported values:
 130          *
 131          * I915_GEM_CREATE_EXT_FLAG_NEEDS_CPU_ACCESS - Signal to the kernel that
 132          * the object will need to be accessed via the CPU.
 133          *
 134          * Only valid when placing objects in I915_MEMORY_CLASS_DEVICE, and only
 135          * strictly required on configurations where some subset of the device
 136          * memory is directly visible/mappable through the CPU (which we also
 137          * call small BAR), like on some DG2+ systems. Note that this is quite
 138          * undesirable, but due to various factors like the client CPU, BIOS etc
 139          * it's something we can expect to see in the wild. See
 140          * &__drm_i915_memory_region_info.probed_cpu_visible_size for how to
 141          * determine if this system applies.
 142          *
 143          * Note that one of the placements MUST be I915_MEMORY_CLASS_SYSTEM, to
 144          * ensure the kernel can always spill the allocation to system memory,
 145          * if the object can't be allocated in the mappable part of
 146          * I915_MEMORY_CLASS_DEVICE.
 147          *
 148          * Also note that since the kernel only supports flat-CCS on objects
 149          * that can *only* be placed in I915_MEMORY_CLASS_DEVICE, we therefore
 150          * don't support I915_GEM_CREATE_EXT_FLAG_NEEDS_CPU_ACCESS together with
 151          * flat-CCS.
 152          *
 153          * Without this hint, the kernel will assume that non-mappable
 154          * I915_MEMORY_CLASS_DEVICE is preferred for this object. Note that the
 155          * kernel can still migrate the object to the mappable part, as a last
 156          * resort, if userspace ever CPU faults this object, but this might be
 157          * expensive, and so ideally should be avoided.
 158          *
 159          * On older kernels which lack the relevant small-bar uAPI support (see
 160          * also &__drm_i915_memory_region_info.probed_cpu_visible_size),
 161          * usage of the flag will result in an error, but it should NEVER be
 162          * possible to end up with a small BAR configuration, assuming we can
 163          * also successfully load the i915 kernel module. In such cases the
 164          * entire I915_MEMORY_CLASS_DEVICE region will be CPU accessible, and as
 165          * such there are zero restrictions on where the object can be placed.
 166          */
 167 #define I915_GEM_CREATE_EXT_FLAG_NEEDS_CPU_ACCESS (1 << 0)
 168         __u32 flags;
 169
 170         /**
 171          * @extensions: The chain of extensions to apply to this object.
 172          *
 173          * This will be useful in the future when we need to support several
 174          * different extensions, and we need to apply more than one when
 175          * creating the object. See struct i915_user_extension.
 176          *
 177          * If we don't supply any extensions then we get the same old gem_create
 178          * behaviour.
 179          *
 180          * For I915_GEM_CREATE_EXT_MEMORY_REGIONS usage see
 181          * struct drm_i915_gem_create_ext_memory_regions.
 182          *
 183          * For I915_GEM_CREATE_EXT_PROTECTED_CONTENT usage see
 184          * struct drm_i915_gem_create_ext_protected_content.
 185          */
 186 #define I915_GEM_CREATE_EXT_MEMORY_REGIONS 0
 187 #define I915_GEM_CREATE_EXT_PROTECTED_CONTENT 1
 188         __u64 extensions;
 189 };