1/* SPDX-License-Identifier: MIT */
2/*
3 * Copyright (c) 2020-2025, Intel Corporation.
4 */
5
6/**
7 * @addtogroup Jsm
8 * @{
9 */
10
11/**
12 * @file
13 * @brief JSM shared definitions
14 */
15#ifndef VPU_JSM_API_H
16#define VPU_JSM_API_H
17
18/*
19 * Major version changes that break backward compatibility
20 */
21#define VPU_JSM_API_VER_MAJOR 3
22
23/*
24 * Minor version changes when API backward compatibility is preserved.
25 */
26#define VPU_JSM_API_VER_MINOR 33
27
28/*
29 * API header changed (field names, documentation, formatting) but API itself has not been changed
30 */
31#define VPU_JSM_API_VER_PATCH 0
32
33/*
34 * Index in the API version table
35 */
36#define VPU_JSM_API_VER_INDEX 4
37
38/*
39 * Number of Priority Bands for Hardware Scheduling
40 * Bands: Idle(0), Normal(1), Focus(2), RealTime(3)
41 */
42#define VPU_HWS_NUM_PRIORITY_BANDS 4
43
44/* Max number of impacted contexts that can be dealt with the engine reset command */
45#define VPU_MAX_ENGINE_RESET_IMPACTED_CONTEXTS 3
46
47/*
48 * Pack the API structures to enforce binary compatibility
49 * Align to 8 bytes for optimal performance
50 */
51#pragma pack(push, 8)
52
53/*
54 * Engine indexes.
55 */
56#define VPU_ENGINE_COMPUTE 0
57#define VPU_ENGINE_NB 1
58
59/*
60 * VPU status values.
61 */
62#define VPU_JSM_STATUS_SUCCESS 0x0U
63#define VPU_JSM_STATUS_PARSING_ERR 0x1U
64#define VPU_JSM_STATUS_PROCESSING_ERR 0x2U
65#define VPU_JSM_STATUS_PREEMPTED 0x3U
66#define VPU_JSM_STATUS_ABORTED 0x4U
67#define VPU_JSM_STATUS_USER_CTX_VIOL_ERR 0x5U
68#define VPU_JSM_STATUS_GLOBAL_CTX_VIOL_ERR 0x6U
69#define VPU_JSM_STATUS_MVNCI_WRONG_INPUT_FORMAT 0x7U
70#define VPU_JSM_STATUS_MVNCI_UNSUPPORTED_NETWORK_ELEMENT 0x8U
71#define VPU_JSM_STATUS_MVNCI_INVALID_HANDLE 0x9U
72#define VPU_JSM_STATUS_MVNCI_OUT_OF_RESOURCES 0xAU
73#define VPU_JSM_STATUS_MVNCI_NOT_IMPLEMENTED 0xBU
74#define VPU_JSM_STATUS_MVNCI_INTERNAL_ERROR 0xCU
75/* @deprecated (use VPU_JSM_STATUS_PREEMPTED_MID_COMMAND instead) */
76#define VPU_JSM_STATUS_PREEMPTED_MID_INFERENCE 0xDU
77/* Job status returned when the job was preempted mid-command */
78#define VPU_JSM_STATUS_PREEMPTED_MID_COMMAND 0xDU
79/* Range of status codes that require engine reset */
80#define VPU_JSM_STATUS_ENGINE_RESET_REQUIRED_MIN 0xEU
81#define VPU_JSM_STATUS_MVNCI_CONTEXT_VIOLATION_HW 0xEU
82#define VPU_JSM_STATUS_MVNCI_PREEMPTION_TIMED_OUT 0xFU
83#define VPU_JSM_STATUS_ENGINE_RESET_REQUIRED_MAX 0x1FU
84
85/*
86 * Host <-> VPU IPC channels.
87 * ASYNC commands use a high priority channel, other messages use low-priority ones.
88 */
89#define VPU_IPC_CHAN_ASYNC_CMD 0
90#define VPU_IPC_CHAN_GEN_CMD 10
91#define VPU_IPC_CHAN_JOB_RET 11
92
93/*
94 * Job flags bit masks.
95 */
96enum {
97 /*
98 * Null submission mask.
99 * When set, batch buffer's commands are not processed but returned as
100 * successful immediately, except fences and timestamps.
101 * When cleared, batch buffer's commands are processed normally.
102 * Used for testing and profiling purposes.
103 */
104 VPU_JOB_FLAGS_NULL_SUBMISSION_MASK = (1 << 0U),
105 /*
106 * Inline command mask.
107 * When set, the object in job queue is an inline command (see struct vpu_inline_cmd below).
108 * When cleared, the object in job queue is a job (see struct vpu_job_queue_entry below).
109 */
110 VPU_JOB_FLAGS_INLINE_CMD_MASK = (1 << 1U),
111 /*
112 * VPU private data mask.
113 * Reserved for the VPU to store private data about the job (or inline command)
114 * while being processed.
115 */
116 VPU_JOB_FLAGS_PRIVATE_DATA_MASK = 0xFFFF0000U
117};
118
119/*
120 * Job queue flags bit masks.
121 */
122enum {
123 /*
124 * No job done notification mask.
125 * When set, indicates that no job done notification should be sent for any
126 * job from this queue. When cleared, indicates that job done notification
127 * should be sent for every job completed from this queue.
128 */
129 VPU_JOB_QUEUE_FLAGS_NO_JOB_DONE_MASK = (1 << 0U),
130 /*
131 * Native fence usage mask.
132 * When set, indicates that job queue uses native fences (as inline commands
133 * in job queue). Such queues may also use legacy fences (as commands in batch buffers).
134 * When cleared, indicates the job queue only uses legacy fences.
135 * NOTES:
136 * 1. For queues using native fences, VPU expects that all jobs in the queue
137 * are immediately followed by an inline command object. This object is expected
138 * to be a fence signal command in most cases, but can also be a NOP in case the host
139 * does not need per-job fence signalling. Other inline commands objects can be
140 * inserted between "job and inline command" pairs.
141 * 2. Native fence queues are only supported on VPU 40xx onwards.
142 */
143 VPU_JOB_QUEUE_FLAGS_USE_NATIVE_FENCE_MASK = (1 << 1U),
144 /*
145 * Enable turbo mode for testing NPU performance; not recommended for regular usage.
146 */
147 VPU_JOB_QUEUE_FLAGS_TURBO_MODE = (1 << 2U),
148 /*
149 * Queue error detection mode flag
150 * For 'interactive' queues (this bit not set), the FW will identify queues that have not
151 * completed a job inside the TDR timeout as in error as part of engine reset sequence.
152 * For 'non-interactive' queues (this bit set), the FW will identify queues that have not
153 * progressed the heartbeat inside the non-interactive no-progress timeout as in error as
154 * part of engine reset sequence. Additionally, there is an upper limit applied to these
155 * queues: even if they progress the heartbeat, if they run longer than non-interactive
156 * timeout, then the FW will also identify them as in error.
157 */
158 VPU_JOB_QUEUE_FLAGS_NON_INTERACTIVE = (1 << 3U)
159};
160
161/*
162 * Max length (including trailing NULL char) of trace entity name (e.g., the
163 * name of a logging destination or a loggable HW component).
164 */
165#define VPU_TRACE_ENTITY_NAME_MAX_LEN 32
166
167/*
168 * Max length (including trailing NULL char) of a dyndbg command.
169 *
170 * NOTE: 96 is used so that the size of 'struct vpu_ipc_msg' in the JSM API is
171 * 128 bytes (multiple of 64 bytes, the cache line size).
172 */
173#define VPU_DYNDBG_CMD_MAX_LEN 96
174
175/*
176 * For HWS command queue scheduling, we can prioritise command queues inside the
177 * same process with a relative in-process priority. Valid values for relative
178 * priority are given below - max and min.
179 */
180#define VPU_HWS_COMMAND_QUEUE_MAX_IN_PROCESS_PRIORITY 7
181#define VPU_HWS_COMMAND_QUEUE_MIN_IN_PROCESS_PRIORITY -7
182
183/*
184 * For HWS priority scheduling, we can have multiple realtime priority bands.
185 * They are numbered 0 to a MAX.
186 */
187#define VPU_HWS_MAX_REALTIME_PRIORITY_LEVEL 31U
188
189/*
190 * vpu_jsm_engine_reset_context flag definitions
191 */
192#define VPU_ENGINE_RESET_CONTEXT_FLAG_COLLATERAL_DAMAGE_MASK BIT(0)
193#define VPU_ENGINE_RESET_CONTEXT_HANG_PRIMARY_CAUSE 0
194#define VPU_ENGINE_RESET_CONTEXT_COLLATERAL_DAMAGE 1
195
196/*
197 * Invalid command queue handle identifier. Applies to cmdq_id and cmdq_group
198 * in this API.
199 */
200#define VPU_HWS_INVALID_CMDQ_HANDLE 0ULL
201
202/*
203 * Inline commands types.
204 */
205/*
206 * NOP.
207 * VPU does nothing other than consuming the inline command object.
208 */
209#define VPU_INLINE_CMD_TYPE_NOP 0x0
210/*
211 * Fence wait.
212 * VPU waits for the fence current value to reach monitored value.
213 * Fence wait operations are executed upon job dispatching. While waiting for
214 * the fence to be satisfied, VPU blocks fetching of the next objects in the queue.
215 * Jobs present in the queue prior to the fence wait object may be processed
216 * concurrently.
217 */
218#define VPU_INLINE_CMD_TYPE_FENCE_WAIT 0x1
219/*
220 * Fence signal.
221 * VPU sets the fence current value to the provided value. If new current value
222 * is equal to or higher than monitored value, VPU sends fence signalled notification
223 * to the host. Fence signal operations are executed upon completion of all the jobs
224 * present in the queue prior to them, and in-order relative to each other in the queue.
225 * But jobs in-between them may be processed concurrently and may complete out-of-order.
226 */
227#define VPU_INLINE_CMD_TYPE_FENCE_SIGNAL 0x2
228
229/**
230 * Job scheduling priority bands for both hardware scheduling and OS scheduling.
231 */
232enum vpu_job_scheduling_priority_band {
233 VPU_JOB_SCHEDULING_PRIORITY_BAND_IDLE = 0,
234 VPU_JOB_SCHEDULING_PRIORITY_BAND_NORMAL = 1,
235 VPU_JOB_SCHEDULING_PRIORITY_BAND_FOCUS = 2,
236 VPU_JOB_SCHEDULING_PRIORITY_BAND_REALTIME = 3,
237 VPU_JOB_SCHEDULING_PRIORITY_BAND_COUNT = 4,
238};
239
240/**
241 * Job format.
242 * Jobs defines the actual workloads to be executed by a given engine.
243 */
244struct vpu_job_queue_entry {
245 /** Address of VPU commands batch buffer */
246 u64 batch_buf_addr;
247 /** Job ID */
248 u32 job_id;
249 /** Flags bit field, see VPU_JOB_FLAGS_* above */
250 u32 flags;
251 /**
252 * Doorbell ring timestamp taken by KMD from SoC's global system clock, in
253 * microseconds. NPU can convert this value to its own fixed clock's timebase,
254 * to match other profiling timestamps.
255 */
256 u64 doorbell_timestamp;
257 /** Extra id for job tracking, used only in the firmware perf traces */
258 u64 host_tracking_id;
259 /** Address of the primary preemption buffer to use for this job */
260 u64 primary_preempt_buf_addr;
261 /** Size of the primary preemption buffer to use for this job */
262 u32 primary_preempt_buf_size;
263 /** Size of secondary preemption buffer to use for this job */
264 u32 secondary_preempt_buf_size;
265 /** Address of secondary preemption buffer to use for this job */
266 u64 secondary_preempt_buf_addr;
267 u64 reserved_0;
268};
269
270/**
271 * Inline command format.
272 * Inline commands are the commands executed at scheduler level (typically,
273 * synchronization directives). Inline command and job objects must be of
274 * the same size and have flags field at same offset.
275 */
276struct vpu_inline_cmd {
277 u64 reserved_0;
278 /** Inline command type, see VPU_INLINE_CMD_TYPE_* defines. */
279 u32 type;
280 /** Flags bit field, see VPU_JOB_FLAGS_* above. */
281 u32 flags;
282 /** Inline command payload. Depends on inline command type. */
283 union payload {
284 /** Fence (wait and signal) commands' payload. */
285 struct fence {
286 /** Fence object handle. */
287 u64 fence_handle;
288 /** User VA of the current fence value. */
289 u64 current_value_va;
290 /** User VA of the monitored fence value (read-only). */
291 u64 monitored_value_va;
292 /** Value to wait for or write in fence location. */
293 u64 value;
294 /** User VA of the log buffer in which to add log entry on completion. */
295 u64 log_buffer_va;
296 /** NPU private data. */
297 u64 npu_private_data;
298 } fence;
299 /**
300 * Other commands do not have a payload:
301 * Payload definition for future inline commands can be inserted here.
302 */
303 u64 reserved_1[6];
304 } payload;
305};
306
307/**
308 * Job queue slots can be populated either with job objects or inline command objects.
309 */
310union vpu_jobq_slot {
311 struct vpu_job_queue_entry job;
312 struct vpu_inline_cmd inline_cmd;
313};
314
315/**
316 * Job queue control registers.
317 */
318struct vpu_job_queue_header {
319 u32 engine_idx;
320 u32 head;
321 u32 tail;
322 u32 flags;
323 /** Set to 1 to indicate priority_band field is valid */
324 u32 priority_band_valid;
325 /**
326 * Priority for the work of this job queue, valid only if the HWS is NOT used
327 * and the @ref priority_band_valid is set to 1. It is applied only during
328 * the @ref VPU_JSM_MSG_REGISTER_DB message processing.
329 * The device firmware might use the priority_band to optimize the power
330 * management logic, but it will not affect the order of jobs.
331 * Available priority bands: @see enum vpu_job_scheduling_priority_band
332 */
333 u32 priority_band;
334 /** Inside realtime band assigns a further priority, limited to 0..31 range */
335 u32 realtime_priority_level;
336 u32 reserved_0[9];
337};
338
339/*
340 * Job queue format.
341 */
342struct vpu_job_queue {
343 struct vpu_job_queue_header header;
344 union vpu_jobq_slot slot[];
345};
346
347/**
348 * Logging entity types.
349 *
350 * This enum defines the different types of entities involved in logging.
351 */
352enum vpu_trace_entity_type {
353 /** Logging destination (entity where logs can be stored / printed). */
354 VPU_TRACE_ENTITY_TYPE_DESTINATION = 1,
355 /** Loggable HW component (HW entity that can be logged). */
356 VPU_TRACE_ENTITY_TYPE_HW_COMPONENT = 2,
357};
358
359/**
360 * HWS specific log buffer header details.
361 * Total size is 32 bytes.
362 */
363struct vpu_hws_log_buffer_header {
364 /** Written by VPU after adding a log entry. Initialised by host to 0. */
365 u32 first_free_entry_index;
366 /** Incremented by VPU every time the VPU writes the 0th entry; initialised by host to 0. */
367 u32 wraparound_count;
368 /**
369 * This is the number of buffers that can be stored in the log buffer provided by the host.
370 * It is written by host before passing buffer to VPU. VPU should consider it read-only.
371 */
372 u64 num_of_entries;
373 u64 reserved[2];
374};
375
376/**
377 * HWS specific log buffer entry details.
378 * Total size is 32 bytes.
379 */
380struct vpu_hws_log_buffer_entry {
381 /** VPU timestamp must be an invariant timer tick (not impacted by DVFS) */
382 u64 vpu_timestamp;
383 /**
384 * Operation type:
385 * 0 - context state change
386 * 1 - queue new work
387 * 2 - queue unwait sync object
388 * 3 - queue no more work
389 * 4 - queue wait sync object
390 */
391 u32 operation_type;
392 u32 reserved;
393 /** Operation data depends on operation type */
394 u64 operation_data[2];
395};
396
397/* Native fence log buffer types. */
398enum vpu_hws_native_fence_log_type {
399 VPU_HWS_NATIVE_FENCE_LOG_TYPE_WAITS = 1,
400 VPU_HWS_NATIVE_FENCE_LOG_TYPE_SIGNALS = 2
401};
402
403/** HWS native fence log buffer header. */
404struct vpu_hws_native_fence_log_header {
405 union {
406 struct {
407 /** Index of the first free entry in buffer. */
408 u32 first_free_entry_idx;
409 /**
410 * Incremented whenever the NPU wraps around the buffer and writes
411 * to the first entry again.
412 */
413 u32 wraparound_count;
414 };
415 /** Field allowing atomic update of both fields above. */
416 u64 atomic_wraparound_and_entry_idx;
417 };
418 /** Log buffer type, see enum vpu_hws_native_fence_log_type. */
419 u64 type;
420 /** Allocated number of entries in the log buffer. */
421 u64 entry_nb;
422 u64 reserved[2];
423};
424
425/** Native fence log operation types. */
426enum vpu_hws_native_fence_log_op {
427 VPU_HWS_NATIVE_FENCE_LOG_OP_SIGNAL_EXECUTED = 0,
428 VPU_HWS_NATIVE_FENCE_LOG_OP_WAIT_UNBLOCKED = 1
429};
430
431/** HWS native fence log entry. */
432struct vpu_hws_native_fence_log_entry {
433 /** Newly signaled/unblocked fence value. */
434 u64 fence_value;
435 /** Native fence object handle to which this operation belongs. */
436 u64 fence_handle;
437 /** Operation type, see enum vpu_hws_native_fence_log_op. */
438 u64 op_type;
439 u64 reserved_0;
440 /**
441 * VPU_HWS_NATIVE_FENCE_LOG_OP_WAIT_UNBLOCKED only: Timestamp at which fence
442 * wait was started (in NPU SysTime).
443 */
444 u64 fence_wait_start_ts;
445 u64 reserved_1;
446 /** Timestamp at which fence operation was completed (in NPU SysTime). */
447 u64 fence_end_ts;
448};
449
450/** Native fence log buffer. */
451struct vpu_hws_native_fence_log_buffer {
452 struct vpu_hws_native_fence_log_header header;
453 struct vpu_hws_native_fence_log_entry entry[];
454};
455
456/*
457 * Host <-> VPU IPC messages types.
458 */
459enum vpu_ipc_msg_type {
460 /** Unsupported command */
461 VPU_JSM_MSG_UNKNOWN = 0xFFFFFFFF,
462
463 /** IPC Host -> Device, base id for async commands */
464 VPU_JSM_MSG_ASYNC_CMD = 0x1100,
465 /**
466 * Reset engine. The NPU cancels all the jobs currently executing on the target
467 * engine making the engine become idle and then does a HW reset, before returning
468 * to the host.
469 * @see struct vpu_ipc_msg_payload_engine_reset
470 */
471 VPU_JSM_MSG_ENGINE_RESET = VPU_JSM_MSG_ASYNC_CMD,
472 /**
473 * Preempt engine. The NPU stops (preempts) all the jobs currently
474 * executing on the target engine making the engine become idle and ready to
475 * execute new jobs.
476 * NOTE: The NPU does not remove unstarted jobs (if any) from job queues of
477 * the target engine, but it stops processing them (until the queue doorbell
478 * is rung again); the host is responsible to reset the job queue, either
479 * after preemption or when resubmitting jobs to the queue.
480 * @see vpu_ipc_msg_payload_engine_preempt
481 */
482 VPU_JSM_MSG_ENGINE_PREEMPT = 0x1101,
483 /**
484 * OS scheduling doorbell register command
485 * @see vpu_ipc_msg_payload_register_db
486 */
487 VPU_JSM_MSG_REGISTER_DB = 0x1102,
488 /**
489 * OS scheduling doorbell unregister command
490 * @see vpu_ipc_msg_payload_unregister_db
491 */
492 VPU_JSM_MSG_UNREGISTER_DB = 0x1103,
493 /**
494 * Query engine heartbeat. Heartbeat is expected to increase monotonically
495 * and increase while work is being progressed by NPU.
496 * @see vpu_ipc_msg_payload_query_engine_hb
497 */
498 VPU_JSM_MSG_QUERY_ENGINE_HB = 0x1104,
499 VPU_JSM_MSG_GET_POWER_LEVEL_COUNT = 0x1105,
500 VPU_JSM_MSG_GET_POWER_LEVEL = 0x1106,
501 VPU_JSM_MSG_SET_POWER_LEVEL = 0x1107,
502 /* @deprecated */
503 VPU_JSM_MSG_METRIC_STREAMER_OPEN = 0x1108,
504 /* @deprecated */
505 VPU_JSM_MSG_METRIC_STREAMER_CLOSE = 0x1109,
506 /** Configure logging (used to modify configuration passed in boot params). */
507 VPU_JSM_MSG_TRACE_SET_CONFIG = 0x110a,
508 /** Return current logging configuration. */
509 VPU_JSM_MSG_TRACE_GET_CONFIG = 0x110b,
510 /**
511 * Get masks of destinations and HW components supported by the firmware
512 * (may vary between HW generations and FW compile
513 * time configurations)
514 */
515 VPU_JSM_MSG_TRACE_GET_CAPABILITY = 0x110c,
516 /** Get the name of a destination or HW component. */
517 VPU_JSM_MSG_TRACE_GET_NAME = 0x110d,
518 /**
519 * Release resource associated with host ssid . All jobs that belong to the host_ssid
520 * aborted and removed from internal scheduling queues. All doorbells assigned
521 * to the host_ssid are unregistered and any internal FW resources belonging to
522 * the host_ssid are released.
523 * @see vpu_ipc_msg_payload_ssid_release
524 */
525 VPU_JSM_MSG_SSID_RELEASE = 0x110e,
526 /**
527 * Start collecting metric data.
528 * @see vpu_jsm_metric_streamer_start
529 */
530 VPU_JSM_MSG_METRIC_STREAMER_START = 0x110f,
531 /**
532 * Stop collecting metric data. This command will return success if it is called
533 * for a metric stream that has already been stopped or was never started.
534 * @see vpu_jsm_metric_streamer_stop
535 */
536 VPU_JSM_MSG_METRIC_STREAMER_STOP = 0x1110,
537 /**
538 * Update current and next buffer for metric data collection. This command can
539 * also be used to request information about the number of collected samples
540 * and the amount of data written to the buffer.
541 * @see vpu_jsm_metric_streamer_update
542 */
543 VPU_JSM_MSG_METRIC_STREAMER_UPDATE = 0x1111,
544 /**
545 * Request description of selected metric groups and metric counters within
546 * each group. The VPU will write the description of groups and counters to
547 * the buffer specified in the command structure.
548 * @see vpu_jsm_metric_streamer_start
549 */
550 VPU_JSM_MSG_METRIC_STREAMER_INFO = 0x1112,
551 /**
552 * Control command: Priority band setup
553 * @see vpu_ipc_msg_payload_hws_priority_band_setup
554 */
555 VPU_JSM_MSG_SET_PRIORITY_BAND_SETUP = 0x1113,
556 /**
557 * Control command: Create command queue
558 * @see vpu_ipc_msg_payload_hws_create_cmdq
559 */
560 VPU_JSM_MSG_CREATE_CMD_QUEUE = 0x1114,
561 /**
562 * Control command: Destroy command queue
563 * @see vpu_ipc_msg_payload_hws_destroy_cmdq
564 */
565 VPU_JSM_MSG_DESTROY_CMD_QUEUE = 0x1115,
566 /**
567 * Control command: Set context scheduling properties
568 * @see vpu_ipc_msg_payload_hws_set_context_sched_properties
569 */
570 VPU_JSM_MSG_SET_CONTEXT_SCHED_PROPERTIES = 0x1116,
571 /**
572 * Register a doorbell to notify VPU of new work. The doorbell may later be
573 * deallocated or reassigned to another context.
574 * @see vpu_jsm_hws_register_db
575 */
576 VPU_JSM_MSG_HWS_REGISTER_DB = 0x1117,
577 /**
578 * Control command: Log buffer setting
579 * @see vpu_ipc_msg_payload_hws_set_scheduling_log
580 */
581 VPU_JSM_MSG_HWS_SET_SCHEDULING_LOG = 0x1118,
582 /**
583 * Control command: Suspend command queue.
584 * @see vpu_ipc_msg_payload_hws_suspend_cmdq
585 */
586 VPU_JSM_MSG_HWS_SUSPEND_CMDQ = 0x1119,
587 /**
588 * Control command: Resume command queue
589 * @see vpu_ipc_msg_payload_hws_resume_cmdq
590 */
591 VPU_JSM_MSG_HWS_RESUME_CMDQ = 0x111a,
592 /**
593 * Control command: Resume engine after reset
594 * @see vpu_ipc_msg_payload_hws_resume_engine
595 */
596 VPU_JSM_MSG_HWS_ENGINE_RESUME = 0x111b,
597 /**
598 * Control command: Enable survivability/DCT mode
599 * @see vpu_ipc_msg_payload_pwr_dct_control
600 */
601 VPU_JSM_MSG_DCT_ENABLE = 0x111c,
602 /**
603 * Control command: Disable survivability/DCT mode
604 * This command has no payload
605 */
606 VPU_JSM_MSG_DCT_DISABLE = 0x111d,
607 /**
608 * Dump VPU state. To be used for debug purposes only.
609 * This command has no payload.
610 * NOTE: Please introduce new ASYNC commands before this one.
611 */
612 VPU_JSM_MSG_STATE_DUMP = 0x11FF,
613
614 /** IPC Host -> Device, base id for general commands */
615 VPU_JSM_MSG_GENERAL_CMD = 0x1200,
616 /** Unsupported command */
617 VPU_JSM_MSG_BLOB_DEINIT_DEPRECATED = VPU_JSM_MSG_GENERAL_CMD,
618 /**
619 * Control dyndbg behavior by executing a dyndbg command; equivalent to
620 * Linux command:
621 * @verbatim echo '<dyndbg_cmd>' > <debugfs>/dynamic_debug/control @endverbatim
622 * @see vpu_ipc_msg_payload_dyndbg_control
623 */
624 VPU_JSM_MSG_DYNDBG_CONTROL = 0x1201,
625 /**
626 * Perform the save procedure for the D0i3 entry
627 */
628 VPU_JSM_MSG_PWR_D0I3_ENTER = 0x1202,
629
630 /**
631 * IPC Device -> Host, Job completion
632 * @see struct vpu_ipc_msg_payload_job_done
633 */
634 VPU_JSM_MSG_JOB_DONE = 0x2100,
635 /**
636 * IPC Device -> Host, Fence signalled
637 * @see vpu_ipc_msg_payload_native_fence_signalled
638 */
639 VPU_JSM_MSG_NATIVE_FENCE_SIGNALLED = 0x2101,
640
641 /* IPC Device -> Host, Async command completion */
642 VPU_JSM_MSG_ASYNC_CMD_DONE = 0x2200,
643 /**
644 * IPC Device -> Host, engine reset complete
645 * @see vpu_ipc_msg_payload_engine_reset_done
646 */
647 VPU_JSM_MSG_ENGINE_RESET_DONE = VPU_JSM_MSG_ASYNC_CMD_DONE,
648 /**
649 * Preempt complete message
650 * @see vpu_ipc_msg_payload_engine_preempt_done
651 */
652 VPU_JSM_MSG_ENGINE_PREEMPT_DONE = 0x2201,
653 VPU_JSM_MSG_REGISTER_DB_DONE = 0x2202,
654 VPU_JSM_MSG_UNREGISTER_DB_DONE = 0x2203,
655 /**
656 * Response to query engine heartbeat.
657 * @see vpu_ipc_msg_payload_query_engine_hb_done
658 */
659 VPU_JSM_MSG_QUERY_ENGINE_HB_DONE = 0x2204,
660 VPU_JSM_MSG_GET_POWER_LEVEL_COUNT_DONE = 0x2205,
661 VPU_JSM_MSG_GET_POWER_LEVEL_DONE = 0x2206,
662 VPU_JSM_MSG_SET_POWER_LEVEL_DONE = 0x2207,
663 /* @deprecated */
664 VPU_JSM_MSG_METRIC_STREAMER_OPEN_DONE = 0x2208,
665 /* @deprecated */
666 VPU_JSM_MSG_METRIC_STREAMER_CLOSE_DONE = 0x2209,
667 /** Response to VPU_JSM_MSG_TRACE_SET_CONFIG. */
668 VPU_JSM_MSG_TRACE_SET_CONFIG_RSP = 0x220a,
669 /** Response to VPU_JSM_MSG_TRACE_GET_CONFIG. */
670 VPU_JSM_MSG_TRACE_GET_CONFIG_RSP = 0x220b,
671 /** Response to VPU_JSM_MSG_TRACE_GET_CAPABILITY. */
672 VPU_JSM_MSG_TRACE_GET_CAPABILITY_RSP = 0x220c,
673 /** Response to VPU_JSM_MSG_TRACE_GET_NAME. */
674 VPU_JSM_MSG_TRACE_GET_NAME_RSP = 0x220d,
675 /**
676 * Response to VPU_JSM_MSG_SSID_RELEASE.
677 * @see vpu_ipc_msg_payload_ssid_release
678 */
679 VPU_JSM_MSG_SSID_RELEASE_DONE = 0x220e,
680 /**
681 * Response to VPU_JSM_MSG_METRIC_STREAMER_START.
682 * VPU will return an error result if metric collection cannot be started,
683 * e.g. when the specified metric mask is invalid.
684 * @see vpu_jsm_metric_streamer_done
685 */
686 VPU_JSM_MSG_METRIC_STREAMER_START_DONE = 0x220f,
687 /**
688 * Response to VPU_JSM_MSG_METRIC_STREAMER_STOP.
689 * Returns information about collected metric data.
690 * @see vpu_jsm_metric_streamer_done
691 */
692 VPU_JSM_MSG_METRIC_STREAMER_STOP_DONE = 0x2210,
693 /**
694 * Response to VPU_JSM_MSG_METRIC_STREAMER_UPDATE.
695 * Returns information about collected metric data.
696 * @see vpu_jsm_metric_streamer_done
697 */
698 VPU_JSM_MSG_METRIC_STREAMER_UPDATE_DONE = 0x2211,
699 /**
700 * Response to VPU_JSM_MSG_METRIC_STREAMER_INFO.
701 * Returns a description of the metric groups and metric counters.
702 * @see vpu_jsm_metric_streamer_done
703 */
704 VPU_JSM_MSG_METRIC_STREAMER_INFO_DONE = 0x2212,
705 /**
706 * Asynchronous event sent from the VPU to the host either when the current
707 * metric buffer is full or when the VPU has collected a multiple of
708 * @ref vpu_jsm_metric_streamer_start::notify_sample_count samples as indicated
709 * through the start command (VPU_JSM_MSG_METRIC_STREAMER_START). Returns
710 * information about collected metric data.
711 * @see vpu_jsm_metric_streamer_done
712 */
713 VPU_JSM_MSG_METRIC_STREAMER_NOTIFICATION = 0x2213,
714 /**
715 * Response to control command: Priority band setup
716 * @see vpu_ipc_msg_payload_hws_priority_band_setup
717 */
718 VPU_JSM_MSG_SET_PRIORITY_BAND_SETUP_RSP = 0x2214,
719 /**
720 * Response to control command: Create command queue
721 * @see vpu_ipc_msg_payload_hws_create_cmdq_rsp
722 */
723 VPU_JSM_MSG_CREATE_CMD_QUEUE_RSP = 0x2215,
724 /**
725 * Response to control command: Destroy command queue
726 * @see vpu_ipc_msg_payload_hws_destroy_cmdq
727 */
728 VPU_JSM_MSG_DESTROY_CMD_QUEUE_RSP = 0x2216,
729 /**
730 * Response to control command: Set context scheduling properties
731 * @see vpu_ipc_msg_payload_hws_set_context_sched_properties
732 */
733 VPU_JSM_MSG_SET_CONTEXT_SCHED_PROPERTIES_RSP = 0x2217,
734 /**
735 * Response to control command: Log buffer setting
736 * @see vpu_ipc_msg_payload_hws_set_scheduling_log
737 */
738 VPU_JSM_MSG_HWS_SET_SCHEDULING_LOG_RSP = 0x2218,
739 /**
740 * IPC Device -> Host, HWS notify index entry of log buffer written
741 * @see vpu_ipc_msg_payload_hws_scheduling_log_notification
742 */
743 VPU_JSM_MSG_HWS_SCHEDULING_LOG_NOTIFICATION = 0x2219,
744 /**
745 * IPC Device -> Host, HWS completion of a context suspend request
746 * @see vpu_ipc_msg_payload_hws_suspend_cmdq
747 */
748 VPU_JSM_MSG_HWS_SUSPEND_CMDQ_DONE = 0x221a,
749 /**
750 * Response to control command: Resume command queue
751 * @see vpu_ipc_msg_payload_hws_resume_cmdq
752 */
753 VPU_JSM_MSG_HWS_RESUME_CMDQ_RSP = 0x221b,
754 /**
755 * Response to control command: Resume engine command response
756 * @see vpu_ipc_msg_payload_hws_resume_engine
757 */
758 VPU_JSM_MSG_HWS_RESUME_ENGINE_DONE = 0x221c,
759 /**
760 * Response to control command: Enable survivability/DCT mode
761 * This command has no payload
762 */
763 VPU_JSM_MSG_DCT_ENABLE_DONE = 0x221d,
764 /**
765 * Response to control command: Disable survivability/DCT mode
766 * This command has no payload
767 */
768 VPU_JSM_MSG_DCT_DISABLE_DONE = 0x221e,
769 /**
770 * Response to state dump control command.
771 * This command has no payload.
772 * NOTE: Please introduce new ASYNC responses before this one.
773 */
774 VPU_JSM_MSG_STATE_DUMP_RSP = 0x22FF,
775
776 /* IPC Device -> Host, General command completion */
777 VPU_JSM_MSG_GENERAL_CMD_DONE = 0x2300,
778 VPU_JSM_MSG_BLOB_DEINIT_DONE = VPU_JSM_MSG_GENERAL_CMD_DONE,
779 /** Response to VPU_JSM_MSG_DYNDBG_CONTROL. */
780 VPU_JSM_MSG_DYNDBG_CONTROL_RSP = 0x2301,
781 /**
782 * Acknowledgment of completion of the save procedure initiated by
783 * VPU_JSM_MSG_PWR_D0I3_ENTER
784 */
785 VPU_JSM_MSG_PWR_D0I3_ENTER_DONE = 0x2302,
786};
787
788enum vpu_ipc_msg_status { VPU_JSM_MSG_FREE, VPU_JSM_MSG_ALLOCATED };
789
790/**
791 * Engine reset request payload
792 * @see VPU_JSM_MSG_ENGINE_RESET
793 */
794struct vpu_ipc_msg_payload_engine_reset {
795 /** Engine to be reset. */
796 u32 engine_idx;
797 /** Reserved */
798 u32 reserved_0;
799};
800
801/**
802 * Engine preemption request struct
803 * @see VPU_JSM_MSG_ENGINE_PREEMPT
804 */
805struct vpu_ipc_msg_payload_engine_preempt {
806 /** Engine to be preempted. */
807 u32 engine_idx;
808 /** ID of the preemption request. */
809 u32 preempt_id;
810};
811
812/**
813 * Register doorbell command structure.
814 * This structure supports doorbell registration for only OS scheduling.
815 * @see VPU_JSM_MSG_REGISTER_DB
816 */
817struct vpu_ipc_msg_payload_register_db {
818 /** Index of the doorbell to register. */
819 u32 db_idx;
820 /** Reserved */
821 u32 reserved_0;
822 /** Virtual address in Global GTT pointing to the start of job queue. */
823 u64 jobq_base;
824 /** Size of the job queue in bytes. */
825 u32 jobq_size;
826 /** Host sub-stream ID for the context assigned to the doorbell. */
827 u32 host_ssid;
828};
829
830/**
831 * Unregister doorbell command structure.
832 * Request structure to unregister a doorbell for both HW and OS scheduling.
833 * @see VPU_JSM_MSG_UNREGISTER_DB
834 */
835struct vpu_ipc_msg_payload_unregister_db {
836 /** Index of the doorbell to unregister. */
837 u32 db_idx;
838 /** Reserved */
839 u32 reserved_0;
840};
841
842/**
843 * Heartbeat request structure
844 * @see VPU_JSM_MSG_QUERY_ENGINE_HB
845 */
846struct vpu_ipc_msg_payload_query_engine_hb {
847 /** Engine to return heartbeat value. */
848 u32 engine_idx;
849 /** Reserved */
850 u32 reserved_0;
851};
852
853struct vpu_ipc_msg_payload_power_level {
854 /**
855 * Requested power level. The power level value is in the
856 * range [0, power_level_count-1] where power_level_count
857 * is the number of available power levels as returned by
858 * the get power level count command. A power level of 0
859 * corresponds to the maximum possible power level, while
860 * power_level_count-1 corresponds to the minimum possible
861 * power level. Values outside of this range are not
862 * considered to be valid.
863 */
864 u32 power_level;
865 /* Reserved */
866 u32 reserved_0;
867};
868
869/**
870 * Structure for requesting ssid release
871 * @see VPU_JSM_MSG_SSID_RELEASE
872 */
873struct vpu_ipc_msg_payload_ssid_release {
874 /** Host sub-stream ID for the context to be released. */
875 u32 host_ssid;
876 /** Reserved */
877 u32 reserved_0;
878};
879
880/**
881 * @brief Metric streamer start command structure.
882 * This structure is also used with VPU_JSM_MSG_METRIC_STREAMER_INFO to request metric
883 * groups and metric counters description from the firmware.
884 * @see VPU_JSM_MSG_METRIC_STREAMER_START
885 * @see VPU_JSM_MSG_METRIC_STREAMER_INFO
886 */
887struct vpu_jsm_metric_streamer_start {
888 /**
889 * Bitmask to select the desired metric groups.
890 * A metric group can belong only to one metric streamer instance at a time.
891 * Since each metric streamer instance has a unique set of metric groups, it
892 * can also identify a metric streamer instance if more than one instance was
893 * started. If the VPU device does not support multiple metric streamer instances,
894 * then VPU_JSM_MSG_METRIC_STREAMER_START will return an error even if the second
895 * instance has different groups to the first.
896 */
897 u64 metric_group_mask;
898 /** Sampling rate in nanoseconds. */
899 u64 sampling_rate;
900 /**
901 * If > 0 the VPU will send a VPU_JSM_MSG_METRIC_STREAMER_NOTIFICATION message
902 * after every @ref notify_sample_count samples is collected or dropped by the VPU.
903 * If set to UINT_MAX the VPU will only generate a notification when the metric
904 * buffer is full. If set to 0 the VPU will never generate a notification.
905 */
906 u32 notify_sample_count;
907 u32 reserved_0;
908 /**
909 * Address and size of the buffer where the VPU will write metric data. The
910 * VPU writes all counters from enabled metric groups one after another. If
911 * there is no space left to write data at the next sample period the VPU
912 * will switch to the next buffer (@ref next_buffer_addr) and will optionally
913 * send a notification to the host driver if @ref notify_sample_count is non-zero.
914 * If @ref next_buffer_addr is NULL the VPU will stop collecting metric data.
915 */
916 u64 buffer_addr;
917 u64 buffer_size;
918 /**
919 * Address and size of the next buffer to write metric data to after the initial
920 * buffer is full. If the address is NULL the VPU will stop collecting metric
921 * data.
922 */
923 u64 next_buffer_addr;
924 u64 next_buffer_size;
925};
926
927/**
928 * @brief Metric streamer stop command structure.
929 * @see VPU_JSM_MSG_METRIC_STREAMER_STOP
930 */
931struct vpu_jsm_metric_streamer_stop {
932 /** Bitmask to select the desired metric groups. */
933 u64 metric_group_mask;
934};
935
936/**
937 * Provide VPU FW with buffers to write metric data.
938 * @see VPU_JSM_MSG_METRIC_STREAMER_UPDATE
939 */
940struct vpu_jsm_metric_streamer_update {
941 /** Metric group mask that identifies metric streamer instance. */
942 u64 metric_group_mask;
943 /**
944 * Address and size of the buffer where the VPU will write metric data.
945 * This member dictates how the update operation should perform:
946 * 1. client needs information about the number of collected samples and the
947 * amount of data written to the current buffer
948 * 2. client wants to switch to a new buffer
949 *
950 * Case 1. is identified by the buffer address being 0 or the same as the
951 * currently used buffer address. In this case the buffer size is ignored and
952 * the size of the current buffer is unchanged. The VPU will return an update
953 * in the vpu_jsm_metric_streamer_done structure. The internal writing position
954 * into the buffer is not changed.
955 *
956 * Case 2. is identified by the address being non-zero and differs from the
957 * current buffer address. The VPU will immediately switch data collection to
958 * the new buffer. Then the VPU will return an update in the
959 * vpu_jsm_metric_streamer_done structure.
960 */
961 u64 buffer_addr;
962 u64 buffer_size;
963 /**
964 * Address and size of the next buffer to write metric data after the initial
965 * buffer is full. If the address is NULL the VPU will stop collecting metric
966 * data but will continue to record dropped samples.
967 *
968 * Note that there is a hazard possible if both buffer_addr and the next_buffer_addr
969 * are non-zero in same update request. It is the host's responsibility to ensure
970 * that both addresses make sense even if the VPU just switched to writing samples
971 * from the current to the next buffer.
972 */
973 u64 next_buffer_addr;
974 u64 next_buffer_size;
975};
976
977/**
978 * Device -> host job completion message.
979 * @see VPU_JSM_MSG_JOB_DONE
980 */
981struct vpu_ipc_msg_payload_job_done {
982 /** Engine to which the job was submitted. */
983 u32 engine_idx;
984 /** Index of the doorbell to which the job was submitted */
985 u32 db_idx;
986 /** ID of the completed job */
987 u32 job_id;
988 /** Status of the completed job */
989 u32 job_status;
990 /** Host SSID */
991 u32 host_ssid;
992 /** Zero Padding */
993 u32 reserved_0;
994 /** Command queue id */
995 u64 cmdq_id;
996};
997
998/**
999 * Notification message upon native fence signalling.
1000 * @see VPU_JSM_MSG_NATIVE_FENCE_SIGNALLED
1001 */
1002struct vpu_ipc_msg_payload_native_fence_signalled {
1003 /** Engine ID. */
1004 u32 engine_idx;
1005 /** Host SSID. */
1006 u32 host_ssid;
1007 /** CMDQ ID */
1008 u64 cmdq_id;
1009 /** Fence object handle. */
1010 u64 fence_handle;
1011};
1012
1013/**
1014 * vpu_ipc_msg_payload_engine_reset_done will contain an array of this structure
1015 * which contains which queues caused reset if FW was able to detect any error.
1016 * @see vpu_ipc_msg_payload_engine_reset_done
1017 */
1018struct vpu_jsm_engine_reset_context {
1019 /** Host SSID */
1020 u32 host_ssid;
1021 /** Zero Padding */
1022 u32 reserved_0;
1023 /** Command queue id */
1024 u64 cmdq_id;
1025 /** See VPU_ENGINE_RESET_CONTEXT_* defines */
1026 u64 flags;
1027};
1028
1029/**
1030 * Engine reset response.
1031 * @see VPU_JSM_MSG_ENGINE_RESET_DONE
1032 */
1033struct vpu_ipc_msg_payload_engine_reset_done {
1034 /** Engine ordinal */
1035 u32 engine_idx;
1036 /** Number of impacted contexts */
1037 u32 num_impacted_contexts;
1038 /** Array of impacted command queue ids and their flags */
1039 struct vpu_jsm_engine_reset_context
1040 impacted_contexts[VPU_MAX_ENGINE_RESET_IMPACTED_CONTEXTS];
1041};
1042
1043/**
1044 * Preemption response struct
1045 * @see VPU_JSM_MSG_ENGINE_PREEMPT_DONE
1046 */
1047struct vpu_ipc_msg_payload_engine_preempt_done {
1048 /** Engine preempted. */
1049 u32 engine_idx;
1050 /** ID of the preemption request. */
1051 u32 preempt_id;
1052};
1053
1054/**
1055 * Response structure for register doorbell command for both OS
1056 * and HW scheduling.
1057 * @see VPU_JSM_MSG_REGISTER_DB
1058 * @see VPU_JSM_MSG_HWS_REGISTER_DB
1059 */
1060struct vpu_ipc_msg_payload_register_db_done {
1061 /* Index of the registered doorbell. */
1062 u32 db_idx;
1063 /* Reserved */
1064 u32 reserved_0;
1065};
1066
1067/**
1068 * Response structure for unregister doorbell command for both OS
1069 * and HW scheduling.
1070 * @see VPU_JSM_MSG_UNREGISTER_DB
1071 */
1072struct vpu_ipc_msg_payload_unregister_db_done {
1073 /* Index of the unregistered doorbell. */
1074 u32 db_idx;
1075 /* Reserved */
1076 u32 reserved_0;
1077};
1078
1079/**
1080 * Structure for heartbeat response
1081 * @see VPU_JSM_MSG_QUERY_ENGINE_HB_DONE
1082 */
1083struct vpu_ipc_msg_payload_query_engine_hb_done {
1084 /** Engine returning heartbeat value. */
1085 u32 engine_idx;
1086 /** Reserved */
1087 u32 reserved_0;
1088 /** Heartbeat value. */
1089 u64 heartbeat;
1090};
1091
1092struct vpu_ipc_msg_payload_get_power_level_count_done {
1093 /**
1094 * Number of supported power levels. The maximum possible
1095 * value of power_level_count is 16 but this may vary across
1096 * implementations.
1097 */
1098 u32 power_level_count;
1099 /* Reserved */
1100 u32 reserved_0;
1101 /**
1102 * Power consumption limit for each supported power level in
1103 * [0-100%] range relative to power level 0.
1104 */
1105 u8 power_limit[16];
1106};
1107
1108/**
1109 * HWS priority band setup request / response
1110 * @see VPU_JSM_MSG_SET_PRIORITY_BAND_SETUP
1111 */
1112struct vpu_ipc_msg_payload_hws_priority_band_setup {
1113 /*
1114 * Grace period in 100ns units when preempting another priority band for
1115 * this priority band
1116 */
1117 u32 grace_period[VPU_HWS_NUM_PRIORITY_BANDS];
1118 /*
1119 * Default quantum in 100ns units for scheduling across processes
1120 * within a priority band
1121 * Minimum value supported by NPU is 1ms (10000 in 100ns units).
1122 */
1123 u32 process_quantum[VPU_HWS_NUM_PRIORITY_BANDS];
1124 /*
1125 * Default grace period in 100ns units for processes that preempt each
1126 * other within a priority band
1127 */
1128 u32 process_grace_period[VPU_HWS_NUM_PRIORITY_BANDS];
1129 /*
1130 * For normal priority band, specifies the target VPU percentage
1131 * in situations when it's starved by the focus band.
1132 */
1133 u32 normal_band_percentage;
1134 /*
1135 * TDR timeout value in milliseconds. Default value of 0 meaning no timeout.
1136 */
1137 u32 tdr_timeout;
1138 /* Non-interactive queue timeout for no progress of heartbeat in milliseconds.
1139 * Default value of 0 meaning no timeout.
1140 */
1141 u32 non_interactive_no_progress_timeout;
1142 /*
1143 * Non-interactive queue upper limit timeout value in milliseconds. Default
1144 * value of 0 meaning no timeout.
1145 */
1146 u32 non_interactive_timeout;
1147};
1148
1149/**
1150 * @brief HWS create command queue request.
1151 * Host will create a command queue via this command.
1152 * Note: Cmdq group is a handle of an object which
1153 * may contain one or more command queues.
1154 * @see VPU_JSM_MSG_CREATE_CMD_QUEUE
1155 */
1156struct vpu_ipc_msg_payload_hws_create_cmdq {
1157 /* Process id */
1158 u64 process_id;
1159 /* Host SSID */
1160 u32 host_ssid;
1161 /* Engine for which queue is being created */
1162 u32 engine_idx;
1163 /* Cmdq group: only used for HWS logging of state changes */
1164 u64 cmdq_group;
1165 /* Command queue id */
1166 u64 cmdq_id;
1167 /* Command queue base */
1168 u64 cmdq_base;
1169 /* Command queue size */
1170 u32 cmdq_size;
1171 /* Zero padding */
1172 u32 reserved_0;
1173};
1174
1175/**
1176 * HWS create command queue response.
1177 * @see VPU_JSM_MSG_CREATE_CMD_QUEUE_RSP
1178 */
1179struct vpu_ipc_msg_payload_hws_create_cmdq_rsp {
1180 /** Process id */
1181 u64 process_id;
1182 /** Host SSID */
1183 u32 host_ssid;
1184 /** Engine for which queue is being created */
1185 u32 engine_idx;
1186 /** Command queue group */
1187 u64 cmdq_group;
1188 /** Command queue id */
1189 u64 cmdq_id;
1190};
1191
1192/**
1193 * HWS destroy command queue request / response
1194 * @see VPU_JSM_MSG_DESTROY_CMD_QUEUE
1195 * @see VPU_JSM_MSG_DESTROY_CMD_QUEUE_RSP
1196 */
1197struct vpu_ipc_msg_payload_hws_destroy_cmdq {
1198 /** Host SSID */
1199 u32 host_ssid;
1200 /** Zero Padding */
1201 u32 reserved;
1202 /** Command queue id */
1203 u64 cmdq_id;
1204};
1205
1206/**
1207 * HWS set context scheduling properties request / response
1208 * @see VPU_JSM_MSG_SET_CONTEXT_SCHED_PROPERTIES
1209 * @see VPU_JSM_MSG_SET_CONTEXT_SCHED_PROPERTIES_RSP
1210 */
1211struct vpu_ipc_msg_payload_hws_set_context_sched_properties {
1212 /** Host SSID */
1213 u32 host_ssid;
1214 /** Zero Padding */
1215 u32 reserved_0;
1216 /** Command queue id */
1217 u64 cmdq_id;
1218 /**
1219 * Priority band to assign to work of this context.
1220 * Available priority bands: @see enum vpu_job_scheduling_priority_band
1221 */
1222 u32 priority_band;
1223 /** Inside realtime band assigns a further priority */
1224 u32 realtime_priority_level;
1225 /** Priority relative to other contexts in the same process */
1226 s32 in_process_priority;
1227 /** Zero padding / Reserved */
1228 u32 reserved_1;
1229 /**
1230 * Context quantum relative to other contexts of same priority in the same process
1231 * Minimum value supported by NPU is 1ms (10000 in 100ns units).
1232 */
1233 u64 context_quantum;
1234 /** Grace period when preempting context of the same priority within the same process */
1235 u64 grace_period_same_priority;
1236 /** Grace period when preempting context of a lower priority within the same process */
1237 u64 grace_period_lower_priority;
1238};
1239
1240/**
1241 * Register doorbell command structure.
1242 * This structure supports doorbell registration for both HW and OS scheduling.
1243 * Note: Queue base and size are added here so that the same structure can be used for
1244 * OS scheduling and HW scheduling. For OS scheduling, cmdq_id will be ignored
1245 * and cmdq_base and cmdq_size will be used. For HW scheduling, cmdq_base and cmdq_size will be
1246 * ignored and cmdq_id is used.
1247 * @see VPU_JSM_MSG_HWS_REGISTER_DB
1248 */
1249struct vpu_jsm_hws_register_db {
1250 /** Index of the doorbell to register. */
1251 u32 db_id;
1252 /** Host sub-stream ID for the context assigned to the doorbell. */
1253 u32 host_ssid;
1254 /** ID of the command queue associated with the doorbell. */
1255 u64 cmdq_id;
1256 /** Virtual address pointing to the start of command queue. */
1257 u64 cmdq_base;
1258 /** Size of the command queue in bytes. */
1259 u64 cmdq_size;
1260};
1261
1262/**
1263 * Structure to set another buffer to be used for scheduling-related logging.
1264 * The size of the logging buffer and the number of entries is defined as part of the
1265 * buffer itself as described next.
1266 * The log buffer received from the host is made up of;
1267 * - header: 32 bytes in size, as shown in @ref vpu_hws_log_buffer_header.
1268 * The header contains the number of log entries in the buffer.
1269 * - log entry: 0 to n-1, each log entry is 32 bytes in size, as shown in
1270 * @ref vpu_hws_log_buffer_entry.
1271 * The entry contains the VPU timestamp, operation type and data.
1272 * The host should provide the notify index value of log buffer to VPU. This is a
1273 * value defined within the log buffer and when written to will generate the
1274 * scheduling log notification.
1275 * The host should set engine_idx and vpu_log_buffer_va to 0 to disable logging
1276 * for a particular engine.
1277 * VPU will handle one log buffer for each of supported engines.
1278 * VPU should allow the logging to consume one host_ssid.
1279 * @see VPU_JSM_MSG_HWS_SET_SCHEDULING_LOG
1280 * @see VPU_JSM_MSG_HWS_SET_SCHEDULING_LOG_RSP
1281 * @see VPU_JSM_MSG_HWS_SCHEDULING_LOG_NOTIFICATION
1282 */
1283struct vpu_ipc_msg_payload_hws_set_scheduling_log {
1284 /** Engine ordinal */
1285 u32 engine_idx;
1286 /** Host SSID */
1287 u32 host_ssid;
1288 /**
1289 * VPU log buffer virtual address.
1290 * Set to 0 to disable logging for this engine.
1291 */
1292 u64 vpu_log_buffer_va;
1293 /**
1294 * Notify index of log buffer. VPU_JSM_MSG_HWS_SCHEDULING_LOG_NOTIFICATION
1295 * is generated when an event log is written to this index.
1296 */
1297 u64 notify_index;
1298 /**
1299 * Field is now deprecated, will be removed when KMD is updated to support removal
1300 */
1301 u32 enable_extra_events;
1302 /** Zero Padding */
1303 u32 reserved_0;
1304};
1305
1306/**
1307 * The scheduling log notification is generated by VPU when it writes
1308 * an event into the log buffer at the notify_index. VPU notifies host with
1309 * VPU_JSM_MSG_HWS_SCHEDULING_LOG_NOTIFICATION. This is an asynchronous
1310 * message from VPU to host.
1311 * @see VPU_JSM_MSG_HWS_SCHEDULING_LOG_NOTIFICATION
1312 * @see VPU_JSM_MSG_HWS_SET_SCHEDULING_LOG
1313 */
1314struct vpu_ipc_msg_payload_hws_scheduling_log_notification {
1315 /** Engine ordinal */
1316 u32 engine_idx;
1317 /** Zero Padding */
1318 u32 reserved_0;
1319};
1320
1321/**
1322 * HWS suspend command queue request and done structure.
1323 * Host will request the suspend of contexts and VPU will;
1324 * - Suspend all work on this context
1325 * - Preempt any running work
1326 * - Asynchronously perform the above and return success immediately once
1327 * all items above are started successfully
1328 * - Notify the host of completion of these operations via
1329 * VPU_JSM_MSG_HWS_SUSPEND_CMDQ_DONE
1330 * - Reject any other context operations on a context with an in-flight
1331 * suspend request running
1332 * Same structure used when VPU notifies host of completion of a context suspend
1333 * request. The ids and suspend fence value reported in this command will match
1334 * the one in the request from the host to suspend the context. Once suspend is
1335 * complete, VPU will not access any data relating to this command queue until
1336 * it is resumed.
1337 * @see VPU_JSM_MSG_HWS_SUSPEND_CMDQ
1338 * @see VPU_JSM_MSG_HWS_SUSPEND_CMDQ_DONE
1339 */
1340struct vpu_ipc_msg_payload_hws_suspend_cmdq {
1341 /** Host SSID */
1342 u32 host_ssid;
1343 /** Zero Padding */
1344 u32 reserved_0;
1345 /** Command queue id */
1346 u64 cmdq_id;
1347 /**
1348 * Suspend fence value - reported by the VPU suspend context
1349 * completed once suspend is complete.
1350 */
1351 u64 suspend_fence_value;
1352};
1353
1354/**
1355 * HWS Resume command queue request / response structure.
1356 * Host will request the resume of a context;
1357 * - VPU will resume all work on this context
1358 * - Scheduler will allow this context to be scheduled
1359 * @see VPU_JSM_MSG_HWS_RESUME_CMDQ
1360 * @see VPU_JSM_MSG_HWS_RESUME_CMDQ_RSP
1361 */
1362struct vpu_ipc_msg_payload_hws_resume_cmdq {
1363 /** Host SSID */
1364 u32 host_ssid;
1365 /** Zero Padding */
1366 u32 reserved_0;
1367 /** Command queue id */
1368 u64 cmdq_id;
1369};
1370
1371/**
1372 * HWS Resume engine request / response structure.
1373 * After a HWS engine reset, all scheduling is stopped on VPU until an engine resume.
1374 * Host shall send this command to resume scheduling of any valid queue.
1375 * @see VPU_JSM_MSG_HWS_ENGINE_RESUME
1376 * @see VPU_JSM_MSG_HWS_RESUME_ENGINE_DONE
1377 */
1378struct vpu_ipc_msg_payload_hws_resume_engine {
1379 /** Engine to be resumed */
1380 u32 engine_idx;
1381 /** Reserved */
1382 u32 reserved_0;
1383};
1384
1385/**
1386 * Payload for VPU_JSM_MSG_TRACE_SET_CONFIG[_RSP] and
1387 * VPU_JSM_MSG_TRACE_GET_CONFIG_RSP messages.
1388 *
1389 * The payload is interpreted differently depending on the type of message:
1390 *
1391 * - For VPU_JSM_MSG_TRACE_SET_CONFIG, the payload specifies the desired
1392 * logging configuration to be set.
1393 *
1394 * - For VPU_JSM_MSG_TRACE_SET_CONFIG_RSP, the payload reports the logging
1395 * configuration that was set after a VPU_JSM_MSG_TRACE_SET_CONFIG request.
1396 * The host can compare this payload with the one it sent in the
1397 * VPU_JSM_MSG_TRACE_SET_CONFIG request to check whether or not the
1398 * configuration was set as desired.
1399 *
1400 * - VPU_JSM_MSG_TRACE_GET_CONFIG_RSP, the payload reports the current logging
1401 * configuration.
1402 */
1403struct vpu_ipc_msg_payload_trace_config {
1404 /**
1405 * Logging level (currently set or to be set); see 'mvLog_t' enum for
1406 * acceptable values. The specified logging level applies to all
1407 * destinations and HW components
1408 */
1409 u32 trace_level;
1410 /**
1411 * Bitmask of logging destinations (currently enabled or to be enabled);
1412 * bitwise OR of values defined in logging_destination enum.
1413 */
1414 u32 trace_destination_mask;
1415 /**
1416 * Bitmask of loggable HW components (currently enabled or to be enabled);
1417 * bitwise OR of values defined in loggable_hw_component enum.
1418 */
1419 u64 trace_hw_component_mask;
1420 u64 reserved_0; /**< Reserved for future extensions. */
1421};
1422
1423/**
1424 * Payload for VPU_JSM_MSG_TRACE_GET_CAPABILITY_RSP messages.
1425 */
1426struct vpu_ipc_msg_payload_trace_capability_rsp {
1427 u32 trace_destination_mask; /**< Bitmask of supported logging destinations. */
1428 u32 reserved_0;
1429 u64 trace_hw_component_mask; /**< Bitmask of supported loggable HW components. */
1430 u64 reserved_1; /**< Reserved for future extensions. */
1431};
1432
1433/**
1434 * Payload for VPU_JSM_MSG_TRACE_GET_NAME requests.
1435 */
1436struct vpu_ipc_msg_payload_trace_get_name {
1437 /**
1438 * The type of the entity to query name for; see logging_entity_type for
1439 * possible values.
1440 */
1441 u32 entity_type;
1442 u32 reserved_0;
1443 /**
1444 * The ID of the entity to query name for; possible values depends on the
1445 * entity type.
1446 */
1447 u64 entity_id;
1448};
1449
1450/**
1451 * Payload for VPU_JSM_MSG_TRACE_GET_NAME_RSP responses.
1452 */
1453struct vpu_ipc_msg_payload_trace_get_name_rsp {
1454 /**
1455 * The type of the entity whose name was queried; see logging_entity_type
1456 * for possible values.
1457 */
1458 u32 entity_type;
1459 u32 reserved_0;
1460 /**
1461 * The ID of the entity whose name was queried; possible values depends on
1462 * the entity type.
1463 */
1464 u64 entity_id;
1465 /** Reserved for future extensions. */
1466 u64 reserved_1;
1467 /** The name of the entity. */
1468 char entity_name[VPU_TRACE_ENTITY_NAME_MAX_LEN];
1469};
1470
1471/**
1472 * Data sent from the VPU to the host in all metric streamer response messages
1473 * and in asynchronous notification.
1474 * @see VPU_JSM_MSG_METRIC_STREAMER_START_DONE
1475 * @see VPU_JSM_MSG_METRIC_STREAMER_STOP_DONE
1476 * @see VPU_JSM_MSG_METRIC_STREAMER_UPDATE_DONE
1477 * @see VPU_JSM_MSG_METRIC_STREAMER_INFO_DONE
1478 * @see VPU_JSM_MSG_METRIC_STREAMER_NOTIFICATION
1479 */
1480struct vpu_jsm_metric_streamer_done {
1481 /** Metric group mask that identifies metric streamer instance. */
1482 u64 metric_group_mask;
1483 /**
1484 * Size in bytes of single sample - total size of all enabled counters.
1485 * Some VPU implementations may align sample_size to more than 8 bytes.
1486 */
1487 u32 sample_size;
1488 u32 reserved_0;
1489 /**
1490 * Number of samples collected since the metric streamer was started.
1491 * This will be 0 if the metric streamer was not started.
1492 */
1493 u32 samples_collected;
1494 /**
1495 * Number of samples dropped since the metric streamer was started. This
1496 * is incremented every time the metric streamer is not able to write
1497 * collected samples because the current buffer is full and there is no
1498 * next buffer to switch to.
1499 */
1500 u32 samples_dropped;
1501 /** Address of the buffer that contains the latest metric data. */
1502 u64 buffer_addr;
1503 /**
1504 * Number of bytes written into the metric data buffer. In response to the
1505 * VPU_JSM_MSG_METRIC_STREAMER_INFO request this field contains the size of
1506 * all group and counter descriptors. The size is updated even if the buffer
1507 * in the request was NULL or too small to hold descriptors of all counters
1508 */
1509 u64 bytes_written;
1510};
1511
1512/**
1513 * Metric group description placed in the metric buffer after successful completion
1514 * of the VPU_JSM_MSG_METRIC_STREAMER_INFO command. This is followed by one or more
1515 * @ref vpu_jsm_metric_counter_descriptor records.
1516 * @see VPU_JSM_MSG_METRIC_STREAMER_INFO
1517 */
1518struct vpu_jsm_metric_group_descriptor {
1519 /**
1520 * Offset to the next metric group (8-byte aligned). If this offset is 0 this
1521 * is the last descriptor. The value of metric_info_size must be greater than
1522 * or equal to sizeof(struct vpu_jsm_metric_group_descriptor) + name_string_size
1523 * + description_string_size and must be 8-byte aligned.
1524 */
1525 u32 next_metric_group_info_offset;
1526 /**
1527 * Offset to the first metric counter description record (8-byte aligned).
1528 * @see vpu_jsm_metric_counter_descriptor
1529 */
1530 u32 next_metric_counter_info_offset;
1531 /** Index of the group. This corresponds to bit index in metric_group_mask. */
1532 u32 group_id;
1533 /** Number of counters in the metric group. */
1534 u32 num_counters;
1535 /** Data size for all counters, must be a multiple of 8 bytes.*/
1536 u32 metric_group_data_size;
1537 /**
1538 * Metric group domain number. Cannot use multiple, simultaneous metric groups
1539 * from the same domain.
1540 */
1541 u32 domain;
1542 /**
1543 * Counter name string size. The string must include a null termination character.
1544 * The FW may use a fixed size name or send a different name for each counter.
1545 * If the VPU uses fixed size strings, all characters from the end of the name
1546 * to the of the fixed size character array must be zeroed.
1547 */
1548 u32 name_string_size;
1549 /** Counter description string size, @see name_string_size */
1550 u32 description_string_size;
1551 u64 reserved_0;
1552 /**
1553 * Right after this structure, the VPU writes name and description of
1554 * the metric group.
1555 */
1556};
1557
1558/**
1559 * Metric counter description, placed in the buffer after vpu_jsm_metric_group_descriptor.
1560 * @see VPU_JSM_MSG_METRIC_STREAMER_INFO
1561 */
1562struct vpu_jsm_metric_counter_descriptor {
1563 /**
1564 * Offset to the next counter in a group (8-byte aligned). If this offset is
1565 * 0 this is the last counter in the group.
1566 */
1567 u32 next_metric_counter_info_offset;
1568 /**
1569 * Offset to the counter data from the start of samples in this metric group.
1570 * Note that metric_data_offset % metric_data_size must be 0.
1571 */
1572 u32 metric_data_offset;
1573 /** Size of the metric counter data in bytes. */
1574 u32 metric_data_size;
1575 /** Metric type, see Level Zero API for definitions. */
1576 u32 tier;
1577 /** Metric type, see set_metric_type_t for definitions. */
1578 u32 metric_type;
1579 /** Metric type, see set_value_type_t for definitions. */
1580 u32 metric_value_type;
1581 /**
1582 * Counter name string size. The string must include a null termination character.
1583 * The FW may use a fixed size name or send a different name for each counter.
1584 * If the VPU uses fixed size strings, all characters from the end of the name
1585 * to the of the fixed size character array must be zeroed.
1586 */
1587 u32 name_string_size;
1588 /** Counter description string size, @see name_string_size */
1589 u32 description_string_size;
1590 /** Counter component name string size, @see name_string_size */
1591 u32 component_string_size;
1592 /** Counter string size, @see name_string_size */
1593 u32 units_string_size;
1594 u64 reserved_0;
1595 /**
1596 * Right after this structure, the VPU writes name, description
1597 * component and unit strings.
1598 */
1599};
1600
1601/**
1602 * Payload for @ref VPU_JSM_MSG_DYNDBG_CONTROL requests.
1603 *
1604 * VPU_JSM_MSG_DYNDBG_CONTROL requests are used to control the VPU FW dynamic debug
1605 * feature, which allows developers to selectively enable/disable code to obtain
1606 * additional FW information. This is equivalent to the dynamic debug functionality
1607 * provided by Linux. The host can control dynamic debug behavior by sending dyndbg
1608 * commands, using the same syntax as for Linux dynamic debug commands.
1609 *
1610 * @see https://www.kernel.org/doc/html/latest/admin-guide/dynamic-debug-howto.html.
1611 *
1612 * NOTE:
1613 * As the dynamic debug feature uses MVLOG messages to provide information, the host
1614 * must first set the logging level to MVLOG_DEBUG, using the @ref VPU_JSM_MSG_TRACE_SET_CONFIG
1615 * command.
1616 */
1617struct vpu_ipc_msg_payload_dyndbg_control {
1618 /**
1619 * Dyndbg command to be executed.
1620 */
1621 char dyndbg_cmd[VPU_DYNDBG_CMD_MAX_LEN];
1622};
1623
1624/**
1625 * Payload for VPU_JSM_MSG_PWR_D0I3_ENTER
1626 *
1627 * This is a bi-directional payload.
1628 */
1629struct vpu_ipc_msg_payload_pwr_d0i3_enter {
1630 /**
1631 * 0: VPU_JSM_MSG_PWR_D0I3_ENTER_DONE is not sent to the host driver
1632 * The driver will poll for D0i2 Idle state transitions.
1633 * 1: VPU_JSM_MSG_PWR_D0I3_ENTER_DONE is sent after VPU state save is complete
1634 */
1635 u32 send_response;
1636 u32 reserved_0;
1637};
1638
1639/**
1640 * Payload for @ref VPU_JSM_MSG_DCT_ENABLE message.
1641 *
1642 * Default values for DCT active/inactive times are 5.3ms and 30ms respectively,
1643 * corresponding to a 85% duty cycle. This payload allows the host to tune these
1644 * values according to application requirements.
1645 */
1646struct vpu_ipc_msg_payload_pwr_dct_control {
1647 /** Duty cycle active time in microseconds */
1648 u32 dct_active_us;
1649 /** Duty cycle inactive time in microseconds */
1650 u32 dct_inactive_us;
1651};
1652
1653/*
1654 * Payloads union, used to define complete message format.
1655 */
1656union vpu_ipc_msg_payload {
1657 struct vpu_ipc_msg_payload_engine_reset engine_reset;
1658 struct vpu_ipc_msg_payload_engine_preempt engine_preempt;
1659 struct vpu_ipc_msg_payload_register_db register_db;
1660 struct vpu_ipc_msg_payload_unregister_db unregister_db;
1661 struct vpu_ipc_msg_payload_query_engine_hb query_engine_hb;
1662 struct vpu_ipc_msg_payload_power_level power_level;
1663 struct vpu_jsm_metric_streamer_start metric_streamer_start;
1664 struct vpu_jsm_metric_streamer_stop metric_streamer_stop;
1665 struct vpu_jsm_metric_streamer_update metric_streamer_update;
1666 struct vpu_ipc_msg_payload_ssid_release ssid_release;
1667 struct vpu_jsm_hws_register_db hws_register_db;
1668 struct vpu_ipc_msg_payload_job_done job_done;
1669 struct vpu_ipc_msg_payload_native_fence_signalled native_fence_signalled;
1670 struct vpu_ipc_msg_payload_engine_reset_done engine_reset_done;
1671 struct vpu_ipc_msg_payload_engine_preempt_done engine_preempt_done;
1672 struct vpu_ipc_msg_payload_register_db_done register_db_done;
1673 struct vpu_ipc_msg_payload_unregister_db_done unregister_db_done;
1674 struct vpu_ipc_msg_payload_query_engine_hb_done query_engine_hb_done;
1675 struct vpu_ipc_msg_payload_get_power_level_count_done get_power_level_count_done;
1676 struct vpu_jsm_metric_streamer_done metric_streamer_done;
1677 struct vpu_ipc_msg_payload_trace_config trace_config;
1678 struct vpu_ipc_msg_payload_trace_capability_rsp trace_capability;
1679 struct vpu_ipc_msg_payload_trace_get_name trace_get_name;
1680 struct vpu_ipc_msg_payload_trace_get_name_rsp trace_get_name_rsp;
1681 struct vpu_ipc_msg_payload_dyndbg_control dyndbg_control;
1682 struct vpu_ipc_msg_payload_hws_priority_band_setup hws_priority_band_setup;
1683 struct vpu_ipc_msg_payload_hws_create_cmdq hws_create_cmdq;
1684 struct vpu_ipc_msg_payload_hws_create_cmdq_rsp hws_create_cmdq_rsp;
1685 struct vpu_ipc_msg_payload_hws_destroy_cmdq hws_destroy_cmdq;
1686 struct vpu_ipc_msg_payload_hws_set_context_sched_properties
1687 hws_set_context_sched_properties;
1688 struct vpu_ipc_msg_payload_hws_set_scheduling_log hws_set_scheduling_log;
1689 struct vpu_ipc_msg_payload_hws_scheduling_log_notification hws_scheduling_log_notification;
1690 struct vpu_ipc_msg_payload_hws_suspend_cmdq hws_suspend_cmdq;
1691 struct vpu_ipc_msg_payload_hws_resume_cmdq hws_resume_cmdq;
1692 struct vpu_ipc_msg_payload_hws_resume_engine hws_resume_engine;
1693 struct vpu_ipc_msg_payload_pwr_d0i3_enter pwr_d0i3_enter;
1694 struct vpu_ipc_msg_payload_pwr_dct_control pwr_dct_control;
1695};
1696
1697/**
1698 * Host <-> NPU IPC message base structure.
1699 *
1700 * NOTE: All instances of this object must be aligned on a 64B boundary
1701 * to allow proper handling of VPU cache operations.
1702 */
1703struct vpu_jsm_msg {
1704 /** Reserved */
1705 u64 reserved_0;
1706 /** Message type, see @ref vpu_ipc_msg_type. */
1707 u32 type;
1708 /** Buffer status, see @ref vpu_ipc_msg_status. */
1709 u32 status;
1710 /**
1711 * Request ID, provided by the host in a request message and passed
1712 * back by VPU in the response message.
1713 */
1714 u32 request_id;
1715 /** Request return code set by the VPU, see VPU_JSM_STATUS_* defines. */
1716 u32 result;
1717 u64 reserved_1;
1718 /** Message payload depending on message type, see vpu_ipc_msg_payload union. */
1719 union vpu_ipc_msg_payload payload;
1720};
1721
1722#pragma pack(pop)
1723
1724#endif
1725
1726///@}
1727

source code of linux/drivers/accel/ivpu/vpu_jsm_api.h