Register Table Processing¶

Internal infrastructure to define how registers should be updated based onrules and actions. This can be used to define tables with multiple entries(one per register) that will be walked over at some point in time to applythe values to the registers that have matching rules.

Internal API¶

structxe_rtp_action¶: action to take for any matching rule

Definition:

struct xe_rtp_action {    struct xe_reg           reg;    u32 clr_bits;    u32 set_bits;#define XE_RTP_NOCHECK          .read_mask = 0;    u32 read_mask;#define XE_RTP_ACTION_FLAG_ENGINE_BASE          BIT(0);    u8 flags;};

Members

reg: Register
clr_bits: bits to clear when updating register. It’s always asuperset of bits being modified
set_bits: bits to set when updating register
read_mask: mask for bits to consider when reading value back
flags: flags to apply on rule evaluation or action

Description

Thisstructrecords what action should be taken in a register that has amatching rule. Example of actions: set/clear bits.

XE_RTP_RULE_PLATFORM¶

XE_RTP_RULE_PLATFORM(plat_)

Create rule matching platform

Parameters

plat_: platform to match

Description

Refer toXE_RTP_RULES() for expected usage.

XE_RTP_RULE_SUBPLATFORM¶

XE_RTP_RULE_SUBPLATFORM(plat_,sub_)

Create rule matching platform and sub-platform

Parameters

plat_: platform to match
sub_: sub-platform to match

Description

Refer toXE_RTP_RULES() for expected usage.

XE_RTP_RULE_GRAPHICS_STEP¶

XE_RTP_RULE_GRAPHICS_STEP(start_,end_)

Create rule matching graphics stepping

Parameters

start_: First stepping matching the rule
end_: First stepping that does not match the rule

Description

Note that the range matching this rule is [start_,end_ ), i.e. inclusiveon the left, exclusive on the right.

Refer toXE_RTP_RULES() for expected usage.

XE_RTP_RULE_MEDIA_STEP¶

XE_RTP_RULE_MEDIA_STEP(start_,end_)

Create rule matching media stepping

Parameters

start_: First stepping matching the rule
end_: First stepping that does not match the rule

Description

Note that the range matching this rule is [start_,end_ ), i.e. inclusiveon the left, exclusive on the right.

Refer toXE_RTP_RULES() for expected usage.

XE_RTP_RULE_ENGINE_CLASS¶

XE_RTP_RULE_ENGINE_CLASS(cls_)

Create rule matching an engine class

Parameters

cls_: Engine class to match

Description

Refer toXE_RTP_RULES() for expected usage.

XE_RTP_RULE_FUNC¶

XE_RTP_RULE_FUNC(func__)

Create rule using callback function for match

Parameters

func__: Function to call to decide if rule matches

Description

This allows more complex checks to be performed. TheXE_RTPinfrastructure will simply call the functionfunc_ passed to decide if thisrule matches the device.

Refer toXE_RTP_RULES() for expected usage.

XE_RTP_RULE_GRAPHICS_VERSION¶

XE_RTP_RULE_GRAPHICS_VERSION(ver__)

Create rule matching graphics version

Parameters

ver__: Graphics IP version to match

Description

Refer toXE_RTP_RULES() for expected usage.

XE_RTP_RULE_GRAPHICS_VERSION_RANGE¶

XE_RTP_RULE_GRAPHICS_VERSION_RANGE(ver_start__,ver_end__)

Create rule matching a range of graphics version

Parameters

ver_start__: First graphics IP version to match
ver_end__: Last graphics IP version to match

Description

Note that the range matching this rule is [ver_start__,ver_end__ ], i.e.inclusive on both sides

Refer toXE_RTP_RULES() for expected usage.

XE_RTP_RULE_GRAPHICS_VERSION_ANY_GT¶

XE_RTP_RULE_GRAPHICS_VERSION_ANY_GT(ver__)

Create rule matching graphics version on any GT

Parameters

ver__: Graphics IP version to match

Description

Like XE_RTP_RULE_GRAPHICS_VERSION, but it matches even if the current GTbeing checked is not of the graphics type. It allows to add RTP entries toanother GT when the device contains a Graphics IP with that version.

Refer toXE_RTP_RULES() for expected usage.

XE_RTP_RULE_MEDIA_VERSION¶

XE_RTP_RULE_MEDIA_VERSION(ver__)

Create rule matching media version

Parameters

ver__: Media IP version to match

Description

Refer toXE_RTP_RULES() for expected usage.

XE_RTP_RULE_MEDIA_VERSION_RANGE¶

XE_RTP_RULE_MEDIA_VERSION_RANGE(ver_start__,ver_end__)

Create rule matching a range of media version

Parameters

ver_start__: First media IP version to match
ver_end__: Last media IP version to match

Description

Note that the range matching this rule is [ver_start__,ver_end__ ], i.e.inclusive on both sides

Refer toXE_RTP_RULES() for expected usage.

XE_RTP_RULE_MEDIA_VERSION_ANY_GT¶

XE_RTP_RULE_MEDIA_VERSION_ANY_GT(ver__)

Create rule matching media version on any GT

Parameters

ver__: Media IP version to match

Description

Like XE_RTP_RULE_MEDIA_VERSION, but it matches even if the current GT beingchecked is not of the media type. It allows to add RTP entries to anotherGT when the device contains a Media IP with that version.

Refer toXE_RTP_RULES() for expected usage.

XE_RTP_RULE_IS_INTEGRATED¶

XE_RTP_RULE_IS_INTEGRATED

Create a rule matching integrated graphics devices
Description
Refer toXE_RTP_RULES() for expected usage.

XE_RTP_RULE_IS_DISCRETE¶

XE_RTP_RULE_IS_DISCRETE

Create a rule matching discrete graphics devices
Description
Refer toXE_RTP_RULES() for expected usage.

XE_RTP_RULE_OR¶

XE_RTP_RULE_OR

Create an OR condition for rtp rules
Description
RTP rules are AND’ed when evaluated and all of them need to match.XE_RTP_RULE_OR allows to create set of rules where any of them matching issufficient for the action to trigger. Example:
conststructxe_rtp_entry_srentries[]={...{XE_RTP_NAME("test-entry"),XE_RTP_RULES(PLATFORM(DG2),OR,PLATFORM(TIGERLAKE)),...},...};

XE_RTP_ACTION_WR¶

XE_RTP_ACTION_WR(reg_,val_,...)

Helper to write a value to the register, overriding all the bits

Parameters

reg_: Register
val_: Value to set
...: Additional fields to override in thestructxe_rtp_action entry

Description

The correspondent notation in bspec is:

REGNAME = VALUE

XE_RTP_ACTION_SET¶

XE_RTP_ACTION_SET(reg_,val_,...)

Set bits fromval_ in the register.

Parameters

reg_: Register
val_: Bits to set in the register
...: Additional fields to override in thestructxe_rtp_action entry

Description

For masked registers this translates to a single write, while for otherregisters it’s a RMW. The correspondent bspec notation is (example for bits 2and 5, but could be any):

REGNAME[2] = 1REGNAME[5] = 1

XE_RTP_ACTION_CLR¶

XE_RTP_ACTION_CLR(reg_,val_,...)

Clear bits fromval_ in the register.

Parameters

reg_: Register
val_: Bits to clear in the register
...: Additional fields to override in thestructxe_rtp_action entry

Description

For masked registers this translates to a single write, while for otherregisters it’s a RMW. The correspondent bspec notation is (example for bits 2and 5, but could be any):

REGNAME[2] = 0REGNAME[5] = 0

XE_RTP_ACTION_FIELD_SET¶

XE_RTP_ACTION_FIELD_SET(reg_,mask_bits_,val_,...)

Set a bit range

Parameters

reg_: Register
mask_bits_: Mask of bits to be changed in the register, forming a field
val_: Value to set in the field denoted bymask_bits_
...: Additional fields to override in thestructxe_rtp_action entry

Description

For masked registers this translates to a single write, while for otherregisters it’s a RMW. The correspondent bspec notation is:

REGNAME[<end>:<start>] = VALUE

XE_RTP_ACTION_WHITELIST¶

XE_RTP_ACTION_WHITELIST(reg_,val_,...)

Add register to userspace whitelist

Parameters

reg_: Register
val_: Whitelist-specific flags to set
...: Additional fields to override in thestructxe_rtp_action entry

Description

Add a register to the whitelist, allowing userspace to modify the ster withregular user privileges.

XE_RTP_NAME¶

XE_RTP_NAME(s_)

Helper to set the name in xe_rtp_entry

Parameters

s_: Name describing this rule, often a HW-specific number

Description

TODO: maybe move this behind a debug config?

XE_RTP_ENTRY_FLAG¶

XE_RTP_ENTRY_FLAG(...)

Helper to add multiple flags to astructxe_rtp_entry_sr

Parameters

...: Entry flags, without theXE_RTP_ENTRY_FLAG_ prefix

Description

Helper to automatically add aXE_RTP_ENTRY_FLAG_ prefix to the flagswhen definingstructxe_rtp_entry entries. Example:

conststructxe_rtp_entry_srwa_entries[]={...{XE_RTP_NAME("test-entry"),...XE_RTP_ENTRY_FLAG(FOREACH_ENGINE),...},...};

XE_RTP_ACTION_FLAG¶

XE_RTP_ACTION_FLAG(...)

Helper to add multiple flags to astructxe_rtp_action

Parameters

...: Action flags, without theXE_RTP_ACTION_FLAG_ prefix

Description

Helper to automatically add aXE_RTP_ACTION_FLAG_ prefix to the flagswhen definingstructxe_rtp_action entries. Example:

conststructxe_rtp_entry_srwa_entries[]={...{XE_RTP_NAME("test-entry"),...XE_RTP_ACTION_SET(...,XE_RTP_ACTION_FLAG(FOREACH_ENGINE)),...},...};

XE_RTP_RULES¶

XE_RTP_RULES(...)

Helper to set multiple rules to astructxe_rtp_entry_sr entry

Parameters

...: Rules

Description

At least one rule is needed and up to 12 are supported. Multiple rules areAND’ed together, i.e. all the rules must evaluate to true for the entry tobe processed. See XE_RTP_MATCH_* for the possible match rules. Example:

conststructxe_rtp_entry_srwa_entries[]={...{XE_RTP_NAME("test-entry"),XE_RTP_RULES(SUBPLATFORM(DG2,G10),GRAPHICS_STEP(A0,B0)),...},...};

XE_RTP_ACTIONS¶

XE_RTP_ACTIONS(...)

Helper to set multiple actions to astructxe_rtp_entry_sr

Parameters

...: Actions to be taken

Description

At least one action is needed and up to 12 are supported. See XE_RTP_ACTION_*for the possible actions. Example:

conststructxe_rtp_entry_srwa_entries[]={...{XE_RTP_NAME("test-entry"),XE_RTP_RULES(...),XE_RTP_ACTIONS(SET(..),SET(...),CLR(...)),...},...};

boolxe_rtp_match_even_instance(conststructxe_device*xe,conststructxe_gt*gt,conststructxe_hw_engine*hwe)¶: Match if engine instance is even

Parameters

conststructxe_device*xe: Device structure
conststructxe_gt*gt: GT structure
conststructxe_hw_engine*hwe: Engine instance

Return

true if engine instance is even, false otherwise

boolxe_rtp_match_has_flat_ccs(conststructxe_device*xe,conststructxe_gt*gt,conststructxe_hw_engine*hwe)¶: Match when platform has FlatCCS compression

Parameters

conststructxe_device*xe: Device structure
conststructxe_gt*gt: GT structure
conststructxe_hw_engine*hwe: Engine instance

Return

true if platform has FlatCCS compression, false otherwise

voidxe_rtp_process_ctx_enable_active_tracking(structxe_rtp_process_ctx*ctx,unsignedlong*active_entries,size_tn_entries)¶: Enable tracking of active entries

Parameters

structxe_rtp_process_ctx*ctx: The context for processing the table
unsignedlong*active_entries: bitmap to store the active entries
size_tn_entries: number of entries to be processed

Description

Set additional metadata to track what entries are considered “active”, i.e.their rules match the condition. Bits are never cleared: entries withmatching rules set the corresponding bit in the bitmap.

voidxe_rtp_process_to_sr(structxe_rtp_process_ctx*ctx,conststructxe_rtp_entry_sr*entries,size_tn_entries,structxe_reg_sr*sr,boolprocess_in_vf)¶: Process all rtpentries, adding the matching ones to the save-restore argument.

Parameters

structxe_rtp_process_ctx*ctx: The context for processing the table, with one of device, gt or hwe
conststructxe_rtp_entry_sr*entries: Table with RTP definitions
size_tn_entries: Number of entries to process, usually ARRAY_SIZE(entries)
structxe_reg_sr*sr: Save-restorestructwhere matching rules execute the action. This can beviewed as the “coalesced view” of multiple the tables. The bits for eachregister set are expected not to collide with previously added entries
boolprocess_in_vf: Whether this RTP table should get processed for SR-IOV VFdevices. Should generally only be ‘true’ for LRC tables.

Description

Walk the table pointed byentries (with an empty sentinel) and add allentries with matching rules tosr. Ifhwe is not NULL, its mmio_base isused to calculate the right register offset

voidxe_rtp_process(structxe_rtp_process_ctx*ctx,conststructxe_rtp_entry*entries)¶: Process all rtpentries, without running any action

Parameters

structxe_rtp_process_ctx*ctx: The context for processing the table, with one of device, gt or hwe
conststructxe_rtp_entry*entries: Table with RTP definitions

Description

Walk the table pointed byentries (with an empty sentinel), executing therules. One difference fromxe_rtp_process_to_sr(): there is no actionassociated with each entry since this usesstructxe_rtp_entry. Its main useis for marking active workarounds viaxe_rtp_process_ctx_enable_active_tracking().

Movatterモバイル変換

Register Table Processing¶

Internal API¶