drm/xe/wa: Document new policy regarding workaround IP ranges

During early Xe driver development, our policy for applying workarounds
to ranges of IP versions was to only use GRAPHICS_VERSION_RANGE and
MEDIA_VERSION_RANGE rules when all of the affected IP versions had
consecutive version numbers; otherwise separate RTP entries should be
used.  For example, a workaround that applies to all Xe2-based platforms
would be implemented in the driver with two RTP entries:  one using
GRAPHICS_VERSION_RANGE(2001, 2002) and the other using
GRAPHICS_VERSION(2004).  This ensured that if a new IP variant showed up
in the future with currently unused version 20.03, an old workaround
entry wouldn't automatically apply to it by accident (and we could
always consolidate those two distinct entries in the future if the
workaround database did explicitly indicate that 20.03 also needed the
workaround).

Now that we're a couple years down the road with this driver, the number
of IP versions supported is much larger (several Xe2 20.xx versions,
several Xe3 30.xx versions, and a couple Xe3p 35.xx versions).  When new
workarounds are discovered that need to apply to a wide range of IPs,
it's becoming more of a pain to create independent entries for each
non-contiguous range of versions, and the general consensus is that we
should revisit our previous policy and start allowing use of
VERSION_RANGE constructs for non-contiguous version ranges.

Note that allowing ranges that cover currently unused versions will
require additional care if/when some of those intermediate version
numbers start being used in the future.  We'll need to re-check every
workaround that has a range including the new IP version and check the
hardware database to see whether the workaround also applies to the new
version (no code change required) or whether we need to split the
existing range into two separate ranges that don't cover the new
version.  The platform enabling engineers are willing to take on this
extra review burden at the time we first enable a new IP in the driver
(see lore link below for one recent discussion).

Update the kerneldoc for the workaround file to make the new policy
official.

Link: https://lore.kernel.org/all/20260203233600.GT458797@mdroper-desk1.amr.corp.intel.com/
Reviewed-by: Balasubramani Vivekanandan <balasubramani.vivekanandan@intel.com>
Link: https://patch.msgid.link/20260220-forupstream-wa_cleanup-v2-3-b12005a05af6@intel.com
Signed-off-by: Matt Roper <matthew.d.roper@intel.com>

diff --git a/drivers/gpu/drm/xe/xe_wa.c b/drivers/gpu/drm/xe/xe_wa.c
index 4b2c77f51fd830fe2439708865fb0b966545bc71..c3d694947bd5d2b178e9da08bb937dc6a171b326 100644 (file)
--- a/drivers/gpu/drm/xe/xe_wa.c
+++ b/drivers/gpu/drm/xe/xe_wa.c
@@ -111,6 +111,17 @@
  *    difference of how they are maintained in the code. In xe it uses the
  *    xe_rtp infrastructure so the workarounds can be kept in tables, following
  *    a more declarative approach rather than procedural.
+ *
+ * .. note::
+ *    When a workaround applies to every single known IP version in a range,
+ *    the preferred handling is to use a single range-based RTP entry rather
+ *    than individual entries for each version, even if some of the intermediate
+ *    version numbers are currently unused.  If a new intermediate IP version
+ *    appears in the future and is enabled in the driver, any existing
+ *    range-based entries that contain the new version number will need to be
+ *    analyzed to determine whether their workarounds should apply to the new
+ *    version, or whether any existing range based entries needs to be split
+ *    into two entries that do not include the new intermediate version.
  */
 
 #undef XE_REG_MCR