Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
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
62struct 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
120enum 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 */
127enum 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 */
142enum 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
180struct 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 */
207enum 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
215struct 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 */
391struct 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///@}