Documentation/gpu/amdgpu/driver-core.rst

   1 ============================
   2  Core Driver Infrastructure
   3 ============================
   4
   5 GPU Hardware Structure
   6 ======================
   7
   8 Each ASIC is a collection of hardware blocks.  We refer to them as
   9 "IPs" (Intellectual Property blocks).  Each IP encapsulates certain
  10 functionality. IPs are versioned and can also be mixed and matched.
  11 E.g., you might have two different ASICs that both have System DMA (SDMA) 5.x IPs.
  12 The driver is arranged by IPs.  There are driver components to handle
  13 the initialization and operation of each IP.  There are also a bunch
  14 of smaller IPs that don't really need much if any driver interaction.
  15 Those end up getting lumped into the common stuff in the soc files.
  16 The soc files (e.g., vi.c, soc15.c nv.c) contain code for aspects of
  17 the SoC itself rather than specific IPs.  E.g., things like GPU resets
  18 and register access functions are SoC dependent.
  19
  20 An APU contains more than just CPU and GPU, it also contains all of
  21 the platform stuff (audio, usb, gpio, etc.).  Also, a lot of
  22 components are shared between the CPU, platform, and the GPU (e.g.,
  23 SMU, PSP, etc.).  Specific components (CPU, GPU, etc.) usually have
  24 their interface to interact with those common components.  For things
  25 like S0i3 there is a ton of coordination required across all the
  26 components, but that is probably a bit beyond the scope of this
  27 section.
  28
  29 With respect to the GPU, we have the following major IPs:
  30
  31 GMC (Graphics Memory Controller)
  32     This was a dedicated IP on older pre-vega chips, but has since
  33     become somewhat decentralized on vega and newer chips.  They now
  34     have dedicated memory hubs for specific IPs or groups of IPs.  We
  35     still treat it as a single component in the driver however since
  36     the programming model is still pretty similar.  This is how the
  37     different IPs on the GPU get the memory (VRAM or system memory).
  38     It also provides the support for per process GPU virtual address
  39     spaces.
  40
  41 IH (Interrupt Handler)
  42     This is the interrupt controller on the GPU.  All of the IPs feed
  43     their interrupts into this IP and it aggregates them into a set of
  44     ring buffers that the driver can parse to handle interrupts from
  45     different IPs.
  46
  47 PSP (Platform Security Processor)
  48     This handles security policy for the SoC and executes trusted
  49     applications, and validates and loads firmwares for other blocks.
  50
  51 SMU (System Management Unit)
  52     This is the power management microcontroller.  It manages the entire
  53     SoC.  The driver interacts with it to control power management
  54     features like clocks, voltages, power rails, etc.
  55
  56 DCN (Display Controller Next)
  57     This is the display controller.  It handles the display hardware.
  58     It is described in more details in :ref:`Display Core <amdgpu-display-core>`.
  59
  60 SDMA (System DMA)
  61     This is a multi-purpose DMA engine.  The kernel driver uses it for
  62     various things including paging and GPU page table updates.  It's also
  63     exposed to userspace for use by user mode drivers (OpenGL, Vulkan,
  64     etc.)
  65
  66 GC (Graphics and Compute)
  67     This is the graphics and compute engine, i.e., the block that
  68     encompasses the 3D pipeline and and shader blocks.  This is by far the
  69     largest block on the GPU.  The 3D pipeline has tons of sub-blocks.  In
  70     addition to that, it also contains the CP microcontrollers (ME, PFP,
  71     CE, MEC) and the RLC microcontroller.  It's exposed to userspace for
  72     user mode drivers (OpenGL, Vulkan, OpenCL, etc.)
  73
  74 VCN (Video Core Next)
  75     This is the multi-media engine.  It handles video and image encode and
  76     decode.  It's exposed to userspace for user mode drivers (VA-API,
  77     OpenMAX, etc.)
  78
  79 Graphics and Compute Microcontrollers
  80 -------------------------------------
  81
  82 CP (Command Processor)
  83     The name for the hardware block that encompasses the front end of the
  84     GFX/Compute pipeline.  Consists mainly of a bunch of microcontrollers
  85     (PFP, ME, CE, MEC).  The firmware that runs on these microcontrollers
  86     provides the driver interface to interact with the GFX/Compute engine.
  87
  88     MEC (MicroEngine Compute)
  89         This is the microcontroller that controls the compute queues on the
  90         GFX/compute engine.
  91
  92     MES (MicroEngine Scheduler)
  93         This is a new engine for managing queues.  This is currently unused.
  94
  95 RLC (RunList Controller)
  96     This is another microcontroller in the GFX/Compute engine.  It handles
  97     power management related functionality within the GFX/Compute engine.
  98     The name is a vestige of old hardware where it was originally added
  99     and doesn't really have much relation to what the engine does now.
 100
 101 Driver Structure
 102 ================
 103
 104 In general, the driver has a list of all of the IPs on a particular
 105 SoC and for things like init/fini/suspend/resume, more or less just
 106 walks the list and handles each IP.
 107
 108 Some useful constructs:
 109
 110 KIQ (Kernel Interface Queue)
 111     This is a control queue used by the kernel driver to manage other gfx
 112     and compute queues on the GFX/compute engine.  You can use it to
 113     map/unmap additional queues, etc.
 114
 115 IB (Indirect Buffer)
 116     A command buffer for a particular engine.  Rather than writing
 117     commands directly to the queue, you can write the commands into a
 118     piece of memory and then put a pointer to the memory into the queue.
 119     The hardware will then follow the pointer and execute the commands in
 120     the memory, then returning to the rest of the commands in the ring.
 121
 122 .. _amdgpu_memory_domains:
 123
 124 Memory Domains
 125 ==============
 126
 127 .. kernel-doc:: include/uapi/drm/amdgpu_drm.h
 128    :doc: memory domains
 129
 130 Buffer Objects
 131 ==============
 132
 133 .. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_object.c
 134    :doc: amdgpu_object
 135
 136 .. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_object.c
 137    :internal:
 138
 139 PRIME Buffer Sharing
 140 ====================
 141
 142 .. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_dma_buf.c
 143    :doc: PRIME Buffer Sharing
 144
 145 .. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_dma_buf.c
 146    :internal:
 147
 148 MMU Notifier
 149 ============
 150
 151 .. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_hmm.c
 152    :doc: MMU Notifier
 153
 154 .. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_hmm.c
 155    :internal:
 156
 157 AMDGPU Virtual Memory
 158 =====================
 159
 160 .. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c
 161    :doc: GPUVM
 162
 163 .. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c
 164    :internal:
 165
 166 Interrupt Handling
 167 ==================
 168
 169 .. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_irq.c
 170    :doc: Interrupt Handling
 171
 172 .. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_irq.c
 173    :internal:
 174
 175 IP Blocks
 176 =========
 177
 178 .. kernel-doc:: drivers/gpu/drm/amd/include/amd_shared.h
 179    :doc: IP Blocks
 180
 181 .. kernel-doc:: drivers/gpu/drm/amd/include/amd_shared.h
 182    :identifiers: amd_ip_block_type amd_ip_funcs