tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
1/* SPDX-License-Identifier: MIT */
2/* Copyright (C) 2023 Collabora ltd. */
3#ifndef _PANTHOR_DRM_H_
4#define _PANTHOR_DRM_H_
5
6#include "drm.h"
7
8#if defined(__cplusplus)
9extern "C" {
10#endif
11
12/**
13 * DOC: Introduction
14 *
15 * This documentation describes the Panthor IOCTLs.
16 *
17 * Just a few generic rules about the data passed to the Panthor IOCTLs:
18 *
19 * - Structures must be aligned on 64-bit/8-byte. If the object is not
20 * naturally aligned, a padding field must be added.
21 * - Fields must be explicitly aligned to their natural type alignment with
22 * pad[0..N] fields.
23 * - All padding fields will be checked by the driver to make sure they are
24 * zeroed.
25 * - Flags can be added, but not removed/replaced.
26 * - New fields can be added to the main structures (the structures
27 * directly passed to the ioctl). Those fields can be added at the end of
28 * the structure, or replace existing padding fields. Any new field being
29 * added must preserve the behavior that existed before those fields were
30 * added when a value of zero is passed.
31 * - New fields can be added to indirect objects (objects pointed by the
32 * main structure), iff those objects are passed a size to reflect the
33 * size known by the userspace driver (see drm_panthor_obj_array::stride
34 * or drm_panthor_dev_query::size).
35 * - If the kernel driver is too old to know some fields, those will be
36 * ignored if zero, and otherwise rejected (and so will be zero on output).
37 * - If userspace is too old to know some fields, those will be zeroed
38 * (input) before the structure is parsed by the kernel driver.
39 * - Each new flag/field addition must come with a driver version update so
40 * the userspace driver doesn't have to trial and error to know which
41 * flags are supported.
42 * - Structures should not contain unions, as this would defeat the
43 * extensibility of such structures.
44 * - IOCTLs can't be removed or replaced. New IOCTL IDs should be placed
45 * at the end of the drm_panthor_ioctl_id enum.
46 */
47
48/**
49 * DOC: MMIO regions exposed to userspace.
50 *
51 * .. c:macro:: DRM_PANTHOR_USER_MMIO_OFFSET
52 *
53 * File offset for all MMIO regions being exposed to userspace. Don't use
54 * this value directly, use DRM_PANTHOR_USER_<name>_OFFSET values instead.
55 * pgoffset passed to mmap2() is an unsigned long, which forces us to use a
56 * different offset on 32-bit and 64-bit systems.
57 *
58 * .. c:macro:: DRM_PANTHOR_USER_FLUSH_ID_MMIO_OFFSET
59 *
60 * File offset for the LATEST_FLUSH_ID register. The Userspace driver controls
61 * GPU cache flushing through CS instructions, but the flush reduction
62 * mechanism requires a flush_id. This flush_id could be queried with an
63 * ioctl, but Arm provides a well-isolated register page containing only this
64 * read-only register, so let's expose this page through a static mmap offset
65 * and allow direct mapping of this MMIO region so we can avoid the
66 * user <-> kernel round-trip.
67 */
68#define DRM_PANTHOR_USER_MMIO_OFFSET_32BIT (1ull << 43)
69#define DRM_PANTHOR_USER_MMIO_OFFSET_64BIT (1ull << 56)
70#define DRM_PANTHOR_USER_MMIO_OFFSET (sizeof(unsigned long) < 8 ? \
71 DRM_PANTHOR_USER_MMIO_OFFSET_32BIT : \
72 DRM_PANTHOR_USER_MMIO_OFFSET_64BIT)
73#define DRM_PANTHOR_USER_FLUSH_ID_MMIO_OFFSET (DRM_PANTHOR_USER_MMIO_OFFSET | 0)
74
75/**
76 * DOC: IOCTL IDs
77 *
78 * enum drm_panthor_ioctl_id - IOCTL IDs
79 *
80 * Place new ioctls at the end, don't re-order, don't replace or remove entries.
81 *
82 * These IDs are not meant to be used directly. Use the DRM_IOCTL_PANTHOR_xxx
83 * definitions instead.
84 */
85enum drm_panthor_ioctl_id {
86 /** @DRM_PANTHOR_DEV_QUERY: Query device information. */
87 DRM_PANTHOR_DEV_QUERY = 0,
88
89 /** @DRM_PANTHOR_VM_CREATE: Create a VM. */
90 DRM_PANTHOR_VM_CREATE,
91
92 /** @DRM_PANTHOR_VM_DESTROY: Destroy a VM. */
93 DRM_PANTHOR_VM_DESTROY,
94
95 /** @DRM_PANTHOR_VM_BIND: Bind/unbind memory to a VM. */
96 DRM_PANTHOR_VM_BIND,
97
98 /** @DRM_PANTHOR_VM_GET_STATE: Get VM state. */
99 DRM_PANTHOR_VM_GET_STATE,
100
101 /** @DRM_PANTHOR_BO_CREATE: Create a buffer object. */
102 DRM_PANTHOR_BO_CREATE,
103
104 /**
105 * @DRM_PANTHOR_BO_MMAP_OFFSET: Get the file offset to pass to
106 * mmap to map a GEM object.
107 */
108 DRM_PANTHOR_BO_MMAP_OFFSET,
109
110 /** @DRM_PANTHOR_GROUP_CREATE: Create a scheduling group. */
111 DRM_PANTHOR_GROUP_CREATE,
112
113 /** @DRM_PANTHOR_GROUP_DESTROY: Destroy a scheduling group. */
114 DRM_PANTHOR_GROUP_DESTROY,
115
116 /**
117 * @DRM_PANTHOR_GROUP_SUBMIT: Submit jobs to queues belonging
118 * to a specific scheduling group.
119 */
120 DRM_PANTHOR_GROUP_SUBMIT,
121
122 /** @DRM_PANTHOR_GROUP_GET_STATE: Get the state of a scheduling group. */
123 DRM_PANTHOR_GROUP_GET_STATE,
124
125 /** @DRM_PANTHOR_TILER_HEAP_CREATE: Create a tiler heap. */
126 DRM_PANTHOR_TILER_HEAP_CREATE,
127
128 /** @DRM_PANTHOR_TILER_HEAP_DESTROY: Destroy a tiler heap. */
129 DRM_PANTHOR_TILER_HEAP_DESTROY,
130};
131
132/**
133 * DRM_IOCTL_PANTHOR() - Build a Panthor IOCTL number
134 * @__access: Access type. Must be R, W or RW.
135 * @__id: One of the DRM_PANTHOR_xxx id.
136 * @__type: Suffix of the type being passed to the IOCTL.
137 *
138 * Don't use this macro directly, use the DRM_IOCTL_PANTHOR_xxx
139 * values instead.
140 *
141 * Return: An IOCTL number to be passed to ioctl() from userspace.
142 */
143#define DRM_IOCTL_PANTHOR(__access, __id, __type) \
144 DRM_IO ## __access(DRM_COMMAND_BASE + DRM_PANTHOR_ ## __id, \
145 struct drm_panthor_ ## __type)
146
147#define DRM_IOCTL_PANTHOR_DEV_QUERY \
148 DRM_IOCTL_PANTHOR(WR, DEV_QUERY, dev_query)
149#define DRM_IOCTL_PANTHOR_VM_CREATE \
150 DRM_IOCTL_PANTHOR(WR, VM_CREATE, vm_create)
151#define DRM_IOCTL_PANTHOR_VM_DESTROY \
152 DRM_IOCTL_PANTHOR(WR, VM_DESTROY, vm_destroy)
153#define DRM_IOCTL_PANTHOR_VM_BIND \
154 DRM_IOCTL_PANTHOR(WR, VM_BIND, vm_bind)
155#define DRM_IOCTL_PANTHOR_VM_GET_STATE \
156 DRM_IOCTL_PANTHOR(WR, VM_GET_STATE, vm_get_state)
157#define DRM_IOCTL_PANTHOR_BO_CREATE \
158 DRM_IOCTL_PANTHOR(WR, BO_CREATE, bo_create)
159#define DRM_IOCTL_PANTHOR_BO_MMAP_OFFSET \
160 DRM_IOCTL_PANTHOR(WR, BO_MMAP_OFFSET, bo_mmap_offset)
161#define DRM_IOCTL_PANTHOR_GROUP_CREATE \
162 DRM_IOCTL_PANTHOR(WR, GROUP_CREATE, group_create)
163#define DRM_IOCTL_PANTHOR_GROUP_DESTROY \
164 DRM_IOCTL_PANTHOR(WR, GROUP_DESTROY, group_destroy)
165#define DRM_IOCTL_PANTHOR_GROUP_SUBMIT \
166 DRM_IOCTL_PANTHOR(WR, GROUP_SUBMIT, group_submit)
167#define DRM_IOCTL_PANTHOR_GROUP_GET_STATE \
168 DRM_IOCTL_PANTHOR(WR, GROUP_GET_STATE, group_get_state)
169#define DRM_IOCTL_PANTHOR_TILER_HEAP_CREATE \
170 DRM_IOCTL_PANTHOR(WR, TILER_HEAP_CREATE, tiler_heap_create)
171#define DRM_IOCTL_PANTHOR_TILER_HEAP_DESTROY \
172 DRM_IOCTL_PANTHOR(WR, TILER_HEAP_DESTROY, tiler_heap_destroy)
173
174/**
175 * DOC: IOCTL arguments
176 */
177
178/**
179 * struct drm_panthor_obj_array - Object array.
180 *
181 * This object is used to pass an array of objects whose size is subject to changes in
182 * future versions of the driver. In order to support this mutability, we pass a stride
183 * describing the size of the object as known by userspace.
184 *
185 * You shouldn't fill drm_panthor_obj_array fields directly. You should instead use
186 * the DRM_PANTHOR_OBJ_ARRAY() macro that takes care of initializing the stride to
187 * the object size.
188 */
189struct drm_panthor_obj_array {
190 /** @stride: Stride of object struct. Used for versioning. */
191 __u32 stride;
192
193 /** @count: Number of objects in the array. */
194 __u32 count;
195
196 /** @array: User pointer to an array of objects. */
197 __u64 array;
198};
199
200/**
201 * DRM_PANTHOR_OBJ_ARRAY() - Initialize a drm_panthor_obj_array field.
202 * @cnt: Number of elements in the array.
203 * @ptr: Pointer to the array to pass to the kernel.
204 *
205 * Macro initializing a drm_panthor_obj_array based on the object size as known
206 * by userspace.
207 */
208#define DRM_PANTHOR_OBJ_ARRAY(cnt, ptr) \
209 { .stride = sizeof((ptr)[0]), .count = (cnt), .array = (__u64)(uintptr_t)(ptr) }
210
211/**
212 * enum drm_panthor_sync_op_flags - Synchronization operation flags.
213 */
214enum drm_panthor_sync_op_flags {
215 /** @DRM_PANTHOR_SYNC_OP_HANDLE_TYPE_MASK: Synchronization handle type mask. */
216 DRM_PANTHOR_SYNC_OP_HANDLE_TYPE_MASK = 0xff,
217
218 /** @DRM_PANTHOR_SYNC_OP_HANDLE_TYPE_SYNCOBJ: Synchronization object type. */
219 DRM_PANTHOR_SYNC_OP_HANDLE_TYPE_SYNCOBJ = 0,
220
221 /**
222 * @DRM_PANTHOR_SYNC_OP_HANDLE_TYPE_TIMELINE_SYNCOBJ: Timeline synchronization
223 * object type.
224 */
225 DRM_PANTHOR_SYNC_OP_HANDLE_TYPE_TIMELINE_SYNCOBJ = 1,
226
227 /** @DRM_PANTHOR_SYNC_OP_WAIT: Wait operation. */
228 DRM_PANTHOR_SYNC_OP_WAIT = 0 << 31,
229
230 /** @DRM_PANTHOR_SYNC_OP_SIGNAL: Signal operation. */
231 DRM_PANTHOR_SYNC_OP_SIGNAL = (int)(1u << 31),
232};
233
234/**
235 * struct drm_panthor_sync_op - Synchronization operation.
236 */
237struct drm_panthor_sync_op {
238 /** @flags: Synchronization operation flags. Combination of DRM_PANTHOR_SYNC_OP values. */
239 __u32 flags;
240
241 /** @handle: Sync handle. */
242 __u32 handle;
243
244 /**
245 * @timeline_value: MBZ if
246 * (flags & DRM_PANTHOR_SYNC_OP_HANDLE_TYPE_MASK) !=
247 * DRM_PANTHOR_SYNC_OP_HANDLE_TYPE_TIMELINE_SYNCOBJ.
248 */
249 __u64 timeline_value;
250};
251
252/**
253 * enum drm_panthor_dev_query_type - Query type
254 *
255 * Place new types at the end, don't re-order, don't remove or replace.
256 */
257enum drm_panthor_dev_query_type {
258 /** @DRM_PANTHOR_DEV_QUERY_GPU_INFO: Query GPU information. */
259 DRM_PANTHOR_DEV_QUERY_GPU_INFO = 0,
260
261 /** @DRM_PANTHOR_DEV_QUERY_CSIF_INFO: Query command-stream interface information. */
262 DRM_PANTHOR_DEV_QUERY_CSIF_INFO,
263
264 /** @DRM_PANTHOR_DEV_QUERY_TIMESTAMP_INFO: Query timestamp information. */
265 DRM_PANTHOR_DEV_QUERY_TIMESTAMP_INFO,
266
267 /**
268 * @DRM_PANTHOR_DEV_QUERY_GROUP_PRIORITIES_INFO: Query allowed group priorities information.
269 */
270 DRM_PANTHOR_DEV_QUERY_GROUP_PRIORITIES_INFO,
271};
272
273/**
274 * struct drm_panthor_gpu_info - GPU information
275 *
276 * Structure grouping all queryable information relating to the GPU.
277 */
278struct drm_panthor_gpu_info {
279 /** @gpu_id : GPU ID. */
280 __u32 gpu_id;
281#define DRM_PANTHOR_ARCH_MAJOR(x) ((x) >> 28)
282#define DRM_PANTHOR_ARCH_MINOR(x) (((x) >> 24) & 0xf)
283#define DRM_PANTHOR_ARCH_REV(x) (((x) >> 20) & 0xf)
284#define DRM_PANTHOR_PRODUCT_MAJOR(x) (((x) >> 16) & 0xf)
285#define DRM_PANTHOR_VERSION_MAJOR(x) (((x) >> 12) & 0xf)
286#define DRM_PANTHOR_VERSION_MINOR(x) (((x) >> 4) & 0xff)
287#define DRM_PANTHOR_VERSION_STATUS(x) ((x) & 0xf)
288
289 /** @gpu_rev: GPU revision. */
290 __u32 gpu_rev;
291
292 /** @csf_id: Command stream frontend ID. */
293 __u32 csf_id;
294#define DRM_PANTHOR_CSHW_MAJOR(x) (((x) >> 26) & 0x3f)
295#define DRM_PANTHOR_CSHW_MINOR(x) (((x) >> 20) & 0x3f)
296#define DRM_PANTHOR_CSHW_REV(x) (((x) >> 16) & 0xf)
297#define DRM_PANTHOR_MCU_MAJOR(x) (((x) >> 10) & 0x3f)
298#define DRM_PANTHOR_MCU_MINOR(x) (((x) >> 4) & 0x3f)
299#define DRM_PANTHOR_MCU_REV(x) ((x) & 0xf)
300
301 /** @l2_features: L2-cache features. */
302 __u32 l2_features;
303
304 /** @tiler_features: Tiler features. */
305 __u32 tiler_features;
306
307 /** @mem_features: Memory features. */
308 __u32 mem_features;
309
310 /** @mmu_features: MMU features. */
311 __u32 mmu_features;
312#define DRM_PANTHOR_MMU_VA_BITS(x) ((x) & 0xff)
313
314 /** @thread_features: Thread features. */
315 __u32 thread_features;
316
317 /** @max_threads: Maximum number of threads. */
318 __u32 max_threads;
319
320 /** @thread_max_workgroup_size: Maximum workgroup size. */
321 __u32 thread_max_workgroup_size;
322
323 /**
324 * @thread_max_barrier_size: Maximum number of threads that can wait
325 * simultaneously on a barrier.
326 */
327 __u32 thread_max_barrier_size;
328
329 /** @coherency_features: Coherency features. */
330 __u32 coherency_features;
331
332 /** @texture_features: Texture features. */
333 __u32 texture_features[4];
334
335 /** @as_present: Bitmask encoding the number of address-space exposed by the MMU. */
336 __u32 as_present;
337
338 /** @shader_present: Bitmask encoding the shader cores exposed by the GPU. */
339 __u64 shader_present;
340
341 /** @l2_present: Bitmask encoding the L2 caches exposed by the GPU. */
342 __u64 l2_present;
343
344 /** @tiler_present: Bitmask encoding the tiler units exposed by the GPU. */
345 __u64 tiler_present;
346
347 /** @core_features: Used to discriminate core variants when they exist. */
348 __u32 core_features;
349
350 /** @pad: MBZ. */
351 __u32 pad;
352};
353
354/**
355 * struct drm_panthor_csif_info - Command stream interface information
356 *
357 * Structure grouping all queryable information relating to the command stream interface.
358 */
359struct drm_panthor_csif_info {
360 /** @csg_slot_count: Number of command stream group slots exposed by the firmware. */
361 __u32 csg_slot_count;
362
363 /** @cs_slot_count: Number of command stream slots per group. */
364 __u32 cs_slot_count;
365
366 /** @cs_reg_count: Number of command stream registers. */
367 __u32 cs_reg_count;
368
369 /** @scoreboard_slot_count: Number of scoreboard slots. */
370 __u32 scoreboard_slot_count;
371
372 /**
373 * @unpreserved_cs_reg_count: Number of command stream registers reserved by
374 * the kernel driver to call a userspace command stream.
375 *
376 * All registers can be used by a userspace command stream, but the
377 * [cs_slot_count - unpreserved_cs_reg_count .. cs_slot_count] registers are
378 * used by the kernel when DRM_PANTHOR_IOCTL_GROUP_SUBMIT is called.
379 */
380 __u32 unpreserved_cs_reg_count;
381
382 /**
383 * @pad: Padding field, set to zero.
384 */
385 __u32 pad;
386};
387
388/**
389 * struct drm_panthor_timestamp_info - Timestamp information
390 *
391 * Structure grouping all queryable information relating to the GPU timestamp.
392 */
393struct drm_panthor_timestamp_info {
394 /**
395 * @timestamp_frequency: The frequency of the timestamp timer or 0 if
396 * unknown.
397 */
398 __u64 timestamp_frequency;
399
400 /** @current_timestamp: The current timestamp. */
401 __u64 current_timestamp;
402
403 /** @timestamp_offset: The offset of the timestamp timer. */
404 __u64 timestamp_offset;
405};
406
407/**
408 * struct drm_panthor_group_priorities_info - Group priorities information
409 *
410 * Structure grouping all queryable information relating to the allowed group priorities.
411 */
412struct drm_panthor_group_priorities_info {
413 /**
414 * @allowed_mask: Bitmask of the allowed group priorities.
415 *
416 * Each bit represents a variant of the enum drm_panthor_group_priority.
417 */
418 __u8 allowed_mask;
419
420 /** @pad: Padding fields, MBZ. */
421 __u8 pad[3];
422};
423
424/**
425 * struct drm_panthor_dev_query - Arguments passed to DRM_PANTHOR_IOCTL_DEV_QUERY
426 */
427struct drm_panthor_dev_query {
428 /** @type: the query type (see drm_panthor_dev_query_type). */
429 __u32 type;
430
431 /**
432 * @size: size of the type being queried.
433 *
434 * If pointer is NULL, size is updated by the driver to provide the
435 * output structure size. If pointer is not NULL, the driver will
436 * only copy min(size, actual_structure_size) bytes to the pointer,
437 * and update the size accordingly. This allows us to extend query
438 * types without breaking userspace.
439 */
440 __u32 size;
441
442 /**
443 * @pointer: user pointer to a query type struct.
444 *
445 * Pointer can be NULL, in which case, nothing is copied, but the
446 * actual structure size is returned. If not NULL, it must point to
447 * a location that's large enough to hold size bytes.
448 */
449 __u64 pointer;
450};
451
452/**
453 * struct drm_panthor_vm_create - Arguments passed to DRM_PANTHOR_IOCTL_VM_CREATE
454 */
455struct drm_panthor_vm_create {
456 /** @flags: VM flags, MBZ. */
457 __u32 flags;
458
459 /** @id: Returned VM ID. */
460 __u32 id;
461
462 /**
463 * @user_va_range: Size of the VA space reserved for user objects.
464 *
465 * The kernel will pick the remaining space to map kernel-only objects to the
466 * VM (heap chunks, heap context, ring buffers, kernel synchronization objects,
467 * ...). If the space left for kernel objects is too small, kernel object
468 * allocation will fail further down the road. One can use
469 * drm_panthor_gpu_info::mmu_features to extract the total virtual address
470 * range, and chose a user_va_range that leaves some space to the kernel.
471 *
472 * If user_va_range is zero, the kernel will pick a sensible value based on
473 * TASK_SIZE and the virtual range supported by the GPU MMU (the kernel/user
474 * split should leave enough VA space for userspace processes to support SVM,
475 * while still allowing the kernel to map some amount of kernel objects in
476 * the kernel VA range). The value chosen by the driver will be returned in
477 * @user_va_range.
478 *
479 * User VA space always starts at 0x0, kernel VA space is always placed after
480 * the user VA range.
481 */
482 __u64 user_va_range;
483};
484
485/**
486 * struct drm_panthor_vm_destroy - Arguments passed to DRM_PANTHOR_IOCTL_VM_DESTROY
487 */
488struct drm_panthor_vm_destroy {
489 /** @id: ID of the VM to destroy. */
490 __u32 id;
491
492 /** @pad: MBZ. */
493 __u32 pad;
494};
495
496/**
497 * enum drm_panthor_vm_bind_op_flags - VM bind operation flags
498 */
499enum drm_panthor_vm_bind_op_flags {
500 /**
501 * @DRM_PANTHOR_VM_BIND_OP_MAP_READONLY: Map the memory read-only.
502 *
503 * Only valid with DRM_PANTHOR_VM_BIND_OP_TYPE_MAP.
504 */
505 DRM_PANTHOR_VM_BIND_OP_MAP_READONLY = 1 << 0,
506
507 /**
508 * @DRM_PANTHOR_VM_BIND_OP_MAP_NOEXEC: Map the memory not-executable.
509 *
510 * Only valid with DRM_PANTHOR_VM_BIND_OP_TYPE_MAP.
511 */
512 DRM_PANTHOR_VM_BIND_OP_MAP_NOEXEC = 1 << 1,
513
514 /**
515 * @DRM_PANTHOR_VM_BIND_OP_MAP_UNCACHED: Map the memory uncached.
516 *
517 * Only valid with DRM_PANTHOR_VM_BIND_OP_TYPE_MAP.
518 */
519 DRM_PANTHOR_VM_BIND_OP_MAP_UNCACHED = 1 << 2,
520
521 /**
522 * @DRM_PANTHOR_VM_BIND_OP_TYPE_MASK: Mask used to determine the type of operation.
523 */
524 DRM_PANTHOR_VM_BIND_OP_TYPE_MASK = (int)(0xfu << 28),
525
526 /** @DRM_PANTHOR_VM_BIND_OP_TYPE_MAP: Map operation. */
527 DRM_PANTHOR_VM_BIND_OP_TYPE_MAP = 0 << 28,
528
529 /** @DRM_PANTHOR_VM_BIND_OP_TYPE_UNMAP: Unmap operation. */
530 DRM_PANTHOR_VM_BIND_OP_TYPE_UNMAP = 1 << 28,
531
532 /**
533 * @DRM_PANTHOR_VM_BIND_OP_TYPE_SYNC_ONLY: No VM operation.
534 *
535 * Just serves as a synchronization point on a VM queue.
536 *
537 * Only valid if %DRM_PANTHOR_VM_BIND_ASYNC is set in drm_panthor_vm_bind::flags,
538 * and drm_panthor_vm_bind_op::syncs contains at least one element.
539 */
540 DRM_PANTHOR_VM_BIND_OP_TYPE_SYNC_ONLY = 2 << 28,
541};
542
543/**
544 * struct drm_panthor_vm_bind_op - VM bind operation
545 */
546struct drm_panthor_vm_bind_op {
547 /** @flags: Combination of drm_panthor_vm_bind_op_flags flags. */
548 __u32 flags;
549
550 /**
551 * @bo_handle: Handle of the buffer object to map.
552 * MBZ for unmap or sync-only operations.
553 */
554 __u32 bo_handle;
555
556 /**
557 * @bo_offset: Buffer object offset.
558 * MBZ for unmap or sync-only operations.
559 */
560 __u64 bo_offset;
561
562 /**
563 * @va: Virtual address to map/unmap.
564 * MBZ for sync-only operations.
565 */
566 __u64 va;
567
568 /**
569 * @size: Size to map/unmap.
570 * MBZ for sync-only operations.
571 */
572 __u64 size;
573
574 /**
575 * @syncs: Array of struct drm_panthor_sync_op synchronization
576 * operations.
577 *
578 * This array must be empty if %DRM_PANTHOR_VM_BIND_ASYNC is not set on
579 * the drm_panthor_vm_bind object containing this VM bind operation.
580 *
581 * This array shall not be empty for sync-only operations.
582 */
583 struct drm_panthor_obj_array syncs;
584
585};
586
587/**
588 * enum drm_panthor_vm_bind_flags - VM bind flags
589 */
590enum drm_panthor_vm_bind_flags {
591 /**
592 * @DRM_PANTHOR_VM_BIND_ASYNC: VM bind operations are queued to the VM
593 * queue instead of being executed synchronously.
594 */
595 DRM_PANTHOR_VM_BIND_ASYNC = 1 << 0,
596};
597
598/**
599 * struct drm_panthor_vm_bind - Arguments passed to DRM_IOCTL_PANTHOR_VM_BIND
600 */
601struct drm_panthor_vm_bind {
602 /** @vm_id: VM targeted by the bind request. */
603 __u32 vm_id;
604
605 /** @flags: Combination of drm_panthor_vm_bind_flags flags. */
606 __u32 flags;
607
608 /** @ops: Array of struct drm_panthor_vm_bind_op bind operations. */
609 struct drm_panthor_obj_array ops;
610};
611
612/**
613 * enum drm_panthor_vm_state - VM states.
614 */
615enum drm_panthor_vm_state {
616 /**
617 * @DRM_PANTHOR_VM_STATE_USABLE: VM is usable.
618 *
619 * New VM operations will be accepted on this VM.
620 */
621 DRM_PANTHOR_VM_STATE_USABLE,
622
623 /**
624 * @DRM_PANTHOR_VM_STATE_UNUSABLE: VM is unusable.
625 *
626 * Something put the VM in an unusable state (like an asynchronous
627 * VM_BIND request failing for any reason).
628 *
629 * Once the VM is in this state, all new MAP operations will be
630 * rejected, and any GPU job targeting this VM will fail.
631 * UNMAP operations are still accepted.
632 *
633 * The only way to recover from an unusable VM is to create a new
634 * VM, and destroy the old one.
635 */
636 DRM_PANTHOR_VM_STATE_UNUSABLE,
637};
638
639/**
640 * struct drm_panthor_vm_get_state - Get VM state.
641 */
642struct drm_panthor_vm_get_state {
643 /** @vm_id: VM targeted by the get_state request. */
644 __u32 vm_id;
645
646 /**
647 * @state: state returned by the driver.
648 *
649 * Must be one of the enum drm_panthor_vm_state values.
650 */
651 __u32 state;
652};
653
654/**
655 * enum drm_panthor_bo_flags - Buffer object flags, passed at creation time.
656 */
657enum drm_panthor_bo_flags {
658 /** @DRM_PANTHOR_BO_NO_MMAP: The buffer object will never be CPU-mapped in userspace. */
659 DRM_PANTHOR_BO_NO_MMAP = (1 << 0),
660};
661
662/**
663 * struct drm_panthor_bo_create - Arguments passed to DRM_IOCTL_PANTHOR_BO_CREATE.
664 */
665struct drm_panthor_bo_create {
666 /**
667 * @size: Requested size for the object
668 *
669 * The (page-aligned) allocated size for the object will be returned.
670 */
671 __u64 size;
672
673 /**
674 * @flags: Flags. Must be a combination of drm_panthor_bo_flags flags.
675 */
676 __u32 flags;
677
678 /**
679 * @exclusive_vm_id: Exclusive VM this buffer object will be mapped to.
680 *
681 * If not zero, the field must refer to a valid VM ID, and implies that:
682 * - the buffer object will only ever be bound to that VM
683 * - cannot be exported as a PRIME fd
684 */
685 __u32 exclusive_vm_id;
686
687 /**
688 * @handle: Returned handle for the object.
689 *
690 * Object handles are nonzero.
691 */
692 __u32 handle;
693
694 /** @pad: MBZ. */
695 __u32 pad;
696};
697
698/**
699 * struct drm_panthor_bo_mmap_offset - Arguments passed to DRM_IOCTL_PANTHOR_BO_MMAP_OFFSET.
700 */
701struct drm_panthor_bo_mmap_offset {
702 /** @handle: Handle of the object we want an mmap offset for. */
703 __u32 handle;
704
705 /** @pad: MBZ. */
706 __u32 pad;
707
708 /** @offset: The fake offset to use for subsequent mmap calls. */
709 __u64 offset;
710};
711
712/**
713 * struct drm_panthor_queue_create - Queue creation arguments.
714 */
715struct drm_panthor_queue_create {
716 /**
717 * @priority: Defines the priority of queues inside a group. Goes from 0 to 15,
718 * 15 being the highest priority.
719 */
720 __u8 priority;
721
722 /** @pad: Padding fields, MBZ. */
723 __u8 pad[3];
724
725 /** @ringbuf_size: Size of the ring buffer to allocate to this queue. */
726 __u32 ringbuf_size;
727};
728
729/**
730 * enum drm_panthor_group_priority - Scheduling group priority
731 */
732enum drm_panthor_group_priority {
733 /** @PANTHOR_GROUP_PRIORITY_LOW: Low priority group. */
734 PANTHOR_GROUP_PRIORITY_LOW = 0,
735
736 /** @PANTHOR_GROUP_PRIORITY_MEDIUM: Medium priority group. */
737 PANTHOR_GROUP_PRIORITY_MEDIUM,
738
739 /**
740 * @PANTHOR_GROUP_PRIORITY_HIGH: High priority group.
741 *
742 * Requires CAP_SYS_NICE or DRM_MASTER.
743 */
744 PANTHOR_GROUP_PRIORITY_HIGH,
745
746 /**
747 * @PANTHOR_GROUP_PRIORITY_REALTIME: Realtime priority group.
748 *
749 * Requires CAP_SYS_NICE or DRM_MASTER.
750 */
751 PANTHOR_GROUP_PRIORITY_REALTIME,
752};
753
754/**
755 * struct drm_panthor_group_create - Arguments passed to DRM_IOCTL_PANTHOR_GROUP_CREATE
756 */
757struct drm_panthor_group_create {
758 /** @queues: Array of drm_panthor_queue_create elements. */
759 struct drm_panthor_obj_array queues;
760
761 /**
762 * @max_compute_cores: Maximum number of cores that can be used by compute
763 * jobs across CS queues bound to this group.
764 *
765 * Must be less or equal to the number of bits set in @compute_core_mask.
766 */
767 __u8 max_compute_cores;
768
769 /**
770 * @max_fragment_cores: Maximum number of cores that can be used by fragment
771 * jobs across CS queues bound to this group.
772 *
773 * Must be less or equal to the number of bits set in @fragment_core_mask.
774 */
775 __u8 max_fragment_cores;
776
777 /**
778 * @max_tiler_cores: Maximum number of tilers that can be used by tiler jobs
779 * across CS queues bound to this group.
780 *
781 * Must be less or equal to the number of bits set in @tiler_core_mask.
782 */
783 __u8 max_tiler_cores;
784
785 /** @priority: Group priority (see enum drm_panthor_group_priority). */
786 __u8 priority;
787
788 /** @pad: Padding field, MBZ. */
789 __u32 pad;
790
791 /**
792 * @compute_core_mask: Mask encoding cores that can be used for compute jobs.
793 *
794 * This field must have at least @max_compute_cores bits set.
795 *
796 * The bits set here should also be set in drm_panthor_gpu_info::shader_present.
797 */
798 __u64 compute_core_mask;
799
800 /**
801 * @fragment_core_mask: Mask encoding cores that can be used for fragment jobs.
802 *
803 * This field must have at least @max_fragment_cores bits set.
804 *
805 * The bits set here should also be set in drm_panthor_gpu_info::shader_present.
806 */
807 __u64 fragment_core_mask;
808
809 /**
810 * @tiler_core_mask: Mask encoding cores that can be used for tiler jobs.
811 *
812 * This field must have at least @max_tiler_cores bits set.
813 *
814 * The bits set here should also be set in drm_panthor_gpu_info::tiler_present.
815 */
816 __u64 tiler_core_mask;
817
818 /**
819 * @vm_id: VM ID to bind this group to.
820 *
821 * All submission to queues bound to this group will use this VM.
822 */
823 __u32 vm_id;
824
825 /**
826 * @group_handle: Returned group handle. Passed back when submitting jobs or
827 * destroying a group.
828 */
829 __u32 group_handle;
830};
831
832/**
833 * struct drm_panthor_group_destroy - Arguments passed to DRM_IOCTL_PANTHOR_GROUP_DESTROY
834 */
835struct drm_panthor_group_destroy {
836 /** @group_handle: Group to destroy */
837 __u32 group_handle;
838
839 /** @pad: Padding field, MBZ. */
840 __u32 pad;
841};
842
843/**
844 * struct drm_panthor_queue_submit - Job submission arguments.
845 *
846 * This is describing the userspace command stream to call from the kernel
847 * command stream ring-buffer. Queue submission is always part of a group
848 * submission, taking one or more jobs to submit to the underlying queues.
849 */
850struct drm_panthor_queue_submit {
851 /** @queue_index: Index of the queue inside a group. */
852 __u32 queue_index;
853
854 /**
855 * @stream_size: Size of the command stream to execute.
856 *
857 * Must be 64-bit/8-byte aligned (the size of a CS instruction)
858 *
859 * Can be zero if stream_addr is zero too.
860 *
861 * When the stream size is zero, the queue submit serves as a
862 * synchronization point.
863 */
864 __u32 stream_size;
865
866 /**
867 * @stream_addr: GPU address of the command stream to execute.
868 *
869 * Must be aligned on 64-byte.
870 *
871 * Can be zero is stream_size is zero too.
872 */
873 __u64 stream_addr;
874
875 /**
876 * @latest_flush: FLUSH_ID read at the time the stream was built.
877 *
878 * This allows cache flush elimination for the automatic
879 * flush+invalidate(all) done at submission time, which is needed to
880 * ensure the GPU doesn't get garbage when reading the indirect command
881 * stream buffers. If you want the cache flush to happen
882 * unconditionally, pass a zero here.
883 *
884 * Ignored when stream_size is zero.
885 */
886 __u32 latest_flush;
887
888 /** @pad: MBZ. */
889 __u32 pad;
890
891 /** @syncs: Array of struct drm_panthor_sync_op sync operations. */
892 struct drm_panthor_obj_array syncs;
893};
894
895/**
896 * struct drm_panthor_group_submit - Arguments passed to DRM_IOCTL_PANTHOR_GROUP_SUBMIT
897 */
898struct drm_panthor_group_submit {
899 /** @group_handle: Handle of the group to queue jobs to. */
900 __u32 group_handle;
901
902 /** @pad: MBZ. */
903 __u32 pad;
904
905 /** @queue_submits: Array of drm_panthor_queue_submit objects. */
906 struct drm_panthor_obj_array queue_submits;
907};
908
909/**
910 * enum drm_panthor_group_state_flags - Group state flags
911 */
912enum drm_panthor_group_state_flags {
913 /**
914 * @DRM_PANTHOR_GROUP_STATE_TIMEDOUT: Group had unfinished jobs.
915 *
916 * When a group ends up with this flag set, no jobs can be submitted to its queues.
917 */
918 DRM_PANTHOR_GROUP_STATE_TIMEDOUT = 1 << 0,
919
920 /**
921 * @DRM_PANTHOR_GROUP_STATE_FATAL_FAULT: Group had fatal faults.
922 *
923 * When a group ends up with this flag set, no jobs can be submitted to its queues.
924 */
925 DRM_PANTHOR_GROUP_STATE_FATAL_FAULT = 1 << 1,
926
927 /**
928 * @DRM_PANTHOR_GROUP_STATE_INNOCENT: Group was killed during a reset caused by other
929 * groups.
930 *
931 * This flag can only be set if DRM_PANTHOR_GROUP_STATE_TIMEDOUT is set and
932 * DRM_PANTHOR_GROUP_STATE_FATAL_FAULT is not.
933 */
934 DRM_PANTHOR_GROUP_STATE_INNOCENT = 1 << 2,
935};
936
937/**
938 * struct drm_panthor_group_get_state - Arguments passed to DRM_IOCTL_PANTHOR_GROUP_GET_STATE
939 *
940 * Used to query the state of a group and decide whether a new group should be created to
941 * replace it.
942 */
943struct drm_panthor_group_get_state {
944 /** @group_handle: Handle of the group to query state on */
945 __u32 group_handle;
946
947 /**
948 * @state: Combination of DRM_PANTHOR_GROUP_STATE_* flags encoding the
949 * group state.
950 */
951 __u32 state;
952
953 /** @fatal_queues: Bitmask of queues that faced fatal faults. */
954 __u32 fatal_queues;
955
956 /** @pad: MBZ */
957 __u32 pad;
958};
959
960/**
961 * struct drm_panthor_tiler_heap_create - Arguments passed to DRM_IOCTL_PANTHOR_TILER_HEAP_CREATE
962 */
963struct drm_panthor_tiler_heap_create {
964 /** @vm_id: VM ID the tiler heap should be mapped to */
965 __u32 vm_id;
966
967 /** @initial_chunk_count: Initial number of chunks to allocate. Must be at least one. */
968 __u32 initial_chunk_count;
969
970 /**
971 * @chunk_size: Chunk size.
972 *
973 * Must be page-aligned and lie in the [128k:8M] range.
974 */
975 __u32 chunk_size;
976
977 /**
978 * @max_chunks: Maximum number of chunks that can be allocated.
979 *
980 * Must be at least @initial_chunk_count.
981 */
982 __u32 max_chunks;
983
984 /**
985 * @target_in_flight: Maximum number of in-flight render passes.
986 *
987 * If the heap has more than tiler jobs in-flight, the FW will wait for render
988 * passes to finish before queuing new tiler jobs.
989 */
990 __u32 target_in_flight;
991
992 /** @handle: Returned heap handle. Passed back to DESTROY_TILER_HEAP. */
993 __u32 handle;
994
995 /** @tiler_heap_ctx_gpu_va: Returned heap GPU virtual address returned */
996 __u64 tiler_heap_ctx_gpu_va;
997
998 /**
999 * @first_heap_chunk_gpu_va: First heap chunk.
1000 *
1001 * The tiler heap is formed of heap chunks forming a single-link list. This
1002 * is the first element in the list.
1003 */
1004 __u64 first_heap_chunk_gpu_va;
1005};
1006
1007/**
1008 * struct drm_panthor_tiler_heap_destroy - Arguments passed to DRM_IOCTL_PANTHOR_TILER_HEAP_DESTROY
1009 */
1010struct drm_panthor_tiler_heap_destroy {
1011 /**
1012 * @handle: Handle of the tiler heap to destroy.
1013 *
1014 * Must be a valid heap handle returned by DRM_IOCTL_PANTHOR_TILER_HEAP_CREATE.
1015 */
1016 __u32 handle;
1017
1018 /** @pad: Padding field, MBZ. */
1019 __u32 pad;
1020};
1021
1022#if defined(__cplusplus)
1023}
1024#endif
1025
1026#endif /* _PANTHOR_DRM_H_ */