ANDROID: Add Android KUnit README

Document how to run a KUnit test module and how to run the ACK KUnit
tests via tradefed. Also, reorganized the toos/testing/kunit/android
file and directory structure slightly. This required a tweak
BUILD.bazel.

Bug: 231159463

Change-Id: I09c47d36593e839911767112176fa84bd7e25fe4
Signed-off-by: Joe Fradley <joefradley@google.com>

BUILD.bazel

@@ -795,9 +795,9 @@ pkg_files(
 
 pkg_files(
     name = "kunit_arm64_test_config",
-    srcs = [":tools/testing/kunit/android/config_arm64.xml"],
+    srcs = [":tools/testing/kunit/android/tradefed_configs/config_arm64.xml"],
     renames = {
-        "tools/testing/kunit/android/config_arm64.xml": "kunit.config",
+        "tools/testing/kunit/android/tradefed_configs/config_arm64.xml": "kunit.config",
     },
     visibility = ["//visibility:private"],
 )
@@ -825,9 +825,9 @@ pkg_files(
 
 pkg_files(
     name = "kunit_x86_64_test_config",
-    srcs = [":tools/testing/kunit/android/config_x86_64.xml"],
+    srcs = [":tools/testing/kunit/android/tradefed_configs/config_x86_64.xml"],
     renames = {
-        "tools/testing/kunit/android/config_x86_64.xml": "kunit.config",
+        "tools/testing/kunit/android/tradefed_configs/config_x86_64.xml": "kunit.config",
     },
     visibility = ["//visibility:private"],
 )
@@ -839,7 +839,7 @@ pkg_filegroup(
         ":kunit_x86_64_test_config",
     ],
     prefix = _KUNIT_DIR,
-    visibility = ["//visibility:private"],
+    #visibility = ["//visibility:private"],
 )
 
 # DDK Headers

tools/testing/kunit/android/README

@@ -0,0 +1,90 @@
+HOW TO RUN KUNIT TESTS IN ANDROID
+=================================
+
+Prerequisites
+ * Pass kunit.enable=1 as a kernel command line argument
+   * This should be done in either userdebug or eng build configs. See
+     the following examples:
+       * https://android-review.git.corp.google.com/c/device/google/cuttlefish/+/2085612
+       * https://android-review.git.corp.google.com/c/kernel/google-modules/raviole-device/+/2095369
+   * For a local device you can run the following:
+      $ fastboot oem cmdline add "kunit.enable=1"
+ * Run a "no trim" kernel (e.g. add `--notrim` to bazel build command)
+
+Run a test module
+ * Push the KUnit test module over to the device. For example using adb:
+   $ adb push kunit-test-example.ko /data
+
+ * (Optional) - Mount debugfs on device:
+    $ mount -t debugfs debugfs /sys/kernel/debug
+
+ * Load test module on device:
+    $ cd /data
+    $ insmod kunit-test-example.ko
+
+View test results
+ * If debugfs is mounted:
+    $ cat /sys/kernel/debug/kunit/<test name>/results
+    KTAP version 1
+    1..1
+        KTAP version 1
+        # Subtest: example
+        1..4
+        # example_simple_test: initializing
+
+        ok 1 example_simple_test
+    <truncated>
+
+ * Via dmesg (check before log cycles out):
+    $ dmesg
+    ....
+    [172434.032618] 1..1
+    [172434.032618]    KTAP version 1
+    [172434.032618]    # Subtest: example
+    [172434.032618]    1..4
+    [172434.032618]    # example_simple_test: initializing
+    [172434.032618]
+    [172434.032618]    ok 1 example_simple_test
+    <truncated>
+    ....
+
+Run ACK KUnit tests via tradefed
+ * Build ACK KUnit tests:
+   $ tools/bazel build //common:tests_zip_arm64_dist
+
+ * Unzip tests.zip (e.g. in local tmp directory):
+   $ unzip bazel-bin/common/arm64/tests.zip -d tmp
+
+ * With device connected and accessible via adb run the tests:
+   $ prebuilts/tradefed/filegroups/tradefed/tradefed.sh run commandAndExit \
+         template/local_min --template:map test=suite/test_mapping_suite   \
+         --include-filter kunit --tests-dir=tmp/testcases --primary-abi-only
+   ....
+   =======================================================
+   =============== Summary ===============
+   Total Run time: 23s
+   1/1 modules completed
+   Total Tests       : 9
+   PASSED            : 9
+   FAILED            : 0
+   ============== End of Results ==============
+   ============================================
+   ....
+
+
+TROUBLESHOOTING
+===============
+
+1. Test module fails to load.
+
+Check dmesg for load errors. If undefined symbol errors are shown, you're
+likely running with a trimmed kernel where the symbols are not available.
+Run with a "no trim" kernel.
+
+2. Test module loaded but no test results
+
+Check dmesg for KUnit errors.
+ $ dmesg | grep kunit
+
+If "kunit: disabled" is shown then `kunit.enable=1` has not been set.
+