/* SPDX-License-Identifier: MIT */ /* * Copyright © 2026 Intel Corporation */ #ifndef _ABI_XE_SIGID_ABI_H_ #define _ABI_XE_SIGID_ABI_H_ /** * DOC: Xe Error Signatures (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=`` (``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. */ /* * Top level Intel Error Signature Identifiers. */ #define INTEL_SIGID_INVALID 0 #define INTEL_SIGID_BATCH 100 #define INTEL_SIGID_RANGE_START(n) ((n) * INTEL_SIGID_BATCH) #define INTEL_SIGID_RANGE_END(n) (INTEL_SIGID_RANGE_START((n) + 1) - 1) /* SIGIDs 1xx are reserved for Xe GPU software and 2xx for Xe GPU hardware */ #define INTEL_SIGID_GPU_XE_SOFTWARE_START INTEL_SIGID_RANGE_START(1) #define INTEL_SIGID_GPU_XE_SOFTWARE_END INTEL_SIGID_RANGE_END(1) #define INTEL_SIGID_GPU_XE_HARDWARE_START INTEL_SIGID_RANGE_START(2) #define INTEL_SIGID_GPU_XE_HARDWARE_END INTEL_SIGID_RANGE_END(2) /** * enum xe_sigid - Stable Xe Error Signature Identifiers (SIGID). * @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. * * 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. */ enum xe_sigid { XE_SIGID_SW = INTEL_SIGID_GPU_XE_SOFTWARE_START, XE_SIGID_PROBE = INTEL_SIGID_GPU_XE_SOFTWARE_START + 1, XE_SIGID_WEDGED = INTEL_SIGID_GPU_XE_SOFTWARE_START + 2, XE_SIGID_SURVIVABILITY = INTEL_SIGID_GPU_XE_SOFTWARE_START + 3, XE_SIGID_RUNTIME_FW = INTEL_SIGID_GPU_XE_SOFTWARE_START + 4, XE_SIGID_DEVICE_FW = INTEL_SIGID_GPU_XE_SOFTWARE_START + 5, XE_SIGID_GT_TDR = INTEL_SIGID_GPU_XE_SOFTWARE_START + 6, XE_SIGID_MEM_FAULT = INTEL_SIGID_GPU_XE_SOFTWARE_START + 7, XE_SIGID_IO_BUS = INTEL_SIGID_GPU_XE_SOFTWARE_START + 8, XE_SIGID_HW = INTEL_SIGID_GPU_XE_HARDWARE_START, XE_SIGID_PCIE = INTEL_SIGID_GPU_XE_HARDWARE_START + 1, XE_SIGID_DEVICE_MEMORY = INTEL_SIGID_GPU_XE_HARDWARE_START + 2, XE_SIGID_CORE_COMPUTE = INTEL_SIGID_GPU_XE_HARDWARE_START + 3, XE_SIGID_FABRIC = INTEL_SIGID_GPU_XE_HARDWARE_START + 4, XE_SIGID_SOC_INTERNAL = INTEL_SIGID_GPU_XE_HARDWARE_START + 5, }; #endif