1 /* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */ 2 /* 3 * 4 * (C) COPYRIGHT 2014, 2017, 2020-2022 ARM Limited. All rights reserved. 5 * 6 * This program is free software and is provided to you under the terms of the 7 * GNU General Public License version 2 as published by the Free Software 8 * Foundation, and any use by you of this program is subject to the terms 9 * of such GNU license. 10 * 11 * This program is distributed in the hope that it will be useful, 12 * but WITHOUT ANY WARRANTY; without even the implied warranty of 13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 14 * GNU General Public License for more details. 15 * 16 * You should have received a copy of the GNU General Public License 17 * along with this program; if not, you can access it online at 18 * http://www.gnu.org/licenses/gpl-2.0.html. 19 * 20 */ 21 22 #ifndef _KERNEL_UTF_SUITE_H_ 23 #define _KERNEL_UTF_SUITE_H_ 24 25 /* kutf_suite.h 26 * Functions for management of test suites. 27 * 28 * This collection of data structures, macros, and functions are used to 29 * create Test Suites, Tests within those Test Suites, and Fixture variants 30 * of each test. 31 */ 32 33 #include <linux/kref.h> 34 #include <linux/workqueue.h> 35 #include <linux/wait.h> 36 37 #include <kutf/kutf_mem.h> 38 #include <kutf/kutf_resultset.h> 39 40 /* Arbitrary maximum size to prevent user space allocating too much kernel 41 * memory 42 */ 43 #define KUTF_MAX_LINE_LENGTH (1024u) 44 45 /** 46 * KUTF_F_TEST_NONE - Pseudo-flag indicating an absence of any specified test class. 47 * Note that tests should not be annotated with this constant as it is simply a zero 48 * value; tests without a more specific class must be marked with the flag 49 * KUTF_F_TEST_GENERIC. 50 */ 51 #define KUTF_F_TEST_NONE ((unsigned int)(0)) 52 53 /** 54 * KUTF_F_TEST_SMOKETEST - Class indicating this test is a smoke test. 55 * A given set of smoke tests should be quick to run, enabling rapid turn-around 56 * of "regress-on-commit" test runs. 57 */ 58 #define KUTF_F_TEST_SMOKETEST ((unsigned int)(1 << 1)) 59 60 /** 61 * KUTF_F_TEST_PERFORMANCE - Class indicating this test is a performance test. 62 * These tests typically produce a performance metric, such as "time to run" or 63 * "frames per second", 64 */ 65 #define KUTF_F_TEST_PERFORMANCE ((unsigned int)(1 << 2)) 66 67 /** 68 * KUTF_F_TEST_DEPRECATED - Class indicating that this test is a deprecated test. 69 * These tests have typically been replaced by an alternative test which is 70 * more efficient, or has better coverage. 71 */ 72 #define KUTF_F_TEST_DEPRECATED ((unsigned int)(1 << 3)) 73 74 /** 75 * KUTF_F_TEST_EXPECTED_FAILURE - Class indicating that this test is a known failure. 76 * These tests have typically been run and failed, but marking them as a known 77 * failure means it is easier to triage results. 78 * 79 * It is typically more convenient to triage known failures using the 80 * results database and web UI, as this means there is no need to modify the 81 * test code. 82 */ 83 #define KUTF_F_TEST_EXPECTED_FAILURE ((unsigned int)(1 << 4)) 84 85 /** 86 * KUTF_F_TEST_GENERIC - Class indicating that this test is a generic test, 87 * which is not a member of a more specific test class. 88 * Tests which are not created with a specific set 89 * of filter flags by the user are assigned this test class by default. 90 */ 91 #define KUTF_F_TEST_GENERIC ((unsigned int)(1 << 5)) 92 93 /** 94 * KUTF_F_TEST_RESFAIL - Class indicating this test is a resource allocation failure test. 95 * A resource allocation failure test will test that an error code is 96 * correctly propagated when an allocation fails. 97 */ 98 #define KUTF_F_TEST_RESFAIL ((unsigned int)(1 << 6)) 99 100 /** 101 * KUTF_F_TEST_EXPECTED_FAILURE_RF - Additional flag indicating that this test 102 * is an expected failure when run in resource failure mode. 103 * These tests are never run when running the low resource mode. 104 */ 105 #define KUTF_F_TEST_EXPECTED_FAILURE_RF ((unsigned int)(1 << 7)) 106 107 /** 108 * KUTF_F_TEST_USER_0 - Flag reserved for user-defined filter zero. 109 */ 110 #define KUTF_F_TEST_USER_0 ((unsigned int)(1 << 24)) 111 112 /** 113 * KUTF_F_TEST_USER_1 - Flag reserved for user-defined filter one. 114 */ 115 #define KUTF_F_TEST_USER_1 ((unsigned int)(1 << 25)) 116 117 /** 118 * KUTF_F_TEST_USER_2 - Flag reserved for user-defined filter two. 119 */ 120 #define KUTF_F_TEST_USER_2 ((unsigned int)(1 << 26)) 121 122 /** 123 * KUTF_F_TEST_USER_3 - Flag reserved for user-defined filter three. 124 */ 125 #define KUTF_F_TEST_USER_3 ((unsigned int)(1 << 27)) 126 127 /** 128 * KUTF_F_TEST_USER_4 - Flag reserved for user-defined filter four. 129 */ 130 #define KUTF_F_TEST_USER_4 ((unsigned int)(1 << 28)) 131 132 /** 133 * KUTF_F_TEST_USER_5 - Flag reserved for user-defined filter five. 134 */ 135 #define KUTF_F_TEST_USER_5 ((unsigned int)(1 << 29)) 136 137 /** 138 * KUTF_F_TEST_USER_6 - Flag reserved for user-defined filter six. 139 */ 140 #define KUTF_F_TEST_USER_6 ((unsigned int)(1 << 30)) 141 142 /** 143 * KUTF_F_TEST_USER_7 - Flag reserved for user-defined filter seven. 144 */ 145 #define KUTF_F_TEST_USER_7 ((unsigned int)(1 << 31)) 146 147 /** 148 * KUTF_F_TEST_ALL - Pseudo-flag indicating that all test classes should be executed. 149 */ 150 #define KUTF_F_TEST_ALL ((unsigned int)(0xFFFFFFFFU)) 151 152 /** 153 * union kutf_callback_data - Union used to store test callback data 154 * @ptr_value: pointer to the location where test callback data 155 * are stored 156 * @u32_value: a number which represents test callback data 157 */ 158 union kutf_callback_data { 159 void *ptr_value; 160 u32 u32_value; 161 }; 162 163 /** 164 * struct kutf_userdata_line - A line of user data to be returned to the user 165 * @node: struct list_head to link this into a list 166 * @str: The line of user data to return to user space 167 * @size: The number of bytes within @str 168 */ 169 struct kutf_userdata_line { 170 struct list_head node; 171 char *str; 172 size_t size; 173 }; 174 175 /** 176 * KUTF_USERDATA_WARNING_OUTPUT - Flag specifying that a warning has been output 177 * 178 * If user space reads the "run" file while the test is waiting for user data, 179 * then the framework will output a warning message and set this flag within 180 * struct kutf_userdata. A subsequent read will then simply return an end of 181 * file condition rather than outputting the warning again. The upshot of this 182 * is that simply running 'cat' on a test which requires user data will produce 183 * the warning followed by 'cat' exiting due to EOF - which is much more user 184 * friendly than blocking indefinitely waiting for user data. 185 */ 186 #define KUTF_USERDATA_WARNING_OUTPUT 1 187 188 /** 189 * struct kutf_userdata - Structure holding user data 190 * @flags: See %KUTF_USERDATA_WARNING_OUTPUT 191 * @input_head: List of struct kutf_userdata_line containing user data 192 * to be read by the kernel space test. 193 * @input_waitq: Wait queue signalled when there is new user data to be 194 * read by the kernel space test. 195 */ 196 struct kutf_userdata { 197 unsigned long flags; 198 struct list_head input_head; 199 wait_queue_head_t input_waitq; 200 }; 201 202 /** 203 * struct kutf_context - Structure representing a kernel test context 204 * @kref: Refcount for number of users of this context 205 * @suite: Convenience pointer to the suite this context 206 * is running 207 * @test_fix: The fixture that is being run in this context 208 * @fixture_pool: The memory pool used for the duration of 209 * the fixture/text context. 210 * @fixture: The user provided fixture structure. 211 * @fixture_index: The index (id) of the current fixture. 212 * @fixture_name: The name of the current fixture (or NULL if unnamed). 213 * @test_data: Any user private data associated with this test 214 * @result_set: All the results logged by this test context 215 * @status: The status of the currently running fixture. 216 * @expected_status: The expected status on exist of the currently 217 * running fixture. 218 * @work: Work item to enqueue onto the work queue to run the test 219 * @userdata: Structure containing the user data for the test to read 220 */ 221 struct kutf_context { 222 struct kref kref; 223 struct kutf_suite *suite; 224 struct kutf_test_fixture *test_fix; 225 struct kutf_mempool fixture_pool; 226 void *fixture; 227 unsigned int fixture_index; 228 const char *fixture_name; 229 union kutf_callback_data test_data; 230 struct kutf_result_set *result_set; 231 enum kutf_result_status status; 232 enum kutf_result_status expected_status; 233 234 struct work_struct work; 235 struct kutf_userdata userdata; 236 }; 237 238 /** 239 * struct kutf_suite - Structure representing a kernel test suite 240 * @app: The application this suite belongs to. 241 * @name: The name of this suite. 242 * @suite_data: Any user private data associated with this 243 * suite. 244 * @create_fixture: Function used to create a new fixture instance 245 * @remove_fixture: Function used to destroy a new fixture instance 246 * @fixture_variants: The number of variants (must be at least 1). 247 * @suite_default_flags: Suite global filter flags which are set on 248 * all tests. 249 * @node: List node for suite_list 250 * @dir: The debugfs directory for this suite 251 * @test_list: List head to store all the tests which are 252 * part of this suite 253 */ 254 struct kutf_suite { 255 struct kutf_application *app; 256 const char *name; 257 union kutf_callback_data suite_data; 258 void *(*create_fixture)(struct kutf_context *context); 259 void (*remove_fixture)(struct kutf_context *context); 260 unsigned int fixture_variants; 261 unsigned int suite_default_flags; 262 struct list_head node; 263 struct dentry *dir; 264 struct list_head test_list; 265 }; 266 267 /** =========================================================================== 268 * Application functions 269 * ============================================================================ 270 */ 271 272 /** 273 * kutf_create_application() - Create an in kernel test application. 274 * @name: The name of the test application. 275 * 276 * Return: pointer to the kutf_application on success or NULL 277 * on failure 278 */ 279 struct kutf_application *kutf_create_application(const char *name); 280 281 /** 282 * kutf_destroy_application() - Destroy an in kernel test application. 283 * 284 * @app: The test application to destroy. 285 */ 286 void kutf_destroy_application(struct kutf_application *app); 287 288 /**============================================================================ 289 * Suite functions 290 * ============================================================================ 291 */ 292 293 /** 294 * kutf_create_suite() - Create a kernel test suite. 295 * @app: The test application to create the suite in. 296 * @name: The name of the suite. 297 * @fixture_count: The number of fixtures to run over the test 298 * functions in this suite 299 * @create_fixture: Callback used to create a fixture. The returned value 300 * is stored in the fixture pointer in the context for 301 * use in the test functions. 302 * @remove_fixture: Callback used to remove a previously created fixture. 303 * 304 * Suite names must be unique. Should two suites with the same name be 305 * registered with the same application then this function will fail, if they 306 * are registered with different applications then the function will not detect 307 * this and the call will succeed. 308 * 309 * Return: pointer to the created kutf_suite on success or NULL 310 * on failure 311 */ 312 struct kutf_suite *kutf_create_suite( 313 struct kutf_application *app, 314 const char *name, 315 unsigned int fixture_count, 316 void *(*create_fixture)(struct kutf_context *context), 317 void (*remove_fixture)(struct kutf_context *context)); 318 319 /** 320 * kutf_create_suite_with_filters() - Create a kernel test suite with user 321 * defined default filters. 322 * @app: The test application to create the suite in. 323 * @name: The name of the suite. 324 * @fixture_count: The number of fixtures to run over the test 325 * functions in this suite 326 * @create_fixture: Callback used to create a fixture. The returned value 327 * is stored in the fixture pointer in the context for 328 * use in the test functions. 329 * @remove_fixture: Callback used to remove a previously created fixture. 330 * @filters: Filters to apply to a test if it doesn't provide its own 331 * 332 * Suite names must be unique. Should two suites with the same name be 333 * registered with the same application then this function will fail, if they 334 * are registered with different applications then the function will not detect 335 * this and the call will succeed. 336 * 337 * Return: pointer to the created kutf_suite on success or NULL on failure 338 */ 339 struct kutf_suite *kutf_create_suite_with_filters( 340 struct kutf_application *app, 341 const char *name, 342 unsigned int fixture_count, 343 void *(*create_fixture)(struct kutf_context *context), 344 void (*remove_fixture)(struct kutf_context *context), 345 unsigned int filters); 346 347 /** 348 * kutf_create_suite_with_filters_and_data() - Create a kernel test suite with 349 * user defined default filters. 350 * @app: The test application to create the suite in. 351 * @name: The name of the suite. 352 * @fixture_count: The number of fixtures to run over the test 353 * functions in this suite 354 * @create_fixture: Callback used to create a fixture. The returned value 355 * is stored in the fixture pointer in the context for 356 * use in the test functions. 357 * @remove_fixture: Callback used to remove a previously created fixture. 358 * @filters: Filters to apply to a test if it doesn't provide its own 359 * @suite_data: Suite specific callback data, provided during the 360 * running of the test in the kutf_context 361 * 362 * Return: pointer to the created kutf_suite on success or NULL 363 * on failure 364 */ 365 struct kutf_suite *kutf_create_suite_with_filters_and_data( 366 struct kutf_application *app, 367 const char *name, 368 unsigned int fixture_count, 369 void *(*create_fixture)(struct kutf_context *context), 370 void (*remove_fixture)(struct kutf_context *context), 371 unsigned int filters, 372 union kutf_callback_data suite_data); 373 374 /** 375 * kutf_add_test() - Add a test to a kernel test suite. 376 * @suite: The suite to add the test to. 377 * @id: The ID of the test. 378 * @name: The name of the test. 379 * @execute: Callback to the test function to run. 380 * 381 * Note: As no filters are provided the test will use the suite filters instead 382 */ 383 void kutf_add_test(struct kutf_suite *suite, 384 unsigned int id, 385 const char *name, 386 void (*execute)(struct kutf_context *context)); 387 388 /** 389 * kutf_add_test_with_filters() - Add a test to a kernel test suite with filters 390 * @suite: The suite to add the test to. 391 * @id: The ID of the test. 392 * @name: The name of the test. 393 * @execute: Callback to the test function to run. 394 * @filters: A set of filtering flags, assigning test categories. 395 */ 396 void kutf_add_test_with_filters(struct kutf_suite *suite, 397 unsigned int id, 398 const char *name, 399 void (*execute)(struct kutf_context *context), 400 unsigned int filters); 401 402 /** 403 * kutf_add_test_with_filters_and_data() - Add a test to a kernel test suite 404 * with filters. 405 * @suite: The suite to add the test to. 406 * @id: The ID of the test. 407 * @name: The name of the test. 408 * @execute: Callback to the test function to run. 409 * @filters: A set of filtering flags, assigning test categories. 410 * @test_data: Test specific callback data, provided during the 411 * running of the test in the kutf_context 412 */ 413 void kutf_add_test_with_filters_and_data( 414 struct kutf_suite *suite, 415 unsigned int id, 416 const char *name, 417 void (*execute)(struct kutf_context *context), 418 unsigned int filters, 419 union kutf_callback_data test_data); 420 421 /** =========================================================================== 422 * Test functions 423 * ============================================================================ 424 */ 425 /** 426 * kutf_test_log_result_external() - Log a result which has been created 427 * externally into a in a standard form 428 * recognized by the log parser. 429 * @context: The test context the test is running in 430 * @message: The message for this result 431 * @new_status: The result status of this log message 432 */ 433 void kutf_test_log_result_external( 434 struct kutf_context *context, 435 const char *message, 436 enum kutf_result_status new_status); 437 438 /** 439 * kutf_test_expect_abort() - Tell the kernel that you expect the current 440 * fixture to produce an abort. 441 * @context: The test context this test is running in. 442 */ 443 void kutf_test_expect_abort(struct kutf_context *context); 444 445 /** 446 * kutf_test_expect_fatal() - Tell the kernel that you expect the current 447 * fixture to produce a fatal error. 448 * @context: The test context this test is running in. 449 */ 450 void kutf_test_expect_fatal(struct kutf_context *context); 451 452 /** 453 * kutf_test_expect_fail() - Tell the kernel that you expect the current 454 * fixture to fail. 455 * @context: The test context this test is running in. 456 */ 457 void kutf_test_expect_fail(struct kutf_context *context); 458 459 /** 460 * kutf_test_expect_warn() - Tell the kernel that you expect the current 461 * fixture to produce a warning. 462 * @context: The test context this test is running in. 463 */ 464 void kutf_test_expect_warn(struct kutf_context *context); 465 466 /** 467 * kutf_test_expect_pass() - Tell the kernel that you expect the current 468 * fixture to pass. 469 * @context: The test context this test is running in. 470 */ 471 void kutf_test_expect_pass(struct kutf_context *context); 472 473 /** 474 * kutf_test_skip() - Tell the kernel that the test should be skipped. 475 * @context: The test context this test is running in. 476 */ 477 void kutf_test_skip(struct kutf_context *context); 478 479 /** 480 * kutf_test_skip_msg() - Tell the kernel that this test has been skipped, 481 * supplying a reason string. 482 * @context: The test context this test is running in. 483 * @message: A message string containing the reason for the skip. 484 * 485 * Note: The message must not be freed during the lifetime of the test run. 486 * This means it should either be a prebaked string, or if a dynamic string 487 * is required it must be created with kutf_dsprintf which will store 488 * the resultant string in a buffer who's lifetime is the same as the test run. 489 */ 490 void kutf_test_skip_msg(struct kutf_context *context, const char *message); 491 492 /** 493 * kutf_test_pass() - Tell the kernel that this test has passed. 494 * @context: The test context this test is running in. 495 * @message: A message string containing the reason for the pass. 496 * 497 * Note: The message must not be freed during the lifetime of the test run. 498 * This means it should either be a pre-baked string, or if a dynamic string 499 * is required it must be created with kutf_dsprintf which will store 500 * the resultant string in a buffer who's lifetime is the same as the test run. 501 */ 502 void kutf_test_pass(struct kutf_context *context, char const *message); 503 504 /** 505 * kutf_test_debug() - Send a debug message 506 * @context: The test context this test is running in. 507 * @message: A message string containing the debug information. 508 * 509 * Note: The message must not be freed during the lifetime of the test run. 510 * This means it should either be a pre-baked string, or if a dynamic string 511 * is required it must be created with kutf_dsprintf which will store 512 * the resultant string in a buffer who's lifetime is the same as the test run. 513 */ 514 void kutf_test_debug(struct kutf_context *context, char const *message); 515 516 /** 517 * kutf_test_info() - Send an information message 518 * @context: The test context this test is running in. 519 * @message: A message string containing the information message. 520 * 521 * Note: The message must not be freed during the lifetime of the test run. 522 * This means it should either be a pre-baked string, or if a dynamic string 523 * is required it must be created with kutf_dsprintf which will store 524 * the resultant string in a buffer who's lifetime is the same as the test run. 525 */ 526 void kutf_test_info(struct kutf_context *context, char const *message); 527 528 /** 529 * kutf_test_warn() - Send a warning message 530 * @context: The test context this test is running in. 531 * @message: A message string containing the warning message. 532 * 533 * Note: The message must not be freed during the lifetime of the test run. 534 * This means it should either be a pre-baked string, or if a dynamic string 535 * is required it must be created with kutf_dsprintf which will store 536 * the resultant string in a buffer who's lifetime is the same as the test run. 537 */ 538 void kutf_test_warn(struct kutf_context *context, char const *message); 539 540 /** 541 * kutf_test_fail() - Tell the kernel that a test has failed 542 * @context: The test context this test is running in. 543 * @message: A message string containing the failure message. 544 * 545 * Note: The message must not be freed during the lifetime of the test run. 546 * This means it should either be a pre-baked string, or if a dynamic string 547 * is required it must be created with kutf_dsprintf which will store 548 * the resultant string in a buffer who's lifetime is the same as the test run. 549 */ 550 void kutf_test_fail(struct kutf_context *context, char const *message); 551 552 /** 553 * kutf_test_fatal() - Tell the kernel that a test has triggered a fatal error 554 * @context: The test context this test is running in. 555 * @message: A message string containing the fatal error message. 556 * 557 * Note: The message must not be freed during the lifetime of the test run. 558 * This means it should either be a pre-baked string, or if a dynamic string 559 * is required it must be created with kutf_dsprintf which will store 560 * the resultant string in a buffer who's lifetime is the same as the test run. 561 */ 562 void kutf_test_fatal(struct kutf_context *context, char const *message); 563 564 /** 565 * kutf_test_abort() - Tell the kernel that a test triggered an abort in the test 566 * 567 * @context: The test context this test is running in. 568 */ 569 void kutf_test_abort(struct kutf_context *context); 570 571 #endif /* _KERNEL_UTF_SUITE_H_ */ 572