Debugging¶

Xe Asserts

While Xe driver aims to be simpler than legacy i915 driver it is stillcomplex enough that some changes introduced while adding new functionalitycould break the existing code.

Addingdrm_WARN ordrm_err to catch unwanted programming usage could leadto undesired increased driver footprint and may impact production driverperformance as this additional code will be always present.

To allow annotate functions with additional detailed debug checks to assertthat all prerequisites are satisfied, without worrying about footprint orperformance penalty on production builds where all potential misusesintroduced during code integration were already fixed, we introduce familyof Xe assert macros that try to follow classicassert() utility:

• xe_assert()

• xe_tile_assert()

• xe_gt_assert()

These macros are implemented on top ofdrm_WARN, but unlikely to the origin,warning is triggered when provided condition is false. Additionally all aboveassert macros cannot be used in expressions or as a condition, sinceunderlying code will be compiled out on non-debug builds.

Note that these macros are not intended for use to cover known gaps in theimplementation; for such cases use regulardrm_WARN ordrm_err and providevalid safe fallback.

Also in cases where performance or footprint is not an issue, developersshould continue to use the regulardrm_WARN ordrm_err to ensure that bugreports from production builds will contain meaningful diagnostics data.

Below code shows how asserts could help in debug to catch unplanned use:

static void one_igfx(struct xe_device *xe){        xe_assert(xe, xe->info.is_dgfx == false);        xe_assert(xe, xe->info.tile_count == 1);}static void two_dgfx(struct xe_device *xe){        xe_assert(xe, xe->info.is_dgfx);        xe_assert(xe, xe->info.tile_count == 2);}void foo(struct xe_device *xe){        if (xe->info.dgfx)                return two_dgfx(xe);        return one_igfx(xe);}void bar(struct xe_device *xe){        if (drm_WARN_ON(xe->drm, xe->info.tile_count > 2))                return;        if (xe->info.tile_count == 2)                return two_dgfx(xe);        return one_igfx(xe);}

xe_assert¶

xe_assert(xe,condition)

warn if condition is false when debugging.

xe_tile_assert¶

xe_tile_assert(tile,condition)

warn if condition is false when debugging.

xe_gt_assert¶

xe_gt_assert(gt,condition)

warn if condition is false when debugging.