[PATCH v6 1/6] drm/xe/guc: Add log init config abi definitions

[Michal Wajdeczko]

On 7/22/2025 3:35 AM, Zhanjun Dong wrote:
> Add GuC log init config (LIC) ABI definitions.
> 
> Signed-off-by: Zhanjun Dong <zhanjun.dong at intel.com>
> ---
>  drivers/gpu/drm/xe/abi/guc_lic_abi.h | 107 +++++++++++++++++++++++++++
>  1 file changed, 107 insertions(+)
>  create mode 100644 drivers/gpu/drm/xe/abi/guc_lic_abi.h
> 
> diff --git a/drivers/gpu/drm/xe/abi/guc_lic_abi.h b/drivers/gpu/drm/xe/abi/guc_lic_abi.h
> new file mode 100644
> index 000000000000..a4e27da304cd
> --- /dev/null
> +++ b/drivers/gpu/drm/xe/abi/guc_lic_abi.h
> @@ -0,0 +1,107 @@
> +/* SPDX-License-Identifier: MIT */
> +/*
> + * Copyright © 2025 Intel Corporation
> + */
> +
> +#ifndef _ABI_GUC_LIC_ABI_H_
> +#define _ABI_GUC_LIC_ABI_H_
> +
> +#include <linux/types.h>
> +
> +/** enum guc_lic_type - Log Init Config TLV IDs. */
> +enum guc_lic_type {
> +	/**
> +	 * @GUC_LIC_TYPE_GUC_SW_VERSION: GuC firmware version. Value
> +	 * is a 32 bit number represented by guc_sw_version.
> +	 */
> +	GUC_LIC_TYPE_GUC_SW_VERSION = 0x1,
> +	/**
> +	 * @GUC_LIC_TYPE_GUC_DEVICE_ID: GuC device id. Value is a 32
> +	 * bit.
> +	 */
> +	GUC_LIC_TYPE_GUC_DEVICE_ID = 0x2,
> +	/**
> +	 * @GUC_LIC_TYPE_TSC_FREQUENCY: GuC timestamp counter
> +	 * frequency. Value is a 32 bit number representing frequency in
> +	 * kHz. This timestamp is utilized in log entries, timer and
> +	 * for engine utilization tracking.
> +	 */
> +	GUC_LIC_TYPE_TSC_FREQUENCY = 0x3,
> +	/**
> +	 * @GUC_LIC_TYPE_GMD_ID: HW GMD ID. Value is a 32 bit number
> +	 * representing graphics, media and display HW architecture IDs.
> +	 */
> +	GUC_LIC_TYPE_GMD_ID = 0x4,
> +	/**
> +	 * @GUC_LIC_TYPE_BUILD_PLATFORM_ID: GuC build platform ID.
> +	 * Value is 32 bits.
> +	 */
> +	GUC_LIC_TYPE_BUILD_PLATFORM_ID = 0x5,
> +};
> +
> +/**
> + * struct guc_sw_version - This structure describes the full version of a
> + * software component.
> + */
> +struct guc_sw_version {
> +	/** @dw0: A 32 bits dword, contains multiple bit fields */
> +	u32 dw0;
> +#define GUC_SW_VERSION_PATCH_VERSION		GENMASK(7, 0)
> +#define GUC_SW_VERSION_MINOR_VERSION		GENMASK(15, 8)
> +#define GUC_SW_VERSION_MAJOR_VERSION		GENMASK(23, 16)
> +#define GUC_SW_VERSION_BRANCH_ID		GENMASK(31, 24)

in other places we start with MSB definitions first

> +} __packed;
> +
> +/**
> + * struct guc_lic_format_version - Log Init Config Structure Version.

    *

> + * Major-Minor is not a fractional number (i.e. Ver 1.3 would be older
> + * than 1.12)
> + */
> +struct guc_lic_format_version {
> +	/** @dw0: A 32 bits dword, contains multiple bit fields */
> +	u32 dw0;
> +	/*
> +	 *  Log-Init-Config structure minor version. Must be
> +	 * GUC_LIC_FORMAT_VERSION_MASK_MINOR

you likely mean GUC_LIC_FORMAT_VERSION_MINOR here

and likely the guc_lic_format_version shall be defined first as all
other definitions depends on this being 1.0, right?

> +	 */
> +#define GUC_LIC_FORMAT_VERSION_MASK_MINOR		GENMASK(15, 0)
> +	/*
> +	 *  Log-Init-Config structure major version. Must be
> +	 * GUC_LIC_FORMAT_VERSION_MASK_MAJOR

GUC_LIC_FORMAT_VERSION_MAJOR

> +	 */
> +#define GUC_LIC_FORMAT_VERSION_MASK_MAJOR		GENMASK(31, 16)

again, start with MSB first

> +} __packed;
> +
> +/**
> + * struct guc_lic - GuC lic (Log-Init-Config) structure.

s/GuC lic/GuC LIC

    *
> + * This is populated by the GUC at log init time and is located in the log
> + * buffer as per the Log Buffer Layout (In Memory). The array of guc log
> + * buffer states plus this structure must not exceed 4KB
> + */
> +struct guc_lic {
> +	/**
> +	 * @magic: A magic number set by GuC to identify that this
> +	 * structure contains valid information: magic = GUC_LIC_MAGIC.
> +	 * Used to verify the information in this structure is valid.

hmm, last sentence is redundant, please rephrase

> +	 */
> +	u32 magic;
> +#define GUC_LIC_MAGIC			0x8086900D
> +
> +	/**
> +	 * @version: The version of the this structure. Represented by
> +	 * guc_lic_format_version
> +	 */
> +	struct guc_lic_format_version version;
> +#define GUC_LIC_FORMAT_VERSION_MAJOR	1u
> +#define GUC_LIC_FORMAT_VERSION_MINOR	0u

those defs should be closer to struct guc_lic_format_version
where they are already referenced in description

> +
> +	/** @dw_size: Number of Dws the `data` array contains. */

s/Dws/DWs or DWORDs or dwords but not Dws
> +	u32 dw_size;

hmm, still dw_size name is suggesting something else...
maybe "@data_size: Number of dwords in the @data array" 

or data_count or data_len

> +	/**
> +	 * @data: Array of dwords representing a list of LIC KLVs of
> +	 * type guc_klv_generic with keys represented by guc_lic_type
> +	 */
> +	u32 data[] __counted_by(dw_size);
> +} __packed;
> +
> +#endif