1 /* SPDX-License-Identifier: MIT */ 2 /* 3 * Copyright (c) 2020-2025, Intel Corporation. 4 */ 5 6 /** 7 * @addtogroup Boot 8 * @{ 9 */ 10 11 /** 12 * @file 13 * @brief Boot API public header file. 14 */ 15 16 #ifndef VPU_BOOT_API_H 17 #define VPU_BOOT_API_H 18 19 /** 20 * The below values will be used to construct the version info this way: 21 * fw_bin_header->api_version[VPU_BOOT_API_VER_ID] = (VPU_BOOT_API_VER_MAJOR << 16) | 22 * VPU_BOOT_API_VER_MINOR; 23 * VPU_BOOT_API_VER_PATCH will be ignored. KMD and compatibility is not affected if this changes 24 * This information is collected by using vpuip_2/application/vpuFirmware/make_std_fw_image.py 25 * If a header is missing this info we ignore the header, if a header is missing or contains 26 * partial info a build error will be generated. 27 */ 28 29 /** 30 * Major version changes that break backward compatibility. 31 * Major version must start from 1 and can only be incremented. 32 */ 33 #define VPU_BOOT_API_VER_MAJOR 3 34 35 /** 36 * Minor version changes when API backward compatibility is preserved. 37 * Resets to 0 if Major version is incremented. 38 */ 39 #define VPU_BOOT_API_VER_MINOR 29 40 41 /** 42 * API header changed (field names, documentation, formatting) but API itself has not been changed 43 */ 44 #define VPU_BOOT_API_VER_PATCH 4 45 46 /** 47 * Index in the API version table 48 * Must be unique for each API 49 */ 50 #define VPU_BOOT_API_VER_INDEX 0 51 52 #pragma pack(push, 4) 53 54 /** 55 * Firmware image header format 56 */ 57 #define VPU_FW_HEADER_SIZE 4096 58 #define VPU_FW_HEADER_VERSION 0x1 59 #define VPU_FW_VERSION_SIZE 32 60 #define VPU_FW_API_VER_NUM 16 61 62 struct vpu_firmware_header { 63 u32 header_version; 64 u32 image_format; 65 u64 image_load_address; 66 u32 image_size; 67 u64 entry_point; 68 u8 vpu_version[VPU_FW_VERSION_SIZE]; 69 u32 compression_type; 70 u64 firmware_version_load_address; 71 u32 firmware_version_size; 72 u64 boot_params_load_address; 73 u32 api_version[VPU_FW_API_VER_NUM]; 74 /** Size of memory require for firmware execution */ 75 u32 runtime_size; 76 u32 shave_nn_fw_size; 77 /** 78 * Size of primary preemption buffer, assuming a 2-job submission queue. 79 * NOTE: host driver is expected to adapt size accordingly to actual 80 * submission queue size and device capabilities. 81 */ 82 u32 preemption_buffer_1_size; 83 /** 84 * Size of secondary preemption buffer, assuming a 2-job submission queue. 85 * NOTE: host driver is expected to adapt size accordingly to actual 86 * submission queue size and device capabilities. 87 */ 88 u32 preemption_buffer_2_size; 89 /** 90 * Maximum preemption buffer size that the FW can use: no need for the host 91 * driver to allocate more space than that specified by these fields. 92 * A value of 0 means no declared limit. 93 */ 94 u32 preemption_buffer_1_max_size; 95 u32 preemption_buffer_2_max_size; 96 /** Space reserved for future preemption-related fields. */ 97 u32 preemption_reserved[4]; 98 /** FW image read only section start address, 4KB aligned */ 99 u64 ro_section_start_address; 100 /** FW image read only section size, 4KB aligned */ 101 u32 ro_section_size; 102 u32 reserved; 103 }; 104 105 /** 106 * Firmware boot parameters format 107 */ 108 109 /** Values for boot_type field */ 110 #define VPU_BOOT_TYPE_COLDBOOT 0 111 #define VPU_BOOT_TYPE_WARMBOOT 1 112 113 /** Value for magic filed */ 114 #define VPU_BOOT_PARAMS_MAGIC 0x10000 115 116 /** VPU scheduling mode. By default, OS scheduling is used. */ 117 #define VPU_SCHEDULING_MODE_OS 0 118 #define VPU_SCHEDULING_MODE_HW 1 119 120 enum VPU_BOOT_L2_CACHE_CFG_TYPE { 121 VPU_BOOT_L2_CACHE_CFG_UPA = 0, 122 VPU_BOOT_L2_CACHE_CFG_NN = 1, 123 VPU_BOOT_L2_CACHE_CFG_NUM = 2 124 }; 125 126 /** VPU MCA ECC signalling mode. By default, no signalling is used */ 127 enum VPU_BOOT_MCA_ECC_SIGNAL_TYPE { 128 VPU_BOOT_MCA_ECC_NONE = 0, 129 VPU_BOOT_MCA_ECC_CORR = 1, 130 VPU_BOOT_MCA_ECC_FATAL = 2, 131 VPU_BOOT_MCA_ECC_BOTH = 3 132 }; 133 134 /** 135 * Logging destinations. 136 * 137 * Logging output can be directed to different logging destinations. This enum 138 * defines the list of logging destinations supported by the VPU firmware (NOTE: 139 * a specific VPU FW binary may support only a subset of such output 140 * destinations, depending on the target platform and compile options). 141 */ 142 enum vpu_trace_destination { 143 VPU_TRACE_DESTINATION_PIPEPRINT = 0x1, 144 VPU_TRACE_DESTINATION_VERBOSE_TRACING = 0x2, 145 VPU_TRACE_DESTINATION_NORTH_PEAK = 0x4, 146 }; 147 148 /* 149 * Processor bit shifts (for loggable HW components). 150 */ 151 #define VPU_TRACE_PROC_BIT_RESERVED 0 152 #define VPU_TRACE_PROC_BIT_LRT 1 153 #define VPU_TRACE_PROC_BIT_LNN 2 154 #define VPU_TRACE_PROC_BIT_SHV_0 3 155 #define VPU_TRACE_PROC_BIT_SHV_1 4 156 #define VPU_TRACE_PROC_BIT_SHV_2 5 157 #define VPU_TRACE_PROC_BIT_SHV_3 6 158 #define VPU_TRACE_PROC_BIT_SHV_4 7 159 #define VPU_TRACE_PROC_BIT_SHV_5 8 160 #define VPU_TRACE_PROC_BIT_SHV_6 9 161 #define VPU_TRACE_PROC_BIT_SHV_7 10 162 #define VPU_TRACE_PROC_BIT_SHV_8 11 163 #define VPU_TRACE_PROC_BIT_SHV_9 12 164 #define VPU_TRACE_PROC_BIT_SHV_10 13 165 #define VPU_TRACE_PROC_BIT_SHV_11 14 166 #define VPU_TRACE_PROC_BIT_SHV_12 15 167 #define VPU_TRACE_PROC_BIT_SHV_13 16 168 #define VPU_TRACE_PROC_BIT_SHV_14 17 169 #define VPU_TRACE_PROC_BIT_SHV_15 18 170 #define VPU_TRACE_PROC_BIT_ACT_SHV_0 19 171 #define VPU_TRACE_PROC_BIT_ACT_SHV_1 20 172 #define VPU_TRACE_PROC_BIT_ACT_SHV_2 21 173 #define VPU_TRACE_PROC_BIT_ACT_SHV_3 22 174 #define VPU_TRACE_PROC_NO_OF_HW_DEVS 23 175 176 /** VPU 30xx HW component IDs are sequential, so define first and last IDs. */ 177 #define VPU_TRACE_PROC_BIT_30XX_FIRST VPU_TRACE_PROC_BIT_LRT 178 #define VPU_TRACE_PROC_BIT_30XX_LAST VPU_TRACE_PROC_BIT_SHV_15 179 180 struct vpu_boot_l2_cache_config { 181 u8 use; 182 u8 cfg; 183 }; 184 185 /** 186 * When HW scheduling mode is enabled, a present period is defined. 187 * It will be used by VPU to swap between normal and focus priorities 188 * to prevent starving of normal priority band (when implemented). 189 * Host must provide a valid value at boot time in 190 * `vpu_focus_present_timer_ms`. If the value provided by the host is not within the 191 * defined range a default value will be used. Here we define the min. and max. 192 * allowed values and the and default value of the present period. Units are milliseconds. 193 */ 194 #define VPU_PRESENT_CALL_PERIOD_MS_DEFAULT 50 195 #define VPU_PRESENT_CALL_PERIOD_MS_MIN 16 196 #define VPU_PRESENT_CALL_PERIOD_MS_MAX 10000 197 198 /** 199 * Macros to enable various power profiles within the NPU. 200 * To be defined as part of 32 bit mask. 201 */ 202 #define POWER_PROFILE_SURVIVABILITY 0x1 203 204 /** 205 * Enum for dvfs_mode boot param. 206 */ 207 enum vpu_governor { 208 VPU_GOV_DEFAULT = 0, /** Default Governor for the system */ 209 VPU_GOV_MAX_PERFORMANCE = 1, /** Maximum performance governor */ 210 VPU_GOV_ON_DEMAND = 2, /** On Demand frequency control governor */ 211 VPU_GOV_POWER_SAVE = 3, /** Power save governor */ 212 VPU_GOV_ON_DEMAND_PRIORITY_AWARE = 4 /** On Demand priority based governor */ 213 }; 214 215 struct vpu_boot_params { 216 u32 magic; 217 u32 vpu_id; 218 u32 vpu_count; 219 u32 reserved_0[5]; 220 /** Clock frequencies: 0x20 - 0xFF */ 221 u32 frequency; 222 u32 reserved_1[12]; 223 u32 perf_clk_frequency; 224 u32 reserved_2[42]; 225 /** Memory regions: 0x100 - 0x1FF */ 226 u64 ipc_header_area_start; 227 u32 ipc_header_area_size; 228 u64 shared_region_base; 229 u32 shared_region_size; 230 u64 ipc_payload_area_start; 231 u32 ipc_payload_area_size; 232 u64 global_aliased_pio_base; 233 u32 global_aliased_pio_size; 234 u32 autoconfig; 235 struct vpu_boot_l2_cache_config cache_defaults[VPU_BOOT_L2_CACHE_CFG_NUM]; 236 u32 reserved_3[3]; 237 /** 238 * ShaveNN FW section VPU base address 239 * On VPU2.7 HW this address must be within 2GB range starting from L2C_PAGE_TABLE base 240 */ 241 u64 shave_nn_fw_base; 242 u64 save_restore_ret_address; /** stores the address of FW's restore entry point */ 243 u32 reserved_4[43]; 244 /** IRQ re-direct numbers: 0x200 - 0x2FF */ 245 s32 watchdog_irq_mss; 246 s32 watchdog_irq_nce; 247 /** ARM -> VPU doorbell interrupt. ARM is notifying VPU of async command or compute job. */ 248 u32 host_to_vpu_irq; 249 /** VPU -> ARM job done interrupt. VPU is notifying ARM of compute job completion. */ 250 u32 job_done_irq; 251 /** Padding. */ 252 u32 reserved_5[60]; 253 /** Silicon information: 0x300 - 0x3FF */ 254 u32 host_version_id; 255 u32 si_stepping; 256 u64 device_id; 257 u64 feature_exclusion; 258 u64 sku; 259 /** PLL ratio for minimum clock frequency */ 260 u32 min_freq_pll_ratio; 261 /** PLL ratio for maximum clock frequency */ 262 u32 max_freq_pll_ratio; 263 /** 264 * Initial log level threshold (messages with log level severity less than 265 * the threshold will not be logged); applies to every enabled logging 266 * destination and loggable HW component. See 'mvLog_t' enum for acceptable 267 * values. 268 * TODO: EISW-33556: Move log level definition (mvLog_t) to this file. 269 */ 270 u32 default_trace_level; 271 u32 boot_type; 272 u64 punit_telemetry_sram_base; 273 u64 punit_telemetry_sram_size; 274 u32 vpu_telemetry_enable; 275 u64 crit_tracing_buff_addr; 276 u32 crit_tracing_buff_size; 277 u64 verbose_tracing_buff_addr; 278 u32 verbose_tracing_buff_size; 279 u64 verbose_tracing_sw_component_mask; /** TO BE REMOVED */ 280 /** 281 * Mask of destinations to which logging messages are delivered; bitwise OR 282 * of values defined in vpu_trace_destination enum. 283 */ 284 u32 trace_destination_mask; 285 /** 286 * Mask of hardware components for which logging is enabled; bitwise OR of 287 * bits defined by the VPU_TRACE_PROC_BIT_* macros. 288 */ 289 u64 trace_hw_component_mask; 290 /** Mask of trace message formats supported by the driver */ 291 u64 tracing_buff_message_format_mask; 292 u64 trace_reserved_1[2]; 293 u32 reserved_6; 294 /** PLL ratio for efficient clock frequency */ 295 u32 pn_freq_pll_ratio; 296 /** 297 * DVFS Mode: 298 * 0 - Default, DVFS mode selected by the firmware 299 * 1 - Max Performance 300 * 2 - On Demand 301 * 3 - Power Save 302 * 4 - On Demand Priority Aware 303 */ 304 u32 dvfs_mode; 305 /** 306 * Depending on DVFS Mode: 307 * On-demand: Default if 0. 308 * Bit 0-7 - uint8_t: Highest residency percent 309 * Bit 8-15 - uint8_t: High residency percent 310 * Bit 16-23 - uint8_t: Low residency percent 311 * Bit 24-31 - uint8_t: Lowest residency percent 312 * Bit 32-35 - unsigned 4b: PLL Ratio increase amount on highest residency 313 * Bit 36-39 - unsigned 4b: PLL Ratio increase amount on high residency 314 * Bit 40-43 - unsigned 4b: PLL Ratio decrease amount on low residency 315 * Bit 44-47 - unsigned 4b: PLL Ratio decrease amount on lowest frequency 316 * Bit 48-55 - uint8_t: Period (ms) for residency decisions 317 * Bit 56-63 - uint8_t: Averaging windows (as multiples of period. Max: 30 decimal) 318 * Power Save/Max Performance: Unused 319 */ 320 u64 dvfs_param; 321 /** 322 * D0i3 delayed entry 323 * Bit0: Disable CPU state save on D0i2 entry flow. 324 * 0: Every D0i2 entry saves state. Save state IPC message ignored. 325 * 1: IPC message required to save state on D0i3 entry flow. 326 */ 327 u32 d0i3_delayed_entry; 328 /** Time spent by VPU in D0i3 state */ 329 u64 d0i3_residency_time_us; 330 /** Value of VPU perf counter at the time of entering D0i3 state . */ 331 u64 d0i3_entry_vpu_ts; 332 /** 333 * The system time of the host operating system in microseconds. 334 * E.g the number of microseconds since 1st of January 1970, or whatever 335 * date the host operating system uses to maintain system time. 336 * This value will be used to track system time on the VPU. 337 * The KMD is required to update this value on every VPU reset. 338 */ 339 u64 system_time_us; 340 u32 reserved_7[2]; 341 /** 342 * The delta between device monotonic time and the current value of the 343 * HW timestamp register, in ticks. Written by the firmware during boot. 344 * Can be used by the KMD to calculate device time. 345 */ 346 u64 device_time_delta_ticks; 347 u32 reserved_8[30]; 348 /** Power States transitions timestamps: 0x440 - 0x46F*/ 349 struct power_states_timestamps { 350 /** VPU_IDLE -> VPU_ACTIVE transition initiated timestamp */ 351 u64 vpu_active_state_requested; 352 /** VPU_IDLE -> VPU_ACTIVE transition completed timestamp */ 353 u64 vpu_active_state_achieved; 354 /** VPU_ACTIVE -> VPU_IDLE transition initiated timestamp */ 355 u64 vpu_idle_state_requested; 356 /** VPU_ACTIVE -> VPU_IDLE transition completed timestamp */ 357 u64 vpu_idle_state_achieved; 358 /** VPU_IDLE -> VPU_STANDBY transition initiated timestamp */ 359 u64 vpu_standby_state_requested; 360 /** VPU_IDLE -> VPU_STANDBY transition completed timestamp */ 361 u64 vpu_standby_state_achieved; 362 } power_states_timestamps; 363 /** VPU scheduling mode. Values defined by VPU_SCHEDULING_MODE_* macros. */ 364 u32 vpu_scheduling_mode; 365 /** Present call period in milliseconds. */ 366 u32 vpu_focus_present_timer_ms; 367 /** VPU ECC Signaling */ 368 u32 vpu_uses_ecc_mca_signal; 369 /** Values defined by POWER_PROFILE* macros */ 370 u32 power_profile; 371 /** Microsecond value for DCT active cycle */ 372 u32 dct_active_us; 373 /** Microsecond value for DCT inactive cycle */ 374 u32 dct_inactive_us; 375 /** Unused/reserved: 0x488 - 0xFFF */ 376 u32 reserved_9[734]; 377 }; 378 379 /** Magic numbers set between host and vpu to detect corruption of tracing init */ 380 #define VPU_TRACING_BUFFER_CANARY (0xCAFECAFE) 381 382 /** Tracing buffer message format definitions */ 383 #define VPU_TRACING_FORMAT_STRING 0 384 #define VPU_TRACING_FORMAT_MIPI 2 385 /** 386 * Header of the tracing buffer. 387 * The below defined header will be stored at the beginning of 388 * each allocated tracing buffer, followed by a series of 256b 389 * of ASCII trace message entries. 390 */ 391 struct vpu_tracing_buffer_header { 392 /** 393 * Magic number set by host to detect corruption 394 * @see VPU_TRACING_BUFFER_CANARY 395 */ 396 u32 host_canary_start; 397 /** offset from start of buffer for trace entries */ 398 u32 read_index; 399 /** keeps track of wrapping on the reader side */ 400 u32 read_wrap_count; 401 u32 pad_to_cache_line_size_0[13]; 402 /** End of first cache line */ 403 404 /** 405 * Magic number set by host to detect corruption 406 * @see VPU_TRACING_BUFFER_CANARY 407 */ 408 u32 vpu_canary_start; 409 /** offset from start of buffer from write start */ 410 u32 write_index; 411 /** counter for buffer wrapping */ 412 u32 wrap_count; 413 /** legacy field - do not use */ 414 u32 reserved_0; 415 /** 416 * Size of the log buffer including this header (`header_size`) and space 417 * reserved for all messages. If `alignment` is greater than 0, the `size` 418 * must be a multiple of `alignment`. 419 */ 420 u32 size; 421 /** Header version */ 422 u16 header_version; 423 /** Header size */ 424 u16 header_size; 425 /** 426 * Format of the messages in the trace buffer 427 * 0 - null terminated string 428 * 1 - size + null terminated string 429 * 2 - MIPI-SysT encoding 430 */ 431 u32 format; 432 /** 433 * Message alignment 434 * 0 - messages are place 1 after another 435 * n - every message starts and multiple on offset 436 */ 437 u32 alignment; /** 64, 128, 256 */ 438 /** Name of the logging entity, i.e "LRT", "LNN", "SHV0", etc */ 439 char name[16]; 440 u32 pad_to_cache_line_size_1[4]; 441 /** End of second cache line */ 442 }; 443 444 #pragma pack(pop) 445 446 #endif 447 448 ///@} 449