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

/* SPDX-License-Identifier: MIT */
/*
 * Copyright (C) 2020-2023 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 0

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

/*
 * 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 for now, once alignment issues are fixed this can be removed */
#pragma pack(push, 1)

/*
 * 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

/*
 * Sizes of the reserved areas in jobs, in bytes.
 */
#define VPU_JOB_RESERVED_BYTES	     16
/*
 * 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

/*
 * 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 preemption_buffer_address; /**< Address of the preemption buffer to use for this job */
	u64 preemption_buffer_size; /**< Size of the 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,
};

/*
 * Host <-> VPU IPC messages types.
 */
enum vpu_ipc_msg_type {
	VPU_JSM_MSG_UNKNOWN = 0xFFFFFFFF,
	/* IPC Host -> Device, Async commands */
	VPU_JSM_MSG_ASYNC_CMD = 0x1100,
	VPU_JSM_MSG_ENGINE_RESET = VPU_JSM_MSG_ASYNC_CMD,
	VPU_JSM_MSG_ENGINE_PREEMPT = 0x1101,
	VPU_JSM_MSG_REGISTER_DB = 0x1102,
	VPU_JSM_MSG_UNREGISTER_DB = 0x1103,
	VPU_JSM_MSG_QUERY_ENGINE_HB = 0x1104,
	VPU_JSM_MSG_GET_POWER_LEVEL_COUNT = 0x1105,
	VPU_JSM_MSG_GET_POWER_LEVEL = 0x1106,
	VPU_JSM_MSG_SET_POWER_LEVEL = 0x1107,
	/* @deprecated */
	VPU_JSM_MSG_METRIC_STREAMER_OPEN = 0x1108,
	/* @deprecated */
	VPU_JSM_MSG_METRIC_STREAMER_CLOSE = 0x1109,
	/** Configure logging (used to modify configuration passed in boot params). */
	VPU_JSM_MSG_TRACE_SET_CONFIG = 0x110a,
	/** Return current logging configuration. */
	VPU_JSM_MSG_TRACE_GET_CONFIG = 0x110b,
	/**
	 * Get masks of destinations and HW components supported by the firmware
	 * (may vary between HW generations and FW compile
	 * time configurations)
	 */
	VPU_JSM_MSG_TRACE_GET_CAPABILITY = 0x110c,
	/** Get the name of a destination or HW component. */
	VPU_JSM_MSG_TRACE_GET_NAME = 0x110d,
	/**
	 * Release resource associated with host ssid . All jobs that belong to the host_ssid
	 * aborted and removed from internal scheduling queues. All doorbells assigned
	 * to the host_ssid are unregistered and any internal FW resources belonging to
	 * the host_ssid are released.
	 */
	VPU_JSM_MSG_SSID_RELEASE = 0x110e,
	/**
	 * Start collecting metric data.
	 * @see vpu_jsm_metric_streamer_start
	 */
	VPU_JSM_MSG_METRIC_STREAMER_START = 0x110f,
	/**
	 * Stop collecting metric data. This command will return success if it is called
	 * for a metric stream that has already been stopped or was never started.
	 * @see vpu_jsm_metric_streamer_stop
	 */
	VPU_JSM_MSG_METRIC_STREAMER_STOP = 0x1110,
	/**
	 * Update current and next buffer for metric data collection. This command can
	 * also be used to request information about the number of collected samples
	 * and the amount of data written to the buffer.
	 * @see vpu_jsm_metric_streamer_update
	 */
	VPU_JSM_MSG_METRIC_STREAMER_UPDATE = 0x1111,
	/**
	 * Request description of selected metric groups and metric counters within
	 * each group. The VPU will write the description of groups and counters to
	 * the buffer specified in the command structure.
	 * @see vpu_jsm_metric_streamer_start
	 */
	VPU_JSM_MSG_METRIC_STREAMER_INFO = 0x1112,
	/** Control command: Priority band setup */
	VPU_JSM_MSG_SET_PRIORITY_BAND_SETUP = 0x1113,
	/** Control command: Create command queue */
	VPU_JSM_MSG_CREATE_CMD_QUEUE = 0x1114,
	/** Control command: Destroy command queue */
	VPU_JSM_MSG_DESTROY_CMD_QUEUE = 0x1115,
	/** Control command: Set context scheduling properties */
	VPU_JSM_MSG_SET_CONTEXT_SCHED_PROPERTIES = 0x1116,
	/*
	 * Register a doorbell to notify VPU of new work. The doorbell may later be
	 * deallocated or reassigned to another context.
	 */
	VPU_JSM_MSG_HWS_REGISTER_DB = 0x1117,
	/* IPC Host -> Device, General commands */
	VPU_JSM_MSG_GENERAL_CMD = 0x1200,
	VPU_JSM_MSG_BLOB_DEINIT = VPU_JSM_MSG_GENERAL_CMD,
	/**
	 * Control dyndbg behavior by executing a dyndbg command; equivalent to
	 * Linux command: `echo '<dyndbg_cmd>' > <debugfs>/dynamic_debug/control`.
	 */
	VPU_JSM_MSG_DYNDBG_CONTROL = 0x1201,
	/* IPC Device -> Host, Job completion */
	VPU_JSM_MSG_JOB_DONE = 0x2100,
	/* IPC Device -> Host, Async command completion */
	VPU_JSM_MSG_ASYNC_CMD_DONE = 0x2200,
	VPU_JSM_MSG_ENGINE_RESET_DONE = VPU_JSM_MSG_ASYNC_CMD_DONE,
	VPU_JSM_MSG_ENGINE_PREEMPT_DONE = 0x2201,
	VPU_JSM_MSG_REGISTER_DB_DONE = 0x2202,
	VPU_JSM_MSG_UNREGISTER_DB_DONE = 0x2203,
	VPU_JSM_MSG_QUERY_ENGINE_HB_DONE = 0x2204,
	VPU_JSM_MSG_GET_POWER_LEVEL_COUNT_DONE = 0x2205,
	VPU_JSM_MSG_GET_POWER_LEVEL_DONE = 0x2206,
	VPU_JSM_MSG_SET_POWER_LEVEL_DONE = 0x2207,
	/* @deprecated */
	VPU_JSM_MSG_METRIC_STREAMER_OPEN_DONE = 0x2208,
	/* @deprecated */
	VPU_JSM_MSG_METRIC_STREAMER_CLOSE_DONE = 0x2209,
	/** Response to VPU_JSM_MSG_TRACE_SET_CONFIG. */
	VPU_JSM_MSG_TRACE_SET_CONFIG_RSP = 0x220a,
	/** Response to VPU_JSM_MSG_TRACE_GET_CONFIG. */
	VPU_JSM_MSG_TRACE_GET_CONFIG_RSP = 0x220b,
	/** Response to VPU_JSM_MSG_TRACE_GET_CAPABILITY. */
	VPU_JSM_MSG_TRACE_GET_CAPABILITY_RSP = 0x220c,
	/** Response to VPU_JSM_MSG_TRACE_GET_NAME. */
	VPU_JSM_MSG_TRACE_GET_NAME_RSP = 0x220d,
	/** Response to VPU_JSM_MSG_SSID_RELEASE. */
	VPU_JSM_MSG_SSID_RELEASE_DONE = 0x220e,
	/**
	 * Response to VPU_JSM_MSG_METRIC_STREAMER_START.
	 * VPU will return an error result if metric collection cannot be started,
	 * e.g. when the specified metric mask is invalid.
	 * @see vpu_jsm_metric_streamer_done
	 */
	VPU_JSM_MSG_METRIC_STREAMER_START_DONE = 0x220f,
	/**
	 * Response to VPU_JSM_MSG_METRIC_STREAMER_STOP.
	 * Returns information about collected metric data.
	 * @see vpu_jsm_metric_streamer_done
	 */
	VPU_JSM_MSG_METRIC_STREAMER_STOP_DONE = 0x2210,
	/**
	 * Response to VPU_JSM_MSG_METRIC_STREAMER_UPDATE.
	 * Returns information about collected metric data.
	 * @see vpu_jsm_metric_streamer_done
	 */
	VPU_JSM_MSG_METRIC_STREAMER_UPDATE_DONE = 0x2211,
	/**
	 * Response to VPU_JSM_MSG_METRIC_STREAMER_INFO.
	 * Returns a description of the metric groups and metric counters.
	 * @see vpu_jsm_metric_streamer_done
	 */
	VPU_JSM_MSG_METRIC_STREAMER_INFO_DONE = 0x2212,
	/**
	 * Asynchronous event sent from the VPU to the host either when the current
	 * metric buffer is full or when the VPU has collected a multiple of
	 * @notify_sample_count samples as indicated through the start command
	 * (VPU_JSM_MSG_METRIC_STREAMER_START). Returns information about collected
	 * metric data.
	 * @see vpu_jsm_metric_streamer_done
	 */
	VPU_JSM_MSG_METRIC_STREAMER_NOTIFICATION = 0x2213,
	/** Response to control command: Priority band setup */
	VPU_JSM_MSG_SET_PRIORITY_BAND_SETUP_RSP = 0x2214,
	/** Response to control command: Create command queue */
	VPU_JSM_MSG_CREATE_CMD_QUEUE_RSP = 0x2215,
	/** Response to control command: Destroy command queue */
	VPU_JSM_MSG_DESTROY_CMD_QUEUE_RSP = 0x2216