From 55c70f11e729f17c86f2400a457138682e03b00f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micka=C3=ABl=20Sala=C3=BCn?= Date: Fri, 26 May 2017 20:43:59 +0200 Subject: Documentation/dev-tools: Add kselftest MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Move kselftest.txt to dev-tools/kselftest.rst . Signed-off-by: Mickaël Salaün Acked-by: Kees Cook Cc: Jonathan Corbet Cc: Shuah Khan Signed-off-by: Shuah Khan --- Documentation/dev-tools/kselftest.rst | 109 ++++++++++++++++++++++++++++++++++ 1 file changed, 109 insertions(+) create mode 100644 Documentation/dev-tools/kselftest.rst (limited to 'Documentation/dev-tools') diff --git a/Documentation/dev-tools/kselftest.rst b/Documentation/dev-tools/kselftest.rst new file mode 100644 index 000000000000..5bd590335839 --- /dev/null +++ b/Documentation/dev-tools/kselftest.rst @@ -0,0 +1,109 @@ +Linux Kernel Selftests + +The kernel contains a set of "self tests" under the tools/testing/selftests/ +directory. These are intended to be small tests to exercise individual code +paths in the kernel. Tests are intended to be run after building, installing +and booting a kernel. + +On some systems, hot-plug tests could hang forever waiting for cpu and +memory to be ready to be offlined. A special hot-plug target is created +to run full range of hot-plug tests. In default mode, hot-plug tests run +in safe mode with a limited scope. In limited mode, cpu-hotplug test is +run on a single cpu as opposed to all hotplug capable cpus, and memory +hotplug test is run on 2% of hotplug capable memory instead of 10%. + +Running the selftests (hotplug tests are run in limited mode) +============================================================= + +To build the tests: + $ make -C tools/testing/selftests + + +To run the tests: + $ make -C tools/testing/selftests run_tests + +To build and run the tests with a single command, use: + $ make kselftest + +- note that some tests will require root privileges. + + +Running a subset of selftests +======================================== +You can use the "TARGETS" variable on the make command line to specify +single test to run, or a list of tests to run. + +To run only tests targeted for a single subsystem: + $ make -C tools/testing/selftests TARGETS=ptrace run_tests + +You can specify multiple tests to build and run: + $ make TARGETS="size timers" kselftest + +See the top-level tools/testing/selftests/Makefile for the list of all +possible targets. + + +Running the full range hotplug selftests +======================================== + +To build the hotplug tests: + $ make -C tools/testing/selftests hotplug + +To run the hotplug tests: + $ make -C tools/testing/selftests run_hotplug + +- note that some tests will require root privileges. + + +Install selftests +================= + +You can use kselftest_install.sh tool installs selftests in default +location which is tools/testing/selftests/kselftest or a user specified +location. + +To install selftests in default location: + $ cd tools/testing/selftests + $ ./kselftest_install.sh + +To install selftests in a user specified location: + $ cd tools/testing/selftests + $ ./kselftest_install.sh install_dir + +Running installed selftests +=========================== + +Kselftest install as well as the Kselftest tarball provide a script +named "run_kselftest.sh" to run the tests. + +You can simply do the following to run the installed Kselftests. Please +note some tests will require root privileges. + +cd kselftest +./run_kselftest.sh + +Contributing new tests +====================== + +In general, the rules for selftests are + + * Do as much as you can if you're not root; + + * Don't take too long; + + * Don't break the build on any architecture, and + + * Don't cause the top-level "make run_tests" to fail if your feature is + unconfigured. + +Contributing new tests(details) +=============================== + + * Use TEST_GEN_XXX if such binaries or files are generated during + compiling. + TEST_PROGS, TEST_GEN_PROGS mean it is the excutable tested by + default. + TEST_PROGS_EXTENDED, TEST_GEN_PROGS_EXTENDED mean it is the + executable which is not tested by default. + TEST_FILES, TEST_GEN_FILES mean it is the file which is used by + test. -- cgit v1.2.3 From cef04cdcb4275592ed6b6822e1939de44acce15b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micka=C3=ABl=20Sala=C3=BCn?= Date: Fri, 26 May 2017 20:44:00 +0200 Subject: Documentation/dev-tools: Use reStructuredText markups for kselftest MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Include and convert kselftest to the Sphinx format. Signed-off-by: Mickaël Salaün Acked-by: Kees Cook Cc: Jonathan Corbet Cc: Shuah Khan Signed-off-by: Shuah Khan --- Documentation/dev-tools/index.rst | 1 + Documentation/dev-tools/kselftest.rst | 67 +++++++++++++++++++++-------------- 2 files changed, 41 insertions(+), 27 deletions(-) (limited to 'Documentation/dev-tools') diff --git a/Documentation/dev-tools/index.rst b/Documentation/dev-tools/index.rst index 07d881147ef3..e50054c6aeaa 100644 --- a/Documentation/dev-tools/index.rst +++ b/Documentation/dev-tools/index.rst @@ -23,6 +23,7 @@ whole; patches welcome! kmemleak kmemcheck gdb-kernel-debugging + kselftest .. only:: subproject and html diff --git a/Documentation/dev-tools/kselftest.rst b/Documentation/dev-tools/kselftest.rst index 5bd590335839..9232ce94612c 100644 --- a/Documentation/dev-tools/kselftest.rst +++ b/Documentation/dev-tools/kselftest.rst @@ -1,4 +1,6 @@ +====================== Linux Kernel Selftests +====================== The kernel contains a set of "self tests" under the tools/testing/selftests/ directory. These are intended to be small tests to exercise individual code @@ -15,29 +17,34 @@ hotplug test is run on 2% of hotplug capable memory instead of 10%. Running the selftests (hotplug tests are run in limited mode) ============================================================= -To build the tests: - $ make -C tools/testing/selftests +To build the tests:: + + make -C tools/testing/selftests + +To run the tests:: + make -C tools/testing/selftests run_tests -To run the tests: - $ make -C tools/testing/selftests run_tests +To build and run the tests with a single command, use:: -To build and run the tests with a single command, use: - $ make kselftest + make kselftest -- note that some tests will require root privileges. +Note that some tests will require root privileges. Running a subset of selftests -======================================== +============================= + You can use the "TARGETS" variable on the make command line to specify single test to run, or a list of tests to run. -To run only tests targeted for a single subsystem: - $ make -C tools/testing/selftests TARGETS=ptrace run_tests +To run only tests targeted for a single subsystem:: + + make -C tools/testing/selftests TARGETS=ptrace run_tests -You can specify multiple tests to build and run: - $ make TARGETS="size timers" kselftest +You can specify multiple tests to build and run:: + + make TARGETS="size timers" kselftest See the top-level tools/testing/selftests/Makefile for the list of all possible targets. @@ -46,13 +53,15 @@ possible targets. Running the full range hotplug selftests ======================================== -To build the hotplug tests: - $ make -C tools/testing/selftests hotplug +To build the hotplug tests:: + + make -C tools/testing/selftests hotplug + +To run the hotplug tests:: -To run the hotplug tests: - $ make -C tools/testing/selftests run_hotplug + make -C tools/testing/selftests run_hotplug -- note that some tests will require root privileges. +Note that some tests will require root privileges. Install selftests @@ -62,13 +71,15 @@ You can use kselftest_install.sh tool installs selftests in default location which is tools/testing/selftests/kselftest or a user specified location. -To install selftests in default location: - $ cd tools/testing/selftests - $ ./kselftest_install.sh +To install selftests in default location:: -To install selftests in a user specified location: - $ cd tools/testing/selftests - $ ./kselftest_install.sh install_dir + cd tools/testing/selftests + ./kselftest_install.sh + +To install selftests in a user specified location:: + + cd tools/testing/selftests + ./kselftest_install.sh install_dir Running installed selftests =========================== @@ -79,8 +90,10 @@ named "run_kselftest.sh" to run the tests. You can simply do the following to run the installed Kselftests. Please note some tests will require root privileges. -cd kselftest -./run_kselftest.sh +:: + + cd kselftest + ./run_kselftest.sh Contributing new tests ====================== @@ -96,8 +109,8 @@ In general, the rules for selftests are * Don't cause the top-level "make run_tests" to fail if your feature is unconfigured. -Contributing new tests(details) -=============================== +Contributing new tests (details) +================================ * Use TEST_GEN_XXX if such binaries or files are generated during compiling. -- cgit v1.2.3 From 7e6a32abdded8ed3d50ca7d26d17b19ffa0ea34d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micka=C3=ABl=20Sala=C3=BCn?= Date: Mon, 5 Jun 2017 20:37:17 +0200 Subject: Documentation/dev-tools: Add kselftest_harness documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add ReST metadata to kselftest_harness.h to be able to include the comments in the Sphinx documentation. Signed-off-by: Mickaël Salaün Cc: Andy Lutomirski Cc: Jonathan Corbet Cc: Kees Cook Cc: Shuah Khan Cc: Will Drewry Signed-off-by: Shuah Khan --- Documentation/dev-tools/kselftest.rst | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) (limited to 'Documentation/dev-tools') diff --git a/Documentation/dev-tools/kselftest.rst b/Documentation/dev-tools/kselftest.rst index 9232ce94612c..b3861500c42d 100644 --- a/Documentation/dev-tools/kselftest.rst +++ b/Documentation/dev-tools/kselftest.rst @@ -120,3 +120,36 @@ Contributing new tests (details) executable which is not tested by default. TEST_FILES, TEST_GEN_FILES mean it is the file which is used by test. + +Test Harness +============ + +The kselftest_harness.h file contains useful helpers to build tests. The tests +from tools/testing/selftests/seccomp/seccomp_bpf.c can be used as example. + +Example +------- + +.. kernel-doc:: tools/testing/selftests/kselftest_harness.h + :doc: example + + +Helpers +------- + +.. kernel-doc:: tools/testing/selftests/kselftest_harness.h + :functions: TH_LOG TEST TEST_SIGNAL FIXTURE FIXTURE_DATA FIXTURE_SETUP + FIXTURE_TEARDOWN TEST_F TEST_HARNESS_MAIN + +Operators +--------- + +.. kernel-doc:: tools/testing/selftests/kselftest_harness.h + :doc: operators + +.. kernel-doc:: tools/testing/selftests/kselftest_harness.h + :functions: ASSERT_EQ ASSERT_NE ASSERT_LT ASSERT_LE ASSERT_GT ASSERT_GE + ASSERT_NULL ASSERT_TRUE ASSERT_NULL ASSERT_TRUE ASSERT_FALSE + ASSERT_STREQ ASSERT_STRNE EXPECT_EQ EXPECT_NE EXPECT_LT + EXPECT_LE EXPECT_GT EXPECT_GE EXPECT_NULL EXPECT_TRUE + EXPECT_FALSE EXPECT_STREQ EXPECT_STRNE -- cgit v1.2.3 From fde662d9c3e09ba54273785de4e12628b7bd9de1 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sat, 17 Jun 2017 12:26:40 -0300 Subject: kselftest.rst: do some adjustments after ReST conversion Do some minor adjustments after ReST conversion: - On most documents, we use prepend a "$ " before command line arguments; - Prefer to use :: on the preceding line; - Split a multi-paragraph description as such. Signed-off-by: Mauro Carvalho Chehab Acked-by: Jonathan Corbet Signed-off-by: Shuah Khan --- Documentation/dev-tools/kselftest.rst | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) (limited to 'Documentation/dev-tools') diff --git a/Documentation/dev-tools/kselftest.rst b/Documentation/dev-tools/kselftest.rst index b3861500c42d..ebd03d11d2c2 100644 --- a/Documentation/dev-tools/kselftest.rst +++ b/Documentation/dev-tools/kselftest.rst @@ -19,15 +19,15 @@ Running the selftests (hotplug tests are run in limited mode) To build the tests:: - make -C tools/testing/selftests + $ make -C tools/testing/selftests To run the tests:: - make -C tools/testing/selftests run_tests + $ make -C tools/testing/selftests run_tests To build and run the tests with a single command, use:: - make kselftest + $ make kselftest Note that some tests will require root privileges. @@ -40,11 +40,11 @@ single test to run, or a list of tests to run. To run only tests targeted for a single subsystem:: - make -C tools/testing/selftests TARGETS=ptrace run_tests + $ make -C tools/testing/selftests TARGETS=ptrace run_tests You can specify multiple tests to build and run:: - make TARGETS="size timers" kselftest + $ make TARGETS="size timers" kselftest See the top-level tools/testing/selftests/Makefile for the list of all possible targets. @@ -55,11 +55,11 @@ Running the full range hotplug selftests To build the hotplug tests:: - make -C tools/testing/selftests hotplug + $ make -C tools/testing/selftests hotplug To run the hotplug tests:: - make -C tools/testing/selftests run_hotplug + $ make -C tools/testing/selftests run_hotplug Note that some tests will require root privileges. @@ -73,13 +73,13 @@ location. To install selftests in default location:: - cd tools/testing/selftests - ./kselftest_install.sh + $ cd tools/testing/selftests + $ ./kselftest_install.sh To install selftests in a user specified location:: - cd tools/testing/selftests - ./kselftest_install.sh install_dir + $ cd tools/testing/selftests + $ ./kselftest_install.sh install_dir Running installed selftests =========================== @@ -88,12 +88,10 @@ Kselftest install as well as the Kselftest tarball provide a script named "run_kselftest.sh" to run the tests. You can simply do the following to run the installed Kselftests. Please -note some tests will require root privileges. +note some tests will require root privileges:: -:: - - cd kselftest - ./run_kselftest.sh + $ cd kselftest + $ ./run_kselftest.sh Contributing new tests ====================== @@ -114,8 +112,10 @@ Contributing new tests (details) * Use TEST_GEN_XXX if such binaries or files are generated during compiling. + TEST_PROGS, TEST_GEN_PROGS mean it is the excutable tested by default. + TEST_PROGS_EXTENDED, TEST_GEN_PROGS_EXTENDED mean it is the executable which is not tested by default. TEST_FILES, TEST_GEN_FILES mean it is the file which is used by -- cgit v1.2.3