From 55c70f11e729f17c86f2400a457138682e03b00f Mon Sep 17 00:00:00 2001 From: Mickaël Salaün 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: Mickaël Salaün 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: Mickaël Salaün 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 +++ tools/testing/selftests/kselftest_harness.h | 415 ++++++++++++++++++++++------ 2 files changed, 363 insertions(+), 85 deletions(-) (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 diff --git a/tools/testing/selftests/kselftest_harness.h b/tools/testing/selftests/kselftest_harness.h index 45f807ce37e1..c56f72e07cd7 100644 --- a/tools/testing/selftests/kselftest_harness.h +++ b/tools/testing/selftests/kselftest_harness.h @@ -4,41 +4,49 @@ * * kselftest_harness.h: simple C unit test helper. * - * Usage: - * #include "../kselftest_harness.h" - * TEST(standalone_test) { - * do_some_stuff; - * EXPECT_GT(10, stuff) { - * stuff_state_t state; - * enumerate_stuff_state(&state); - * TH_LOG("expectation failed with state: %s", state.msg); - * } - * more_stuff; - * ASSERT_NE(some_stuff, NULL) TH_LOG("how did it happen?!"); - * last_stuff; - * EXPECT_EQ(0, last_stuff); - * } - * - * FIXTURE(my_fixture) { - * mytype_t *data; - * int awesomeness_level; - * }; - * FIXTURE_SETUP(my_fixture) { - * self->data = mytype_new(); - * ASSERT_NE(NULL, self->data); - * } - * FIXTURE_TEARDOWN(my_fixture) { - * mytype_free(self->data); - * } - * TEST_F(my_fixture, data_is_good) { - * EXPECT_EQ(1, is_my_data_good(self->data)); - * } - * - * TEST_HARNESS_MAIN + * See documentation in Documentation/dev-tools/kselftest.rst * * API inspired by code.google.com/p/googletest */ +/** + * DOC: example + * + * .. code-block:: c + * + * #include "../kselftest_harness.h" + * + * TEST(standalone_test) { + * do_some_stuff; + * EXPECT_GT(10, stuff) { + * stuff_state_t state; + * enumerate_stuff_state(&state); + * TH_LOG("expectation failed with state: %s", state.msg); + * } + * more_stuff; + * ASSERT_NE(some_stuff, NULL) TH_LOG("how did it happen?!"); + * last_stuff; + * EXPECT_EQ(0, last_stuff); + * } + * + * FIXTURE(my_fixture) { + * mytype_t *data; + * int awesomeness_level; + * }; + * FIXTURE_SETUP(my_fixture) { + * self->data = mytype_new(); + * ASSERT_NE(NULL, self->data); + * } + * FIXTURE_TEARDOWN(my_fixture) { + * mytype_free(self->data); + * } + * TEST_F(my_fixture, data_is_good) { + * EXPECT_EQ(1, is_my_data_good(self->data)); + * } + * + * TEST_HARNESS_MAIN + */ + #ifndef __KSELFTEST_HARNESS_H #define __KSELFTEST_HARNESS_H @@ -61,10 +69,20 @@ # define TH_LOG_ENABLED 1 #endif -/* TH_LOG(format, ...) +/** + * TH_LOG(fmt, ...) + * + * @fmt: format string + * @...: optional arguments + * + * .. code-block:: c + * + * TH_LOG(format, ...) + * * Optional debug logging function available for use in tests. * Logging may be enabled or disabled by defining TH_LOG_ENABLED. * E.g., #define TH_LOG_ENABLED 1 + * * If no definition is provided, logging is enabled by default. */ #define TH_LOG(fmt, ...) do { \ @@ -77,7 +95,16 @@ fprintf(TH_LOG_STREAM, "%s:%d:%s:" fmt "\n", \ __FILE__, __LINE__, _metadata->name, ##__VA_ARGS__) -/* TEST(name) { implementation } +/** + * TEST(test_name) - Defines the test function and creates the registration + * stub + * + * @test_name: test name + * + * .. code-block:: c + * + * TEST(name) { implementation } + * * Defines a test by name. * Names must be unique and tests must not be run in parallel. The * implementation containing block is a function and scoping should be treated @@ -85,10 +112,18 @@ * * EXPECT_* and ASSERT_* are valid in a TEST() { } context. */ -/* Defines the test function and creates the registration stub. */ #define TEST(test_name) __TEST_IMPL(test_name, -1) -/* TEST_SIGNAL(name, signal) { implementation } +/** + * TEST_SIGNAL(test_name, signal) + * + * @test_name: test name + * @signal: signal number + * + * .. code-block:: c + * + * TEST_SIGNAL(name, signal) { implementation } + * * Defines a test by name and the expected term signal. * Names must be unique and tests must not be run in parallel. The * implementation containing block is a function and scoping should be treated @@ -110,22 +145,38 @@ static void test_name( \ struct __test_metadata __attribute__((unused)) *_metadata) -/* FIXTURE_DATA(datatype name) +/** + * FIXTURE_DATA(datatype_name) - Wraps the struct name so we have one less + * argument to pass around + * + * @datatype_name: datatype name + * + * .. code-block:: c + * + * FIXTURE_DATA(datatype name) + * * This call may be used when the type of the fixture data * is needed. In general, this should not be needed unless - * the |self| is being passed to a helper directly. + * the *self* is being passed to a helper directly. */ -/* Wraps the struct name so we have one less argument to pass around. */ #define FIXTURE_DATA(datatype_name) struct _test_data_##datatype_name -/* FIXTURE(datatype name) { - * type property1; - * ... - * }; - * Defines the data provided to TEST_F()-defined tests as |self|. It should be - * populated and cleaned up using FIXTURE_SETUP and FIXTURE_TEARDOWN. +/** + * FIXTURE(fixture_name) - Called once per fixture to setup the data and + * register + * + * @fixture_name: fixture name + * + * .. code-block:: c + * + * FIXTURE(datatype name) { + * type property1; + * ... + * }; + * + * Defines the data provided to TEST_F()-defined tests as *self*. It should be + * populated and cleaned up using FIXTURE_SETUP() and FIXTURE_TEARDOWN(). */ -/* Called once per fixture to setup the data and register. */ #define FIXTURE(fixture_name) \ static void __attribute__((constructor)) \ _register_##fixture_name##_data(void) \ @@ -134,9 +185,18 @@ } \ FIXTURE_DATA(fixture_name) -/* FIXTURE_SETUP(fixture name) { implementation } +/** + * FIXTURE_SETUP(fixture_name) - Prepares the setup function for the fixture. + * *_metadata* is included so that ASSERT_* work as a convenience + * + * @fixture_name: fixture name + * + * .. code-block:: c + * + * FIXTURE_SETUP(fixture name) { implementation } + * * Populates the required "setup" function for a fixture. An instance of the - * datatype defined with _FIXTURE_DATA will be exposed as |self| for the + * datatype defined with FIXTURE_DATA() will be exposed as *self* for the * implementation. * * ASSERT_* are valid for use in this context and will prempt the execution @@ -144,16 +204,21 @@ * * A bare "return;" statement may be used to return early. */ -/* Prepares the setup function for the fixture. |_metadata| is included - * so that ASSERT_* work as a convenience. - */ #define FIXTURE_SETUP(fixture_name) \ void fixture_name##_setup( \ struct __test_metadata __attribute__((unused)) *_metadata, \ FIXTURE_DATA(fixture_name) __attribute__((unused)) *self) -/* FIXTURE_TEARDOWN(fixture name) { implementation } +/** + * FIXTURE_TEARDOWN(fixture_name) + * + * @fixture_name: fixture name + * + * .. code-block:: c + * + * FIXTURE_TEARDOWN(fixture name) { implementation } + * * Populates the required "teardown" function for a fixture. An instance of the - * datatype defined with _FIXTURE_DATA will be exposed as |self| for the + * datatype defined with FIXTURE_DATA() will be exposed as *self* for the * implementation to clean up. * * A bare "return;" statement may be used to return early. @@ -163,15 +228,22 @@ struct __test_metadata __attribute__((unused)) *_metadata, \ FIXTURE_DATA(fixture_name) __attribute__((unused)) *self) -/* TEST_F(fixture, name) { implementation } +/** + * TEST_F(fixture_name, test_name) - Emits test registration and helpers for + * fixture-based test cases + * + * @fixture_name: fixture name + * @test_name: test name + * + * .. code-block:: c + * + * TEST_F(fixture, name) { implementation } + * * Defines a test that depends on a fixture (e.g., is part of a test case). - * Very similar to TEST() except that |self| is the setup instance of fixture's + * Very similar to TEST() except that *self* is the setup instance of fixture's * datatype exposed for use by the implementation. */ -/* Emits test registration and helpers for fixture-based test - * cases. - * TODO(wad) register fixtures on dedicated test lists. - */ +/* TODO(wad) register fixtures on dedicated test lists. */ #define TEST_F(fixture_name, test_name) \ __TEST_F_IMPL(fixture_name, test_name, -1) @@ -210,10 +282,15 @@ struct __test_metadata __attribute__((unused)) *_metadata, \ FIXTURE_DATA(fixture_name) __attribute__((unused)) *self) -/* Use once to append a main() to the test file. E.g., - * TEST_HARNESS_MAIN +/** + * TEST_HARNESS_MAIN - Simple wrapper to run the test harness + * + * .. code-block:: c + * + * TEST_HARNESS_MAIN + * + * Use once to append a main() to the test file. */ -/* Exports a simple wrapper to run the test harness. */ #define TEST_HARNESS_MAIN \ static void __attribute__((constructor)) \ __constructor_order_last(void) \ @@ -225,79 +302,247 @@ return test_harness_run(argc, argv); \ } -/* - * Operators for use in TEST and TEST_F. +/** + * DOC: operators + * + * Operators for use in TEST() and TEST_F(). * ASSERT_* calls will stop test execution immediately. * EXPECT_* calls will emit a failure warning, note it, and continue. */ -/* ASSERT_EQ(expected, measured): expected == measured */ + +/** + * ASSERT_EQ(expected, seen) + * + * @expected: expected value + * @seen: measured value + * + * ASSERT_EQ(expected, measured): expected == measured + */ #define ASSERT_EQ(expected, seen) \ __EXPECT(expected, seen, ==, 1) -/* ASSERT_NE(expected, measured): expected != measured */ + +/** + * ASSERT_NE(expected, seen) + * + * @expected: expected value + * @seen: measured value + * + * ASSERT_NE(expected, measured): expected != measured + */ #define ASSERT_NE(expected, seen) \ __EXPECT(expected, seen, !=, 1) -/* ASSERT_LT(expected, measured): expected < measured */ + +/** + * ASSERT_LT(expected, seen) + * + * @expected: expected value + * @seen: measured value + * + * ASSERT_LT(expected, measured): expected < measured + */ #define ASSERT_LT(expected, seen) \ __EXPECT(expected, seen, <, 1) -/* ASSERT_LE(expected, measured): expected <= measured */ + +/** + * ASSERT_LE(expected, seen) + * + * @expected: expected value + * @seen: measured value + * + * ASSERT_LE(expected, measured): expected <= measured + */ #define ASSERT_LE(expected, seen) \ __EXPECT(expected, seen, <=, 1) -/* ASSERT_GT(expected, measured): expected > measured */ + +/** + * ASSERT_GT(expected, seen) + * + * @expected: expected value + * @seen: measured value + * + * ASSERT_GT(expected, measured): expected > measured + */ #define ASSERT_GT(expected, seen) \ __EXPECT(expected, seen, >, 1) -/* ASSERT_GE(expected, measured): expected >= measured */ + +/** + * ASSERT_GE(expected, seen) + * + * @expected: expected value + * @seen: measured value + * + * ASSERT_GE(expected, measured): expected >= measured + */ #define ASSERT_GE(expected, seen) \ __EXPECT(expected, seen, >=, 1) -/* ASSERT_NULL(measured): NULL == measured */ + +/** + * ASSERT_NULL(seen) + * + * @seen: measured value + * + * ASSERT_NULL(measured): NULL == measured + */ #define ASSERT_NULL(seen) \ __EXPECT(NULL, seen, ==, 1) -/* ASSERT_TRUE(measured): measured != 0 */ +/** + * ASSERT_TRUE(seen) + * + * @seen: measured value + * + * ASSERT_TRUE(measured): measured != 0 + */ #define ASSERT_TRUE(seen) \ ASSERT_NE(0, seen) -/* ASSERT_FALSE(measured): measured == 0 */ + +/** + * ASSERT_FALSE(seen) + * + * @seen: measured value + * + * ASSERT_FALSE(measured): measured == 0 + */ #define ASSERT_FALSE(seen) \ ASSERT_EQ(0, seen) -/* ASSERT_STREQ(expected, measured): !strcmp(expected, measured) */ + +/** + * ASSERT_STREQ(expected, seen) + * + * @expected: expected value + * @seen: measured value + * + * ASSERT_STREQ(expected, measured): !strcmp(expected, measured) + */ #define ASSERT_STREQ(expected, seen) \ __EXPECT_STR(expected, seen, ==, 1) -/* ASSERT_STRNE(expected, measured): strcmp(expected, measured) */ + +/** + * ASSERT_STRNE(expected, seen) + * + * @expected: expected value + * @seen: measured value + * + * ASSERT_STRNE(expected, measured): strcmp(expected, measured) + */ #define ASSERT_STRNE(expected, seen) \ __EXPECT_STR(expected, seen, !=, 1) -/* EXPECT_EQ(expected, measured): expected == measured */ +/** + * EXPECT_EQ(expected, seen) + * + * @expected: expected value + * @seen: measured value + * + * EXPECT_EQ(expected, measured): expected == measured + */ #define EXPECT_EQ(expected, seen) \ __EXPECT(expected, seen, ==, 0) -/* EXPECT_NE(expected, measured): expected != measured */ + +/** + * EXPECT_NE(expected, seen) + * + * @expected: expected value + * @seen: measured value + * + * EXPECT_NE(expected, measured): expected != measured + */ #define EXPECT_NE(expected, seen) \ __EXPECT(expected, seen, !=, 0) -/* EXPECT_LT(expected, measured): expected < measured */ + +/** + * EXPECT_LT(expected, seen) + * + * @expected: expected value + * @seen: measured value + * + * EXPECT_LT(expected, measured): expected < measured + */ #define EXPECT_LT(expected, seen) \ __EXPECT(expected, seen, <, 0) -/* EXPECT_LE(expected, measured): expected <= measured */ + +/** + * EXPECT_LE(expected, seen) + * + * @expected: expected value + * @seen: measured value + * + * EXPECT_LE(expected, measured): expected <= measured + */ #define EXPECT_LE(expected, seen) \ __EXPECT(expected, seen, <=, 0) -/* EXPECT_GT(expected, measured): expected > measured */ + +/** + * EXPECT_GT(expected, seen) + * + * @expected: expected value + * @seen: measured value + * + * EXPECT_GT(expected, measured): expected > measured + */ #define EXPECT_GT(expected, seen) \ __EXPECT(expected, seen, >, 0) -/* EXPECT_GE(expected, measured): expected >= measured */ + +/** + * EXPECT_GE(expected, seen) + * + * @expected: expected value + * @seen: measured value + * + * EXPECT_GE(expected, measured): expected >= measured + */ #define EXPECT_GE(expected, seen) \ __EXPECT(expected, seen, >=, 0) -/* EXPECT_NULL(measured): NULL == measured */ +/** + * EXPECT_NULL(seen) + * + * @seen: measured value + * + * EXPECT_NULL(measured): NULL == measured + */ #define EXPECT_NULL(seen) \ __EXPECT(NULL, seen, ==, 0) -/* EXPECT_TRUE(measured): 0 != measured */ + +/** + * EXPECT_TRUE(seen) + * + * @seen: measured value + * + * EXPECT_TRUE(measured): 0 != measured + */ #define EXPECT_TRUE(seen) \ EXPECT_NE(0, seen) -/* EXPECT_FALSE(measured): 0 == measured */ + +/** + * EXPECT_FALSE(seen) + * + * @seen: measured value + * + * EXPECT_FALSE(measured): 0 == measured + */ #define EXPECT_FALSE(seen) \ EXPECT_EQ(0, seen) -/* EXPECT_STREQ(expected, measured): !strcmp(expected, measured) */ +/** + * EXPECT_STREQ(expected, seen) + * + * @expected: expected value + * @seen: measured value + * + * EXPECT_STREQ(expected, measured): !strcmp(expected, measured) + */ #define EXPECT_STREQ(expected, seen) \ __EXPECT_STR(expected, seen, ==, 0) -/* EXPECT_STRNE(expected, measured): strcmp(expected, measured) */ + +/** + * EXPECT_STRNE(expected, seen) + * + * @expected: expected value + * @seen: measured value + * + * EXPECT_STRNE(expected, measured): strcmp(expected, measured) + */ #define EXPECT_STRNE(expected, seen) \ __EXPECT_STR(expected, seen, !=, 0) -- 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