[PATCH 15/66] tests/xe_eudebug: Add TEST/SUBTEST documentation

[Christoph Manszewski]

From: Dominik Grzegorzek <dominik.grzegorzek at intel.com>

Document xe_eudebug IGT test basing on its internal logic.

Signed-off-by: Dominik Grzegorzek <dominik.grzegorzek at intel.com>
---
 tests/intel/xe_eudebug.c | 45 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/tests/intel/xe_eudebug.c b/tests/intel/xe_eudebug.c
index 147836bd1..cf8f01684 100644
--- a/tests/intel/xe_eudebug.c
+++ b/tests/intel/xe_eudebug.c
@@ -2,6 +2,16 @@
 /*
  * Copyright © 2023 Intel Corporation
  */
+
+/**
+ * TEST: Test EU Debugger functionality
+ * Category: Core
+ * Mega feature: EUdebug
+ * Sub-category: EUdebug tests
+ * Functionality: eu debugger framework
+ * Test category: functionality test
+ */
+
 #include <poll.h>
 #include <sys/ioctl.h>
 
@@ -86,6 +96,12 @@ static int __debug_connect(int fd, int *debugfd, struct drm_xe_eudebug_connect *
 	return ret;
 }
 
+/**
+ * SUBTEST: basic-connect
+ * Description:
+ *	Exercise XE_EUDEBG_CONNECT ioctl with passing
+ *	valid and invalid params.
+ */
 static void test_connect(int fd)
 {
 	struct drm_xe_eudebug_connect param = {};
@@ -138,6 +154,11 @@ static void test_connect(int fd)
 	close(debugfd);
 }
 
+/**
+ * SUBTEST: basic-close
+ * Description:
+ *	Test whether eudebug can be reattached after closure.
+ */
 static void test_close(int fd)
 {
 	struct drm_xe_eudebug_connect param = { 0,  };
@@ -224,6 +245,20 @@ static void test_read_event(int fd)
 	free(event);
 }
 
+/**
+ * SUBTEST: basic-client
+ * Description:
+ *	Attach the debugger to process which opens and closes xe drm client.
+ *
+ * SUBTEST: multiple-sessions
+ * Description:
+ *	Simultaneously attach many debuggers to many processes.
+ *	Each process opens and closes xe drm client.
+ *
+ * SUBTEST: basic-vms
+ * Description:
+ *	Attach the debugger to process which creates and destroys a few vms.
+ */
 static void test_basic_sessions(int fd, unsigned int flags, int count)
 {
 	struct xe_eudebug_session **s;
@@ -279,6 +314,16 @@ static void run_discovery_client(struct xe_eudebug_client *c)
 	}
 }
 
+/**
+ * SUBTEST: discovery-%s
+ * Description: Race discovery against %arg[1] and the debugger dettach.
+ *
+ * arg[1]:
+ *
+ * @race:		resources creation
+ * @empty:		resources destruction
+ * @empty-clients:	client closure
+ */
 static void *discovery_race_thread(void *data)
 {
 	struct {
-- 
2.34.1