accel/ivpu/vpu_jsm_api.h

1 /* SPDX-License-Identifier: MIT */
3  * Copyright (c) 2020-2024, Intel Corporation.
33  * Index in the API version table
74 /* Job status returned when the job was preempted mid-inference */
79  * Host <-> VPU IPC channels.
80  * ASYNC commands use a high priority channel, other messages use low-priority ones.
100 	 * When set, the object in job queue is an inline command (see struct vpu_inline_cmd below).
101 	 * When cleared, the object in job queue is a job (see struct vpu_job_queue_entry below).
117 	 * No job done notification mask.
118 	 * When set, indicates that no job done notification should be sent for any
126 	 * in job queue). Such queues may also use legacy fences (as commands in batch buffers).
129 	 *   1. For queues using native fences, VPU expects that all jobs in the queue
131 	 *      to be a fence signal command in most cases, but can also be a NOP in case the host
132 	 *      does not need per-job fence signalling. Other inline commands objects can be
153  * NOTE: 96 is used so that the size of 'struct vpu_ipc_msg' in the JSM API is
160  * same process with a relative in-process priority. Valid values for relative
161  * priority are given below - max and min.
164 #define VPU_HWS_COMMAND_QUEUE_MIN_IN_PROCESS_PRIORITY -7
181  * in this API.
197  * the fence to be satisfied, VPU blocks fetching of the next objects in the queue.
198  * Jobs present in the queue prior to the fence wait object may be processed
207  * present in the queue prior to them, and in-order relative to each other in the queue.
208  * But jobs in-between them may be processed concurrently and may complete out-of-order.
235 	 * Doorbell ring timestamp taken by KMD from SoC's global system clock, in
240 	/**< Extra id for job tracking, used only in the firmware perf traces */
273 			/* User VA of the monitored fence value (read-only). */
275 			/* Value to wait for or write in fence location. */
277 			/* User VA of the log buffer in which to add log entry on completion. */
331  * This enum defines the different types of entities involved in logging.
350 	 * This is the number of buffers that can be stored in the log buffer provided by the host.
351 	 * It is written by host before passing buffer to VPU. VPU should consider it read-only.
362 	/* VPU timestamp must be an invariant timer tick (not impacted by DVFS) */
366 	 *     0 - context state change
367 	 *     1 - queue new work
368 	 *     2 - queue unwait sync object
369 	 *     3 - queue no more work
370 	 *     4 - queue wait sync object
388 			/* Index of the first free entry in buffer. */
398 	/* Allocated number of entries in the log buffer. */
420 	 * wait was started (in NPU SysTime).
424 	/* Timestamp at which fence operation was completed (in NPU SysTime). */
435  * Host <-> VPU IPC messages types.
440 	/* IPC Host -> Device, Async commands */
463 	/** Configure logging (used to modify configuration passed in boot params). */
503 	 * the buffer specified in the command structure.
522 	/* Control command: Suspend command queue. */
538 	/* IPC Host -> Device, General commands */
551 	/* IPC Device -> Host, Job completion */
553 	/* IPC Device -> Host, Fence signalled */
556 	/* IPC Device -> Host, Async command completion */
624 	/* IPC Device -> Host, HWS notify index entry of log buffer written */
626 	/* IPC Device -> Host, HWS completion of a context suspend request */
642 	/* IPC Device -> Host, General command completion */
657  * Host <-> LRT IPC message payload definitions
683 	/* Virtual address in Global GTT pointing to the start of job queue. */
685 	/* Size of the job queue in bytes. */
687 	/* Host sub-stream ID for the context assigned to the doorbell. */
712 	 * Requested power level. The power level value is in the
713 	 * range [0, power_level_count-1] where power_level_count
717 	 * power_level_count-1 corresponds to the minimum possible
727 	/* Host sub-stream ID for the context to be released. */
751 	/** Sampling rate in nanoseconds. */
764 	 * there is no space left to write data at the next sample period the VPU
766 	 * send a notification to the host driver if @notify_sample_count is non-zero.
804 	 * currently used buffer address. In this case the buffer size is ignored and
806 	 * in the vpu_jsm_metric_streamer_done structure. The internal writing position
809 	 * Case 2. is identified by the address being non-zero and differs from the
811 	 * the new buffer. Then the VPU will return an update in the
822 	 * are non-zero in same update request. It is the host's responsibility to ensure
934 	 * Power consumption limit for each supported power level in
935 	 * [0-100%] range relative to power level 0.
943 	 * Grace period in 100ns units when preempting another priority band for
948 	 * Default quantum in 100ns units for scheduling across processes
950 	 * Minimum value supported by NPU is 1ms (10000 in 100ns units).
954 	 * Default grace period in 100ns units for processes that preempt each
960 	 * in situations when it's starved by the focus band.
964 	 * TDR timeout value in milliseconds. Default value of 0 meaning no timeout.
1039 	/* Priority relative to other contexts in the same process */
1044 	 * Context quantum relative to other contexts of same priority in the same process
1045 	 * Minimum value supported by NPU is 1ms (10000 in 100ns units).
1066 	/* Host sub-stream ID for the context assigned to the doorbell. */
1072 	/* Size of the command queue in bytes. */
1077  * @brief Structure to set another buffer to be used for scheduling-related logging.
1081  *   - header:     32 bytes in size, as shown in 'struct vpu_hws_log_buffer_header'.
1082  *                 The header contains the number of log entries in the buffer.
1083  *   - log entry:  0 to n-1, each log entry is 32 bytes in size, as shown in
1136  * @brief HWS suspend command queue request and done structure.
1137  * Host will request the suspend of contexts and VPU will;
1138  *   - Suspend all work on this context
1139  *   - Preempt any running work
1140  *   - Asynchronously perform the above and return success immediately once
1142  *   - Notify the host of completion of these operations via
1144  *   - Reject any other context operations on a context with an in-flight
1145  *     suspend request running
1146  * Same structure used when VPU notifies host of completion of a context suspend
1147  * request. The ids and suspend fence value reported in this command will match
1148  * the one in the request from the host to suspend the context. Once suspend is
1162 	 * Suspend fence value - reported by the VPU suspend context
1163 	 * completed once suspend is complete.
1171  *  - VPU will resume all work on this context
1172  *  - Scheduler will allow this context to be scheduled
1205  * - For VPU_JSM_MSG_TRACE_SET_CONFIG, the payload specifies the desired
1208  * - For VPU_JSM_MSG_TRACE_SET_CONFIG_RSP, the payload reports the logging
1210  *   The host can compare this payload with the one it sent in the
1214  * - VPU_JSM_MSG_TRACE_GET_CONFIG_RSP, the payload reports the current logging
1226 	 * bitwise OR of values defined in logging_destination enum.
1231 	 * bitwise OR of values defined in loggable_hw_component enum.
1286  * Data sent from the VPU to the host in all metric streamer response messages
1287  * and in asynchronous notification.
1298 	 * Size in bytes of single sample - total size of all enabled counters.
1311 	 * collected samples because the current buffer is full and there is no
1318 	 * Number of bytes written into the metric data buffer. In response to the
1321 	 * in the request was NULL or too small to hold descriptors of all counters
1327  * Metric group description placed in the metric buffer after successful completion
1334 	 * Offset to the next metric group (8-byte aligned). If this offset is 0 this
1337 	 * + description_string_size and must be 8-byte aligned.
1341 	 * Offset to the first metric counter description record (8-byte aligned).
1345 	/** Index of the group. This corresponds to bit index in metric_group_mask. */
1347 	/** Number of counters in the metric group. */
1373  * Metric counter description, placed in the buffer after vpu_jsm_metric_group_descriptor.
1378 	 * Offset to the next counter in a group (8-byte aligned). If this offset is
1379 	 * 0 this is the last counter in the group.
1383 	 * Offset to the counter data from the start of samples in this metric group.
1387 	/** Size of the metric counter data in bytes. */
1422  * (https://www.kernel.org/doc/html/latest/admin-guide/dynamic-debug-howto.html)
1427  * NOTE: in order for MVLOG_DEBUG messages to be actually printed, the host
1437 	 * Dyndbg command (same format as Linux dyndbg); must be a NULL-terminated
1446  * This is a bi-directional payload.
1466 	/** Duty cycle active time in microseconds */
1468 	/** Duty cycle inactive time in microseconds */
1517  * Host <-> LRT IPC message base structure.
1530 	 * Request ID, provided by the host in a request message and passed
1531 	 * back by VPU in the response message.