1 .. SPDX-License-Identifier: (GPL-2.0+ OR MIT)
2
3 ====================
4 Asynchronous VM_BIND
5 ====================
6
7 Nomenclature:
8 =============
9
10 * ``VRAM``: On-device memory. Sometimes referr
11
12 * ``gpu_vm``: A virtual GPU address space. Typ
13 can be shared by multiple processes.
14
15 * ``VM_BIND``: An operation or a list of opera
16 an IOCTL. The operations include mapping and
17 VRAM memory.
18
19 * ``syncobj``: A container that abstracts sync
20 synchronization objects can be either generi
21 driver specific. A syncobj typically indicat
22 underlying synchronization object.
23
24 * ``in-syncobj``: Argument to a VM_BIND IOCTL,
25 for these before starting.
26
27 * ``out-syncobj``: Argument to a VM_BIND_IOCTL
28 signals these when the bind operation is com
29
30 * ``dma-fence``: A cross-driver synchronizatio
31 understanding of dma-fences is required to d
32 document. Please refer to the ``DMA Fences``
33 :doc:`dma-buf doc </driver-api/dma-buf>`.
34
35 * ``memory fence``: A synchronization object,
36 A memory fence uses the value of a specified
37 signaled status. A memory fence can be await
38 the GPU and CPU. Memory fences are sometimes
39 user-fences, userspace-fences or gpu futexes
40 the dma-fence rule of signaling within a "re
41 The kernel should thus avoid waiting for mem
42
43 * ``long-running workload``: A workload that m
44 current stipulated dma-fence maximum signal
45 which therefore needs to set the gpu_vm or t
46 a certain mode that disallows completion dma
47
48 * ``exec function``: An exec function is a fun
49 affected gpu_vmas, submits a GPU command bat
50 dma_fence representing the GPU command's act
51 dma_resvs. For completeness, although not co
52 it's worth mentioning that an exec function
53 revalidation worker that is used by some dri
54 long-running mode.
55
56 * ``bind context``: A context identifier used
57 operation. VM_BIND operations that use the s
58 assumed, where it matters, to complete in or
59 assumptions can be made for VM_BIND operatio
60
61 * ``UMD``: User-mode driver.
62
63 * ``KMD``: Kernel-mode driver.
64
65
66 Synchronous / Asynchronous VM_BIND operation
67 ============================================
68
69 Synchronous VM_BIND
70 ___________________
71 With Synchronous VM_BIND, the VM_BIND operatio
72 IOCTL returns. A synchronous VM_BIND takes nei
73 out-fences. Synchronous VM_BIND may block and
74 for example swap-in or clearing, or even previ
75
76 Asynchronous VM_BIND
77 ____________________
78 Asynchronous VM_BIND accepts both in-syncobjs
79 IOCTL may return immediately, the VM_BIND oper
80 before modifying the GPU page-tables, and sign
81 the modification is done in the sense that the
82 awaits for the out-syncobjs will see the chang
83 synchronously.
84 In low-memory situations the implementation ma
85 VM_BIND synchronously, because there might not
86 immediately available for preparing the asynch
87
88 If the VM_BIND IOCTL takes a list or an array
89 the in-syncobjs needs to signal before the fir
90 execute, and the out-syncobjs signal after the
91 completes. Operations in the operation list ca
92 matters, to complete in order.
93
94 Since asynchronous VM_BIND operations may use
95 out-syncobjs and internally in KMD to signal b
96 memory fences given as VM_BIND in-fences need
97 synchronously before the VM_BIND ioctl returns
98 required to signal in a reasonable amount of t
99 to depend on memory fences that don't have suc
100
101 The purpose of an Asynchronous VM_BIND operati
102 drivers to be able to pipeline interleaved gpu
103 exec functions. For long-running workloads, su
104 operation is not allowed and any in-fences nee
105 synchronously. The reason for this is twofold.
106 fences gated by a long-running workload and us
107 VM_BIND operation will need to be awaited sync
108 above). Second, any dma-fences used as in-sync
109 operations for long-running workloads will not
110 anyway since long-running workloads don't allo
111 out-syncobjs, so while theoretically possible
112 questionable and should be rejected until ther
113 Note that this is not a limitation imposed by
114 rather a limitation imposed to keep KMD implem
115 not affect using dma-fences as dependencies fo
116 workload itself, which is allowed by dma-fence
117 the VM_BIND operation only.
118
119 An asynchronous VM_BIND operation may take sub
120 complete and signal the out_fence. In particul
121 deeply pipelined behind other VM_BIND operatio
122 submitted using exec functions. In that case,
123 subsequent VM_BIND operation to be queued behi
124 there are no explicit dependencies. In order t
125 VM_BIND implementation may allow for VM_BIND c
126 created. For each context, VM_BIND operations
127 complete in the order they were submitted, but
128 for VM_BIND operations executing on separate V
129 KMD will attempt to execute such VM_BIND opera
130 leaving no guarantee that they will actually b
131 parallel. There may be internal implicit depen
132 about, for example page-table structure change
133 to avoid such internal dependencies is to have
134 contexts use separate regions of a VM.
135
136 Also for VM_BINDS for long-running gpu_vms the
137 select memory fences as out-fences since that
138 the kernel mode driver to inject other operati
139 unbind operations. Like for example inserting
140 buffers. The workload execution can then easil
141 the bind completion using the memory out-fence
142 for a GPU semaphore embedded by UMD in the wor
143
144 There is no difference in the operations suppo
145 multi-operation support between asynchronous V
146
147 Multi-operation VM_BIND IOCTL error handling a
148 ==============================================
149
150 The VM_BIND operations of the IOCTL may error
151 example due to lack of resources to complete a
152 waits.
153 In these situations UMD should preferably rest
154 taking suitable action.
155 If UMD has over-committed a memory resource, a
156 returned, and UMD may then unbind resources th
157 moment and rerun the IOCTL. On -EINTR, UMD sho
158 IOCTL and on -ENOMEM user-space may either att
159 system memory resources or fail. In case of UM
160 bind operation, due to an error return, no add
161 to clean up the failed operation, and the VM i
162 as it was before the failing IOCTL.
163 Unbind operations are guaranteed not to return
164 resource constraints, but may return errors du
165 invalid arguments or the gpu_vm being banned.
166 In the case an unexpected error happens during
167 process, the gpu_vm will be banned, and attemp
168 will return -ENOENT.
169
170 Example: The Xe VM_BIND uAPI
171 ============================
172
173 Starting with the VM_BIND operation struct, th
174 zero, one or many such operations. A zero numb
175 synchronization part of the IOCTL is carried o
176 VM_BIND updates the syncobjects, whereas a syn
177 implicit dependencies to be fulfilled.
178
179 .. code-block:: c
180
181 struct drm_xe_vm_bind_op {
182 /**
183 * @obj: GEM object to operate on, MBZ
184 */
185 __u32 obj;
186
187 /** @pad: MBZ */
188 __u32 pad;
189
190 union {
191 /**
192 * @obj_offset: Offset into th
193 */
194 __u64 obj_offset;
195
196 /** @userptr: user virtual add
197 __u64 userptr;
198 };
199
200 /**
201 * @range: Number of bytes from the ob
202 */
203 __u64 range;
204
205 /** @addr: Address to operate on, MBZ
206 __u64 addr;
207
208 /**
209 * @tile_mask: Mask for which tiles to
210 * only applies to creating new VMAs
211 */
212 __u64 tile_mask;
213
214 /* Map (parts of) an object into the GP
215 #define XE_VM_BIND_OP_MAP 0x0
216 /* Unmap a GPU virtual address range *
217 #define XE_VM_BIND_OP_UNMAP 0x1
218 /*
219 * Map a CPU virtual address range int
220 * address range.
221 */
222 #define XE_VM_BIND_OP_MAP_USERPTR 0x2
223 /* Unmap a gem object from the VM. */
224 #define XE_VM_BIND_OP_UNMAP_ALL 0x3
225 /*
226 * Make the backing memory of an addre
227 * possible. Note that this doesn't pi
228 */
229 #define XE_VM_BIND_OP_PREFETCH 0x4
230
231 /* Make the GPU map readonly. */
232 #define XE_VM_BIND_FLAG_READONLY (0x1 <
233 /*
234 * Valid on a faulting VM only, do the
235 * than deferring the MAP to the page
236 */
237 #define XE_VM_BIND_FLAG_IMMEDIATE (0x1 <
238 /*
239 * When the NULL flag is set, the page
240 * bit which indicates writes are drop
241 * the future, the NULL flags will onl
242 * operations, the BO handle MBZ, and
243 * intended to implement VK sparse bin
244 */
245 #define XE_VM_BIND_FLAG_NULL (0x1 <
246 /** @op: Operation to perform (lower 1
247 __u32 op;
248
249 /** @mem_region: Memory region to pref
250 __u32 region;
251
252 /** @reserved: Reserved */
253 __u64 reserved[2];
254 };
255
256
257 The VM_BIND IOCTL argument itself, looks like
258 synchronous VM_BIND, the num_syncs and syncs f
259 the ``exec_queue_id`` field is the VM_BIND con
260 that is used to facilitate out-of-order VM_BIN
261
262 .. code-block:: c
263
264 struct drm_xe_vm_bind {
265 /** @extensions: Pointer to the first
266 __u64 extensions;
267
268 /** @vm_id: The ID of the VM to bind t
269 __u32 vm_id;
270
271 /**
272 * @exec_queue_id: exec_queue_id, must
273 * and exec queue must have same vm_id
274 * is used.
275 */
276 __u32 exec_queue_id;
277
278 /** @num_binds: number of binds in thi
279 __u32 num_binds;
280
281 /* If set, perform an async VM_BIND, i
282 #define XE_VM_BIND_IOCTL_FLAG_ASYNC (0x1 <
283
284 /** @flag: Flags controlling all opera
285 __u32 flags;
286
287 union {
288 /** @bind: used if num_binds =
289 struct drm_xe_vm_bind_op bind;
290
291 /**
292 * @vector_of_binds: userptr t
293 * drm_xe_vm_bind_op if num_bi
294 */
295 __u64 vector_of_binds;
296 };
297
298 /** @num_syncs: amount of syncs to wai
299 __u32 num_syncs;
300
301 /** @pad2: MBZ */
302 __u32 pad2;
303
304 /** @syncs: pointer to struct drm_xe_s
305 __u64 syncs;
306
307 /** @reserved: Reserved */
308 __u64 reserved[2];
309 };
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.