vpu_boot_api.h

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