drivers/gpu/drm/xe/xe_assert.h

Source file repositories/reference/linux-study-clean/drivers/gpu/drm/xe/xe_assert.h

File Facts

System
Linux kernel
Corpus path
drivers/gpu/drm/xe/xe_assert.h
Extension
.h
Size
6242 bytes
Lines
177
Domain
Driver Families
Bucket
drivers/gpu
Inferred role
Driver Families: implementation source
Status
source implementation candidate

Why This File Exists

Repeatable hardware-adapter layer. Deep compatibility for every driver is out of scope; this atlas records patterns, probe lifecycles, bus glue, IRQ/DMA usage, and links back to core abstractions.

Dependency Surface

Detected Declarations

Annotated Snippet

#ifndef _XE_ASSERT_H_
#define _XE_ASSERT_H_

#include <linux/string_helpers.h>

#include <drm/drm_print.h>

#include "xe_gt_types.h"
#include "xe_step.h"
#include "xe_vram.h"

/**
 * DOC: Xe Asserts
 *
 * While Xe driver aims to be simpler than legacy i915 driver it is still
 * complex enough that some changes introduced while adding new functionality
 * could break the existing code.
 *
 * Adding &drm_WARN or &drm_err to catch unwanted programming usage could lead
 * to undesired increased driver footprint and may impact production driver
 * performance as this additional code will be always present.
 *
 * To allow annotate functions with additional detailed debug checks to assert
 * that all prerequisites are satisfied, without worrying about footprint or
 * performance penalty on production builds where all potential misuses
 * introduced during code integration were already fixed, we introduce family
 * of Xe assert macros that try to follow classic assert() utility:
 *
 *  * xe_assert()
 *  * xe_tile_assert()
 *  * xe_gt_assert()
 *
 * These macros are implemented on top of &drm_WARN, but unlikely to the origin,
 * warning is triggered when provided condition is false. Additionally all above
 * assert macros cannot be used in expressions or as a condition, since
 * underlying code will be compiled out on non-debug builds.
 *
 * Note that these macros are not intended for use to cover known gaps in the
 * implementation; for such cases use regular &drm_WARN or &drm_err and provide
 * valid safe fallback.
 *
 * Also in cases where performance or footprint is not an issue, developers
 * should continue to use the regular &drm_WARN or &drm_err to ensure that bug
 * reports 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);
 *	}
 */

#if IS_ENABLED(CONFIG_DRM_XE_DEBUG)
#define __xe_assert_msg(xe, condition, msg, arg...) ({						\
	(void)drm_WARN(&(xe)->drm, !(condition), "Assertion `%s` failed!\n" msg,		\
		       __stringify(condition), ## arg);						\
})
#else
#define __xe_assert_msg(xe, condition, msg, arg...) ({						\
	typecheck(const struct xe_device *, xe);						\
	BUILD_BUG_ON_INVALID(condition);							\
})
#endif

/**

Annotation

Implementation Notes