[Intel-xe] [RFC v1 16/17] drm/xe/uapi: Be more specific around GuC Version Type

[Francois Dugast]

From: Rodrigo Vivi <rodrigo.vivi at intel.com>

Make it very clear and documented that it is about the submission
version, and also what that actually means.

Signed-off-by: Rodrigo Vivi <rodrigo.vivi at intel.com>
---
 drivers/gpu/drm/xe/xe_query.c |  2 +-
 include/uapi/drm/xe_drm.h     | 16 ++++++++++++++--
 2 files changed, 15 insertions(+), 3 deletions(-)

diff --git a/drivers/gpu/drm/xe/xe_query.c b/drivers/gpu/drm/xe/xe_query.c
index c5196abbd15d..e0c634c6d326 100644
--- a/drivers/gpu/drm/xe/xe_query.c
+++ b/drivers/gpu/drm/xe/xe_query.c
@@ -520,7 +520,7 @@ query_uc_fw_version(struct xe_device *xe, struct drm_xe_device_query *query)
 		return -EINVAL;
 
 	switch (resp.uc_type) {
-	case DRM_XE_QUERY_UC_TYPE_GUC: {
+	case DRM_XE_QUERY_UC_TYPE_GUC_SUBMISSION: {
 		struct xe_guc *guc = &xe->tiles[0].primary_gt->uc.guc;
 
 		resp.major_ver = guc->submission_state.version.major;
diff --git a/include/uapi/drm/xe_drm.h b/include/uapi/drm/xe_drm.h
index 97e5f8f4aca3..31a46b32f315 100644
--- a/include/uapi/drm/xe_drm.h
+++ b/include/uapi/drm/xe_drm.h
@@ -468,11 +468,23 @@ struct drm_xe_query_topology_mask {
  *
  * Given a uc_type this will return the major, minor, patch and branch version
  * of the micro-controller firmware.
+ *
+ * The @uc_type can be:
+ *  - %DRM_XE_QUERY_UC_TYPE_GUC_SUBMISSION - This is the GuC Submission Version,
+ * a.k.a 'VF version'. It is not the actual GuC blob version. A running GuC can
+ * support multiple VF APIs with different Submission Versions. This version is
+ * negotiated by the VF KMD with GuC during VF initialization. In most of the
+ * current available GuC blobs, this is a 1-1 relationship where the Submission
+ * version could be inferred from the running version and vice-versa. However,
+ * the submission version is the most useful information for the user space
+ * perspective and needs.
+ *  - %DRM_XE_QUERY_TYPE_HUC - The actual HuC blob that is currently running
+ * in the platform. It returns 0 when HuC is not currently loaded.
  */
 struct drm_xe_query_uc_fw_version {
 	/** @uc_type: The micro-controller type to query firmware version */
-#define DRM_XE_QUERY_UC_TYPE_GUC	0
-#define DRM_XE_QUERY_UC_TYPE_HUC	1
+#define DRM_XE_QUERY_UC_TYPE_GUC_SUBMISSION	0
+#define DRM_XE_QUERY_UC_TYPE_HUC		1
 	__u16 uc_type;
 
 	/** @pad: MBZ */
-- 
2.34.1