ivpu_accel.h

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