[PATCH v2] x86: Add documentation to RTM test code.

[Carlos O'Donell]

Provide additional comments documenting what the string-related RTM
test does and reasons for why it might fail.
---
Changes in v2:
* s/CPUID/CPU/g, s/CPUID instructions/CPUID instruction/g.

 sysdeps/x86/tst-string-rtm.h | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/sysdeps/x86/tst-string-rtm.h b/sysdeps/x86/tst-string-rtm.h
index 2a6c32d2ce..f86d3d0721 100644
--- a/sysdeps/x86/tst-string-rtm.h
+++ b/sysdeps/x86/tst-string-rtm.h
@@ -16,19 +16,41 @@
    License along with the GNU C Library; if not, see
    <https://www.gnu.org/licenses/>.  */
 
+/* This header provides a test framework for string functions when executed
+   inside Intel TSX (Transactional Synchronization Extensions) RTM (Restricted
+   Transactional Memory) regions.  RTM allows speculative execution of code
+   blocks as atomic transactions that can be rolled back if conflicts occur.
+
+   String functions must be carefully implemented to avoid causing spurious
+   transaction aborts, which can happen if they use instructions or patterns
+   that are incompatible with transactional execution (e.g., certain CPU
+   instructions, system calls, or conflicting memory accesses).  */
+
 #include <string.h>
 #include <x86intrin.h>
 #include <sys/platform/x86.h>
 #include <support/check.h>
 #include <support/test-driver.h>
 
+/* Test a string function both inside and outside RTM transactions.
+
+   NAME: Name of the function being tested (for error messages).
+   LOOP: Number of iterations to run the test.
+   PREPARE: Setup function called once before testing begins.
+   FUNCTION: The string function to test; returns 0 on success, non-zero on failure.
+
+   Returns EXIT_SUCCESS if the test passes, EXIT_UNSUPPORTED if RTM is not
+   available, or EXIT_FAILURE if the function fails or abort rate is too high.  */
 static int
 do_test_1 (const char *name, unsigned int loop, int (*prepare) (void),
 	   int (*function) (void))
 {
+  /* Check if RTM (Restricted Transactional Memory) is supported and enabled
+     on this CPU.  If not, skip the test.  */
   if (!CPU_FEATURE_ACTIVE (RTM))
     return EXIT_UNSUPPORTED;
 
+  /* Run the preparation function to set up test data or state.  */
   int status = prepare ();
   if (status != EXIT_SUCCESS)
     return status;
@@ -58,6 +80,15 @@ do_test_1 (const char *name, unsigned int loop, int (*prepare) (void),
 	}
       else
 	{
+	  /* Transaction aborted.  Common causes for string function aborts:
+	     - CPUID instruction used for runtime feature detection
+	     - Memory conflicts with other threads
+	     - Exceeding TSX capacity limits (read/write set too large)
+	     - Page faults or TLB misses during transaction
+	     - Use of non-transactional instructions (syscalls, serializing ops)
+	     - Cache line conflicts or evictions
+	     - Hardware interrupts
+	     Well-implemented string functions should minimize these issues.  */
 	  failed |= function ();
 	  ++naborts;
 	}
-- 
2.52.0