xref: /openbmc/linux/drivers/accel/ivpu/vpu_jsm_api.h (revision 98d41871)
1 /* SPDX-License-Identifier: MIT */
2 /*
3  * Copyright (C) 2020-2023 Intel Corporation
4  */
5 
6 /**
7  * @file
8  * @brief JSM shared definitions
9  *
10  * @ingroup Jsm
11  * @brief JSM shared definitions
12  * @{
13  */
14 #ifndef VPU_JSM_API_H
15 #define VPU_JSM_API_H
16 
17 /*
18  * Major version changes that break backward compatibility
19  */
20 #define VPU_JSM_API_VER_MAJOR 3
21 
22 /*
23  * Minor version changes when API backward compatibility is preserved.
24  */
25 #define VPU_JSM_API_VER_MINOR 0
26 
27 /*
28  * API header changed (field names, documentation, formatting) but API itself has not been changed
29  */
30 #define VPU_JSM_API_VER_PATCH 1
31 
32 /*
33  * Index in the API version table
34  */
35 #define VPU_JSM_API_VER_INDEX 4
36 
37 /*
38  * Number of Priority Bands for Hardware Scheduling
39  * Bands: RealTime, Focus, Normal, Idle
40  */
41 #define VPU_HWS_NUM_PRIORITY_BANDS 4
42 
43 /* Max number of impacted contexts that can be dealt with the engine reset command */
44 #define VPU_MAX_ENGINE_RESET_IMPACTED_CONTEXTS 3
45 
46 /** Pack the API structures for now, once alignment issues are fixed this can be removed */
47 #pragma pack(push, 1)
48 
49 /*
50  * Engine indexes.
51  */
52 #define VPU_ENGINE_COMPUTE 0
53 #define VPU_ENGINE_COPY	   1
54 #define VPU_ENGINE_NB	   2
55 
56 /*
57  * VPU status values.
58  */
59 #define VPU_JSM_STATUS_SUCCESS				 0x0U
60 #define VPU_JSM_STATUS_PARSING_ERR			 0x1U
61 #define VPU_JSM_STATUS_PROCESSING_ERR			 0x2U
62 #define VPU_JSM_STATUS_PREEMPTED			 0x3U
63 #define VPU_JSM_STATUS_ABORTED				 0x4U
64 #define VPU_JSM_STATUS_USER_CTX_VIOL_ERR		 0x5U
65 #define VPU_JSM_STATUS_GLOBAL_CTX_VIOL_ERR		 0x6U
66 #define VPU_JSM_STATUS_MVNCI_WRONG_INPUT_FORMAT		 0x7U
67 #define VPU_JSM_STATUS_MVNCI_UNSUPPORTED_NETWORK_ELEMENT 0x8U
68 #define VPU_JSM_STATUS_MVNCI_INVALID_HANDLE		 0x9U
69 #define VPU_JSM_STATUS_MVNCI_OUT_OF_RESOURCES		 0xAU
70 #define VPU_JSM_STATUS_MVNCI_NOT_IMPLEMENTED		 0xBU
71 #define VPU_JSM_STATUS_MVNCI_INTERNAL_ERROR		 0xCU
72 /* Job status returned when the job was preempted mid-inference */
73 #define VPU_JSM_STATUS_PREEMPTED_MID_INFERENCE		 0xDU
74 
75 /*
76  * Host <-> VPU IPC channels.
77  * ASYNC commands use a high priority channel, other messages use low-priority ones.
78  */
79 #define VPU_IPC_CHAN_ASYNC_CMD 0
80 #define VPU_IPC_CHAN_GEN_CMD   10
81 #define VPU_IPC_CHAN_JOB_RET   11
82 
83 /*
84  * Job flags bit masks.
85  */
86 #define VPU_JOB_FLAGS_NULL_SUBMISSION_MASK 0x00000001
87 
88 /*
89  * Sizes of the reserved areas in jobs, in bytes.
90  */
91 #define VPU_JOB_RESERVED_BYTES	     16
92 /*
93  * Sizes of the reserved areas in job queues, in bytes.
94  */
95 #define VPU_JOB_QUEUE_RESERVED_BYTES 52
96 
97 /*
98  * Max length (including trailing NULL char) of trace entity name (e.g., the
99  * name of a logging destination or a loggable HW component).
100  */
101 #define VPU_TRACE_ENTITY_NAME_MAX_LEN 32
102 
103 /*
104  * Max length (including trailing NULL char) of a dyndbg command.
105  *
106  * NOTE: 96 is used so that the size of 'struct vpu_ipc_msg' in the JSM API is
107  * 128 bytes (multiple of 64 bytes, the cache line size).
108  */
109 #define VPU_DYNDBG_CMD_MAX_LEN 96
110 
111 /*
112  * Job format.
113  */
114 struct vpu_job_queue_entry {
115 	u64 batch_buf_addr; /**< Address of VPU commands batch buffer */
116 	u32 job_id;	  /**< Job ID */
117 	u32 flags; /**< Flags bit field, see VPU_JOB_FLAGS_* above */
118 	u64 root_page_table_addr; /**< Address of root page table to use for this job */
119 	u64 root_page_table_update_counter; /**< Page tables update events counter */
120 	u64 preemption_buffer_address; /**< Address of the preemption buffer to use for this job */
121 	u64 preemption_buffer_size; /**< Size of the preemption buffer to use for this job */
122 	u8 reserved_0[VPU_JOB_RESERVED_BYTES];
123 };
124 
125 /*
126  * Job queue control registers.
127  */
128 struct vpu_job_queue_header {
129 	u32 engine_idx;
130 	u32 head;
131 	u32 tail;
132 	u8 reserved_0[VPU_JOB_QUEUE_RESERVED_BYTES];
133 };
134 
135 /*
136  * Job queue format.
137  */
138 struct vpu_job_queue {
139 	struct vpu_job_queue_header header;
140 	struct vpu_job_queue_entry job[];
141 };
142 
143 /**
144  * Logging entity types.
145  *
146  * This enum defines the different types of entities involved in logging.
147  */
148 enum vpu_trace_entity_type {
149 	/** Logging destination (entity where logs can be stored / printed). */
150 	VPU_TRACE_ENTITY_TYPE_DESTINATION = 1,
151 	/** Loggable HW component (HW entity that can be logged). */
152 	VPU_TRACE_ENTITY_TYPE_HW_COMPONENT = 2,
153 };
154 
155 /*
156  * Host <-> VPU IPC messages types.
157  */
158 enum vpu_ipc_msg_type {
159 	VPU_JSM_MSG_UNKNOWN = 0xFFFFFFFF,
160 	/* IPC Host -> Device, Async commands */
161 	VPU_JSM_MSG_ASYNC_CMD = 0x1100,
162 	VPU_JSM_MSG_ENGINE_RESET = VPU_JSM_MSG_ASYNC_CMD,
163 	VPU_JSM_MSG_ENGINE_PREEMPT = 0x1101,
164 	VPU_JSM_MSG_REGISTER_DB = 0x1102,
165 	VPU_JSM_MSG_UNREGISTER_DB = 0x1103,
166 	VPU_JSM_MSG_QUERY_ENGINE_HB = 0x1104,
167 	VPU_JSM_MSG_GET_POWER_LEVEL_COUNT = 0x1105,
168 	VPU_JSM_MSG_GET_POWER_LEVEL = 0x1106,
169 	VPU_JSM_MSG_SET_POWER_LEVEL = 0x1107,
170 	/* @deprecated */
171 	VPU_JSM_MSG_METRIC_STREAMER_OPEN = 0x1108,
172 	/* @deprecated */
173 	VPU_JSM_MSG_METRIC_STREAMER_CLOSE = 0x1109,
174 	/** Configure logging (used to modify configuration passed in boot params). */
175 	VPU_JSM_MSG_TRACE_SET_CONFIG = 0x110a,
176 	/** Return current logging configuration. */
177 	VPU_JSM_MSG_TRACE_GET_CONFIG = 0x110b,
178 	/**
179 	 * Get masks of destinations and HW components supported by the firmware
180 	 * (may vary between HW generations and FW compile
181 	 * time configurations)
182 	 */
183 	VPU_JSM_MSG_TRACE_GET_CAPABILITY = 0x110c,
184 	/** Get the name of a destination or HW component. */
185 	VPU_JSM_MSG_TRACE_GET_NAME = 0x110d,
186 	/**
187 	 * Release resource associated with host ssid . All jobs that belong to the host_ssid
188 	 * aborted and removed from internal scheduling queues. All doorbells assigned
189 	 * to the host_ssid are unregistered and any internal FW resources belonging to
190 	 * the host_ssid are released.
191 	 */
192 	VPU_JSM_MSG_SSID_RELEASE = 0x110e,
193 	/**
194 	 * Start collecting metric data.
195 	 * @see vpu_jsm_metric_streamer_start
196 	 */
197 	VPU_JSM_MSG_METRIC_STREAMER_START = 0x110f,
198 	/**
199 	 * Stop collecting metric data. This command will return success if it is called
200 	 * for a metric stream that has already been stopped or was never started.
201 	 * @see vpu_jsm_metric_streamer_stop
202 	 */
203 	VPU_JSM_MSG_METRIC_STREAMER_STOP = 0x1110,
204 	/**
205 	 * Update current and next buffer for metric data collection. This command can
206 	 * also be used to request information about the number of collected samples
207 	 * and the amount of data written to the buffer.
208 	 * @see vpu_jsm_metric_streamer_update
209 	 */
210 	VPU_JSM_MSG_METRIC_STREAMER_UPDATE = 0x1111,
211 	/**
212 	 * Request description of selected metric groups and metric counters within
213 	 * each group. The VPU will write the description of groups and counters to
214 	 * the buffer specified in the command structure.
215 	 * @see vpu_jsm_metric_streamer_start
216 	 */
217 	VPU_JSM_MSG_METRIC_STREAMER_INFO = 0x1112,
218 	/** Control command: Priority band setup */
219 	VPU_JSM_MSG_SET_PRIORITY_BAND_SETUP = 0x1113,
220 	/** Control command: Create command queue */
221 	VPU_JSM_MSG_CREATE_CMD_QUEUE = 0x1114,
222 	/** Control command: Destroy command queue */
223 	VPU_JSM_MSG_DESTROY_CMD_QUEUE = 0x1115,
224 	/** Control command: Set context scheduling properties */
225 	VPU_JSM_MSG_SET_CONTEXT_SCHED_PROPERTIES = 0x1116,
226 	/*
227 	 * Register a doorbell to notify VPU of new work. The doorbell may later be
228 	 * deallocated or reassigned to another context.
229 	 */
230 	VPU_JSM_MSG_HWS_REGISTER_DB = 0x1117,
231 	/* IPC Host -> Device, General commands */
232 	VPU_JSM_MSG_GENERAL_CMD = 0x1200,
233 	VPU_JSM_MSG_BLOB_DEINIT = VPU_JSM_MSG_GENERAL_CMD,
234 	/**
235 	 * Control dyndbg behavior by executing a dyndbg command; equivalent to
236 	 * Linux command: `echo '<dyndbg_cmd>' > <debugfs>/dynamic_debug/control`.
237 	 */
238 	VPU_JSM_MSG_DYNDBG_CONTROL = 0x1201,
239 	/* IPC Device -> Host, Job completion */
240 	VPU_JSM_MSG_JOB_DONE = 0x2100,
241 	/* IPC Device -> Host, Async command completion */
242 	VPU_JSM_MSG_ASYNC_CMD_DONE = 0x2200,
243 	VPU_JSM_MSG_ENGINE_RESET_DONE = VPU_JSM_MSG_ASYNC_CMD_DONE,
244 	VPU_JSM_MSG_ENGINE_PREEMPT_DONE = 0x2201,
245 	VPU_JSM_MSG_REGISTER_DB_DONE = 0x2202,
246 	VPU_JSM_MSG_UNREGISTER_DB_DONE = 0x2203,
247 	VPU_JSM_MSG_QUERY_ENGINE_HB_DONE = 0x2204,
248 	VPU_JSM_MSG_GET_POWER_LEVEL_COUNT_DONE = 0x2205,
249 	VPU_JSM_MSG_GET_POWER_LEVEL_DONE = 0x2206,
250 	VPU_JSM_MSG_SET_POWER_LEVEL_DONE = 0x2207,
251 	/* @deprecated */
252 	VPU_JSM_MSG_METRIC_STREAMER_OPEN_DONE = 0x2208,
253 	/* @deprecated */
254 	VPU_JSM_MSG_METRIC_STREAMER_CLOSE_DONE = 0x2209,
255 	/** Response to VPU_JSM_MSG_TRACE_SET_CONFIG. */
256 	VPU_JSM_MSG_TRACE_SET_CONFIG_RSP = 0x220a,
257 	/** Response to VPU_JSM_MSG_TRACE_GET_CONFIG. */
258 	VPU_JSM_MSG_TRACE_GET_CONFIG_RSP = 0x220b,
259 	/** Response to VPU_JSM_MSG_TRACE_GET_CAPABILITY. */
260 	VPU_JSM_MSG_TRACE_GET_CAPABILITY_RSP = 0x220c,
261 	/** Response to VPU_JSM_MSG_TRACE_GET_NAME. */
262 	VPU_JSM_MSG_TRACE_GET_NAME_RSP = 0x220d,
263 	/** Response to VPU_JSM_MSG_SSID_RELEASE. */
264 	VPU_JSM_MSG_SSID_RELEASE_DONE = 0x220e,
265 	/**
266 	 * Response to VPU_JSM_MSG_METRIC_STREAMER_START.
267 	 * VPU will return an error result if metric collection cannot be started,
268 	 * e.g. when the specified metric mask is invalid.
269 	 * @see vpu_jsm_metric_streamer_done
270 	 */
271 	VPU_JSM_MSG_METRIC_STREAMER_START_DONE = 0x220f,
272 	/**
273 	 * Response to VPU_JSM_MSG_METRIC_STREAMER_STOP.
274 	 * Returns information about collected metric data.
275 	 * @see vpu_jsm_metric_streamer_done
276 	 */
277 	VPU_JSM_MSG_METRIC_STREAMER_STOP_DONE = 0x2210,
278 	/**
279 	 * Response to VPU_JSM_MSG_METRIC_STREAMER_UPDATE.
280 	 * Returns information about collected metric data.
281 	 * @see vpu_jsm_metric_streamer_done
282 	 */
283 	VPU_JSM_MSG_METRIC_STREAMER_UPDATE_DONE = 0x2211,
284 	/**
285 	 * Response to VPU_JSM_MSG_METRIC_STREAMER_INFO.
286 	 * Returns a description of the metric groups and metric counters.
287 	 * @see vpu_jsm_metric_streamer_done
288 	 */
289 	VPU_JSM_MSG_METRIC_STREAMER_INFO_DONE = 0x2212,
290 	/**
291 	 * Asynchronous event sent from the VPU to the host either when the current
292 	 * metric buffer is full or when the VPU has collected a multiple of
293 	 * @notify_sample_count samples as indicated through the start command
294 	 * (VPU_JSM_MSG_METRIC_STREAMER_START). Returns information about collected
295 	 * metric data.
296 	 * @see vpu_jsm_metric_streamer_done
297 	 */
298 	VPU_JSM_MSG_METRIC_STREAMER_NOTIFICATION = 0x2213,
299 	/** Response to control command: Priority band setup */
300 	VPU_JSM_MSG_SET_PRIORITY_BAND_SETUP_RSP = 0x2214,
301 	/** Response to control command: Create command queue */
302 	VPU_JSM_MSG_CREATE_CMD_QUEUE_RSP = 0x2215,
303 	/** Response to control command: Destroy command queue */
304 	VPU_JSM_MSG_DESTROY_CMD_QUEUE_RSP = 0x2216,
305 	/** Response to control command: Set context scheduling properties */
306 	VPU_JSM_MSG_SET_CONTEXT_SCHED_PROPERTIES_RSP = 0x2217,
307 	/* IPC Device -> Host, General command completion */
308 	VPU_JSM_MSG_GENERAL_CMD_DONE = 0x2300,
309 	VPU_JSM_MSG_BLOB_DEINIT_DONE = VPU_JSM_MSG_GENERAL_CMD_DONE,
310 	/** Response to VPU_JSM_MSG_DYNDBG_CONTROL. */
311 	VPU_JSM_MSG_DYNDBG_CONTROL_RSP = 0x2301,
312 };
313 
314 enum vpu_ipc_msg_status { VPU_JSM_MSG_FREE, VPU_JSM_MSG_ALLOCATED };
315 
316 /*
317  * Host <-> LRT IPC message payload definitions
318  */
319 struct vpu_ipc_msg_payload_engine_reset {
320 	/* Engine to be reset. */
321 	u32 engine_idx;
322 	/* Reserved */
323 	u32 reserved_0;
324 };
325 
326 struct vpu_ipc_msg_payload_engine_preempt {
327 	/* Engine to be preempted. */
328 	u32 engine_idx;
329 	/* ID of the preemption request. */
330 	u32 preempt_id;
331 };
332 
333 /*
334  * @brief Register doorbell command structure.
335  * This structure supports doorbell registration for only OS scheduling.
336  * @see VPU_JSM_MSG_REGISTER_DB
337  */
338 struct vpu_ipc_msg_payload_register_db {
339 	/* Index of the doorbell to register. */
340 	u32 db_idx;
341 	/* Reserved */
342 	u32 reserved_0;
343 	/* Virtual address in Global GTT pointing to the start of job queue. */
344 	u64 jobq_base;
345 	/* Size of the job queue in bytes. */
346 	u32 jobq_size;
347 	/* Host sub-stream ID for the context assigned to the doorbell. */
348 	u32 host_ssid;
349 };
350 
351 /**
352  * @brief Unregister doorbell command structure.
353  * Request structure to unregister a doorbell for both HW and OS scheduling.
354  * @see VPU_JSM_MSG_UNREGISTER_DB
355  */
356 struct vpu_ipc_msg_payload_unregister_db {
357 	/* Index of the doorbell to unregister. */
358 	u32 db_idx;
359 	/* Reserved */
360 	u32 reserved_0;
361 };
362 
363 struct vpu_ipc_msg_payload_query_engine_hb {
364 	/* Engine to return heartbeat value. */
365 	u32 engine_idx;
366 	/* Reserved */
367 	u32 reserved_0;
368 };
369 
370 struct vpu_ipc_msg_payload_power_level {
371 	/**
372 	 * Requested power level. The power level value is in the
373 	 * range [0, power_level_count-1] where power_level_count
374 	 * is the number of available power levels as returned by
375 	 * the get power level count command. A power level of 0
376 	 * corresponds to the maximum possible power level, while
377 	 * power_level_count-1 corresponds to the minimum possible
378 	 * power level. Values outside of this range are not
379 	 * considered to be valid.
380 	 */
381 	u32 power_level;
382 	/* Reserved */
383 	u32 reserved_0;
384 };
385 
386 struct vpu_ipc_msg_payload_ssid_release {
387 	/* Host sub-stream ID for the context to be released. */
388 	u32 host_ssid;
389 	/* Reserved */
390 	u32 reserved_0;
391 };
392 
393 /**
394  * @brief Metric streamer start command structure.
395  * This structure is also used with VPU_JSM_MSG_METRIC_STREAMER_INFO to request metric
396  * groups and metric counters description from the firmware.
397  * @see VPU_JSM_MSG_METRIC_STREAMER_START
398  * @see VPU_JSM_MSG_METRIC_STREAMER_INFO
399  */
400 struct vpu_jsm_metric_streamer_start {
401 	/**
402 	 * Bitmask to select the desired metric groups.
403 	 * A metric group can belong only to one metric streamer instance at a time.
404 	 * Since each metric streamer instance has a unique set of metric groups, it
405 	 * can also identify a metric streamer instance if more than one instance was
406 	 * started. If the VPU device does not support multiple metric streamer instances,
407 	 * then VPU_JSM_MSG_METRIC_STREAMER_START will return an error even if the second
408 	 * instance has different groups to the first.
409 	 */
410 	u64 metric_group_mask;
411 	/** Sampling rate in nanoseconds. */
412 	u64 sampling_rate;
413 	/**
414 	 * If > 0 the VPU will send a VPU_JSM_MSG_METRIC_STREAMER_NOTIFICATION message
415 	 * after every @notify_sample_count samples is collected or dropped by the VPU.
416 	 * If set to UINT_MAX the VPU will only generate a notification when the metric
417 	 * buffer is full. If set to 0 the VPU will never generate a notification.
418 	 */
419 	u32 notify_sample_count;
420 	u32 reserved_0;
421 	/**
422 	 * Address and size of the buffer where the VPU will write metric data. The
423 	 * VPU writes all counters from enabled metric groups one after another. If
424 	 * there is no space left to write data at the next sample period the VPU
425 	 * will switch to the next buffer (@see next_buffer_addr) and will optionally
426 	 * send a notification to the host driver if @notify_sample_count is non-zero.
427 	 * If @next_buffer_addr is NULL the VPU will stop collecting metric data.
428 	 */
429 	u64 buffer_addr;
430 	u64 buffer_size;
431 	/**
432 	 * Address and size of the next buffer to write metric data to after the initial
433 	 * buffer is full. If the address is NULL the VPU will stop collecting metric
434 	 * data.
435 	 */
436 	u64 next_buffer_addr;
437 	u64 next_buffer_size;
438 };
439 
440 /**
441  * @brief Metric streamer stop command structure.
442  * @see VPU_JSM_MSG_METRIC_STREAMER_STOP
443  */
444 struct vpu_jsm_metric_streamer_stop {
445 	/** Bitmask to select the desired metric groups. */
446 	u64 metric_group_mask;
447 };
448 
449 /**
450  * Provide VPU FW with buffers to write metric data.
451  * @see VPU_JSM_MSG_METRIC_STREAMER_UPDATE
452  */
453 struct vpu_jsm_metric_streamer_update {
454 	/** Metric group mask that identifies metric streamer instance. */
455 	u64 metric_group_mask;
456 	/**
457 	 * Address and size of the buffer where the VPU will write metric data. If
458 	 * the buffer address is 0 or same as the currently used buffer the VPU will
459 	 * continue writing metric data to the current buffer. In this case the
460 	 * buffer size is ignored and the size of the current buffer is unchanged.
461 	 * If the address is non-zero and differs from the current buffer address the
462 	 * VPU will immediately switch data collection to the new buffer.
463 	 */
464 	u64 buffer_addr;
465 	u64 buffer_size;
466 	/**
467 	 * Address and size of the next buffer to write metric data after the initial
468 	 * buffer is full. If the address is NULL the VPU will stop collecting metric
469 	 * data but will continue to record dropped samples.
470 	 *
471 	 * Note that there is a hazard possible if both buffer_addr and the next_buffer_addr
472 	 * are non-zero in same update request. It is the host's responsibility to ensure
473 	 * that both addresses make sense even if the VPU just switched to writing samples
474 	 * from the current to the next buffer.
475 	 */
476 	u64 next_buffer_addr;
477 	u64 next_buffer_size;
478 };
479 
480 struct vpu_ipc_msg_payload_blob_deinit {
481 	/* 64-bit unique ID for the blob to be de-initialized. */
482 	u64 blob_id;
483 };
484 
485 struct vpu_ipc_msg_payload_job_done {
486 	/* Engine to which the job was submitted. */
487 	u32 engine_idx;
488 	/* Index of the doorbell to which the job was submitted */
489 	u32 db_idx;
490 	/* ID of the completed job */
491 	u32 job_id;
492 	/* Status of the completed job */
493 	u32 job_status;
494 	/* Host SSID */
495 	u32 host_ssid;
496 	/* Zero Padding */
497 	u32 reserved_0;
498 	/* Command queue id */
499 	u64 cmdq_id;
500 };
501 
502 struct vpu_jsm_engine_reset_context {
503 	/* Host SSID */
504 	u32 host_ssid;
505 	/* Zero Padding */
506 	u32 reserved_0;
507 	/* Command queue id */
508 	u64 cmdq_id;
509 	/* Flags: 0: cause of hang; 1: collateral damage of reset */
510 	u64 flags;
511 };
512 
513 struct vpu_ipc_msg_payload_engine_reset_done {
514 	/* Engine ordinal */
515 	u32 engine_idx;
516 	/* Number of impacted contexts */
517 	u32 num_impacted_contexts;
518 	/* Array of impacted command queue ids and their flags */
519 	struct vpu_jsm_engine_reset_context
520 		impacted_contexts[VPU_MAX_ENGINE_RESET_IMPACTED_CONTEXTS];
521 };
522 
523 struct vpu_ipc_msg_payload_engine_preempt_done {
524 	/* Engine preempted. */
525 	u32 engine_idx;
526 	/* ID of the preemption request. */
527 	u32 preempt_id;
528 };
529 
530 /**
531  * Response structure for register doorbell command for both OS
532  * and HW scheduling.
533  * @see VPU_JSM_MSG_REGISTER_DB
534  * @see VPU_JSM_MSG_HWS_REGISTER_DB
535  */
536 struct vpu_ipc_msg_payload_register_db_done {
537 	/* Index of the registered doorbell. */
538 	u32 db_idx;
539 	/* Reserved */
540 	u32 reserved_0;
541 };
542 
543 /**
544  * Response structure for unregister doorbell command for both OS
545  * and HW scheduling.
546  * @see VPU_JSM_MSG_UNREGISTER_DB
547  */
548 struct vpu_ipc_msg_payload_unregister_db_done {
549 	/* Index of the unregistered doorbell. */
550 	u32 db_idx;
551 	/* Reserved */
552 	u32 reserved_0;
553 };
554 
555 struct vpu_ipc_msg_payload_query_engine_hb_done {
556 	/* Engine returning heartbeat value. */
557 	u32 engine_idx;
558 	/* Reserved */
559 	u32 reserved_0;
560 	/* Heartbeat value. */
561 	u64 heartbeat;
562 };
563 
564 struct vpu_ipc_msg_payload_get_power_level_count_done {
565 	/**
566 	 * Number of supported power levels. The maximum possible
567 	 * value of power_level_count is 16 but this may vary across
568 	 * implementations.
569 	 */
570 	u32 power_level_count;
571 	/* Reserved */
572 	u32 reserved_0;
573 	/**
574 	 * Power consumption limit for each supported power level in
575 	 * [0-100%] range relative to power level 0.
576 	 */
577 	u8 power_limit[16];
578 };
579 
580 struct vpu_ipc_msg_payload_blob_deinit_done {
581 	/* 64-bit unique ID for the blob de-initialized. */
582 	u64 blob_id;
583 };
584 
585 /* HWS priority band setup request / response */
586 struct vpu_ipc_msg_payload_hws_priority_band_setup {
587 	/*
588 	 * Grace period in 100ns units when preempting another priority band for
589 	 * this priority band
590 	 */
591 	u32 grace_period[VPU_HWS_NUM_PRIORITY_BANDS];
592 	/*
593 	 * Default quantum in 100ns units for scheduling across processes
594 	 * within a priority band
595 	 */
596 	u64 process_quantum[VPU_HWS_NUM_PRIORITY_BANDS];
597 	/*
598 	 * Default grace period in 100ns units for processes that preempt each
599 	 * other within a priority band
600 	 */
601 	u64 process_grace_period[VPU_HWS_NUM_PRIORITY_BANDS];
602 	/*
603 	 * For normal priority band, specifies the target VPU percentage
604 	 * in situations when it's starved by the focus band.
605 	 */
606 	u32 normal_band_percentage;
607 	/* Reserved */
608 	u32 reserved_0;
609 };
610 
611 /* HWS create command queue request */
612 struct vpu_ipc_msg_payload_hws_create_cmdq {
613 	/* Process id */
614 	u64 process_id;
615 	/* Host SSID */
616 	u32 host_ssid;
617 	/* Zero Padding */
618 	u32 reserved;
619 	/* Command queue id */
620 	u64 cmdq_id;
621 	/* Command queue base */
622 	u64 cmdq_base;
623 	/* Command queue size */
624 	u32 cmdq_size;
625 	/* Reserved */
626 	u32 reserved_0;
627 };
628 
629 /* HWS create command queue response */
630 struct vpu_ipc_msg_payload_hws_create_cmdq_rsp {
631 	/* Process id */
632 	u64 process_id;
633 	/* Host SSID */
634 	u32 host_ssid;
635 	/* Zero Padding */
636 	u32 reserved;
637 	/* Command queue id */
638 	u64 cmdq_id;
639 };
640 
641 /* HWS destroy command queue request / response */
642 struct vpu_ipc_msg_payload_hws_destroy_cmdq {
643 	/* Host SSID */
644 	u32 host_ssid;
645 	/* Zero Padding */
646 	u32 reserved;
647 	/* Command queue id */
648 	u64 cmdq_id;
649 };
650 
651 /* HWS set context scheduling properties request / response */
652 struct vpu_ipc_msg_payload_hws_set_context_sched_properties {
653 	/* Host SSID */
654 	u32 host_ssid;
655 	/* Zero Padding */
656 	u32 reserved_0;
657 	/* Command queue id */
658 	u64 cmdq_id;
659 	/* Priority band to assign to work of this context */
660 	u32 priority_band;
661 	/* Inside realtime band assigns a further priority */
662 	u32 realtime_priority_level;
663 	/* Priority relative to other contexts in the same process */
664 	u32 in_process_priority;
665 	/* Zero padding / Reserved */
666 	u32 reserved_1;
667 	/* Context quantum relative to other contexts of same priority in the same process */
668 	u64 context_quantum;
669 	/* Grace period when preempting context of the same priority within the same process */
670 	u64 grace_period_same_priority;
671 	/* Grace period when preempting context of a lower priority within the same process */
672 	u64 grace_period_lower_priority;
673 };
674 
675 /*
676  * @brief Register doorbell command structure.
677  * This structure supports doorbell registration for both HW and OS scheduling.
678  * Note: Queue base and size are added here so that the same structure can be used for
679  * OS scheduling and HW scheduling. For OS scheduling, cmdq_id will be ignored
680  * and cmdq_base and cmdq_size will be used. For HW scheduling, cmdq_base and cmdq_size will be
681  * ignored and cmdq_id is used.
682  * @see VPU_JSM_MSG_HWS_REGISTER_DB
683  */
684 struct vpu_jsm_hws_register_db {
685 	/* Index of the doorbell to register. */
686 	u32 db_id;
687 	/* Host sub-stream ID for the context assigned to the doorbell. */
688 	u32 host_ssid;
689 	/* ID of the command queue associated with the doorbell. */
690 	u64 cmdq_id;
691 	/* Virtual address pointing to the start of command queue. */
692 	u64 cmdq_base;
693 	/* Size of the command queue in bytes. */
694 	u64 cmdq_size;
695 };
696 
697 /**
698  * Payload for VPU_JSM_MSG_TRACE_SET_CONFIG[_RSP] and
699  * VPU_JSM_MSG_TRACE_GET_CONFIG_RSP messages.
700  *
701  * The payload is interpreted differently depending on the type of message:
702  *
703  * - For VPU_JSM_MSG_TRACE_SET_CONFIG, the payload specifies the desired
704  *   logging configuration to be set.
705  *
706  * - For VPU_JSM_MSG_TRACE_SET_CONFIG_RSP, the payload reports the logging
707  *   configuration that was set after a VPU_JSM_MSG_TRACE_SET_CONFIG request.
708  *   The host can compare this payload with the one it sent in the
709  *   VPU_JSM_MSG_TRACE_SET_CONFIG request to check whether or not the
710  *   configuration was set as desired.
711  *
712  * - VPU_JSM_MSG_TRACE_GET_CONFIG_RSP, the payload reports the current logging
713  *   configuration.
714  */
715 struct vpu_ipc_msg_payload_trace_config {
716 	/**
717 	 * Logging level (currently set or to be set); see 'mvLog_t' enum for
718 	 * acceptable values. The specified logging level applies to all
719 	 * destinations and HW components
720 	 */
721 	u32 trace_level;
722 	/**
723 	 * Bitmask of logging destinations (currently enabled or to be enabled);
724 	 * bitwise OR of values defined in logging_destination enum.
725 	 */
726 	u32 trace_destination_mask;
727 	/**
728 	 * Bitmask of loggable HW components (currently enabled or to be enabled);
729 	 * bitwise OR of values defined in loggable_hw_component enum.
730 	 */
731 	u64 trace_hw_component_mask;
732 	u64 reserved_0; /**< Reserved for future extensions. */
733 };
734 
735 /**
736  * Payload for VPU_JSM_MSG_TRACE_GET_CAPABILITY_RSP messages.
737  */
738 struct vpu_ipc_msg_payload_trace_capability_rsp {
739 	u32 trace_destination_mask; /**< Bitmask of supported logging destinations. */
740 	u32 reserved_0;
741 	u64 trace_hw_component_mask; /**< Bitmask of supported loggable HW components. */
742 	u64 reserved_1; /**< Reserved for future extensions. */
743 };
744 
745 /**
746  * Payload for VPU_JSM_MSG_TRACE_GET_NAME requests.
747  */
748 struct vpu_ipc_msg_payload_trace_get_name {
749 	/**
750 	 * The type of the entity to query name for; see logging_entity_type for
751 	 * possible values.
752 	 */
753 	u32 entity_type;
754 	u32 reserved_0;
755 	/**
756 	 * The ID of the entity to query name for; possible values depends on the
757 	 * entity type.
758 	 */
759 	u64 entity_id;
760 };
761 
762 /**
763  * Payload for VPU_JSM_MSG_TRACE_GET_NAME_RSP responses.
764  */
765 struct vpu_ipc_msg_payload_trace_get_name_rsp {
766 	/**
767 	 * The type of the entity whose name was queried; see logging_entity_type
768 	 * for possible values.
769 	 */
770 	u32 entity_type;
771 	u32 reserved_0;
772 	/**
773 	 * The ID of the entity whose name was queried; possible values depends on
774 	 * the entity type.
775 	 */
776 	u64 entity_id;
777 	/** Reserved for future extensions. */
778 	u64 reserved_1;
779 	/** The name of the entity. */
780 	char entity_name[VPU_TRACE_ENTITY_NAME_MAX_LEN];
781 };
782 
783 /**
784  * Data sent from the VPU to the host in all metric streamer response messages
785  * and in asynchronous notification.
786  * @see VPU_JSM_MSG_METRIC_STREAMER_START_DONE
787  * @see VPU_JSM_MSG_METRIC_STREAMER_STOP_DONE
788  * @see VPU_JSM_MSG_METRIC_STREAMER_UPDATE_DONE
789  * @see VPU_JSM_MSG_METRIC_STREAMER_INFO_DONE
790  * @see VPU_JSM_MSG_METRIC_STREAMER_NOTIFICATION
791  */
792 struct vpu_jsm_metric_streamer_done {
793 	/** Metric group mask that identifies metric streamer instance. */
794 	u64 metric_group_mask;
795 	/**
796 	 * Size in bytes of single sample - total size of all enabled counters.
797 	 * Some VPU implementations may align sample_size to more than 8 bytes.
798 	 */
799 	u32 sample_size;
800 	u32 reserved_0;
801 	/**
802 	 * Number of samples collected since the metric streamer was started.
803 	 * This will be 0 if the metric streamer was not started.
804 	 */
805 	u32 samples_collected;
806 	/**
807 	 * Number of samples dropped since the metric streamer was started. This
808 	 * is incremented every time the metric streamer is not able to write
809 	 * collected samples because the current buffer is full and there is no
810 	 * next buffer to switch to.
811 	 */
812 	u32 samples_dropped;
813 	/** Address of the buffer that contains the latest metric data. */
814 	u64 buffer_addr;
815 	/**
816 	 * Number of bytes written into the metric data buffer. In response to the
817 	 * VPU_JSM_MSG_METRIC_STREAMER_INFO request this field contains the size of
818 	 * all group and counter descriptors. The size is updated even if the buffer
819 	 * in the request was NULL or too small to hold descriptors of all counters
820 	 */
821 	u64 bytes_written;
822 };
823 
824 /**
825  * Metric group description placed in the metric buffer after successful completion
826  * of the VPU_JSM_MSG_METRIC_STREAMER_INFO command. This is followed by one or more
827  * @vpu_jsm_metric_counter_descriptor records.
828  * @see VPU_JSM_MSG_METRIC_STREAMER_INFO
829  */
830 struct vpu_jsm_metric_group_descriptor {
831 	/**
832 	 * Offset to the next metric group (8-byte aligned). If this offset is 0 this
833 	 * is the last descriptor. The value of metric_info_size must be greater than
834 	 * or equal to sizeof(struct vpu_jsm_metric_group_descriptor) + name_string_size
835 	 * + description_string_size and must be 8-byte aligned.
836 	 */
837 	u32 next_metric_group_info_offset;
838 	/**
839 	 * Offset to the first metric counter description record (8-byte aligned).
840 	 * @see vpu_jsm_metric_counter_descriptor
841 	 */
842 	u32 next_metric_counter_info_offset;
843 	/** Index of the group. This corresponds to bit index in metric_group_mask. */
844 	u32 group_id;
845 	/** Number of counters in the metric group. */
846 	u32 num_counters;
847 	/** Data size for all counters, must be a multiple of 8 bytes.*/
848 	u32 metric_group_data_size;
849 	/**
850 	 * Metric group domain number. Cannot use multiple, simultaneous metric groups
851 	 * from the same domain.
852 	 */
853 	u32 domain;
854 	/**
855 	 * Counter name string size. The string must include a null termination character.
856 	 * The FW may use a fixed size name or send a different name for each counter.
857 	 * If the VPU uses fixed size strings, all characters from the end of the name
858 	 * to the of the fixed size character array must be zeroed.
859 	 */
860 	u32 name_string_size;
861 	/** Counter description string size, @see name_string_size */
862 	u32 description_string_size;
863 	u64 reserved_0;
864 	/**
865 	 * Right after this structure, the VPU writes name and description of
866 	 * the metric group.
867 	 */
868 };
869 
870 /**
871  * Metric counter description, placed in the buffer after vpu_jsm_metric_group_descriptor.
872  * @see VPU_JSM_MSG_METRIC_STREAMER_INFO
873  */
874 struct vpu_jsm_metric_counter_descriptor {
875 	/**
876 	 * Offset to the next counter in a group (8-byte aligned). If this offset is
877 	 * 0 this is the last counter in the group.
878 	 */
879 	u32 next_metric_counter_info_offset;
880 	/**
881 	 * Offset to the counter data from the start of samples in this metric group.
882 	 * Note that metric_data_offset % metric_data_size must be 0.
883 	 */
884 	u32 metric_data_offset;
885 	/** Size of the metric counter data in bytes. */
886 	u32 metric_data_size;
887 	/** Metric type, see Level Zero API for definitions. */
888 	u32 tier;
889 	/** Metric type, see set_metric_type_t for definitions. */
890 	u32 metric_type;
891 	/** Metric type, see set_value_type_t for definitions. */
892 	u32 metric_value_type;
893 	/**
894 	 * Counter name string size. The string must include a null termination character.
895 	 * The FW may use a fixed size name or send a different name for each counter.
896 	 * If the VPU uses fixed size strings, all characters from the end of the name
897 	 * to the of the fixed size character array must be zeroed.
898 	 */
899 	u32 name_string_size;
900 	/** Counter description string size, @see name_string_size */
901 	u32 description_string_size;
902 	/** Counter component name string size, @see name_string_size */
903 	u32 component_string_size;
904 	/** Counter string size, @see name_string_size */
905 	u32 units_string_size;
906 	u64 reserved_0;
907 	/**
908 	 * Right after this structure, the VPU writes name, description
909 	 * component and unit strings.
910 	 */
911 };
912 
913 /**
914  * Payload for VPU_JSM_MSG_DYNDBG_CONTROL requests.
915  *
916  * VPU_JSM_MSG_DYNDBG_CONTROL are used to control the VPU FW Dynamic Debug
917  * feature, which allows developers to selectively enable / disable MVLOG_DEBUG
918  * messages. This is equivalent to the Dynamic Debug functionality provided by
919  * Linux
920  * (https://www.kernel.org/doc/html/latest/admin-guide/dynamic-debug-howto.html)
921  * The host can control Dynamic Debug behavior by sending dyndbg commands, which
922  * have the same syntax as Linux
923  * dyndbg commands.
924  *
925  * NOTE: in order for MVLOG_DEBUG messages to be actually printed, the host
926  * still has to set the logging level to MVLOG_DEBUG, using the
927  * VPU_JSM_MSG_TRACE_SET_CONFIG command.
928  *
929  * The host can see the current dynamic debug configuration by executing a
930  * special 'show' command. The dyndbg configuration will be printed to the
931  * configured logging destination using MVLOG_INFO logging level.
932  */
933 struct vpu_ipc_msg_payload_dyndbg_control {
934 	/**
935 	 * Dyndbg command (same format as Linux dyndbg); must be a NULL-terminated
936 	 * string.
937 	 */
938 	char dyndbg_cmd[VPU_DYNDBG_CMD_MAX_LEN];
939 };
940 
941 /*
942  * Payloads union, used to define complete message format.
943  */
944 union vpu_ipc_msg_payload {
945 	struct vpu_ipc_msg_payload_engine_reset engine_reset;
946 	struct vpu_ipc_msg_payload_engine_preempt engine_preempt;
947 	struct vpu_ipc_msg_payload_register_db register_db;
948 	struct vpu_ipc_msg_payload_unregister_db unregister_db;
949 	struct vpu_ipc_msg_payload_query_engine_hb query_engine_hb;
950 	struct vpu_ipc_msg_payload_power_level power_level;
951 	struct vpu_jsm_metric_streamer_start metric_streamer_start;
952 	struct vpu_jsm_metric_streamer_stop metric_streamer_stop;
953 	struct vpu_jsm_metric_streamer_update metric_streamer_update;
954 	struct vpu_ipc_msg_payload_blob_deinit blob_deinit;
955 	struct vpu_ipc_msg_payload_ssid_release ssid_release;
956 	struct vpu_jsm_hws_register_db hws_register_db;
957 	struct vpu_ipc_msg_payload_job_done job_done;
958 	struct vpu_ipc_msg_payload_engine_reset_done engine_reset_done;
959 	struct vpu_ipc_msg_payload_engine_preempt_done engine_preempt_done;
960 	struct vpu_ipc_msg_payload_register_db_done register_db_done;
961 	struct vpu_ipc_msg_payload_unregister_db_done unregister_db_done;
962 	struct vpu_ipc_msg_payload_query_engine_hb_done query_engine_hb_done;
963 	struct vpu_ipc_msg_payload_get_power_level_count_done get_power_level_count_done;
964 	struct vpu_jsm_metric_streamer_done metric_streamer_done;
965 	struct vpu_ipc_msg_payload_blob_deinit_done blob_deinit_done;
966 	struct vpu_ipc_msg_payload_trace_config trace_config;
967 	struct vpu_ipc_msg_payload_trace_capability_rsp trace_capability;
968 	struct vpu_ipc_msg_payload_trace_get_name trace_get_name;
969 	struct vpu_ipc_msg_payload_trace_get_name_rsp trace_get_name_rsp;
970 	struct vpu_ipc_msg_payload_dyndbg_control dyndbg_control;
971 	struct vpu_ipc_msg_payload_hws_priority_band_setup hws_priority_band_setup;
972 	struct vpu_ipc_msg_payload_hws_create_cmdq hws_create_cmdq;
973 	struct vpu_ipc_msg_payload_hws_create_cmdq_rsp hws_create_cmdq_rsp;
974 	struct vpu_ipc_msg_payload_hws_destroy_cmdq hws_destroy_cmdq;
975 	struct vpu_ipc_msg_payload_hws_set_context_sched_properties
976 		hws_set_context_sched_properties;
977 };
978 
979 /*
980  * Host <-> LRT IPC message base structure.
981  *
982  * NOTE: All instances of this object must be aligned on a 64B boundary
983  * to allow proper handling of VPU cache operations.
984  */
985 struct vpu_jsm_msg {
986 	/* Reserved */
987 	u64 reserved_0;
988 	/* Message type, see vpu_ipc_msg_type enum. */
989 	u32 type;
990 	/* Buffer status, see vpu_ipc_msg_status enum. */
991 	u32 status;
992 	/*
993 	 * Request ID, provided by the host in a request message and passed
994 	 * back by VPU in the response message.
995 	 */
996 	u32 request_id;
997 	/* Request return code set by the VPU, see VPU_JSM_STATUS_* defines. */
998 	u32 result;
999 	u64 reserved_1;
1000 	/* Message payload depending on message type, see vpu_ipc_msg_payload union. */
1001 	union vpu_ipc_msg_payload payload;
1002 };
1003 
1004 #pragma pack(pop)
1005 
1006 #endif
1007 
1008 ///@}
1009