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
- 
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
- 
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
- 
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
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
Description
Refer to
XE_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 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_actionentry
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_actionentry
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_actionentry
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_actionentry
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_actionentry
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().