guc_klvs_abi.h

  1/* SPDX-License-Identifier: MIT */
  2/*
  3 * Copyright © 2021 Intel Corporation
  4 */
  5
  6#ifndef _ABI_GUC_KLVS_ABI_H
  7#define _ABI_GUC_KLVS_ABI_H
  8
  9#include <linux/types.h>
 10
 11/**
 12 * DOC: GuC KLV
 13 *
 14 *  +---+-------+--------------------------------------------------------------+
 15 *  |   | Bits  | Description                                                  |
 16 *  +===+=======+==============================================================+
 17 *  | 0 | 31:16 | **KEY** - KLV key identifier                                 |
 18 *  |   |       |   - `GuC Self Config KLVs`_                                  |
 19 *  |   |       |   - `GuC Opt In Feature KLVs`_                               |
 20 *  |   |       |   - `GuC Scheduling Policies KLVs`_                          |
 21 *  |   |       |   - `GuC VGT Policy KLVs`_                                   |
 22 *  |   |       |   - `GuC VF Configuration KLVs`_                             |
 23 *  |   |       |                                                              |
 24 *  |   +-------+--------------------------------------------------------------+
 25 *  |   |  15:0 | **LEN** - length of VALUE (in 32bit dwords)                  |
 26 *  +---+-------+--------------------------------------------------------------+
 27 *  | 1 |  31:0 | **VALUE** - actual value of the KLV (format depends on KEY)  |
 28 *  +---+-------+                                                              |
 29 *  |...|       |                                                              |
 30 *  +---+-------+                                                              |
 31 *  | n |  31:0 |                                                              |
 32 *  +---+-------+--------------------------------------------------------------+
 33 */
 34
 35#define GUC_KLV_LEN_MIN				1u
 36#define GUC_KLV_0_KEY				(0xffffu << 16)
 37#define GUC_KLV_0_LEN				(0xffffu << 0)
 38#define GUC_KLV_n_VALUE				(0xffffffffu << 0)
 39
 40/**
 41 * DOC: GuC Global Config KLVs
 42 *
 43 * `GuC KLV`_ keys available for use with HOST2GUC_SELF_CFG_.
 44 *
 45 * _`GUC_KLV_GLOBAL_CFG_GMD_ID` : 0x3000
 46 *      Refers to 32 bit architecture version as reported by the HW IP.
 47 *      This key is supported on MTL+ platforms only.
 48 *      Requires GuC ABI 1.2+.
 49 */
 50
 51#define GUC_KLV_GLOBAL_CFG_GMD_ID_KEY			0x3000u
 52#define GUC_KLV_GLOBAL_CFG_GMD_ID_LEN			1u
 53
 54/**
 55 * DOC: GuC Self Config KLVs
 56 *
 57 * `GuC KLV`_ keys available for use with HOST2GUC_SELF_CFG_.
 58 *
 59 * _`GUC_KLV_SELF_CFG_MEMIRQ_STATUS_ADDR` : 0x0900
 60 *      Refers to 64 bit Global Gfx address (in bytes) of memory based interrupts
 61 *      status vector for use by the GuC.
 62 *
 63 * _`GUC_KLV_SELF_CFG_MEMIRQ_SOURCE_ADDR` : 0x0901
 64 *      Refers to 64 bit Global Gfx address (in bytes) of memory based interrupts
 65 *      source vector for use by the GuC.
 66 *
 67 * _`GUC_KLV_SELF_CFG_H2G_CTB_ADDR` : 0x0902
 68 *      Refers to 64 bit Global Gfx address of H2G `CT Buffer`_.
 69 *      Should be above WOPCM address but below APIC base address for native mode.
 70 *
 71 * _`GUC_KLV_SELF_CFG_H2G_CTB_DESCRIPTOR_ADDR : 0x0903
 72 *      Refers to 64 bit Global Gfx address of H2G `CTB Descriptor`_.
 73 *      Should be above WOPCM address but below APIC base address for native mode.
 74 *
 75 * _`GUC_KLV_SELF_CFG_H2G_CTB_SIZE : 0x0904
 76 *      Refers to size of H2G `CT Buffer`_ in bytes.
 77 *      Should be a multiple of 4K.
 78 *
 79 * _`GUC_KLV_SELF_CFG_G2H_CTB_ADDR : 0x0905
 80 *      Refers to 64 bit Global Gfx address of G2H `CT Buffer`_.
 81 *      Should be above WOPCM address but below APIC base address for native mode.
 82 *
 83 * _GUC_KLV_SELF_CFG_G2H_CTB_DESCRIPTOR_ADDR : 0x0906
 84 *      Refers to 64 bit Global Gfx address of G2H `CTB Descriptor`_.
 85 *      Should be above WOPCM address but below APIC base address for native mode.
 86 *
 87 * _GUC_KLV_SELF_CFG_G2H_CTB_SIZE : 0x0907
 88 *      Refers to size of G2H `CT Buffer`_ in bytes.
 89 *      Should be a multiple of 4K.
 90 */
 91
 92#define GUC_KLV_SELF_CFG_MEMIRQ_STATUS_ADDR_KEY		0x0900
 93#define GUC_KLV_SELF_CFG_MEMIRQ_STATUS_ADDR_LEN		2u
 94
 95#define GUC_KLV_SELF_CFG_MEMIRQ_SOURCE_ADDR_KEY		0x0901
 96#define GUC_KLV_SELF_CFG_MEMIRQ_SOURCE_ADDR_LEN		2u
 97
 98#define GUC_KLV_SELF_CFG_H2G_CTB_ADDR_KEY		0x0902
 99#define GUC_KLV_SELF_CFG_H2G_CTB_ADDR_LEN		2u
100
101#define GUC_KLV_SELF_CFG_H2G_CTB_DESCRIPTOR_ADDR_KEY	0x0903
102#define GUC_KLV_SELF_CFG_H2G_CTB_DESCRIPTOR_ADDR_LEN	2u
103
104#define GUC_KLV_SELF_CFG_H2G_CTB_SIZE_KEY		0x0904
105#define GUC_KLV_SELF_CFG_H2G_CTB_SIZE_LEN		1u
106
107#define GUC_KLV_SELF_CFG_G2H_CTB_ADDR_KEY		0x0905
108#define GUC_KLV_SELF_CFG_G2H_CTB_ADDR_LEN		2u
109
110#define GUC_KLV_SELF_CFG_G2H_CTB_DESCRIPTOR_ADDR_KEY	0x0906
111#define GUC_KLV_SELF_CFG_G2H_CTB_DESCRIPTOR_ADDR_LEN	2u
112
113#define GUC_KLV_SELF_CFG_G2H_CTB_SIZE_KEY		0x0907
114#define GUC_KLV_SELF_CFG_G2H_CTB_SIZE_LEN		1u
115
116/*
117 * Per context scheduling policy update keys.
118 */
119enum  {
120	GUC_CONTEXT_POLICIES_KLV_ID_EXECUTION_QUANTUM			= 0x2001,
121	GUC_CONTEXT_POLICIES_KLV_ID_PREEMPTION_TIMEOUT			= 0x2002,
122	GUC_CONTEXT_POLICIES_KLV_ID_SCHEDULING_PRIORITY			= 0x2003,
123	GUC_CONTEXT_POLICIES_KLV_ID_PREEMPT_TO_IDLE_ON_QUANTUM_EXPIRY	= 0x2004,
124	GUC_CONTEXT_POLICIES_KLV_ID_SLPM_GT_FREQUENCY			= 0x2005,
125
126	GUC_CONTEXT_POLICIES_KLV_NUM_IDS = 5,
127};
128
129/**
130 * DOC: GuC Opt In Feature KLVs
131 *
132 * `GuC KLV`_ keys available for use with OPT_IN_FEATURE_KLV
133 *
134 *  _`GUC_KLV_OPT_IN_FEATURE_EXT_CAT_ERR_TYPE` : 0x4001
135 *      Adds an extra dword to the XE_GUC_ACTION_NOTIFY_MEMORY_CAT_ERROR G2H
136 *      containing the type of the CAT error. On HW that does not support
137 *      reporting the CAT error type, the extra dword is set to 0xdeadbeef.
138 *
139 * _`GUC_KLV_OPT_IN_FEATURE_DYNAMIC_INHIBIT_CONTEXT_SWITCH` : 0x4003
140 *      This KLV enables the Dynamic Inhibit Context Switch optimization, which
141 *      consists in the GuC setting the CTX_CTRL_INHIBIT_SYN_CTX_SWITCH bit to
142 *      zero in the CTX_CONTEXT_CONTROL register of LRCs that are submitted
143 *      to an oversubscribed engine. This will cause those contexts to be
144 *      switched out immediately if they hit an unsatisfied semaphore wait
145 *      (instead of waiting the full timeslice duration). The bit is instead set
146 *      to one if a single context is queued on the engine, to avoid it being
147 *      switched out if there isn't another context that can run in its place.
148 */
149
150#define GUC_KLV_OPT_IN_FEATURE_EXT_CAT_ERR_TYPE_KEY 0x4001
151#define GUC_KLV_OPT_IN_FEATURE_EXT_CAT_ERR_TYPE_LEN 0u
152
153#define GUC_KLV_OPT_IN_FEATURE_DYNAMIC_INHIBIT_CONTEXT_SWITCH_KEY 0x4003
154#define GUC_KLV_OPT_IN_FEATURE_DYNAMIC_INHIBIT_CONTEXT_SWITCH_LEN 0u
155
156/**
157 * DOC: GuC Scheduling Policies KLVs
158 *
159 * `GuC KLV`_ keys available for use with UPDATE_SCHEDULING_POLICIES_KLV.
160 *
161 * _`GUC_KLV_SCHEDULING_POLICIES_RENDER_COMPUTE_YIELD` : 0x1001
162 *      Some platforms do not allow concurrent execution of RCS and CCS
163 *      workloads from different address spaces. By default, the GuC prioritizes
164 *      RCS submissions over CCS ones, which can lead to CCS workloads being
165 *      significantly (or completely) starved of execution time. This KLV allows
166 *      the driver to specify a quantum (in ms) and a ratio (percentage value
167 *      between 0 and 100), and the GuC will prioritize the CCS for that
168 *      percentage of each quantum. For example, specifying 100ms and 30% will
169 *      make the GuC prioritize the CCS for 30ms of every 100ms.
170 *      Note that this does not necessarly mean that RCS and CCS engines will
171 *      only be active for their percentage of the quantum, as the restriction
172 *      only kicks in if both classes are fully busy with non-compatible address
173 *      spaces; i.e., if one engine is idle or running the same address space,
174 *      a pending job on the other engine will still be submitted to the HW no
175 *      matter what the ratio is
176 */
177#define GUC_KLV_SCHEDULING_POLICIES_RENDER_COMPUTE_YIELD_KEY	0x1001
178#define GUC_KLV_SCHEDULING_POLICIES_RENDER_COMPUTE_YIELD_LEN	2u
179
180/**
181 * DOC: GuC VGT Policy KLVs
182 *
183 * `GuC KLV`_ keys available for use with PF2GUC_UPDATE_VGT_POLICY.
184 *
185 * _`GUC_KLV_VGT_POLICY_SCHED_IF_IDLE` : 0x8001
186 *      This config sets whether strict scheduling is enabled whereby any VF
187 *      that doesn’t have work to submit is still allocated a fixed execution
188 *      time-slice to ensure active VFs execution is always consistent even
189 *      during other VF reprovisiong / rebooting events. Changing this KLV
190 *      impacts all VFs and takes effect on the next VF-Switch event.
191 *
192 *      :0: don't schedule idle (default)
193 *      :1: schedule if idle
194 *
195 * _`GUC_KLV_VGT_POLICY_ADVERSE_SAMPLE_PERIOD` : 0x8002
196 *      This config sets the sample period for tracking adverse event counters.
197 *       A sample period is the period in millisecs during which events are counted.
198 *       This is applicable for all the VFs.
199 *
200 *      :0: adverse events are not counted (default)
201 *      :n: sample period in milliseconds
202 *
203 * _`GUC_KLV_VGT_POLICY_RESET_AFTER_VF_SWITCH` : 0x8D00
204 *      This enum is to reset utilized HW engine after VF Switch (i.e to clean
205 *      up Stale HW register left behind by previous VF)
206 *
207 *      :0: don't reset (default)
208 *      :1: reset
209 */
210
211#define GUC_KLV_VGT_POLICY_SCHED_IF_IDLE_KEY		0x8001
212#define GUC_KLV_VGT_POLICY_SCHED_IF_IDLE_LEN		1u
213
214#define GUC_KLV_VGT_POLICY_ADVERSE_SAMPLE_PERIOD_KEY	0x8002
215#define GUC_KLV_VGT_POLICY_ADVERSE_SAMPLE_PERIOD_LEN	1u
216
217#define GUC_KLV_VGT_POLICY_RESET_AFTER_VF_SWITCH_KEY	0x8D00
218#define GUC_KLV_VGT_POLICY_RESET_AFTER_VF_SWITCH_LEN	1u
219
220/**
221 * DOC: GuC VF Configuration KLVs
222 *
223 * `GuC KLV`_ keys available for use with PF2GUC_UPDATE_VF_CFG.
224 *
225 * _`GUC_KLV_VF_CFG_GGTT_START` : 0x0001
226 *      A 4K aligned start GTT address/offset assigned to VF.
227 *      Value is 64 bits.
228 *
229 * _`GUC_KLV_VF_CFG_GGTT_SIZE` : 0x0002
230 *      A 4K aligned size of GGTT assigned to VF.
231 *      Value is 64 bits.
232 *
233 * _`GUC_KLV_VF_CFG_LMEM_SIZE` : 0x0003
234 *      A 2M aligned size of local memory assigned to VF.
235 *      Value is 64 bits.
236 *
237 * _`GUC_KLV_VF_CFG_NUM_CONTEXTS` : 0x0004
238 *      Refers to the number of contexts allocated to this VF.
239 *
240 *      :0: no contexts (default)
241 *      :1-65535: number of contexts (Gen12)
242 *
243 * _`GUC_KLV_VF_CFG_TILE_MASK` : 0x0005
244 *      For multi-tiled products, this field contains the bitwise-OR of tiles
245 *      assigned to the VF. Bit-0-set means VF has access to Tile-0,
246 *      Bit-31-set means VF has access to Tile-31, and etc.
247 *      At least one tile will always be allocated.
248 *      If all bits are zero, VF KMD should treat this as a fatal error.
249 *      For, single-tile products this KLV config is ignored.
250 *
251 * _`GUC_KLV_VF_CFG_NUM_DOORBELLS` : 0x0006
252 *      Refers to the number of doorbells allocated to this VF.
253 *
254 *      :0: no doorbells (default)
255 *      :1-255: number of doorbells (Gen12)
256 *
257 * _`GUC_KLV_VF_CFG_EXEC_QUANTUM` : 0x8A01
258 *      This config sets the VFs-execution-quantum in milliseconds.
259 *      GUC will attempt to obey the maximum values as much as HW is capable
260 *      of and this will never be perfectly-exact (accumulated nano-second
261 *      granularity) since the GPUs clock time runs off a different crystal
262 *      from the CPUs clock. Changing this KLV on a VF that is currently
263 *      running a context won't take effect until a new context is scheduled in.
264 *      That said, when the PF is changing this value from 0x0 to
265 *      a non-zero value, it might never take effect if the VF is running an
266 *      infinitely long compute or shader kernel. In such a scenario, the
267 *      PF would need to trigger a VM PAUSE and then change the KLV to force
268 *      it to take effect. Such cases might typically happen on a 1PF+1VF
269 *      Virtualization config enabled for heavier workloads like AI/ML.
270 *
271 *      The max value for this KLV is 100 seconds, anything exceeding that
272 *      will be clamped to the max.
273 *
274 *      :0: infinite exec quantum (default)
275 *      :100000: maximum exec quantum (100000ms == 100s)
276 *
277 * _`GUC_KLV_VF_CFG_PREEMPT_TIMEOUT` : 0x8A02
278 *      This config sets the VF-preemption-timeout in microseconds.
279 *      GUC will attempt to obey the minimum and maximum values as much as
280 *      HW is capable and this will never be perfectly-exact (accumulated
281 *      nano-second granularity) since the GPUs clock time runs off a
282 *      different crystal from the CPUs clock. Changing this KLV on a VF
283 *      that is currently running a context won't take effect until a new
284 *      context is scheduled in.
285 *      That said, when the PF is changing this value from 0x0 to
286 *      a non-zero value, it might never take effect if the VF is running an
287 *      infinitely long compute or shader kernel.
288 *      In this case, the PF would need to trigger a VM PAUSE and then change
289 *      the KLV to force it to take effect. Such cases might typically happen
290 *      on a 1PF+1VF Virtualization config enabled for heavier workloads like
291 *      AI/ML.
292 *
293 *      The max value for this KLV is 100 seconds, anything exceeding that
294 *      will be clamped to the max.
295 *
296 *      :0: no preemption timeout (default)
297 *      :100000000: maximum preemption timeout (100000000us == 100s)
298 *
299 * _`GUC_KLV_VF_CFG_THRESHOLD_CAT_ERR` : 0x8A03
300 *      This config sets threshold for CAT errors caused by the VF.
301 *
302 *      :0: adverse events or error will not be reported (default)
303 *      :n: event occurrence count per sampling interval
304 *
305 * _`GUC_KLV_VF_CFG_THRESHOLD_ENGINE_RESET` : 0x8A04
306 *      This config sets threshold for engine reset caused by the VF.
307 *
308 *      :0: adverse events or error will not be reported (default)
309 *      :n: event occurrence count per sampling interval
310 *
311 * _`GUC_KLV_VF_CFG_THRESHOLD_PAGE_FAULT` : 0x8A05
312 *      This config sets threshold for page fault errors caused by the VF.
313 *
314 *      :0: adverse events or error will not be reported (default)
315 *      :n: event occurrence count per sampling interval
316 *
317 * _`GUC_KLV_VF_CFG_THRESHOLD_H2G_STORM` : 0x8A06
318 *      This config sets threshold for H2G interrupts triggered by the VF.
319 *
320 *      :0: adverse events or error will not be reported (default)
321 *      :n: time (us) per sampling interval
322 *
323 * _`GUC_KLV_VF_CFG_THRESHOLD_IRQ_STORM` : 0x8A07
324 *      This config sets threshold for GT interrupts triggered by the VF's
325 *      workloads.
326 *
327 *      :0: adverse events or error will not be reported (default)
328 *      :n: time (us) per sampling interval
329 *
330 * _`GUC_KLV_VF_CFG_THRESHOLD_DOORBELL_STORM` : 0x8A08
331 *      This config sets threshold for doorbell's ring triggered by the VF.
332 *
333 *      :0: adverse events or error will not be reported (default)
334 *      :n: time (us) per sampling interval
335 *
336 * _`GUC_KLV_VF_CFG_BEGIN_DOORBELL_ID` : 0x8A0A
337 *      Refers to the start index of doorbell assigned to this VF.
338 *
339 *      :0: (default)
340 *      :1-255: number of doorbells (Gen12)
341 *
342 * _`GUC_KLV_VF_CFG_BEGIN_CONTEXT_ID` : 0x8A0B
343 *      Refers to the start index in context array allocated to this VF’s use.
344 *
345 *      :0: (default)
346 *      :1-65535: number of contexts (Gen12)
347 *
348 * _`GUC_KLV_VF_CFG_SCHED_PRIORITY` : 0x8A0C
349 *      This config controls VF’s scheduling priority.
350 *
351 *      :0: LOW = schedule VF only if it has active work (default)
352 *      :1: NORMAL = schedule VF always, irrespective of whether it has work or not
353 *      :2: HIGH = schedule VF in the next time-slice after current active
354 *          time-slice completes if it has active work
355 */
356
357#define GUC_KLV_VF_CFG_GGTT_START_KEY		0x0001
358#define GUC_KLV_VF_CFG_GGTT_START_LEN		2u
359
360#define GUC_KLV_VF_CFG_GGTT_SIZE_KEY		0x0002
361#define GUC_KLV_VF_CFG_GGTT_SIZE_LEN		2u
362
363#define GUC_KLV_VF_CFG_LMEM_SIZE_KEY		0x0003
364#define GUC_KLV_VF_CFG_LMEM_SIZE_LEN		2u
365
366#define GUC_KLV_VF_CFG_NUM_CONTEXTS_KEY		0x0004
367#define GUC_KLV_VF_CFG_NUM_CONTEXTS_LEN		1u
368
369#define GUC_KLV_VF_CFG_TILE_MASK_KEY		0x0005
370#define GUC_KLV_VF_CFG_TILE_MASK_LEN		1u
371
372#define GUC_KLV_VF_CFG_NUM_DOORBELLS_KEY	0x0006
373#define GUC_KLV_VF_CFG_NUM_DOORBELLS_LEN	1u
374
375#define GUC_KLV_VF_CFG_EXEC_QUANTUM_KEY		0x8a01
376#define GUC_KLV_VF_CFG_EXEC_QUANTUM_LEN		1u
377#define GUC_KLV_VF_CFG_EXEC_QUANTUM_MAX_VALUE	100000u
378
379#define GUC_KLV_VF_CFG_PREEMPT_TIMEOUT_KEY		0x8a02
380#define GUC_KLV_VF_CFG_PREEMPT_TIMEOUT_LEN		1u
381#define GUC_KLV_VF_CFG_PREEMPT_TIMEOUT_MAX_VALUE	100000000u
382
383#define GUC_KLV_VF_CFG_THRESHOLD_CAT_ERR_KEY		0x8a03
384#define GUC_KLV_VF_CFG_THRESHOLD_CAT_ERR_LEN		1u
385
386#define GUC_KLV_VF_CFG_THRESHOLD_ENGINE_RESET_KEY	0x8a04
387#define GUC_KLV_VF_CFG_THRESHOLD_ENGINE_RESET_LEN	1u
388
389#define GUC_KLV_VF_CFG_THRESHOLD_PAGE_FAULT_KEY		0x8a05
390#define GUC_KLV_VF_CFG_THRESHOLD_PAGE_FAULT_LEN		1u
391
392#define GUC_KLV_VF_CFG_THRESHOLD_H2G_STORM_KEY		0x8a06
393#define GUC_KLV_VF_CFG_THRESHOLD_H2G_STORM_LEN		1u
394
395#define GUC_KLV_VF_CFG_THRESHOLD_IRQ_STORM_KEY		0x8a07
396#define GUC_KLV_VF_CFG_THRESHOLD_IRQ_STORM_LEN		1u
397
398#define GUC_KLV_VF_CFG_THRESHOLD_DOORBELL_STORM_KEY	0x8a08
399#define GUC_KLV_VF_CFG_THRESHOLD_DOORBELL_STORM_LEN	1u
400
401#define GUC_KLV_VF_CFG_BEGIN_DOORBELL_ID_KEY	0x8a0a
402#define GUC_KLV_VF_CFG_BEGIN_DOORBELL_ID_LEN	1u
403
404#define GUC_KLV_VF_CFG_BEGIN_CONTEXT_ID_KEY	0x8a0b
405#define GUC_KLV_VF_CFG_BEGIN_CONTEXT_ID_LEN	1u
406
407#define GUC_KLV_VF_CFG_SCHED_PRIORITY_KEY	0x8a0c
408#define GUC_KLV_VF_CFG_SCHED_PRIORITY_LEN	1u
409#define   GUC_SCHED_PRIORITY_LOW		0u
410#define   GUC_SCHED_PRIORITY_NORMAL		1u
411#define   GUC_SCHED_PRIORITY_HIGH		2u
412
413/*
414 * Workaround keys:
415 */
416enum xe_guc_klv_ids {
417	GUC_WORKAROUND_KLV_BLOCK_INTERRUPTS_WHEN_MGSR_BLOCKED				= 0x9002,
418	GUC_WORKAROUND_KLV_DISABLE_PSMI_INTERRUPTS_AT_C6_ENTRY_RESTORE_AT_EXIT		= 0x9004,
419	GUC_WORKAROUND_KLV_ID_GAM_PFQ_SHADOW_TAIL_POLLING				= 0x9005,
420	GUC_WORKAROUND_KLV_ID_DISABLE_MTP_DURING_ASYNC_COMPUTE				= 0x9007,
421	GUC_WA_KLV_NP_RD_WRITE_TO_CLEAR_RCSM_AT_CGP_LATE_RESTORE			= 0x9008,
422	GUC_WORKAROUND_KLV_ID_BACK_TO_BACK_RCS_ENGINE_RESET				= 0x9009,
423	GUC_WA_KLV_WAKE_POWER_DOMAINS_FOR_OUTBOUND_MMIO					= 0x900a,
424	GUC_WA_KLV_RESET_BB_STACK_PTR_ON_VF_SWITCH					= 0x900b,
425	GUC_WA_KLV_RESTORE_UNSAVED_MEDIA_CONTROL_REG					= 0x900c,
426};
427
428#endif