drivers/accel/ivpu/vpu_boot_api.h

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

/**
 * @addtogroup Boot
 * @{
 */

/**
 * @file
 * @brief Boot API public header file.
 */

#ifndef VPU_BOOT_API_H
#define VPU_BOOT_API_H

/**
 *  The below values will be used to construct the version info this way:
 *  fw_bin_header->api_version[VPU_BOOT_API_VER_ID] = (VPU_BOOT_API_VER_MAJOR << 16) |
 *  VPU_BOOT_API_VER_MINOR;
 *  VPU_BOOT_API_VER_PATCH will be ignored. KMD and compatibility is not affected if this changes
 *  This information is collected by using vpuip_2/application/vpuFirmware/make_std_fw_image.py
 *  If a header is missing this info we ignore the header, if a header is missing or contains
 *  partial info a build error will be generated.
 */

/**
 * Major version changes that break backward compatibility.
 * Major version must start from 1 and can only be incremented.
 */
#define VPU_BOOT_API_VER_MAJOR 3

/**
 * Minor version changes when API backward compatibility is preserved.
 * Resets to 0 if Major version is incremented.
 */
#define VPU_BOOT_API_VER_MINOR 29

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

/**
 * Index in the API version table
 * Must be unique for each API
 */
#define VPU_BOOT_API_VER_INDEX 0

#pragma pack(push, 4)

/**
 * Firmware image header format
 */
#define VPU_FW_HEADER_SIZE    4096
#define VPU_FW_HEADER_VERSION 0x1
#define VPU_FW_VERSION_SIZE   32
#define VPU_FW_API_VER_NUM    16

struct vpu_firmware_header {
	u32 header_version;
	u32 image_format;
	u64 image_load_address;
	u32 image_size;
	u64 entry_point;
	u8 vpu_version[VPU_FW_VERSION_SIZE];
	u32 compression_type;
	u64 firmware_version_load_address;
	u32 firmware_version_size;
	u64 boot_params_load_address;
	u32 api_version[VPU_FW_API_VER_NUM];
	/** Size of memory require for firmware execution */
	u32 runtime_size;
	u32 shave_nn_fw_size;
	/**
	 * Size of primary preemption buffer, assuming a 2-job submission queue.
	 * NOTE: host driver is expected to adapt size accordingly to actual
	 * submission queue size and device capabilities.
	 */
	u32 preemption_buffer_1_size;
	/**
	 * Size of secondary preemption buffer, assuming a 2-job submission queue.
	 * NOTE: host driver is expected to adapt size accordingly to actual
	 * submission queue size and device capabilities.
	 */
	u32 preemption_buffer_2_size;
	/**
	 * Maximum preemption buffer size that the FW can use: no need for the host
	 * driver to allocate more space than that specified by these fields.
	 * A value of 0 means no declared limit.
	 */
	u32 preemption_buffer_1_max_size;
	u32 preemption_buffer_2_max_size;
	/** Space reserved for future preemption-related fields. */
	u32 preemption_reserved[4];
	/** FW image read only section start address, 4KB aligned */
	u64 ro_section_start_address;
	/** FW image read only section size, 4KB aligned */
	u32 ro_section_size;
	u32 reserved;
};

/**
 * Firmware boot parameters format
 */

/** Values for boot_type field */
#define VPU_BOOT_TYPE_COLDBOOT 0
#define VPU_BOOT_TYPE_WARMBOOT 1

/** Value for magic filed */
#define VPU_BOOT_PARAMS_MAGIC 0x10000

/** VPU scheduling mode. By default, OS scheduling is used. */
#define VPU_SCHEDULING_MODE_OS 0
#define VPU_SCHEDULING_MODE_HW 1

enum VPU_BOOT_L2_CACHE_CFG_TYPE {
	VPU_BOOT_L2_CACHE_CFG_UPA = 0,
	VPU_BOOT_L2_CACHE_CFG_NN = 1,
	VPU_BOOT_L2_CACHE_CFG_NUM = 2
};

/** VPU MCA ECC signalling mode. By default, no signalling is used */
enum VPU_BOOT_MCA_ECC_SIGNAL_TYPE {
	VPU_BOOT_MCA_ECC_NONE = 0,
	VPU_BOOT_MCA_ECC_CORR = 1,
	VPU_BOOT_MCA_ECC_FATAL = 2,
	VPU_BOOT_MCA_ECC_BOTH = 3
};

/**
 * Logging destinations.
 *
 * Logging output can be directed to different logging destinations. This enum
 * defines the list of logging destinations supported by the VPU firmware (NOTE:
 * a specific VPU FW binary may support only a subset of such output
 * destinations, depending on the target platform and compile options).
 */
enum vpu_trace_destination {
	VPU_TRACE_DESTINATION_PIPEPRINT = 0x1,
	VPU_TRACE_DESTINATION_VERBOSE_TRACING = 0x2,
	VPU_TRACE_DESTINATION_NORTH_PEAK = 0x4,
};

/*
 * Processor bit shifts (for loggable HW components).
 */
#define VPU_TRACE_PROC_BIT_RESERVED  0
#define VPU_TRACE_PROC_BIT_LRT	     1
#define VPU_TRACE_PROC_BIT_LNN	     2
#define VPU_TRACE_PROC_BIT_SHV_0     3
#define VPU_TRACE_PROC_BIT_SHV_1     4
#define VPU_TRACE_PROC_BIT_SHV_2     5
#define VPU_TRACE_PROC_BIT_SHV_3     6
#define VPU_TRACE_PROC_BIT_SHV_4     7
#define VPU_TRACE_PROC_BIT_SHV_5     8
#define VPU_TRACE_PROC_BIT_SHV_6     9
#define VPU_TRACE_PROC_BIT_SHV_7     10
#define VPU_TRACE_PROC_BIT_SHV_8     11
#define VPU_TRACE_PROC_BIT_SHV_9     12
#define VPU_TRACE_PROC_BIT_SHV_10    13
#define VPU_TRACE_PROC_BIT_SHV_11    14
#define VPU_TRACE_PROC_BIT_SHV_12    15
#define VPU_TRACE_PROC_BIT_SHV_13    16
#define VPU_TRACE_PROC_BIT_SHV_14    17
#define VPU_TRACE_PROC_BIT_SHV_15    18
#define VPU_TRACE_PROC_BIT_ACT_SHV_0 19
#define VPU_TRACE_PROC_BIT_ACT_SHV_1 20
#define VPU_TRACE_PROC_BIT_ACT_SHV_2 21
#define VPU_TRACE_PROC_BIT_ACT_SHV_3 22
#define VPU_TRACE_PROC_NO_OF_HW_DEVS 23

/** VPU 30xx HW component IDs are sequential, so define first and last IDs. */
#define VPU_TRACE_PROC_BIT_30XX_FIRST VPU_TRACE_PROC_BIT_LRT
#define VPU_TRACE_PROC_BIT_30XX_LAST  VPU_TRACE_PROC_BIT_SHV_15

struct vpu_boot_l2_cache_config {
	u8 use;
	u8 cfg;
};

/**
 * When HW scheduling mode is enabled, a present period is defined.
 * It will be used by VPU to swap between normal and focus priorities
 * to prevent starving of normal priority band (when implemented).
 * Host must provide a valid value at boot time in
 * `vpu_focus_present_timer_ms`. If the value provided by the host is not within the
 * defined range a default value will be used. Here we define the min. and max.
 * allowed values and the and default value of the present period. Units are milliseconds.
 */
#define VPU_PRESENT_CALL_PERIOD_MS_DEFAULT 50
#define VPU_PRESENT_CALL_PERIOD_MS_MIN	   16
#define VPU_PRESENT_CALL_PERIOD_MS_MAX	   10000

/**
 * Macros to enable various power profiles within the NPU.
 * To be defined as part of 32 bit mask.
 */
#define POWER_PROFILE_SURVIVABILITY 0x1

/**
 * Enum for dvfs_mode boot param.
 */
enum vpu_governor {
	VPU_GOV_DEFAULT = 0, /** Default Governor for the system */
	VPU_GOV_MAX_PERFORMANCE = 1, /** Maximum performance governor */
	VPU_GOV_ON_DEMAND = 2, /** On Demand frequency control governor */
	VPU_GOV_POWER_SAVE = 3, /** Power save governor */
	VPU_GOV_ON_DEMAND_PRIORITY_AWARE = 4 /** On Demand priority based governor */
};

struct vpu_boot_params {
	u32 magic;
	u32 vpu_id;
	u32 vpu_count;
	u32 reserved_0[5];
	/** Clock frequencies: 0x20 - 0xFF */
	u32 frequency;
	u32 reserved_1[12];
	u32 perf_clk_frequency;
	u32 reserved_2[42];
	/** Memory regions: 0x100 - 0x1FF */
	u64 ipc_header_area_start;
	u32 ipc_header_area_size;
	u64 shared_region_base;
	u32 shared_region_size;
	u64 ipc_payload_area_start;
	u32 ipc_payload_area_size;
	u64 global_aliased_pio_base;
	u32 global_aliased_pio_size;
	u32 autoconfig;
	struct vpu_boot_l2_cache_config cache_defaults[VPU_BOOT_L2_CACHE_CFG_NUM];
	u32 reserved_3[3];
	/**
	 * ShaveNN FW section VPU base address
	 * On VPU2.7 HW this address must be within 2GB range starting from L2C_PAGE_TABLE base
	 */
	u64 shave_nn_fw_base;
	u64 save_restore_ret_address; /** stores the address of FW's restore entry point */
	u32 reserved_4[43];
	/** IRQ re-direct numbers: 0x200 - 0x2FF */
	s32 watchdog_irq_mss;
	s32 watchdog_irq_nce;
	/** ARM -> VPU doorbell interrupt. ARM is notifying VPU of async command or compute job. */
	u32 host_to_vpu_irq;
	/** VPU -> ARM job done interrupt. VPU is notifying ARM of compute job completion. */
	u32 job_done_irq;
	/** Padding. */
	u32 reserved_5[60];
	/** Silicon information: 0x300 - 0x3FF */
	u32 host_version_id;
	u32 si_stepping;
	u64 device_id;
	u64 feature_exclusion;
	u64 sku;
	/** PLL ratio for minimum clock frequency */
	u32 min_freq_pll_ratio;
	/** PLL ratio for maximum clock frequency */
	u32 max_freq_pll_ratio;
	/**
	 * Initial log level threshold (messages with log level severity less than
	 * the threshold will not be logged); applies to every enabled logging
	 * destination and loggable HW component. See 'mvLog_t' enum for acceptable
	 * values.
	 * TODO: EISW-33556: Move log level definition (mvLog_t) to this file.
	 */
	u32 default_trace_level;
	u32 boot_type;
	u64 punit_telemetry_sram_base;
	u64 punit_telemetry_sram_size;
	u32 vpu_telemetry_enable;
	u64 crit_tracing_buff_addr;
	u32 crit_tracing_buff_size;
	u64 verbose_tracing_buff_addr;
	u32 verbose_tracing_buff_size;
	u64 verbose_tracing_sw_component_mask; /** TO BE REMOVED */
	/**
	 * Mask of destinations to which logging messages are delivered; bitwise OR
	 * of values defined in vpu_trace_destination enum.
	 */
	u32 trace_destination_mask;
	/**
	 * Mask of hardware components for which logging is enabled; bitwise OR of
	 * bits defined by the VPU_TRACE_PROC_BIT_* macros.
	 */
	u64 trace_hw_component_mask;
	/** Mask of trace message formats supported by the driver */
	u64 tracing_buff_message_format_mask;
	u64 trace_reserved_1[2];
	u32 reserved_6;
	/** PLL ratio for efficient clock frequency */
	u32 pn_freq_pll_ratio;
	/**
	 * DVFS Mode:
	 * 0 - Default, DVFS mode selected by the firmware
	 * 1 - Max Performance
	 * 2 - On Demand
	 * 3 - Power Save
	 * 4 - On Demand Priority Aware
	 */
	u32 dvfs_mode;
	/**
	 * Depending on DVFS Mode:
	 * On-demand: Default if 0.
	 *    Bit 0-7   - uint8_t: Highest residency percent
	 *    Bit 8-15  - uint8_t: High residency percent
	 *    Bit 16-23 - uint8_t: Low residency percent
	 *    Bit 24-31 - uint8_t: Lowest residency percent
	 *    Bit 32-35 - unsigned 4b: PLL Ratio increase amount on highest residency
	 *    Bit 36-39 - unsigned 4b: PLL Ratio increase amount on high residency
	 *    Bit 40-43 - unsigned 4b: PLL Ratio decrease amount on low residency
	 *    Bit 44-47 - unsigned 4b: PLL Ratio decrease amount on lowest frequency
	 *    Bit 48-55 - uint8_t: Period (ms) for residency decisions
	 *    Bit 56-63 - uint8_t: Averaging windows (as multiples of period. Max: 30 decimal)
	 * Power Save/Max Performance: Unused
	 */
	u64 dvfs_param;
	/**
	 * D0i3 delayed entry
	 * Bit 0: Disable CPU state save on D0i2 entry flow.
	 *       0: Every D0i2 entry saves state. Save state IPC message ignored.
	 *       1: IPC message required to save state on D0i3 entry flow.
	 * NOTE: This parameter is deprecated starting NPU50xx+. Bit 0 is now hardcoded to 1,
	 * meaning CPU state save always requires IPC message on D0i3 entry flow.
	 */
	u32 d0i3_delayed_entry;
	/** Time spent by VPU in D0i3 state */
	u64 d0i3_residency_time_us;
	/** Value of VPU perf counter at the time of entering D0i3 state . */
	u64 d0i3_entry_vpu_ts;
	/**
	 * The system time of the host operating system in microseconds.
	 * E.g the number of microseconds since 1st of January 1970, or whatever
	 * date the host operating system uses to maintain system time.
	 * This value will be used to track system time on the VPU.
	 * The KMD is required to update this value on every VPU reset.
	 */
	u64 system_time_us;
	u32 reserved_7[2];
	/**
	 * The delta between device monotonic time and the current value of the
	 * HW timestamp register, in ticks. Written by the firmware during boot.
	 * Can be used by the KMD to calculate device time.
	 */
	u64 device_time_delta_ticks;
	u32 reserved_8[30];
	/** Power States transitions timestamps: 0x440 - 0x46F*/
	struct power_states_timestamps {
		/** VPU_IDLE -> VPU_ACTIVE transition initiated timestamp */
		u64 vpu_active_state_requested;
		/** VPU_IDLE -> VPU_ACTIVE transition completed timestamp */
		u64 vpu_active_state_achieved;
		/** VPU_ACTIVE -> VPU_IDLE transition initiated timestamp */
		u64 vpu_idle_state_requested;
		/** VPU_ACTIVE -> VPU_IDLE transition completed timestamp */
		u64 vpu_idle_state_achieved;
		/** VPU_IDLE -> VPU_STANDBY transition initiated timestamp */
		u64 vpu_standby_state_requested;
		/** VPU_IDLE -> VPU_STANDBY transition completed timestamp */
		u64 vpu_standby_state_achieved;
	} power_states_timestamps;
	/** VPU scheduling mode. Values defined by VPU_SCHEDULING_MODE_* macros. */
	u32 vpu_scheduling_mode;
	/** Present call period in milliseconds. */
	u32 vpu_focus_present_timer_ms;
	/** VPU ECC Signaling */
	u32 vpu_uses_ecc_mca_signal;
	/** Values defined by POWER_PROFILE* macros */
	u32 power_profile;
	/** Microsecond value for DCT active cycle */
	u32 dct_active_us;
	/** Microsecond value for DCT inactive cycle */
	u32 dct_inactive_us;
	/** Unused/reserved: 0x488 - 0xFFF */
	u32 reserved_9[734];
};

/** Magic numbers set between host and vpu to detect corruption of tracing init */
#define VPU_TRACING_BUFFER_CANARY (0xCAFECAFE)

/** Tracing buffer message format definitions */
#define VPU_TRACING_FORMAT_STRING 0
#define VPU_TRACING_FORMAT_MIPI	  2
/**
 * Header of the tracing buffer.
 * The below defined header will be stored at the beginning of
 * each allocated tracing buffer, followed by a series of 256b
 * of ASCII trace message entries.
 */
struct vpu_tracing_buffer_header {
	/**
	 * Magic number set by host to detect corruption
	 * @see VPU_TRACING_BUFFER_CANARY
	 */
	u32 host_canary_start;
	/** offset from start of buffer for trace entries */
	u32 read_index;
	/** keeps track of wrapping on the reader side */
	u32 read_wrap_count;
	u32 pad_to_cache_line_size_0[13];
	/** End of first cache line */

	/**
	 * Magic number set by host to detect corruption
	 * @see VPU_TRACING_BUFFER_CANARY
	 */
	u32 vpu_canary_start;
	/** offset from start of buffer from write start */
	u32 write_index;
	/** counter for buffer wrapping */
	u32 wrap_count;
	/** legacy field - do not use */
	u32 reserved_0;
	/**
	 * Size of the log buffer including this header (`header_size`) and space
	 * reserved for all messages. If `alignment` is greater than 0, the `size`
	 * must be a multiple of `alignment`.
	 */
	u32 size;
	/** Header version */
	u16 header_version;
	/** Header size */
	u16 header_size;
	/**
	 * Format of the messages in the trace buffer
	 * 0 - null terminated string
	 * 1 - size + null terminated string
	 * 2 - MIPI-SysT encoding
	 */
	u32 format;
	/**
	 * Message alignment
	 * 0 - messages are place 1 after another
	 * n - every message starts and multiple on offset
	 */
	u32 alignment; /** 64, 128, 256 */
	/** Name of the logging entity, i.e "LRT", "LNN", "SHV0", etc */
	char name[16];
	u32 pad_to_cache_line_size_1[4];
	/** End of second cache line */
};

#pragma pack(pop)

#endif

///@}