1============================
2 Core Driver Infrastructure
3============================
4
5GPU Hardware Structure
6======================
7
8Each ASIC is a collection of hardware blocks.  We refer to them as
9"IPs" (Intellectual Property blocks).  Each IP encapsulates certain
10functionality. IPs are versioned and can also be mixed and matched.
11E.g., you might have two different ASICs that both have System DMA (SDMA) 5.x IPs.
12The driver is arranged by IPs.  There are driver components to handle
13the initialization and operation of each IP.  There are also a bunch
14of smaller IPs that don't really need much if any driver interaction.
15Those end up getting lumped into the common stuff in the soc files.
16The soc files (e.g., vi.c, soc15.c nv.c) contain code for aspects of
17the SoC itself rather than specific IPs.  E.g., things like GPU resets
18and register access functions are SoC dependent.
19
20An APU contains more than just CPU and GPU, it also contains all of
21the platform stuff (audio, usb, gpio, etc.).  Also, a lot of
22components are shared between the CPU, platform, and the GPU (e.g.,
23SMU, PSP, etc.).  Specific components (CPU, GPU, etc.) usually have
24their interface to interact with those common components.  For things
25like S0i3 there is a ton of coordination required across all the
26components, but that is probably a bit beyond the scope of this
27section.
28
29With respect to the GPU, we have the following major IPs:
30
31GMC (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
41IH (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
47PSP (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
51SMU (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
56DCN (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
60SDMA (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
66GC (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, CE,
71    MEC) and the RLC microcontroller.  It's exposed to userspace for user mode
72    drivers (OpenGL, Vulkan, OpenCL, etc.). More details in :ref:`Graphics (GFX)
73    and Compute <amdgpu-gc>`.
74
75VCN (Video Core Next)
76    This is the multi-media engine.  It handles video and image encode and
77    decode.  It's exposed to userspace for user mode drivers (VA-API,
78    OpenMAX, etc.)
79
80.. _pipes-and-queues-description:
81
82GFX, Compute, and SDMA Overall Behavior
83=======================================
84
85.. note:: For simplicity, whenever the term block is used in this section, it
86   means GFX, Compute, and SDMA.
87
88GFX, Compute and SDMA share a similar form of operation that can be abstracted
89to facilitate understanding of the behavior of these blocks. See the figure
90below illustrating the common components of these blocks:
91
92.. kernel-figure:: pipe_and_queue_abstraction.svg
93
94In the central part of this figure, you can see two hardware elements, one called
95**Pipes** and another called **Queues**; it is important to highlight that Queues
96must be associated with a Pipe and vice-versa. Every specific hardware IP may have
97a different number of Pipes and, in turn, a different number of Queues; for
98example, GFX 11 has two Pipes and two Queues per Pipe for the GFX front end.
99
100Pipe is the hardware that processes the instructions available in the Queues;
101in other words, it is a thread executing the operations inserted in the Queue.
102One crucial characteristic of Pipes is that they can only execute one Queue at
103a time; no matter if the hardware has multiple Queues in the Pipe, it only runs
104one Queue per Pipe.
105
106Pipes have the mechanics of swapping between queues at the hardware level.
107Nonetheless, they only make use of Queues that are considered mapped. Pipes can
108switch between queues based on any of the following inputs:
109
1101. Command Stream;
1112. Packet by Packet;
1123. Other hardware requests the change (e.g., MES).
113
114Queues within Pipes are defined by the Hardware Queue Descriptors (HQD).
115Associated with the HQD concept, we have the Memory Queue Descriptor (MQD),
116which is responsible for storing information about the state of each of the
117available Queues in the memory. The state of a Queue contains information such
118as the GPU virtual address of the queue itself, save areas, doorbell, etc. The
119MQD also stores the HQD registers, which are vital for activating or
120deactivating a given Queue.  The scheduling firmware (e.g., MES) is responsible
121for loading HQDs from MQDs and vice versa.
122
123The Queue-switching process can also happen with the firmware requesting the
124preemption or unmapping of a Queue. The firmware waits for the HQD_ACTIVE bit
125to change to low before saving the state into the MQD. To make a different
126Queue become active, the firmware copies the MQD state into the HQD registers
127and loads any additional state. Finally, it sets the HQD_ACTIVE bit to high to
128indicate that the queue is active.  The Pipe will then execute work from active
129Queues.
130
131Driver Structure
132================
133
134In general, the driver has a list of all of the IPs on a particular
135SoC and for things like init/fini/suspend/resume, more or less just
136walks the list and handles each IP.
137
138Some useful constructs:
139
140KIQ (Kernel Interface Queue)
141    This is a control queue used by the kernel driver to manage other gfx
142    and compute queues on the GFX/compute engine.  You can use it to
143    map/unmap additional queues, etc.  This is replaced by MES on
144    GFX 11 and newer hardware.
145
146IB (Indirect Buffer)
147    A command buffer for a particular engine.  Rather than writing
148    commands directly to the queue, you can write the commands into a
149    piece of memory and then put a pointer to the memory into the queue.
150    The hardware will then follow the pointer and execute the commands in
151    the memory, then returning to the rest of the commands in the ring.
152
153.. _amdgpu_memory_domains:
154
155Memory Domains
156==============
157
158.. kernel-doc:: include/uapi/drm/amdgpu_drm.h
159   :doc: memory domains
160
161Buffer Objects
162==============
163
164.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_object.c
165   :doc: amdgpu_object
166
167.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_object.c
168   :internal:
169
170PRIME Buffer Sharing
171====================
172
173.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_dma_buf.c
174   :doc: PRIME Buffer Sharing
175
176.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_dma_buf.c
177   :internal:
178
179MMU Notifier
180============
181
182.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_hmm.c
183   :doc: MMU Notifier
184
185.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_hmm.c
186   :internal:
187
188AMDGPU Virtual Memory
189=====================
190
191.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c
192   :doc: GPUVM
193
194.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c
195   :internal:
196
197Interrupt Handling
198==================
199
200.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_irq.c
201   :doc: Interrupt Handling
202
203.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_irq.c
204   :internal:
205
206IP Blocks
207=========
208
209.. kernel-doc:: drivers/gpu/drm/amd/include/amd_shared.h
210   :doc: IP Blocks
211
212.. kernel-doc:: drivers/gpu/drm/amd/include/amd_shared.h
213   :identifiers: amd_ip_block_type amd_ip_funcs DC_DEBUG_MASK
214