| /* |
| * |
| * (C) COPYRIGHT 2014, 2017 ARM Limited. All rights reserved. |
| * |
| * This program is free software and is provided to you under the terms of the |
| * GNU General Public License version 2 as published by the Free Software |
| * Foundation, and any use by you of this program is subject to the terms |
| * of such GNU licence. |
| * |
| * This program is distributed in the hope that it will be useful, |
| * but WITHOUT ANY WARRANTY; without even the implied warranty of |
| * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| * GNU General Public License for more details. |
| * |
| * You should have received a copy of the GNU General Public License |
| * along with this program; if not, you can access it online at |
| * http://www.gnu.org/licenses/gpl-2.0.html. |
| * |
| * SPDX-License-Identifier: GPL-2.0 |
| * |
| */ |
| |
| #ifndef _KERNEL_UTF_SUITE_H_ |
| #define _KERNEL_UTF_SUITE_H_ |
| |
| /* kutf_suite.h |
| * Functions for management of test suites. |
| * |
| * This collection of data structures, macros, and functions are used to |
| * create Test Suites, Tests within those Test Suites, and Fixture variants |
| * of each test. |
| */ |
| |
| #include <linux/kref.h> |
| #include <linux/workqueue.h> |
| #include <linux/wait.h> |
| |
| #include <kutf/kutf_mem.h> |
| #include <kutf/kutf_resultset.h> |
| |
| /* Arbitrary maximum size to prevent user space allocating too much kernel |
| * memory |
| */ |
| #define KUTF_MAX_LINE_LENGTH (1024u) |
| |
| /** |
| * Pseudo-flag indicating an absence of any specified test class. Note that |
| * tests should not be annotated with this constant as it is simply a zero |
| * value; tests without a more specific class must be marked with the flag |
| * KUTF_F_TEST_GENERIC. |
| */ |
| #define KUTF_F_TEST_NONE ((unsigned int)(0)) |
| |
| /** |
| * Class indicating this test is a smoke test. |
| * A given set of smoke tests should be quick to run, enabling rapid turn-around |
| * of "regress-on-commit" test runs. |
| */ |
| #define KUTF_F_TEST_SMOKETEST ((unsigned int)(1 << 1)) |
| |
| /** |
| * Class indicating this test is a performance test. |
| * These tests typically produce a performance metric, such as "time to run" or |
| * "frames per second", |
| */ |
| #define KUTF_F_TEST_PERFORMANCE ((unsigned int)(1 << 2)) |
| |
| /** |
| * Class indicating that this test is a deprecated test. |
| * These tests have typically been replaced by an alternative test which is |
| * more efficient, or has better coverage. |
| */ |
| #define KUTF_F_TEST_DEPRECATED ((unsigned int)(1 << 3)) |
| |
| /** |
| * Class indicating that this test is a known failure. |
| * These tests have typically been run and failed, but marking them as a known |
| * failure means it is easier to triage results. |
| * |
| * It is typically more convenient to triage known failures using the |
| * results database and web UI, as this means there is no need to modify the |
| * test code. |
| */ |
| #define KUTF_F_TEST_EXPECTED_FAILURE ((unsigned int)(1 << 4)) |
| |
| /** |
| * Class indicating that this test is a generic test, which is not a member of |
| * a more specific test class. Tests which are not created with a specific set |
| * of filter flags by the user are assigned this test class by default. |
| */ |
| #define KUTF_F_TEST_GENERIC ((unsigned int)(1 << 5)) |
| |
| /** |
| * Class indicating this test is a resource allocation failure test. |
| * A resource allocation failure test will test that an error code is |
| * correctly propagated when an allocation fails. |
| */ |
| #define KUTF_F_TEST_RESFAIL ((unsigned int)(1 << 6)) |
| |
| /** |
| * Additional flag indicating that this test is an expected failure when |
| * run in resource failure mode. These tests are never run when running |
| * the low resource mode. |
| */ |
| #define KUTF_F_TEST_EXPECTED_FAILURE_RF ((unsigned int)(1 << 7)) |
| |
| /** |
| * Flag reserved for user-defined filter zero. |
| */ |
| #define KUTF_F_TEST_USER_0 ((unsigned int)(1 << 24)) |
| |
| /** |
| * Flag reserved for user-defined filter one. |
| */ |
| #define KUTF_F_TEST_USER_1 ((unsigned int)(1 << 25)) |
| |
| /** |
| * Flag reserved for user-defined filter two. |
| */ |
| #define KUTF_F_TEST_USER_2 ((unsigned int)(1 << 26)) |
| |
| /** |
| * Flag reserved for user-defined filter three. |
| */ |
| #define KUTF_F_TEST_USER_3 ((unsigned int)(1 << 27)) |
| |
| /** |
| * Flag reserved for user-defined filter four. |
| */ |
| #define KUTF_F_TEST_USER_4 ((unsigned int)(1 << 28)) |
| |
| /** |
| * Flag reserved for user-defined filter five. |
| */ |
| #define KUTF_F_TEST_USER_5 ((unsigned int)(1 << 29)) |
| |
| /** |
| * Flag reserved for user-defined filter six. |
| */ |
| #define KUTF_F_TEST_USER_6 ((unsigned int)(1 << 30)) |
| |
| /** |
| * Flag reserved for user-defined filter seven. |
| */ |
| #define KUTF_F_TEST_USER_7 ((unsigned int)(1 << 31)) |
| |
| /** |
| * Pseudo-flag indicating that all test classes should be executed. |
| */ |
| #define KUTF_F_TEST_ALL ((unsigned int)(0xFFFFFFFFU)) |
| |
| /** |
| * union kutf_callback_data - Union used to store test callback data |
| * @ptr_value: pointer to the location where test callback data |
| * are stored |
| * @u32_value: a number which represents test callback data |
| */ |
| union kutf_callback_data { |
| void *ptr_value; |
| u32 u32_value; |
| }; |
| |
| /** |
| * struct kutf_userdata_line - A line of user data to be returned to the user |
| * @node: struct list_head to link this into a list |
| * @str: The line of user data to return to user space |
| * @size: The number of bytes within @str |
| */ |
| struct kutf_userdata_line { |
| struct list_head node; |
| char *str; |
| size_t size; |
| }; |
| |
| /** |
| * KUTF_USERDATA_WARNING_OUTPUT - Flag specifying that a warning has been output |
| * |
| * If user space reads the "run" file while the test is waiting for user data, |
| * then the framework will output a warning message and set this flag within |
| * struct kutf_userdata. A subsequent read will then simply return an end of |
| * file condition rather than outputting the warning again. The upshot of this |
| * is that simply running 'cat' on a test which requires user data will produce |
| * the warning followed by 'cat' exiting due to EOF - which is much more user |
| * friendly than blocking indefinitely waiting for user data. |
| */ |
| #define KUTF_USERDATA_WARNING_OUTPUT 1 |
| |
| /** |
| * struct kutf_userdata - Structure holding user data |
| * @flags: See %KUTF_USERDATA_WARNING_OUTPUT |
| * @input_head: List of struct kutf_userdata_line containing user data |
| * to be read by the kernel space test. |
| * @input_waitq: Wait queue signalled when there is new user data to be |
| * read by the kernel space test. |
| */ |
| struct kutf_userdata { |
| unsigned long flags; |
| struct list_head input_head; |
| wait_queue_head_t input_waitq; |
| }; |
| |
| /** |
| * struct kutf_context - Structure representing a kernel test context |
| * @kref: Refcount for number of users of this context |
| * @suite: Convenience pointer to the suite this context |
| * is running |
| * @test_fix: The fixture that is being run in this context |
| * @fixture_pool: The memory pool used for the duration of |
| * the fixture/text context. |
| * @fixture: The user provided fixture structure. |
| * @fixture_index: The index (id) of the current fixture. |
| * @fixture_name: The name of the current fixture (or NULL if unnamed). |
| * @test_data: Any user private data associated with this test |
| * @result_set: All the results logged by this test context |
| * @status: The status of the currently running fixture. |
| * @expected_status: The expected status on exist of the currently |
| * running fixture. |
| * @work: Work item to enqueue onto the work queue to run the test |
| * @userdata: Structure containing the user data for the test to read |
| */ |
| struct kutf_context { |
| struct kref kref; |
| struct kutf_suite *suite; |
| struct kutf_test_fixture *test_fix; |
| struct kutf_mempool fixture_pool; |
| void *fixture; |
| unsigned int fixture_index; |
| const char *fixture_name; |
| union kutf_callback_data test_data; |
| struct kutf_result_set *result_set; |
| enum kutf_result_status status; |
| enum kutf_result_status expected_status; |
| |
| struct work_struct work; |
| struct kutf_userdata userdata; |
| }; |
| |
| /** |
| * struct kutf_suite - Structure representing a kernel test suite |
| * @app: The application this suite belongs to. |
| * @name: The name of this suite. |
| * @suite_data: Any user private data associated with this |
| * suite. |
| * @create_fixture: Function used to create a new fixture instance |
| * @remove_fixture: Function used to destroy a new fixture instance |
| * @fixture_variants: The number of variants (must be at least 1). |
| * @suite_default_flags: Suite global filter flags which are set on |
| * all tests. |
| * @node: List node for suite_list |
| * @dir: The debugfs directory for this suite |
| * @test_list: List head to store all the tests which are |
| * part of this suite |
| */ |
| struct kutf_suite { |
| struct kutf_application *app; |
| const char *name; |
| union kutf_callback_data suite_data; |
| void *(*create_fixture)(struct kutf_context *context); |
| void (*remove_fixture)(struct kutf_context *context); |
| unsigned int fixture_variants; |
| unsigned int suite_default_flags; |
| struct list_head node; |
| struct dentry *dir; |
| struct list_head test_list; |
| }; |
| |
| /* ============================================================================ |
| Application functions |
| ============================================================================ */ |
| |
| /** |
| * kutf_create_application() - Create an in kernel test application. |
| * @name: The name of the test application. |
| * |
| * Return: pointer to the kutf_application on success or NULL |
| * on failure |
| */ |
| struct kutf_application *kutf_create_application(const char *name); |
| |
| /** |
| * kutf_destroy_application() - Destroy an in kernel test application. |
| * |
| * @app: The test application to destroy. |
| */ |
| void kutf_destroy_application(struct kutf_application *app); |
| |
| /* ============================================================================ |
| Suite functions |
| ============================================================================ */ |
| |
| /** |
| * kutf_create_suite() - Create a kernel test suite. |
| * @app: The test application to create the suite in. |
| * @name: The name of the suite. |
| * @fixture_count: The number of fixtures to run over the test |
| * functions in this suite |
| * @create_fixture: Callback used to create a fixture. The returned value |
| * is stored in the fixture pointer in the context for |
| * use in the test functions. |
| * @remove_fixture: Callback used to remove a previously created fixture. |
| * |
| * Suite names must be unique. Should two suites with the same name be |
| * registered with the same application then this function will fail, if they |
| * are registered with different applications then the function will not detect |
| * this and the call will succeed. |
| * |
| * Return: pointer to the created kutf_suite on success or NULL |
| * on failure |
| */ |
| struct kutf_suite *kutf_create_suite( |
| struct kutf_application *app, |
| const char *name, |
| unsigned int fixture_count, |
| void *(*create_fixture)(struct kutf_context *context), |
| void (*remove_fixture)(struct kutf_context *context)); |
| |
| /** |
| * kutf_create_suite_with_filters() - Create a kernel test suite with user |
| * defined default filters. |
| * @app: The test application to create the suite in. |
| * @name: The name of the suite. |
| * @fixture_count: The number of fixtures to run over the test |
| * functions in this suite |
| * @create_fixture: Callback used to create a fixture. The returned value |
| * is stored in the fixture pointer in the context for |
| * use in the test functions. |
| * @remove_fixture: Callback used to remove a previously created fixture. |
| * @filters: Filters to apply to a test if it doesn't provide its own |
| * |
| * Suite names must be unique. Should two suites with the same name be |
| * registered with the same application then this function will fail, if they |
| * are registered with different applications then the function will not detect |
| * this and the call will succeed. |
| * |
| * Return: pointer to the created kutf_suite on success or NULL on failure |
| */ |
| struct kutf_suite *kutf_create_suite_with_filters( |
| struct kutf_application *app, |
| const char *name, |
| unsigned int fixture_count, |
| void *(*create_fixture)(struct kutf_context *context), |
| void (*remove_fixture)(struct kutf_context *context), |
| unsigned int filters); |
| |
| /** |
| * kutf_create_suite_with_filters_and_data() - Create a kernel test suite with |
| * user defined default filters. |
| * @app: The test application to create the suite in. |
| * @name: The name of the suite. |
| * @fixture_count: The number of fixtures to run over the test |
| * functions in this suite |
| * @create_fixture: Callback used to create a fixture. The returned value |
| * is stored in the fixture pointer in the context for |
| * use in the test functions. |
| * @remove_fixture: Callback used to remove a previously created fixture. |
| * @filters: Filters to apply to a test if it doesn't provide its own |
| * @suite_data: Suite specific callback data, provided during the |
| * running of the test in the kutf_context |
| * |
| * Return: pointer to the created kutf_suite on success or NULL |
| * on failure |
| */ |
| struct kutf_suite *kutf_create_suite_with_filters_and_data( |
| struct kutf_application *app, |
| const char *name, |
| unsigned int fixture_count, |
| void *(*create_fixture)(struct kutf_context *context), |
| void (*remove_fixture)(struct kutf_context *context), |
| unsigned int filters, |
| union kutf_callback_data suite_data); |
| |
| /** |
| * kutf_add_test() - Add a test to a kernel test suite. |
| * @suite: The suite to add the test to. |
| * @id: The ID of the test. |
| * @name: The name of the test. |
| * @execute: Callback to the test function to run. |
| * |
| * Note: As no filters are provided the test will use the suite filters instead |
| */ |
| void kutf_add_test(struct kutf_suite *suite, |
| unsigned int id, |
| const char *name, |
| void (*execute)(struct kutf_context *context)); |
| |
| /** |
| * kutf_add_test_with_filters() - Add a test to a kernel test suite with filters |
| * @suite: The suite to add the test to. |
| * @id: The ID of the test. |
| * @name: The name of the test. |
| * @execute: Callback to the test function to run. |
| * @filters: A set of filtering flags, assigning test categories. |
| */ |
| void kutf_add_test_with_filters(struct kutf_suite *suite, |
| unsigned int id, |
| const char *name, |
| void (*execute)(struct kutf_context *context), |
| unsigned int filters); |
| |
| /** |
| * kutf_add_test_with_filters_and_data() - Add a test to a kernel test suite |
| * with filters. |
| * @suite: The suite to add the test to. |
| * @id: The ID of the test. |
| * @name: The name of the test. |
| * @execute: Callback to the test function to run. |
| * @filters: A set of filtering flags, assigning test categories. |
| * @test_data: Test specific callback data, provided during the |
| * running of the test in the kutf_context |
| */ |
| void kutf_add_test_with_filters_and_data( |
| struct kutf_suite *suite, |
| unsigned int id, |
| const char *name, |
| void (*execute)(struct kutf_context *context), |
| unsigned int filters, |
| union kutf_callback_data test_data); |
| |
| |
| /* ============================================================================ |
| Test functions |
| ============================================================================ */ |
| /** |
| * kutf_test_log_result_external() - Log a result which has been created |
| * externally into a in a standard form |
| * recognized by the log parser. |
| * @context: The test context the test is running in |
| * @message: The message for this result |
| * @new_status: The result status of this log message |
| */ |
| void kutf_test_log_result_external( |
| struct kutf_context *context, |
| const char *message, |
| enum kutf_result_status new_status); |
| |
| /** |
| * kutf_test_expect_abort() - Tell the kernel that you expect the current |
| * fixture to produce an abort. |
| * @context: The test context this test is running in. |
| */ |
| void kutf_test_expect_abort(struct kutf_context *context); |
| |
| /** |
| * kutf_test_expect_fatal() - Tell the kernel that you expect the current |
| * fixture to produce a fatal error. |
| * @context: The test context this test is running in. |
| */ |
| void kutf_test_expect_fatal(struct kutf_context *context); |
| |
| /** |
| * kutf_test_expect_fail() - Tell the kernel that you expect the current |
| * fixture to fail. |
| * @context: The test context this test is running in. |
| */ |
| void kutf_test_expect_fail(struct kutf_context *context); |
| |
| /** |
| * kutf_test_expect_warn() - Tell the kernel that you expect the current |
| * fixture to produce a warning. |
| * @context: The test context this test is running in. |
| */ |
| void kutf_test_expect_warn(struct kutf_context *context); |
| |
| /** |
| * kutf_test_expect_pass() - Tell the kernel that you expect the current |
| * fixture to pass. |
| * @context: The test context this test is running in. |
| */ |
| void kutf_test_expect_pass(struct kutf_context *context); |
| |
| /** |
| * kutf_test_skip() - Tell the kernel that the test should be skipped. |
| * @context: The test context this test is running in. |
| */ |
| void kutf_test_skip(struct kutf_context *context); |
| |
| /** |
| * kutf_test_skip_msg() - Tell the kernel that this test has been skipped, |
| * supplying a reason string. |
| * @context: The test context this test is running in. |
| * @message: A message string containing the reason for the skip. |
| * |
| * Note: The message must not be freed during the lifetime of the test run. |
| * This means it should either be a prebaked string, or if a dynamic string |
| * is required it must be created with kutf_dsprintf which will store |
| * the resultant string in a buffer who's lifetime is the same as the test run. |
| */ |
| void kutf_test_skip_msg(struct kutf_context *context, const char *message); |
| |
| /** |
| * kutf_test_pass() - Tell the kernel that this test has passed. |
| * @context: The test context this test is running in. |
| * @message: A message string containing the reason for the pass. |
| * |
| * Note: The message must not be freed during the lifetime of the test run. |
| * This means it should either be a pre-baked string, or if a dynamic string |
| * is required it must be created with kutf_dsprintf which will store |
| * the resultant string in a buffer who's lifetime is the same as the test run. |
| */ |
| void kutf_test_pass(struct kutf_context *context, char const *message); |
| |
| /** |
| * kutf_test_debug() - Send a debug message |
| * @context: The test context this test is running in. |
| * @message: A message string containing the debug information. |
| * |
| * Note: The message must not be freed during the lifetime of the test run. |
| * This means it should either be a pre-baked string, or if a dynamic string |
| * is required it must be created with kutf_dsprintf which will store |
| * the resultant string in a buffer who's lifetime is the same as the test run. |
| */ |
| void kutf_test_debug(struct kutf_context *context, char const *message); |
| |
| /** |
| * kutf_test_info() - Send an information message |
| * @context: The test context this test is running in. |
| * @message: A message string containing the information message. |
| * |
| * Note: The message must not be freed during the lifetime of the test run. |
| * This means it should either be a pre-baked string, or if a dynamic string |
| * is required it must be created with kutf_dsprintf which will store |
| * the resultant string in a buffer who's lifetime is the same as the test run. |
| */ |
| void kutf_test_info(struct kutf_context *context, char const *message); |
| |
| /** |
| * kutf_test_warn() - Send a warning message |
| * @context: The test context this test is running in. |
| * @message: A message string containing the warning message. |
| * |
| * Note: The message must not be freed during the lifetime of the test run. |
| * This means it should either be a pre-baked string, or if a dynamic string |
| * is required it must be created with kutf_dsprintf which will store |
| * the resultant string in a buffer who's lifetime is the same as the test run. |
| */ |
| void kutf_test_warn(struct kutf_context *context, char const *message); |
| |
| /** |
| * kutf_test_fail() - Tell the kernel that a test has failed |
| * @context: The test context this test is running in. |
| * @message: A message string containing the failure message. |
| * |
| * Note: The message must not be freed during the lifetime of the test run. |
| * This means it should either be a pre-baked string, or if a dynamic string |
| * is required it must be created with kutf_dsprintf which will store |
| * the resultant string in a buffer who's lifetime is the same as the test run. |
| */ |
| void kutf_test_fail(struct kutf_context *context, char const *message); |
| |
| /** |
| * kutf_test_fatal() - Tell the kernel that a test has triggered a fatal error |
| * @context: The test context this test is running in. |
| * @message: A message string containing the fatal error message. |
| * |
| * Note: The message must not be freed during the lifetime of the test run. |
| * This means it should either be a pre-baked string, or if a dynamic string |
| * is required it must be created with kutf_dsprintf which will store |
| * the resultant string in a buffer who's lifetime is the same as the test run. |
| */ |
| void kutf_test_fatal(struct kutf_context *context, char const *message); |
| |
| /** |
| * kutf_test_abort() - Tell the kernel that a test triggered an abort in the test |
| * |
| * @context: The test context this test is running in. |
| */ |
| void kutf_test_abort(struct kutf_context *context); |
| |
| #endif /* _KERNEL_UTF_SUITE_H_ */ |
