SDL: testevdev: Explain why the test data is encoded the way it is

From 7d230af51d5e9f735a6e5534cb9a9fbc01a7f026 Mon Sep 17 00:00:00 2001
From: Simon McVittie <[EMAIL REDACTED]>
Date: Wed, 12 Oct 2022 12:41:30 +0100
Subject: [PATCH] testevdev: Explain why the test data is encoded the way it is

Signed-off-by: Simon McVittie <smcv@collabora.com>
---
 test/testevdev.c | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/test/testevdev.c b/test/testevdev.c
index 2ac7ad5b31d8..22465ff81647 100644
--- a/test/testevdev.c
+++ b/test/testevdev.c
@@ -1,6 +1,6 @@
 /*
   Copyright (C) 1997-2022 Sam Lantinga <slouken@libsdl.org>
-  Copyright (C) 2020 Collabora Ltd.
+  Copyright (C) 2020-2022 Collabora Ltd.
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -935,6 +935,19 @@ static const GuessTest guess_tests[] =
     }
 };
 
+/* The Linux kernel provides capability info in EVIOCGBIT and in /sys
+ * as an array of unsigned long in native byte order, rather than an array
+ * of bytes, an array of native-endian 32-bit words or an array of
+ * native-endian 64-bit words like you might have reasonably expected.
+ * The order of words in the array is always lowest-valued first: for
+ * instance, the first unsigned long in abs[] contains the bit representing
+ * absolute axis 0 (ABS_X).
+ *
+ * The constant arrays above provide test data in little-endian, because
+ * that's the easiest representation for hard-coding into a test like this.
+ * On a big-endian platform we need to byteswap it, one unsigned long at a
+ * time, to match what the kernel would produce. This requires us to choose
+ * an appropriate byteswapping function for the architecture's word size. */
 SDL_COMPILE_TIME_ASSERT(sizeof_long, sizeof(unsigned long) == 4 || sizeof(unsigned long) == 8);
 #define SwapLongLE(X) \
 	((sizeof(unsigned long) == 4) ? SDL_SwapLE32(X) : SDL_SwapLE64(X))