175 lines · c
1/* SPDX-License-Identifier: MIT */2/*3 * Copyright © 2023 Intel Corporation4 */5 6#ifndef _XE_ASSERT_H_7#define _XE_ASSERT_H_8 9#include <linux/string_helpers.h>10 11#include <drm/drm_print.h>12 13#include "xe_device_types.h"14#include "xe_step.h"15 16/**17 * DOC: Xe ASSERTs18 *19 * While Xe driver aims to be simpler than legacy i915 driver it is still20 * complex enough that some changes introduced while adding new functionality21 * could break the existing code.22 *23 * Adding &drm_WARN or &drm_err to catch unwanted programming usage could lead24 * to undesired increased driver footprint and may impact production driver25 * performance as this additional code will be always present.26 *27 * To allow annotate functions with additional detailed debug checks to assert28 * that all prerequisites are satisfied, without worrying about footprint or29 * performance penalty on production builds where all potential misuses30 * introduced during code integration were already fixed, we introduce family31 * of Xe assert macros that try to follow classic assert() utility:32 *33 * * xe_assert()34 * * xe_tile_assert()35 * * xe_gt_assert()36 *37 * These macros are implemented on top of &drm_WARN, but unlikely to the origin,38 * warning is triggered when provided condition is false. Additionally all above39 * assert macros cannot be used in expressions or as a condition, since40 * underlying code will be compiled out on non-debug builds.41 *42 * Note that these macros are not intended for use to cover known gaps in the43 * implementation; for such cases use regular &drm_WARN or &drm_err and provide44 * valid safe fallback.45 *46 * Also in cases where performance or footprint is not an issue, developers47 * should continue to use the regular &drm_WARN or &drm_err to ensure that bug48 * reports from production builds will contain meaningful diagnostics data.49 *50 * Below code shows how asserts could help in debug to catch unplanned use::51 *52 * static void one_igfx(struct xe_device *xe)53 * {54 * xe_assert(xe, xe->info.is_dgfx == false);55 * xe_assert(xe, xe->info.tile_count == 1);56 * }57 *58 * static void two_dgfx(struct xe_device *xe)59 * {60 * xe_assert(xe, xe->info.is_dgfx);61 * xe_assert(xe, xe->info.tile_count == 2);62 * }63 *64 * void foo(struct xe_device *xe)65 * {66 * if (xe->info.dgfx)67 * return two_dgfx(xe);68 * return one_igfx(xe);69 * }70 *71 * void bar(struct xe_device *xe)72 * {73 * if (drm_WARN_ON(xe->drm, xe->info.tile_count > 2))74 * return;75 *76 * if (xe->info.tile_count == 2)77 * return two_dgfx(xe);78 * return one_igfx(xe);79 * }80 */81 82#if IS_ENABLED(CONFIG_DRM_XE_DEBUG)83#define __xe_assert_msg(xe, condition, msg, arg...) ({ \84 (void)drm_WARN(&(xe)->drm, !(condition), "Assertion `%s` failed!\n" msg, \85 __stringify(condition), ## arg); \86})87#else88#define __xe_assert_msg(xe, condition, msg, arg...) ({ \89 typecheck(const struct xe_device *, xe); \90 BUILD_BUG_ON_INVALID(condition); \91})92#endif93 94/**95 * xe_assert - warn if condition is false when debugging.96 * @xe: the &struct xe_device pointer to which &condition applies97 * @condition: condition to check98 *99 * xe_assert() uses &drm_WARN to emit a warning and print additional information100 * that could be read from the &xe pointer if provided &condition is false.101 *102 * Contrary to &drm_WARN, xe_assert() is effective only on debug builds103 * (&CONFIG_DRM_XE_DEBUG must be enabled) and cannot be used in expressions104 * or as a condition.105 *106 * See `Xe ASSERTs`_ for general usage guidelines.107 */108#define xe_assert(xe, condition) xe_assert_msg((xe), condition, "")109#define xe_assert_msg(xe, condition, msg, arg...) ({ \110 const struct xe_device *__xe = (xe); \111 __xe_assert_msg(__xe, condition, \112 "platform: %s subplatform: %d\n" \113 "graphics: %s %u.%02u step %s\n" \114 "media: %s %u.%02u step %s\n" \115 msg, \116 __xe->info.platform_name, __xe->info.subplatform, \117 __xe->info.graphics_name, \118 __xe->info.graphics_verx100 / 100, \119 __xe->info.graphics_verx100 % 100, \120 xe_step_name(__xe->info.step.graphics), \121 __xe->info.media_name, \122 __xe->info.media_verx100 / 100, \123 __xe->info.media_verx100 % 100, \124 xe_step_name(__xe->info.step.media), \125 ## arg); \126})127 128/**129 * xe_tile_assert - warn if condition is false when debugging.130 * @tile: the &struct xe_tile pointer to which &condition applies131 * @condition: condition to check132 *133 * xe_tile_assert() uses &drm_WARN to emit a warning and print additional134 * information that could be read from the &tile pointer if provided &condition135 * is false.136 *137 * Contrary to &drm_WARN, xe_tile_assert() is effective only on debug builds138 * (&CONFIG_DRM_XE_DEBUG must be enabled) and cannot be used in expressions139 * or as a condition.140 *141 * See `Xe ASSERTs`_ for general usage guidelines.142 */143#define xe_tile_assert(tile, condition) xe_tile_assert_msg((tile), condition, "")144#define xe_tile_assert_msg(tile, condition, msg, arg...) ({ \145 const struct xe_tile *__tile = (tile); \146 char __buf[10] __maybe_unused; \147 xe_assert_msg(tile_to_xe(__tile), condition, "tile: %u VRAM %s\n" msg, \148 __tile->id, ({ string_get_size(__tile->mem.vram.actual_physical_size, 1, \149 STRING_UNITS_2, __buf, sizeof(__buf)); __buf; }), ## arg); \150})151 152/**153 * xe_gt_assert - warn if condition is false when debugging.154 * @gt: the &struct xe_gt pointer to which &condition applies155 * @condition: condition to check156 *157 * xe_gt_assert() uses &drm_WARN to emit a warning and print additional158 * information that could be safetely read from the > pointer if provided159 * &condition is false.160 *161 * Contrary to &drm_WARN, xe_gt_assert() is effective only on debug builds162 * (&CONFIG_DRM_XE_DEBUG must be enabled) and cannot be used in expressions163 * or as a condition.164 *165 * See `Xe ASSERTs`_ for general usage guidelines.166 */167#define xe_gt_assert(gt, condition) xe_gt_assert_msg((gt), condition, "")168#define xe_gt_assert_msg(gt, condition, msg, arg...) ({ \169 const struct xe_gt *__gt = (gt); \170 xe_tile_assert_msg(gt_to_tile(__gt), condition, "GT: %u type %d\n" msg, \171 __gt->info.id, __gt->info.type, ## arg); \172})173 174#endif175