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