[Intel-xe] [PATCH v2] drm/xe/hw_engine: Document difference between instance and logical instance

[Francois Dugast]

Add explanation provided by Matt next to the definition, so that
it can easily found later.

v2: Fix typos, make comment more generic, remove FIXME (Rodrigo Vivi)

Signed-off-by: Francois Dugast <francois.dugast at intel.com>
---
 drivers/gpu/drm/xe/xe_hw_engine.c       |  1 -
 drivers/gpu/drm/xe/xe_hw_engine_types.h | 11 ++++++++++-
 2 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/drivers/gpu/drm/xe/xe_hw_engine.c b/drivers/gpu/drm/xe/xe_hw_engine.c
index b5b084590888..ee7066041a29 100644
--- a/drivers/gpu/drm/xe/xe_hw_engine.c
+++ b/drivers/gpu/drm/xe/xe_hw_engine.c
@@ -474,7 +474,6 @@ static void hw_engine_setup_logical_mapping(struct xe_gt *gt)
 {
 	int class;
 
-	/* FIXME: Doing a simple logical mapping that works for most hardware */
 	for (class = 0; class < XE_ENGINE_CLASS_MAX; ++class) {
 		struct xe_hw_engine *hwe;
 		enum xe_hw_engine_id id;
diff --git a/drivers/gpu/drm/xe/xe_hw_engine_types.h b/drivers/gpu/drm/xe/xe_hw_engine_types.h
index 5d4ee2904240..ccf014f5f994 100644
--- a/drivers/gpu/drm/xe/xe_hw_engine_types.h
+++ b/drivers/gpu/drm/xe/xe_hw_engine_types.h
@@ -114,7 +114,16 @@ struct xe_hw_engine {
 	enum xe_engine_class class;
 	/** @instance: physical instance of this hw engine */
 	u16 instance;
-	/** @logical_instance: logical instance of this hw engine */
+	/**
+	 * @logical_instance: logical identification of this hardware
+	 * engine. A 0..n sequencing number assigned at driver
+	 * initialization for each engine of a giving class of a specific
+	 * GT. Although it is per-class and per-GT, it might be different
+	 * from the @engine on platforms where we can have gaps on the
+	 * hardware assigned number such as platforms where we have VCS0
+	 * and VCS2, but no VCS1. Only logical instance numbers should be
+	 * exposed to user space.
+	 */
 	u16 logical_instance;
 	/** @mmio_base: MMIO base address of this hw engine*/
 	u32 mmio_base;
-- 
2.34.1