Xe SIGID

What SIGID stands for

SIGID is short for Signature Identifier. It is a small, stable integer that names one of the recognised fault sites -- nothing more. It is the primary handle used for triage and maps directly to a specific report site.

Numbering

SIGIDs are a single flat list numbered sequentially within the assigned range, in the order the fault sites were introduced. Values are stable: once assigned they are only ever appended, never renumbered or reused. A retired fault site SIGID value is deprecated in place, never re-purposed.

Why this exists

Today the driver reports faults with ad-hoc xe_err() / xe_gt_err() strings that have no stable shape. That is fine for a human reading dmesg, but it gives fleet tooling nothing durable to match on: the wording changes between releases, lines can be rate-limited or dropped under an error storm, and there is no consistent way to ask “which recognised fault just happened?”

A SIGID answers exactly that one question, identically across driver and firmware versions, and (eventually) across other Intel devices in a node.

What a SIGID is not

SIGID deliberately does not encode the detailed reason or the outcome. Those are carried alongside it:

SIGID    -> which recognised fault site is being reported
severity -> how serious this instance is
errno    -> the failing operation's error, if available, shown with %pe
message  -> free-form human-readable context

Severity is independent of the SIGID. The same SIGID can be reported at different severities depending on the instance and the recovery taken.

When to use SIGID logging

The xe_log_*() helpers are for these recognised fault sites only -- important, operator-relevant faults and events. The driver’s only job is to emit the right SIGID next to the usual human-readable text. They are not a replacement for xe_info() / xe_dbg() / tracing, nor for one-off diagnostics; using them for ordinary logging would dilute the fault stream. Not every xe_err() needs to become a SIGID report -- only those that correspond to a published fault site.

SIGID log output (dmesg vs. the machine record)

The dmesg line stays close to a normal xe error message so it remains readable for admins; the only stable, machine-matchable token on it is SIGID=<n> (dmesg | grep SIGID=).

The full dmesg line is not an ABI: the surrounding text may change freely, and lines may be dropped. The durable record for tooling is the CPER record carrying the same SIGID (generation is a planned follow-up).

How to pick a SIGID (the uniqueness rule)

Pick per report site, not per incident. Each site emits the single most specific recognised SIGID for that site -- so the question is never “classify this whole failure”, it is “what does this site detect?”, which has one answer. A single underlying failure therefore legitimately produces a chain of reports from different layers, each with its own SIGID -- e.g. a GuC communication failure is reported as XE_SIGID_RUNTIME_FW by the firmware path, the failed recovery as XE_SIGID_GT_TDR by the reset path, and an aborted bind as XE_SIGID_PROBE by the probe path. That chain lets triage follow a fault from origin to final effect; it is not a duplicate.

If a site does not match any defined SIGID, keep using the ordinary xe_err() / xe_gt_err() logging rather than forcing a SIGID: a wrong or over-broad classification is harder to retire than a missing one. When a new report site is genuinely worth triaging, add it to the list below.

Usage of the existing SIGID reports must reevaluated according to this section after making significant changes to the site that emits this SIGID.

Scope: software vs hardware emitted signatures

Some SIGID represents fault sites that the driver itself detects and reports from the software POV: probe abort, wedged, survivability, driver- detected firmware failures, engine TDR, memory faults and IO/bus faults. These are the only values the driver assigns on its own.

Signatures that originate in firmware or hardware are a different thing: they are produced and identified by the firmware or the hardware itself (e.g. via their own records or error counters), and the driver merely logs them as they are given to us. They are deliberately enumerated separately.

The two driver-detected firmware report sites below (XE_SIGID_RUNTIME_FW, XE_SIGID_DEVICE_FW) are software signatures: they mark that the driver observed a firmware problem, not a signature reported by the firmware.

enum xe_sigid

Stable Xe Error Signature Identifiers (SIGID).

Constants

XE_SIGID_SW

Software component failure.

XE_SIGID_PROBE

Device probe/bind was aborted.

XE_SIGID_WEDGED

Device was declared wedged and is no longer usable.

XE_SIGID_SURVIVABILITY

Device entered survivability mode.

XE_SIGID_RUNTIME_FW

Driver-detected runtime firmware failure, GuC/HuC/GSC.

XE_SIGID_DEVICE_FW

Driver-detected device firmware failure, PCODE/sysctrl.

XE_SIGID_GT_TDR

Engine hang / timeout detection and recovery (reset).

XE_SIGID_MEM_FAULT

VM bind, page fault or GTT fault.

XE_SIGID_IO_BUS

Runtime PCIe / IOMMU / MMIO access fault.

XE_SIGID_HW

Generic hardware failure.

XE_SIGID_PCIE

PCIe interface errors.

XE_SIGID_DEVICE_MEMORY

Device memory errors.

XE_SIGID_CORE_COMPUTE

Compute/shader core errors.

XE_SIGID_FABRIC

Fabric errors.

XE_SIGID_SOC_INTERNAL

SoC-internal errors.

Description

Each SIGID represents the report sites the driver detects and reports. Values are numbered sequentially, are only ever appended, and are never renumbered or reused.

Firmware- and hardware-originated signatures are numbered separately.