master
1/* SPDX-License-Identifier: GPL-2.0-only WITH Linux-syscall-note */
2/*
3 * Copyright (C) 2020-2025 Intel Corporation
4 */
5
6#ifndef __UAPI_IVPU_DRM_H__
7#define __UAPI_IVPU_DRM_H__
8
9#include "drm.h"
10
11#if defined(__cplusplus)
12extern "C" {
13#endif
14
15#define DRM_IVPU_GET_PARAM 0x00
16#define DRM_IVPU_SET_PARAM 0x01
17#define DRM_IVPU_BO_CREATE 0x02
18#define DRM_IVPU_BO_INFO 0x03
19#define DRM_IVPU_SUBMIT 0x05
20#define DRM_IVPU_BO_WAIT 0x06
21#define DRM_IVPU_METRIC_STREAMER_START 0x07
22#define DRM_IVPU_METRIC_STREAMER_STOP 0x08
23#define DRM_IVPU_METRIC_STREAMER_GET_DATA 0x09
24#define DRM_IVPU_METRIC_STREAMER_GET_INFO 0x0a
25#define DRM_IVPU_CMDQ_CREATE 0x0b
26#define DRM_IVPU_CMDQ_DESTROY 0x0c
27#define DRM_IVPU_CMDQ_SUBMIT 0x0d
28
29#define DRM_IOCTL_IVPU_GET_PARAM \
30 DRM_IOWR(DRM_COMMAND_BASE + DRM_IVPU_GET_PARAM, struct drm_ivpu_param)
31
32#define DRM_IOCTL_IVPU_SET_PARAM \
33 DRM_IOW(DRM_COMMAND_BASE + DRM_IVPU_SET_PARAM, struct drm_ivpu_param)
34
35#define DRM_IOCTL_IVPU_BO_CREATE \
36 DRM_IOWR(DRM_COMMAND_BASE + DRM_IVPU_BO_CREATE, struct drm_ivpu_bo_create)
37
38#define DRM_IOCTL_IVPU_BO_INFO \
39 DRM_IOWR(DRM_COMMAND_BASE + DRM_IVPU_BO_INFO, struct drm_ivpu_bo_info)
40
41#define DRM_IOCTL_IVPU_SUBMIT \
42 DRM_IOW(DRM_COMMAND_BASE + DRM_IVPU_SUBMIT, struct drm_ivpu_submit)
43
44#define DRM_IOCTL_IVPU_BO_WAIT \
45 DRM_IOWR(DRM_COMMAND_BASE + DRM_IVPU_BO_WAIT, struct drm_ivpu_bo_wait)
46
47#define DRM_IOCTL_IVPU_METRIC_STREAMER_START \
48 DRM_IOWR(DRM_COMMAND_BASE + DRM_IVPU_METRIC_STREAMER_START, \
49 struct drm_ivpu_metric_streamer_start)
50
51#define DRM_IOCTL_IVPU_METRIC_STREAMER_STOP \
52 DRM_IOW(DRM_COMMAND_BASE + DRM_IVPU_METRIC_STREAMER_STOP, \
53 struct drm_ivpu_metric_streamer_stop)
54
55#define DRM_IOCTL_IVPU_METRIC_STREAMER_GET_DATA \
56 DRM_IOWR(DRM_COMMAND_BASE + DRM_IVPU_METRIC_STREAMER_GET_DATA, \
57 struct drm_ivpu_metric_streamer_get_data)
58
59#define DRM_IOCTL_IVPU_METRIC_STREAMER_GET_INFO \
60 DRM_IOWR(DRM_COMMAND_BASE + DRM_IVPU_METRIC_STREAMER_GET_INFO, \
61 struct drm_ivpu_metric_streamer_get_data)
62
63#define DRM_IOCTL_IVPU_CMDQ_CREATE \
64 DRM_IOWR(DRM_COMMAND_BASE + DRM_IVPU_CMDQ_CREATE, struct drm_ivpu_cmdq_create)
65
66#define DRM_IOCTL_IVPU_CMDQ_DESTROY \
67 DRM_IOW(DRM_COMMAND_BASE + DRM_IVPU_CMDQ_DESTROY, struct drm_ivpu_cmdq_destroy)
68
69#define DRM_IOCTL_IVPU_CMDQ_SUBMIT \
70 DRM_IOW(DRM_COMMAND_BASE + DRM_IVPU_CMDQ_SUBMIT, struct drm_ivpu_cmdq_submit)
71
72/**
73 * DOC: contexts
74 *
75 * VPU contexts have private virtual address space, job queues and priority.
76 * Each context is identified by an unique ID. Context is created on open().
77 */
78
79#define DRM_IVPU_PARAM_DEVICE_ID 0
80#define DRM_IVPU_PARAM_DEVICE_REVISION 1
81#define DRM_IVPU_PARAM_PLATFORM_TYPE 2
82#define DRM_IVPU_PARAM_CORE_CLOCK_RATE 3
83#define DRM_IVPU_PARAM_NUM_CONTEXTS 4
84#define DRM_IVPU_PARAM_CONTEXT_BASE_ADDRESS 5
85#define DRM_IVPU_PARAM_CONTEXT_PRIORITY 6 /* Deprecated */
86#define DRM_IVPU_PARAM_CONTEXT_ID 7
87#define DRM_IVPU_PARAM_FW_API_VERSION 8
88#define DRM_IVPU_PARAM_ENGINE_HEARTBEAT 9
89#define DRM_IVPU_PARAM_UNIQUE_INFERENCE_ID 10
90#define DRM_IVPU_PARAM_TILE_CONFIG 11
91#define DRM_IVPU_PARAM_SKU 12
92#define DRM_IVPU_PARAM_CAPABILITIES 13
93
94#define DRM_IVPU_PLATFORM_TYPE_SILICON 0
95
96/* Deprecated, use DRM_IVPU_JOB_PRIORITY */
97#define DRM_IVPU_CONTEXT_PRIORITY_IDLE 0
98#define DRM_IVPU_CONTEXT_PRIORITY_NORMAL 1
99#define DRM_IVPU_CONTEXT_PRIORITY_FOCUS 2
100#define DRM_IVPU_CONTEXT_PRIORITY_REALTIME 3
101
102#define DRM_IVPU_JOB_PRIORITY_DEFAULT 0
103#define DRM_IVPU_JOB_PRIORITY_IDLE 1
104#define DRM_IVPU_JOB_PRIORITY_NORMAL 2
105#define DRM_IVPU_JOB_PRIORITY_FOCUS 3
106#define DRM_IVPU_JOB_PRIORITY_REALTIME 4
107
108/**
109 * DRM_IVPU_CAP_METRIC_STREAMER
110 *
111 * Metric streamer support. Provides sampling of various hardware performance
112 * metrics like DMA bandwidth and cache miss/hits. Can be used for profiling.
113 */
114#define DRM_IVPU_CAP_METRIC_STREAMER 1
115/**
116 * DRM_IVPU_CAP_DMA_MEMORY_RANGE
117 *
118 * Driver has capability to allocate separate memory range
119 * accessible by hardware DMA.
120 */
121#define DRM_IVPU_CAP_DMA_MEMORY_RANGE 2
122/**
123 * DRM_IVPU_CAP_MANAGE_CMDQ
124 *
125 * Driver supports explicit command queue operations like command queue create,
126 * command queue destroy and submit job on specific command queue.
127 */
128#define DRM_IVPU_CAP_MANAGE_CMDQ 3
129
130/**
131 * struct drm_ivpu_param - Get/Set VPU parameters
132 */
133struct drm_ivpu_param {
134 /**
135 * @param:
136 *
137 * Supported params:
138 *
139 * %DRM_IVPU_PARAM_DEVICE_ID:
140 * PCI Device ID of the VPU device (read-only)
141 *
142 * %DRM_IVPU_PARAM_DEVICE_REVISION:
143 * VPU device revision (read-only)
144 *
145 * %DRM_IVPU_PARAM_PLATFORM_TYPE:
146 * Returns %DRM_IVPU_PLATFORM_TYPE_SILICON on real hardware or device specific
147 * platform type when executing on a simulator or emulator (read-only)
148 *
149 * %DRM_IVPU_PARAM_CORE_CLOCK_RATE:
150 * Maximum frequency of the NPU data processing unit clock (read-only)
151 *
152 * %DRM_IVPU_PARAM_NUM_CONTEXTS:
153 * Maximum number of simultaneously existing contexts (read-only)
154 *
155 * %DRM_IVPU_PARAM_CONTEXT_BASE_ADDRESS:
156 * Lowest VPU virtual address available in the current context (read-only)
157 *
158 * %DRM_IVPU_PARAM_CONTEXT_ID:
159 * Current context ID, always greater than 0 (read-only)
160 *
161 * %DRM_IVPU_PARAM_FW_API_VERSION:
162 * Firmware API version array (read-only)
163 *
164 * %DRM_IVPU_PARAM_ENGINE_HEARTBEAT:
165 * Heartbeat value from an engine (read-only).
166 * Engine ID (i.e. DRM_IVPU_ENGINE_COMPUTE) is given via index.
167 *
168 * %DRM_IVPU_PARAM_UNIQUE_INFERENCE_ID:
169 * Device-unique inference ID (read-only)
170 *
171 * %DRM_IVPU_PARAM_TILE_CONFIG:
172 * VPU tile configuration (read-only)
173 *
174 * %DRM_IVPU_PARAM_SKU:
175 * VPU SKU ID (read-only)
176 *
177 * %DRM_IVPU_PARAM_CAPABILITIES:
178 * Supported capabilities (read-only)
179 */
180 __u32 param;
181
182 /** @index: Index for params that have multiple instances */
183 __u32 index;
184
185 /** @value: Param value */
186 __u64 value;
187};
188
189#define DRM_IVPU_BO_SHAVE_MEM 0x00000001
190#define DRM_IVPU_BO_HIGH_MEM DRM_IVPU_BO_SHAVE_MEM
191#define DRM_IVPU_BO_MAPPABLE 0x00000002
192#define DRM_IVPU_BO_DMA_MEM 0x00000004
193
194#define DRM_IVPU_BO_CACHED 0x00000000
195#define DRM_IVPU_BO_UNCACHED 0x00010000
196#define DRM_IVPU_BO_WC 0x00020000
197#define DRM_IVPU_BO_CACHE_MASK 0x00030000
198
199#define DRM_IVPU_BO_FLAGS \
200 (DRM_IVPU_BO_HIGH_MEM | \
201 DRM_IVPU_BO_MAPPABLE | \
202 DRM_IVPU_BO_DMA_MEM | \
203 DRM_IVPU_BO_CACHE_MASK)
204
205/**
206 * struct drm_ivpu_bo_create - Create BO backed by SHMEM
207 *
208 * Create GEM buffer object allocated in SHMEM memory.
209 */
210struct drm_ivpu_bo_create {
211 /** @size: The size in bytes of the allocated memory */
212 __u64 size;
213
214 /**
215 * @flags:
216 *
217 * Supported flags:
218 *
219 * %DRM_IVPU_BO_HIGH_MEM:
220 *
221 * Allocate VPU address from >4GB range.
222 * Buffer object with vpu address >4GB can be always accessed by the
223 * VPU DMA engine, but some HW generation may not be able to access
224 * this memory from then firmware running on the VPU management processor.
225 * Suitable for input, output and some scratch buffers.
226 *
227 * %DRM_IVPU_BO_MAPPABLE:
228 *
229 * Buffer object can be mapped using mmap().
230 *
231 * %DRM_IVPU_BO_CACHED:
232 *
233 * Allocated BO will be cached on host side (WB) and snooped on the VPU side.
234 * This is the default caching mode.
235 *
236 * %DRM_IVPU_BO_UNCACHED:
237 *
238 * Not supported. Use DRM_IVPU_BO_WC instead.
239 *
240 * %DRM_IVPU_BO_WC:
241 *
242 * Allocated BO will use write combining buffer for writes but reads will be
243 * uncached.
244 */
245 __u32 flags;
246
247 /** @handle: Returned GEM object handle */
248 __u32 handle;
249
250 /** @vpu_addr: Returned VPU virtual address */
251 __u64 vpu_addr;
252};
253
254/**
255 * struct drm_ivpu_bo_info - Query buffer object info
256 */
257struct drm_ivpu_bo_info {
258 /** @handle: Handle of the queried BO */
259 __u32 handle;
260
261 /** @flags: Returned flags used to create the BO */
262 __u32 flags;
263
264 /** @vpu_addr: Returned VPU virtual address */
265 __u64 vpu_addr;
266
267 /**
268 * @mmap_offset:
269 *
270 * Returned offset to be used in mmap(). 0 in case the BO is not mappable.
271 */
272 __u64 mmap_offset;
273
274 /** @size: Returned GEM object size, aligned to PAGE_SIZE */
275 __u64 size;
276};
277
278/* drm_ivpu_submit engines */
279#define DRM_IVPU_ENGINE_COMPUTE 0
280#define DRM_IVPU_ENGINE_COPY 1 /* Deprecated */
281
282/**
283 * struct drm_ivpu_submit - Submit commands to the VPU
284 *
285 * Execute a single command buffer on a given VPU engine.
286 * Handles to all referenced buffer objects have to be provided in @buffers_ptr.
287 *
288 * User space may wait on job completion using %DRM_IVPU_BO_WAIT ioctl.
289 */
290struct drm_ivpu_submit {
291 /**
292 * @buffers_ptr:
293 *
294 * A pointer to an u32 array of GEM handles of the BOs required for this job.
295 * The number of elements in the array must be equal to the value given by @buffer_count.
296 *
297 * The first BO is the command buffer. The rest of array has to contain all
298 * BOs referenced from the command buffer.
299 */
300 __u64 buffers_ptr;
301
302 /** @buffer_count: Number of elements in the @buffers_ptr */
303 __u32 buffer_count;
304
305 /**
306 * @engine: Select the engine this job should be executed on
307 *
308 * %DRM_IVPU_ENGINE_COMPUTE:
309 *
310 * Performs Deep Learning Neural Compute Inference Operations
311 */
312 __u32 engine;
313
314 /** @flags: Reserved for future use - must be zero */
315 __u32 flags;
316
317 /**
318 * @commands_offset:
319 *
320 * Offset inside the first buffer in @buffers_ptr containing commands
321 * to be executed. The offset has to be 8-byte aligned.
322 */
323 __u32 commands_offset;
324
325 /**
326 * @priority:
327 *
328 * Priority to be set for related job command queue, can be one of the following:
329 * %DRM_IVPU_JOB_PRIORITY_DEFAULT
330 * %DRM_IVPU_JOB_PRIORITY_IDLE
331 * %DRM_IVPU_JOB_PRIORITY_NORMAL
332 * %DRM_IVPU_JOB_PRIORITY_FOCUS
333 * %DRM_IVPU_JOB_PRIORITY_REALTIME
334 */
335 __u32 priority;
336};
337
338/**
339 * struct drm_ivpu_cmdq_submit - Submit commands to the VPU using explicit command queue
340 *
341 * Execute a single command buffer on a given command queue.
342 * Handles to all referenced buffer objects have to be provided in @buffers_ptr.
343 *
344 * User space may wait on job completion using %DRM_IVPU_BO_WAIT ioctl.
345 */
346struct drm_ivpu_cmdq_submit {
347 /**
348 * @buffers_ptr:
349 *
350 * A pointer to an u32 array of GEM handles of the BOs required for this job.
351 * The number of elements in the array must be equal to the value given by @buffer_count.
352 *
353 * The first BO is the command buffer. The rest of array has to contain all
354 * BOs referenced from the command buffer.
355 */
356 __u64 buffers_ptr;
357
358 /** @buffer_count: Number of elements in the @buffers_ptr */
359 __u32 buffer_count;
360
361 /** @cmdq_id: ID for the command queue where job will be submitted */
362 __u32 cmdq_id;
363
364 /** @flags: Reserved for future use - must be zero */
365 __u32 flags;
366
367 /**
368 * @commands_offset:
369 *
370 * Offset inside the first buffer in @buffers_ptr containing commands
371 * to be executed. The offset has to be 8-byte aligned.
372 */
373 __u32 commands_offset;
374};
375
376/* drm_ivpu_bo_wait job status codes */
377#define DRM_IVPU_JOB_STATUS_SUCCESS 0
378#define DRM_IVPU_JOB_STATUS_ABORTED 256
379
380/**
381 * struct drm_ivpu_bo_wait - Wait for BO to become inactive
382 *
383 * Blocks until a given buffer object becomes inactive.
384 * With @timeout_ms set to 0 returns immediately.
385 */
386struct drm_ivpu_bo_wait {
387 /** @handle: Handle to the buffer object to be waited on */
388 __u32 handle;
389
390 /** @flags: Reserved for future use - must be zero */
391 __u32 flags;
392
393 /** @timeout_ns: Absolute timeout in nanoseconds (may be zero) */
394 __s64 timeout_ns;
395
396 /**
397 * @job_status:
398 *
399 * Job status code which is updated after the job is completed.
400 * &DRM_IVPU_JOB_STATUS_SUCCESS or device specific error otherwise.
401 * Valid only if @handle points to a command buffer.
402 */
403 __u32 job_status;
404
405 /** @pad: Padding - must be zero */
406 __u32 pad;
407};
408
409/**
410 * struct drm_ivpu_metric_streamer_start - Start collecting metric data
411 */
412struct drm_ivpu_metric_streamer_start {
413 /** @metric_group_mask: Indicates metric streamer instance */
414 __u64 metric_group_mask;
415 /** @sampling_period_ns: Sampling period in nanoseconds */
416 __u64 sampling_period_ns;
417 /**
418 * @read_period_samples:
419 *
420 * Number of samples after which user space will try to read the data.
421 * Reading the data after significantly longer period may cause data loss.
422 */
423 __u32 read_period_samples;
424 /** @sample_size: Returned size of a single sample in bytes */
425 __u32 sample_size;
426 /** @max_data_size: Returned max @data_size from %DRM_IOCTL_IVPU_METRIC_STREAMER_GET_DATA */
427 __u32 max_data_size;
428};
429
430/**
431 * struct drm_ivpu_metric_streamer_get_data - Copy collected metric data
432 */
433struct drm_ivpu_metric_streamer_get_data {
434 /** @metric_group_mask: Indicates metric streamer instance */
435 __u64 metric_group_mask;
436 /** @buffer_ptr: A pointer to a destination for the copied data */
437 __u64 buffer_ptr;
438 /** @buffer_size: Size of the destination buffer */
439 __u64 buffer_size;
440 /**
441 * @data_size: Returned size of copied metric data
442 *
443 * If the @buffer_size is zero, returns the amount of data ready to be copied.
444 */
445 __u64 data_size;
446};
447
448/* Command queue flags */
449#define DRM_IVPU_CMDQ_FLAG_TURBO 0x00000001
450
451/**
452 * struct drm_ivpu_cmdq_create - Create command queue for job submission
453 */
454struct drm_ivpu_cmdq_create {
455 /** @cmdq_id: Returned ID of created command queue */
456 __u32 cmdq_id;
457 /**
458 * @priority:
459 *
460 * Priority to be set for related job command queue, can be one of the following:
461 * %DRM_IVPU_JOB_PRIORITY_DEFAULT
462 * %DRM_IVPU_JOB_PRIORITY_IDLE
463 * %DRM_IVPU_JOB_PRIORITY_NORMAL
464 * %DRM_IVPU_JOB_PRIORITY_FOCUS
465 * %DRM_IVPU_JOB_PRIORITY_REALTIME
466 */
467 __u32 priority;
468 /**
469 * @flags:
470 *
471 * Supported flags:
472 *
473 * %DRM_IVPU_CMDQ_FLAG_TURBO
474 *
475 * Enable low-latency mode for the command queue. The NPU will maximize performance
476 * when executing jobs from such queue at the cost of increased power usage.
477 */
478 __u32 flags;
479};
480
481/**
482 * struct drm_ivpu_cmdq_destroy - Destroy a command queue
483 */
484struct drm_ivpu_cmdq_destroy {
485 /** @cmdq_id: ID of command queue to destroy */
486 __u32 cmdq_id;
487};
488
489/**
490 * struct drm_ivpu_metric_streamer_stop - Stop collecting metric data
491 */
492struct drm_ivpu_metric_streamer_stop {
493 /** @metric_group_mask: Indicates metric streamer instance */
494 __u64 metric_group_mask;
495};
496
497#if defined(__cplusplus)
498}
499#endif
500
501#endif /* __UAPI_IVPU_DRM_H__ */