Register Table Processing¶

Internal infrastructure to define how registers should be updated based on rules 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 apply the values to the registers that have matching rules.

Internal API¶

struct xe_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 a superset 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

This struct records what action should be taken in a register that has a matching 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 to XE_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 to XE_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. inclusive on the left, exclusive on the right.

Refer to XE_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. inclusive on the left, exclusive on the right.

Refer to XE_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 to XE_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. The XE_RTP infrastructure will simply call the function func_ passed to decide if this rule matches the device.

Refer to XE_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 to XE_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 boths sides

Refer to XE_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 GT being checked is not of the graphics type. It allows to add RTP entries to another GT when the device contains a Graphics IP with that version.

Refer to XE_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 to XE_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 boths sides

Refer to XE_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 being checked is not of the media type. It allows to add RTP entries to another GT when the device contains a Media IP with that version.

Refer to XE_RTP_RULES() for expected usage.

XE_RTP_RULE_IS_INTEGRATED¶

XE_RTP_RULE_IS_INTEGRATED ()

Create a rule matching integrated graphics devices

Parameters

Description

Refer to XE_RTP_RULES() for expected usage.

XE_RTP_RULE_IS_DISCRETE¶

XE_RTP_RULE_IS_DISCRETE ()

Create a rule matching discrete graphics devices

Parameters

Description

Refer to XE_RTP_RULES() for expected usage.

XE_RTP_RULE_OR¶

XE_RTP_RULE_OR ()

Create an OR condition for rtp rules

Parameters

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 is sufficient for the action to trigger. Example:

const struct xe_rtp_entry_sr entries[] = {
        ...
        { 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 the struct xe_rtp_action entry

Description

The correspondent notation in bspec is:

REGNAME = VALUE

XE_RTP_ACTION_SET¶

XE_RTP_ACTION_SET (reg_, val_, ...)

Set bits from val_ in the register.

Parameters

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

Description

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

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

XE_RTP_ACTION_CLR¶

XE_RTP_ACTION_CLR (reg_, val_, ...)

Clear bits from val_ in the register.

Parameters

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

Description

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

REGNAME[2] = 0 REGNAME[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 by mask_bits_
...: Additional fields to override in the struct xe_rtp_action entry

Description

For masked registers this translates to a single write, while for other registers 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 the struct xe_rtp_action entry

Description

Add a register to the whitelist, allowing userspace to modify the ster with regular 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 a struct xe_rtp_entry_sr

Parameters

...: Entry flags, without the XE_RTP_ENTRY_FLAG_ prefix

Description

Helper to automatically add a XE_RTP_ENTRY_FLAG_ prefix to the flags when defining struct xe_rtp_entry entries. Example:

const struct xe_rtp_entry_sr wa_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 a struct xe_rtp_action

Parameters

...: Action flags, without the XE_RTP_ACTION_FLAG_ prefix

Description

Helper to automatically add a XE_RTP_ACTION_FLAG_ prefix to the flags when defining struct xe_rtp_action entries. Example:

const struct xe_rtp_entry_sr wa_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 a struct xe_rtp_entry_sr entry

Parameters

...: Rules

Description

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

const struct xe_rtp_entry_sr wa_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 a struct xe_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:

const struct xe_rtp_entry_sr wa_entries[] = {
        ...
        { XE_RTP_NAME("test-entry"),
          XE_RTP_RULES(...),
          XE_RTP_ACTIONS(SET(..), SET(...), CLR(...)),
          ...
        },
        ...
};

bool xe_rtp_match_even_instance(const struct xe_gt *gt, const struct xe_hw_engine *hwe)¶: Match if engine instance is even

Parameters

const struct xe_gt *gt: GT structure
const struct xe_hw_engine *hwe: Engine instance

Return

true if engine instance is even, false otherwise

void xe_rtp_process_ctx_enable_active_tracking(struct xe_rtp_process_ctx *ctx, unsigned long *active_entries, size_t n_entries)¶: Enable tracking of active entries

Parameters

struct xe_rtp_process_ctx *ctx: The context for processing the table
unsigned long *active_entries: bitmap to store the active entries
size_t n_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 with matching rules set the corresponding bit in the bitmap.

void xe_rtp_process_to_sr(struct xe_rtp_process_ctx *ctx, const struct xe_rtp_entry_sr *entries, struct xe_reg_sr *sr)¶: Process all rtp entries, adding the matching ones to the save-restore argument.

Parameters

struct xe_rtp_process_ctx *ctx: The context for processing the table, with one of device, gt or hwe
const struct xe_rtp_entry_sr *entries: Table with RTP definitions
struct xe_reg_sr *sr: Save-restore struct where matching rules execute the action. This can be viewed as the “coalesced view” of multiple the tables. The bits for each register set are expected not to collide with previously added entries

Description

Walk the table pointed by entries (with an empty sentinel) and add all entries with matching rules to sr. If hwe is not NULL, its mmio_base is used to calculate the right register offset

void xe_rtp_process(struct xe_rtp_process_ctx *ctx, const struct xe_rtp_entry *entries)¶: Process all rtp entries, without running any action

Parameters

struct xe_rtp_process_ctx *ctx: The context for processing the table, with one of device, gt or hwe
const struct xe_rtp_entry *entries: Table with RTP definitions

Description

Walk the table pointed by entries (with an empty sentinel), executing the rules. One difference from xe_rtp_process_to_sr(): there is no action associated with each entry since this uses struct xe_rtp_entry. Its main use is for marking active workarounds via xe_rtp_process_ctx_enable_active_tracking().