From 99d5e6fbb96f3b896223ca5788703dc9329b7e6c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcin=20Wcis=C5=82o?= Date: Fri, 9 May 2025 01:21:55 +0200 Subject: [PATCH] lkdtm: basic description --- kselftests/lkdtm/README.rst | 162 ++++++++++++++++++++++++++++++++++++ 1 file changed, 162 insertions(+) create mode 100644 kselftests/lkdtm/README.rst diff --git a/kselftests/lkdtm/README.rst b/kselftests/lkdtm/README.rst new file mode 100644 index 0000000000000..5ab96a027c894 --- /dev/null +++ b/kselftests/lkdtm/README.rst @@ -0,0 +1,162 @@ +About +===== + +LKDTM (Linux Kernel Dump Test Module) is used for crashing the kernel on +demand and checking whether the kernel handled this properly. + +Related files +============= + +``Documentation/fault-injection/provoke-crashes.rst`` +----------------------------------------------------- + +Describes the ``lkdtm`` module allowing for provoked kernel crashes. + +The collection's test names correspond to the ``cpoint_type`` ("crash +point type") values mentioned in that document. + +``tools/testing/selftests/lkdtm/tests.txt`` +------------------------------------------- + +List of the actual tests contained in the collection, with some +meta-data attached. The mapping: + +:: + + #PANIC + BUG kernel BUG at + WARNING WARNING: + WARNING_MESSAGE message trigger + EXCEPTION + #LOOP Hangs the system + #EXHAUST_STACK Corrupts memory on failure + #CORRUPT_STACK Crashes entire system on success + #CORRUPT_STACK_STRONG Crashes entire system on success + … + +-> + +:: + + lkdtm:PANIC.sh + lkdtm:BUG.sh + lkdtm:WARNING.sh + lkdtm:WARNING_MESSAGE.sh + lkdtm:EXCEPTION.sh + lkdtm:LOOP.sh + lkdtm:EXHAUST_STACK.sh + lkdtm:CORRUPT_STACK.sh + lkdtm:CORRUPT_STACK_STRONG.sh + … + +#. The lines starting with ``#`` aren't really comments, in a sense that + whatever follows the ``#`` isn't ignored - it does in fact specify a + test, but it will be reported as skipped when executed. The + "dangerous" tests are commented out by default. + +#. When a line contains multiple words only the first one is used as the + test's name. + + :: + + BUDDY_INIT_ON_ALLOC Memory appears initialized + + -> + + :: + + lkdtm:BUDDY_INIT_ON_ALLOC.sh + + The rest is used as a short *note* about what is to be expected from + this test, displayed upon the test execution. It's also what's being + searched for in dmesg after provoking the failure, as a test's + success criterion. + +``tools/testing/selftests/lkdtm/run.sh`` +---------------------------------------- + +The template for each test in the collection. Although the test names +like ``lkdtm:WARNING_MESSAGE.sh`` suggest there is a shell script for +each of them there is in fact only one - the ``run.sh`` - which is +copied multiple times inside the ``tools/testing/selftests/lkdtm/`` +directory with different names corresponding to different test names +when the ``lkdtm`` collection is build. Each script then, when run, +introspects its own name to know which test it should conduct and then +just writes the test's name into the +``/sys/kernel/debug/provoke-crash/DIRECT``, like + +.. code:: shell + + echo ‹test› > /sys/kernel/debug/provoke-crash/DIRECT + +After that the newly shown dmesg lines are searched for the test's note, +or for "call trace:" if it doesn't have any. If the text was found the +test reports success, otherwise failure. + +For example, the ``lkdtm:WARNING_MESSAGE.sh`` test is realized by +``tools/testing/selftests/lkdtm/WARNING_MESSAGE.sh``, copied from +``tools/testing/selftests/lkdtm/run.sh``, which writes + +.. code:: shell + + echo WARNING_MESSAGE > /sys/kernel/debug/provoke-crash/DIRECT + +Then the dmesg is searched for "message trigger", as that is the +``WARNING_MESSAGE``'s note defined in the +`tools/testing/selftests/lkdtm/tests.txt`_ + +``tools/testing/selftests/lkdtm/stack-entropy.sh`` +-------------------------------------------------- + +Corresponds to the ``lkdtm:stack-entropy.sh`` test, the only one not +realized by the ``run.sh`` script. + +Requirements and applicability +============================== + +The ``lkdtm`` collection is not available in pre-``9.2`` versions. The +tests don't have any compilation requirements, but to run them the +``lkdtm`` module has to be available in the tested kernel, provided by +the ``CONFIG_LKDTM`` option, which is disabled in all default +configurations of LTS versions ``9.2``, ``9.4`` (other not checked) + +.. code:: shell + + grep CONFIG_LKDTM kernel-src-tree-{ciqlts9_2,ciqlts9_4}/configs/kernel*.config + +:: + + kernel-src-tree-ciqlts9_2/configs/kernel-aarch64-64k-debug-rhel.config:# CONFIG_LKDTM is not set + kernel-src-tree-ciqlts9_2/configs/kernel-aarch64-64k-rhel.config:# CONFIG_LKDTM is not set + kernel-src-tree-ciqlts9_2/configs/kernel-aarch64-debug-rhel.config:# CONFIG_LKDTM is not set + kernel-src-tree-ciqlts9_2/configs/kernel-aarch64-rhel.config:# CONFIG_LKDTM is not set + kernel-src-tree-ciqlts9_2/configs/kernel-ppc64le-debug-rhel.config:# CONFIG_LKDTM is not set + kernel-src-tree-ciqlts9_2/configs/kernel-ppc64le-rhel.config:# CONFIG_LKDTM is not set + kernel-src-tree-ciqlts9_2/configs/kernel-s390x-debug-rhel.config:# CONFIG_LKDTM is not set + kernel-src-tree-ciqlts9_2/configs/kernel-s390x-rhel.config:# CONFIG_LKDTM is not set + kernel-src-tree-ciqlts9_2/configs/kernel-s390x-zfcpdump-rhel.config:# CONFIG_LKDTM is not set + kernel-src-tree-ciqlts9_2/configs/kernel-x86_64-debug-rhel.config:# CONFIG_LKDTM is not set + kernel-src-tree-ciqlts9_2/configs/kernel-x86_64-rhel.config:# CONFIG_LKDTM is not set + kernel-src-tree-ciqlts9_4/configs/kernel-aarch64-64k-debug-rhel.config:# CONFIG_LKDTM is not set + kernel-src-tree-ciqlts9_4/configs/kernel-aarch64-64k-rhel.config:# CONFIG_LKDTM is not set + kernel-src-tree-ciqlts9_4/configs/kernel-aarch64-debug-rhel.config:# CONFIG_LKDTM is not set + kernel-src-tree-ciqlts9_4/configs/kernel-aarch64-rhel.config:# CONFIG_LKDTM is not set + kernel-src-tree-ciqlts9_4/configs/kernel-aarch64-rt-debug-rhel.config:# CONFIG_LKDTM is not set + kernel-src-tree-ciqlts9_4/configs/kernel-aarch64-rt-rhel.config:# CONFIG_LKDTM is not set + kernel-src-tree-ciqlts9_4/configs/kernel-ppc64le-debug-rhel.config:# CONFIG_LKDTM is not set + kernel-src-tree-ciqlts9_4/configs/kernel-ppc64le-rhel.config:# CONFIG_LKDTM is not set + kernel-src-tree-ciqlts9_4/configs/kernel-s390x-debug-rhel.config:# CONFIG_LKDTM is not set + kernel-src-tree-ciqlts9_4/configs/kernel-s390x-rhel.config:# CONFIG_LKDTM is not set + kernel-src-tree-ciqlts9_4/configs/kernel-s390x-zfcpdump-rhel.config:# CONFIG_LKDTM is not set + kernel-src-tree-ciqlts9_4/configs/kernel-x86_64-debug-rhel.config:# CONFIG_LKDTM is not set + kernel-src-tree-ciqlts9_4/configs/kernel-x86_64-rhel.config:# CONFIG_LKDTM is not set + kernel-src-tree-ciqlts9_4/configs/kernel-x86_64-rt-debug-rhel.config:# CONFIG_LKDTM is not set + kernel-src-tree-ciqlts9_4/configs/kernel-x86_64-rt-rhel.config:# CONFIG_LKDTM is not set + +This does not mean that these tests don't apply to Rocky Linux in +general (disabling ``CONFIG_LKDTM`` does not eliminate potentially +malfunctioning code branches, only the way to expose them), but it +certainly doesn't make sense to run them on the default builds. + +Note that for full functionality also other options may need to be +enabled - see the ``tools/testing/selftests/lkdtm/config`` file.