Documentation/gpu/rfc/xe.rst

   1 ==========================
   2 Xe – Merge Acceptance Plan
   3 ==========================
   4 Xe is a new driver for Intel GPUs that supports both integrated and
   5 discrete platforms starting with Tiger Lake (first Intel Xe Architecture).
   6
   7 This document aims to establish a merge plan for the Xe, by writing down clear
   8 pre-merge goals, in order to avoid unnecessary delays.
   9
  10 Xe – Overview
  11 =============
  12 The main motivation of Xe is to have a fresh base to work from that is
  13 unencumbered by older platforms, whilst also taking the opportunity to
  14 rearchitect our driver to increase sharing across the drm subsystem, both
  15 leveraging and allowing us to contribute more towards other shared components
  16 like TTM and drm/scheduler.
  17
  18 This is also an opportunity to start from the beginning with a clean uAPI that is
  19 extensible by design and already aligned with the modern userspace needs. For
  20 this reason, the memory model is solely based on GPU Virtual Address space
  21 bind/unbind (‘VM_BIND’) of GEM buffer objects (BOs) and execution only supporting
  22 explicit synchronization. With persistent mapping across the execution, the
  23 userspace does not need to provide a list of all required mappings during each
  24 submission.
  25
  26 The new driver leverages a lot from i915. As for display, the intent is to share
  27 the display code with the i915 driver so that there is maximum reuse there.
  28
  29 As for the power management area, the goal is to have a much-simplified support
  30 for the system suspend states (S-states), PCI device suspend states (D-states),
  31 GPU/Render suspend states (R-states) and frequency management. It should leverage
  32 as much as possible all the existent PCI-subsystem infrastructure (pm and
  33 runtime_pm) and underlying firmware components such PCODE and GuC for the power
  34 states and frequency decisions.
  35
  36 Repository:
  37
  38 https://gitlab.freedesktop.org/drm/xe/kernel (branch drm-xe-next)
  39
  40 Xe – Platforms
  41 ==============
  42 Currently, Xe is already functional and has experimental support for multiple
  43 platforms starting from Tiger Lake, with initial support in userspace implemented
  44 in Mesa (for Iris and Anv, our OpenGL and Vulkan drivers), as well as in NEO
  45 (for OpenCL and Level0).
  46
  47 During a transition period, platforms will be supported by both Xe and i915.
  48 However, the force_probe mechanism existent in both drivers will allow only one
  49 official and by-default probe at a given time.
  50
  51 For instance, in order to probe a DG2 which PCI ID is 0x5690 by Xe instead of
  52 i915, the following set of parameters need to be used:
  53
  54 ```
  55 i915.force_probe=!5690 xe.force_probe=5690
  56 ```
  57
  58 In both drivers, the ‘.require_force_probe’ protection forces the user to use the
  59 force_probe parameter while the driver is under development. This protection is
  60 only removed when the support for the platform and the uAPI are stable. Stability
  61 which needs to be demonstrated by CI results.
  62
  63 In order to avoid user space regressions, i915 will continue to support all the
  64 current platforms that are already out of this protection. Xe support will be
  65 forever experimental and dependent on the usage of force_probe for these
  66 platforms.
  67
  68 When the time comes for Xe, the protection will be lifted on Xe and kept in i915.
  69
  70 Xe – Pre-Merge Goals - Work-in-Progress
  71 =======================================
  72
  73 Display integration with i915
  74 -----------------------------
  75 In order to share the display code with the i915 driver so that there is maximum
  76 reuse, the i915/display/ code is built twice, once for i915.ko and then for
  77 xe.ko. Currently, the i915/display code in Xe tree is polluted with many 'ifdefs'
  78 depending on the build target. The goal is to refactor both Xe and i915/display
  79 code simultaneously in order to get a clean result before they land upstream, so
  80 that display can already be part of the initial pull request towards drm-next.
  81
  82 However, display code should not gate the acceptance of Xe in upstream. Xe
  83 patches will be refactored in a way that display code can be removed, if needed,
  84 from the first pull request of Xe towards drm-next. The expectation is that when
  85 both drivers are part of the drm-tip, the introduction of cleaner patches will be
  86 easier and speed up.
  87
  88 Xe – uAPI high level overview
  89 =============================
  90
  91 ...Warning: To be done in follow up patches after/when/where the main consensus in various items are individually reached.
  92
  93 Xe – Pre-Merge Goals - Completed
  94 ================================
  95
  96 Drm_exec
  97 --------
  98 Helper to make dma_resv locking for a big number of buffers is getting removed in
  99 the drm_exec series proposed in https://patchwork.freedesktop.org/patch/524376/
 100 If that happens, Xe needs to change and incorporate the changes in the driver.
 101 The goal is to engage with the Community to understand if the best approach is to
 102 move that to the drivers that are using it or if we should keep the helpers in
 103 place waiting for Xe to get merged.
 104
 105 This item ties into the GPUVA, VM_BIND, and even long-running compute support.
 106
 107 As a key measurable result, we need to have a community consensus documented in
 108 this document and the Xe driver prepared for the changes, if necessary.
 109
 110 Userptr integration and vm_bind
 111 -------------------------------
 112 Different drivers implement different ways of dealing with execution of userptr.
 113 With multiple drivers currently introducing support to VM_BIND, the goal is to
 114 aim for a DRM consensus on what’s the best way to have that support. To some
 115 extent this is already getting addressed itself with the GPUVA where likely the
 116 userptr will be a GPUVA with a NULL GEM call VM bind directly on the userptr.
 117 However, there are more aspects around the rules for that and the usage of
 118 mmu_notifiers, locking and other aspects.
 119
 120 This task here has the goal of introducing a documentation of the basic rules.
 121
 122 The documentation *needs* to first live in this document (API session below) and
 123 then moved to another more specific document or at Xe level or at DRM level.
 124
 125 Documentation should include:
 126
 127  * The userptr part of the VM_BIND api.
 128
 129  * Locking, including the page-faulting case.
 130
 131  * O(1) complexity under VM_BIND.
 132
 133 The document is now included in the drm documentation :doc:`here </gpu/drm-vm-bind-async>`.
 134
 135 Some parts of userptr like mmu_notifiers should become GPUVA or DRM helpers when
 136 the second driver supporting VM_BIND+userptr appears. Details to be defined when
 137 the time comes.
 138
 139 The DRM GPUVM helpers do not yet include the userptr parts, but discussions
 140 about implementing them are ongoing.
 141
 142 ASYNC VM_BIND
 143 -------------
 144 Although having a common DRM level IOCTL for VM_BIND is not a requirement to get
 145 Xe merged, it is mandatory to have a consensus with other drivers and Mesa.
 146 It needs to be clear how to handle async VM_BIND and interactions with userspace
 147 memory fences. Ideally with helper support so people don't get it wrong in all
 148 possible ways.
 149
 150 As a key measurable result, the benefits of ASYNC VM_BIND and a discussion of
 151 various flavors, error handling and sample API suggestions are documented in
 152 :doc:`The ASYNC VM_BIND document </gpu/drm-vm-bind-async>`.
 153
 154 Drm_scheduler
 155 -------------
 156 Xe primarily uses Firmware based scheduling (GuC FW). However, it will use
 157 drm_scheduler as the scheduler ‘frontend’ for userspace submission in order to
 158 resolve syncobj and dma-buf implicit sync dependencies. However, drm_scheduler is
 159 not yet prepared to handle the 1-to-1 relationship between drm_gpu_scheduler and
 160 drm_sched_entity.
 161
 162 Deeper changes to drm_scheduler should *not* be required to get Xe accepted, but
 163 some consensus needs to be reached between Xe and other community drivers that
 164 could also benefit from this work, for coupling FW based/assisted submission such
 165 as the ARM’s new Mali GPU driver, and others.
 166
 167 As a key measurable result, the patch series introducing Xe itself shall not
 168 depend on any other patch touching drm_scheduler itself that was not yet merged
 169 through drm-misc. This, by itself, already includes the reach of an agreement for
 170 uniform 1 to 1 relationship implementation / usage across drivers.
 171
 172 Long running compute: minimal data structure/scaffolding
 173 --------------------------------------------------------
 174 The generic scheduler code needs to include the handling of endless compute
 175 contexts, with the minimal scaffolding for preempt-ctx fences (probably on the
 176 drm_sched_entity) and making sure drm_scheduler can cope with the lack of job
 177 completion fence.
 178
 179 The goal is to achieve a consensus ahead of Xe initial pull-request, ideally with
 180 this minimal drm/scheduler work, if needed, merged to drm-misc in a way that any
 181 drm driver, including Xe, could re-use and add their own individual needs on top
 182 in a next stage. However, this should not block the initial merge.
 183
 184 Dev_coredump
 185 ------------
 186
 187 Xe needs to align with other drivers on the way that the error states are
 188 dumped, avoiding a Xe only error_state solution. The goal is to use devcoredump
 189 infrastructure to report error states, since it produces a standardized way
 190 by exposing a virtual and temporary /sys/class/devcoredump device.
 191
 192 As the key measurable result, Xe driver needs to provide GPU snapshots captured
 193 at hang time through devcoredump, but without depending on any core modification
 194 of devcoredump infrastructure itself.
 195
 196 Later, when we are in-tree, the goal is to collaborate with devcoredump
 197 infrastructure with overall possible improvements, like multiple file support
 198 for better organization of the dumps, snapshot support, dmesg extra print,
 199 and whatever may make sense and help the overall infrastructure.
 200
 201 DRM_VM_BIND
 202 -----------
 203 Nouveau, and Xe are all implementing ‘VM_BIND’ and new ‘Exec’ uAPIs in order to
 204 fulfill the needs of the modern uAPI. Xe merge should *not* be blocked on the
 205 development of a common new drm_infrastructure. However, the Xe team needs to
 206 engage with the community to explore the options of a common API.
 207
 208 As a key measurable result, the DRM_VM_BIND needs to be documented in this file
 209 below, or this entire block deleted if the consensus is for independent drivers
 210 vm_bind ioctls.
 211
 212 Although having a common DRM level IOCTL for VM_BIND is not a requirement to get
 213 Xe merged, it is mandatory to enforce the overall locking scheme for all major
 214 structs and list (so vm and vma). So, a consensus is needed, and possibly some
 215 common helpers. If helpers are needed, they should be also documented in this
 216 document.
 217
 218 GPU VA
 219 ------
 220 Two main goals of Xe are meeting together here:
 221
 222 1) Have an uAPI that aligns with modern UMD needs.
 223
 224 2) Early upstream engagement.
 225
 226 RedHat engineers working on Nouveau proposed a new DRM feature to handle keeping
 227 track of GPU virtual address mappings. This is still not merged upstream, but
 228 this aligns very well with our goals and with our VM_BIND. The engagement with
 229 upstream and the port of Xe towards GPUVA is already ongoing.
 230
 231 As a key measurable result, Xe needs to be aligned with the GPU VA and working in
 232 our tree. Missing Nouveau patches should *not* block Xe and any needed GPUVA
 233 related patch should be independent and present on dri-devel or acked by
 234 maintainers to go along with the first Xe pull request towards drm-next.