path: root/drivers/accel/ivpu/vpu_jsm_api.h

/* SPDX-License-Identifier: MIT */
/*
 * Copyright (c) 2020-2024, Intel Corporation.
 */

/**
 * @file
 * @brief JSM shared definitions
 *
 * @ingroup Jsm
 * @brief JSM shared definitions
 * @{
 */
#ifndef VPU_JSM_API_H
#define VPU_JSM_API_H

/*
 * Major version changes that break backward compatibility
 */
#define VPU_JSM_API_VER_MAJOR 3

/*
 * Minor version changes when API backward compatibility is preserved.
 */
#define VPU_JSM_API_VER_MINOR 16

/*
 * API header changed (field names, documentation, formatting) but API itself has not been changed
 */
#define VPU_JSM_API_VER_PATCH 0

/*
 * Index in the API version table
 */
#define VPU_JSM_API_VER_INDEX 4

/*
 * Number of Priority Bands for Hardware Scheduling
 * Bands: RealTime, Focus, Normal, Idle
 */
#define VPU_HWS_NUM_PRIORITY_BANDS 4

/* Max number of impacted contexts that can be dealt with the engine reset command */
#define VPU_MAX_ENGINE_RESET_IMPACTED_CONTEXTS 3

/*
 * Pack the API structures to enforce binary compatibility
 * Align to 8 bytes for optimal performance
 */
#pragma pack(push, 8)

/*
 * Engine indexes.
 */
#define VPU_ENGINE_COMPUTE 0
#define VPU_ENGINE_COPY	   1
#define VPU_ENGINE_NB	   2

/*
 * VPU status values.
 */
#define VPU_JSM_STATUS_SUCCESS				 0x0U
#define VPU_JSM_STATUS_PARSING_ERR			 0x1U
#define VPU_JSM_STATUS_PROCESSING_ERR			 0x2U
#define VPU_JSM_STATUS_PREEMPTED			 0x3U
#define VPU_JSM_STATUS_ABORTED				 0x4U
#define VPU_JSM_STATUS_USER_CTX_VIOL_ERR		 0x5U
#define VPU_JSM_STATUS_GLOBAL_CTX_VIOL_ERR		 0x6U
#define VPU_JSM_STATUS_MVNCI_WRONG_INPUT_FORMAT		 0x7U
#define VPU_JSM_STATUS_MVNCI_UNSUPPORTED_NETWORK_ELEMENT 0x8U
#define VPU_JSM_STATUS_MVNCI_INVALID_HANDLE		 0x9U
#define VPU_JSM_STATUS_MVNCI_OUT_OF_RESOURCES		 0xAU
#define VPU_JSM_STATUS_MVNCI_NOT_IMPLEMENTED		 0xBU
#define VPU_JSM_STATUS_MVNCI_INTERNAL_ERROR		 0xCU
/* Job status returned when the job was preempted mid-inference */
#define VPU_JSM_STATUS_PREEMPTED_MID_INFERENCE		 0xDU

/*
 * Host <-> VPU IPC channels.
 * ASYNC commands use a high priority channel, other messages use low-priority ones.
 */
#define VPU_IPC_CHAN_ASYNC_CMD 0
#define VPU_IPC_CHAN_GEN_CMD   10
#define VPU_IPC_CHAN_JOB_RET   11

/*
 * Job flags bit masks.
 */
#define VPU_JOB_FLAGS_NULL_SUBMISSION_MASK 0x00000001
#define VPU_JOB_FLAGS_PRIVATE_DATA_MASK	   0xFF000000

/*
 * Sizes of the reserved areas in jobs, in bytes.
 */
#define VPU_JOB_RESERVED_BYTES 8

/*
 * Sizes of the reserved areas in job queues, in bytes.
 */
#define VPU_JOB_QUEUE_RESERVED_BYTES 52

/*
 * Max length (including trailing NULL char) of trace entity name (e.g., the
 * name of a logging destination or a loggable HW component).
 */
#define VPU_TRACE_ENTITY_NAME_MAX_LEN 32

/*
 * Max length (including trailing NULL char) of a dyndbg command.
 *
 * NOTE: 96 is used so that the size of 'struct vpu_ipc_msg' in the JSM API is
 * 128 bytes (multiple of 64 bytes, the cache line size).
 */
#define VPU_DYNDBG_CMD_MAX_LEN 96

/*
 * For HWS command queue scheduling, we can prioritise command queues inside the
 * same process with a relative in-process priority. Valid values for relative
 * priority are given below - max and min.
 */
#define VPU_HWS_COMMAND_QUEUE_MAX_IN_PROCESS_PRIORITY 7
#define VPU_HWS_COMMAND_QUEUE_MIN_IN_PROCESS_PRIORITY -7

/*
 * For HWS priority scheduling, we can have multiple realtime priority bands.
 * They are numbered 0 to a MAX.
 */
#define VPU_HWS_MAX_REALTIME_PRIORITY_LEVEL 31U

/*
 * vpu_jsm_engine_reset_context flag definitions
 */
#define VPU_ENGINE_RESET_CONTEXT_FLAG_COLLATERAL_DAMAGE_MASK BIT(0)
#define VPU_ENGINE_RESET_CONTEXT_HANG_PRIMARY_CAUSE	     0
#define VPU_ENGINE_RESET_CONTEXT_COLLATERAL_DAMAGE	     1

/*
 * Invalid command queue handle identifier. Applies to cmdq_id and cmdq_group
 * in this API.
 */
#define VPU_HWS_INVALID_CMDQ_HANDLE 0ULL

/*
 * Job format.
 */
struct vpu_job_queue_entry {
	u64 batch_buf_addr; /**< Address of VPU commands batch buffer */
	u32 job_id;	  /**< Job ID */
	u32 flags; /**< Flags bit field, see VPU_JOB_FLAGS_* above */
	u64 root_page_table_addr; /**< Address of root page table to use for this job */
	u64 root_page_table_update_counter; /**< Page tables update events counter */
	u64 primary_preempt_buf_addr;
	/**< Address of the primary preemption buffer to use for this job */
	u32 primary_preempt_buf_size;
	/**< Size of the primary preemption buffer to use for this job */
	u32 secondary_preempt_buf_size;
	/**< Size of secondary preemption buffer to use for this job */
	u64 secondary_preempt_buf_addr;
	/**< Address of secondary preemption buffer to use for this job */
	u8 reserved_0[VPU_JOB_RESERVED_BYTES];
};

/*
 * Job queue control registers.
 */
struct vpu_job_queue_header {
	u32 engine_idx;
	u32 head;
	u32 tail;
	u8 reserved_0[VPU_JOB_QUEUE_RESERVED_BYTES];
};

/*
 * Job queue format.
 */
struct vpu_job_queue {
	struct vpu_job_queue_header header;
	struct vpu_job_queue_entry job[];
};

/**
 * Logging entity types.
 *
 * This enum defines the different types of entities involved in logging.
 */
enum vpu_trace_entity_type {
	/** Logging destination (entity where logs can be stored / printed). */
	VPU_TRACE_ENTITY_TYPE_DESTINATION = 1,
	/** Loggable HW component (HW entity that can be logged). */
	VPU_TRACE_ENTITY_TYPE_HW_COMPONENT = 2,
};

/*
 * HWS specific log buffer header details.
 * Total size is 32 bytes.
 */
struct vpu_hws_log_buffer_header {
	/* Written by VPU after adding a log entry. Initialised by host to 0. */
	u32 first_free_entry_index;
	/* Incremented by VPU every time the VPU overwrites the 0th entry;
	 * initialised by host to 0.
	 */
	u32 wraparound_count;
	/*
	 * This is the number of buffers that can be stored in the log buffer provided by the host.
	 * It is written by host before passing buffer to VPU. VPU should consider it read-only.
	 */
	u64