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