1 /* SPDX-License-Identifier: GPL-2.0-or-later */
2 /*
3 * Copyright (c) 2015-2016 Cyril Hrubis <[email protected]>
4 * Copyright (c) Linux Test Project, 2016-2024
5 */
6
7 #ifndef TST_TEST_H__
8 #define TST_TEST_H__
9
10 #ifdef __TEST_H__
11 # error Oldlib test.h already included
12 #endif /* __TEST_H__ */
13
14 #include <unistd.h>
15 #include <limits.h>
16 #include <string.h>
17 #include <errno.h>
18 #include <sys/resource.h>
19
20 #include "tst_common.h"
21 #include "tst_res_flags.h"
22 #include "tst_parse.h"
23 #include "tst_test_macros.h"
24 #include "tst_checkpoint.h"
25 #include "tst_device.h"
26 #include "tst_mkfs.h"
27 #include "tst_fs.h"
28 #include "tst_pid.h"
29 #include "tst_cmd.h"
30 #include "tst_cpu.h"
31 #include "tst_process_state.h"
32 #include "tst_atomic.h"
33 #include "tst_kvercmp.h"
34 #include "tst_kernel.h"
35 #include "tst_minmax.h"
36 #include "tst_get_bad_addr.h"
37 #include "tst_path_has_mnt_flags.h"
38 #include "tst_sys_conf.h"
39 #include "tst_coredump.h"
40 #include "tst_buffers.h"
41 #include "tst_capability.h"
42 #include "tst_hugepage.h"
43 #include "tst_assert.h"
44 #include "tst_security.h"
45 #include "tst_taint.h"
46 #include "tst_memutils.h"
47 #include "tst_arch.h"
48 #include "tst_fd.h"
49
50 void tst_res_(const char *file, const int lineno, int ttype,
51 const char *fmt, ...)
52 __attribute__ ((format (printf, 4, 5)));
53
54 /**
55 * tst_res() - Reports a test result.
56 *
57 * @ttype: An enum tst_res_type.
58 * @arg_fmt: A printf-like format.
59 * @...: A printf-like parameters.
60 *
61 * This is the main test reporting function. Each time this function is called
62 * with one of TPASS, TFAIL, TCONF, TBROK or TWARN a counter in page of shared
63 * memory is incremented. This means that there is no need to propagate test
64 * results from children and that results are accounted for once this function
65 * returns. The counters are incremented atomically which makes this function
66 * thread-safe.
67 */
68 #define tst_res(ttype, arg_fmt, ...) \
69 ({ \
70 TST_RES_SUPPORTS_TCONF_TDEBUG_TFAIL_TINFO_TPASS_TWARN(\
71 !((TTYPE_RESULT(ttype) ?: TCONF) & \
72 (TCONF | TDEBUG | TFAIL | TINFO | TPASS | TWARN))); \
73 tst_res_(__FILE__, __LINE__, (ttype), (arg_fmt), ##__VA_ARGS__);\
74 })
75
76 void tst_resm_hexd_(const char *file, const int lineno, int ttype,
77 const void *buf, size_t size, const char *arg_fmt, ...)
78 __attribute__ ((format (printf, 6, 7)));
79 /**
80 * tst_res_hexd() - Reports a test result along with hex dump of a buffer.
81 *
82 * This call is the same as tst_res() but includes a pointer and size of the
83 * buffer that is going to be printed in the output in a hexadecimal format.
84 *
85 * @ttype: An enum tst_res_type.
86 * @buf: A pointer to a buffer to print in hexadecimal format.
87 * @size: A size of the buffer.
88 * @arg_fmt: A printf-like format.
89 * @...: A printf-like parameters.
90 */
91 #define tst_res_hexd(ttype, buf, size, arg_fmt, ...) \
92 tst_resm_hexd_(__FILE__, __LINE__, (ttype), (buf), (size), \
93 (arg_fmt), ##__VA_ARGS__)
94
95 void tst_brk_(const char *file, const int lineno, int ttype,
96 const char *fmt, ...)
97 __attribute__ ((format (printf, 4, 5)));
98
99 /**
100 * tst_brk() - Reports a breakage and exits the test.
101 *
102 * @ttype: An enum tst_res_type.
103 * @arg_fmt: A printf-like format.
104 * @...: A printf-like parameters.
105 *
106 * Reports either TBROK or TCONF and exits the test immediately. When called
107 * all children in the same process group as the main test library process are
108 * killed. This function, unless in a test cleanup, calls _exit() and does not
109 * return.
110 *
111 * When test is in cleanup() function TBROK is converted into TWARN by the test
112 * library and we attempt to carry on with a cleanup even when tst_brk() was
113 * called. This makes it possible to use SAFE_FOO() macros in the test cleanup
114 * without interrupting the cleanup process on a failure.
115 */
116 #define tst_brk(ttype, arg_fmt, ...) \
117 ({ \
118 TST_BRK_SUPPORTS_ONLY_TCONF_TBROK(!((ttype) & \
119 (TBROK | TCONF | TFAIL))); \
120 tst_brk_(__FILE__, __LINE__, (ttype), (arg_fmt), ##__VA_ARGS__);\
121 })
122
123 void tst_printf(const char *const fmt, ...)
124 __attribute__((nonnull(1), format (printf, 1, 2)));
125
126 /**
127 * tst_flush() - Flushes the output file streams.
128 *
129 * There are rare cases when we want to flush the output file streams
130 * explicitly, e.g. before we do an action that may crash the test to ensure
131 * that the messages have been written out.
132 *
133 * This is also called by the SAFE_FORK() because otherwise each child would
134 * end up with the same copy of the file in it's memory and any messages in
135 * buffers would be multiplied.
136 */
137 void tst_flush(void);
138
139 pid_t safe_fork(const char *filename, unsigned int lineno);
140 /**
141 * SAFE_FORK() - Forks a test child.
142 *
143 * This call makes sure that output file streams are flushed and also handles
144 * errors from fork(). Use this instead of fork() whenever possible!
145 */
146 #define SAFE_FORK() \
147 safe_fork(__FILE__, __LINE__)
148
149 #define TST_TRACE(expr) \
150 ({int ret = expr; \
151 ret != 0 ? tst_res(TINFO, #expr " failed"), ret : ret; }) \
152
153 /**
154 * tst_strerrno() - Converts an errno number into a name.
155 *
156 * @err: An errno number.
157 * return: An errno name e.g. "EINVAL".
158 */
159 const char *tst_strerrno(int err);
160
161 /**
162 * tst_strsig() - Converts a signal number into a name.
163 *
164 * @sig: A signal number.
165 * return: A signal name e.g. "SIGINT".
166 */
167 const char *tst_strsig(int sig);
168
169
170 /**
171 * tst_strstatus() - Returns string describing status as returned by wait().
172 *
173 * WARNING: Not thread safe.
174 *
175 * @status: A status as returned by wait()
176 * return: A string description for the status e.g. "killed by SIGKILL".
177 */
178 const char *tst_strstatus(int status);
179
180 #include "tst_safe_macros.h"
181 #include "tst_safe_file_ops.h"
182 #include "tst_safe_net.h"
183 #include "tst_clone.h"
184 #include "tst_cgroup.h"
185
186 /**
187 * tst_reap_children() - Waits for all child processes to exit.
188 *
189 * Wait for all children and exit with TBROK if any of them returned a non-zero
190 * exit status.
191 */
192 void tst_reap_children(void);
193
194 /**
195 * struct tst_option - Test command line option.
196 *
197 * @optstr: A short command line option, e.g. "a" or "a:".
198 * @arg: A pointer to store the option value to.
199 * @help: A help string for the option displayed when test is passed '-h' on
200 * the command-line.
201 */
202 struct tst_option {
203 char *optstr;
204 char **arg;
205 char *help;
206 };
207
208 /**
209 * struct tst_tag - A test tag.
210 *
211 * @name: A tag name.
212 * @value: A tag value.
213 *
214 * This structure is used to encode pointers to upstream commits in regression
215 * tests as well as CVE numbers or any additional useful hints.
216 *
217 * The content of these tags is printed by the test on a failure to help the
218 * testers with debugging.
219 *
220 * The supported tags are:
221 *
222 * - "linux-git" with first 12 numbers from an upstream kernel git hash.
223 * - "CVE" with a CVE number e.g. "2000-1234".
224 * - "glibc-git" with first 12 numbers from an upstream glibc git hash.
225 * - "musl-git" with first 12 numbers from an upstream musl git hash.
226 * - "known-fail" a message describing something that is supposed to work but
227 * rather than that produces a longstanding failures.
228 */
229 struct tst_tag {
230 const char *name;
231 const char *value;
232 };
233
234 extern unsigned int tst_variant;
235
236 #define TST_UNLIMITED_RUNTIME (-1)
237
238 /**
239 * struct tst_ulimit_val - An ulimit resource and value.
240 *
241 * @resource: Which resource limits should be adjusted. See setrlimit(2) for
242 * the list of the RLIMIT_* constants.
243 * @rlim_cur: A limit value.
244 */
245 struct tst_ulimit_val {
246 int resource;
247 rlim_t rlim_cur;
248 };
249
250 /**
251 * struct tst_test - A test description.
252 *
253 * @tcnt: A number of tests. If set the test() callback is called tcnt times
254 * and each time passed an increasing counter value.
255 * @options: An NULL optstr terminated array of struct tst_option.
256 *
257 * @min_kver: A minimal kernel version the test can run on. e.g. "3.10".
258 *
259 * @supported_archs: A NULL terminated array of architectures the test runs on
260 * e.g. {"x86_64, "x86", NULL}. Calls tst_is_on_arch() to
261 * check if current CPU architecture is supported and exits
262 * the test with TCONF if it's not.
263 *
264 * @tconf_msg: If set the test exits with TCONF right after entering the test
265 * library. This is used by the TST_TEST_TCONF() macro to disable
266 * tests at compile time.
267 *
268 * @needs_tmpdir: If set a temporary directory is prepared for the test inside
269 * $TMPDIR and the test $CWD is set to point to it. The content
270 * of the temporary directory is removed automatically after
271 * the test is finished.
272 *
273 * @needs_root: If set the test exit with TCONF unless it's executed under root
274 * user.
275 *
276 * @forks_child: Has to be set if the test intends to fork children.
277 *
278 * @needs_device: If set a block device is prepared for the test, the device
279 * path and size are set in the struct tst_device variable
280 * called tst_device. If $LTP_DEV variable exists in the test
281 * environment the test attempts to use that device first and
282 * only if that fails the test falls back to use loop devices.
283 * This flag implies needs_tmpdir flag because loop device
284 * backing files are created in the test temporary directory.
285 *
286 * @needs_checkpoints: Has to be set if the test wants to use checkpoint
287 * synchronization primitives.
288 *
289 * @needs_overlay: If set overlay file system is mounted on the top of the
290 * file system at tst_test.mntpoint.
291 *
292 * @format_device: Does all tst_test.needs_device would do and also formats
293 * the device with tst_test.dev_fs_type file system as well.
294 *
295 * @mount_device: Does all tst_test.format_device would do and also mounts the
296 * device at tst_test.mntpoint.
297 *
298 * @needs_rofs: If set a read-only file system is mounted at tst_test.mntpoint.
299 *
300 * @child_needs_reinit: Has to be set if the test needs to call tst_reinit()
301 * from a process started by exec().
302 *
303 * @needs_devfs: If set the devfs is mounted at tst_test.mntpoint. This is
304 * needed for tests that need to create device files since tmpfs
305 * at /tmp is usually mounted with 'nodev' option.
306 *
307 * @restore_wallclock: Saves wall clock at the start of the test and restores
308 * it at the end with the help of monotonic timers.
309 * Testcases that modify system wallclock use this to
310 * restore the system to the previous state.
311 *
312 * @all_filesystems: If set the test is executed for all supported filesytems,
313 * i.e. file system that is supported by the kernel and has
314 * mkfs installed on the system.The file system is mounted at
315 * tst_test.mntpoint and file system details, e.g. type are set
316 * in the struct tst_device. Each execution is independent,
317 * that means that for each iteration tst_test.setup() is
318 * called at the test start and tst_test.cleanup() is called
319 * at the end and tst_brk() only exits test for a single
320 * file system. That especially means that calling
321 * tst_brk(TCONF, ...) in the test setup will skip the
322 * current file system.
323 *
324 * @skip_in_lockdown: Skip the test if kernel lockdown is enabled.
325 *
326 * @skip_in_secureboot: Skip the test if secureboot is enabled.
327 *
328 * @skip_in_compat: Skip the test if we are executing 32bit binary on a 64bit
329 * kernel, i.e. we are testing the kernel compat layer.
330 *
331 * @needs_abi_bits: Skip the test if runs on a different kernel ABI than
332 * requested (on 32bit instead of 64bit or vice versa).
333 * Possible values: 32, 64.
334 *
335 * @needs_hugetlbfs: If set hugetlbfs is mounted at tst_test.mntpoint.
336 *
337 * @skip_filesystems: A NULL terminated array of unsupported file systems. The
338 * test reports TCONF if the file system to be tested is
339 * present in the array. This is especially useful to filter
340 * out unsupported file system when tst_test.all_filesystems
341 * is enabled.
342 *
343 * @min_cpus: Minimal number of online CPUs the test needs to run.
344 *
345 * @min_mem_avail: Minimal amount of available RAM memory in megabytes required
346 * for the test to run.
347 *
348 * @min_swap_avail: Minimal amount of available swap memory in megabytes
349 * required for the test to run.
350 *
351 * @hugepages: An interface to reserve hugepages prior running the test.
352 * Request how many hugepages should be reserved in the global
353 * pool and also if having hugepages is required for the test run
354 * or not, i.e. if test should exit with TCONF if the requested
355 * amount of hugepages cannot be reserved. If TST_REQUEST is set
356 * the library will try it's best to reserve the hugepages and
357 * return the number of available hugepages in tst_hugepages, which
358 * may be 0 if there is no free memory or hugepages are not
359 * supported at all. If TST_NEEDS the requested hugepages are
360 * required for the test and the test exits if it couldn't be
361 * required. It can also be used to disable hugepages by setting
362 * .hugepages = {TST_NO_HUGEPAGES}. The test library restores the
363 * original poll allocations after the test has finished.
364 *
365 * @taint_check: If set the test fails if kernel is tainted during the test run.
366 * That means tst_taint_init() is called during the test setup
367 * and tst_taint_check() at the end of the test. If all_filesystems
368 * is set taint check will be performed after each iteration and
369 * testing will be terminated by TBROK if taint is detected.
370 *
371 * @test_variants: If set denotes number of test variant, the test is executed
372 * variants times each time with tst_variant set to different
373 * number. This allows us to run the same test for different
374 * settings. The intended use is to test different syscall
375 * wrappers/variants but the API is generic and does not limit
376 * usage in any way.
377 *
378 * @dev_min_size: A minimal device size in megabytes.
379 *
380 * @dev_fs_type: If set overrides the default file system type for the device and
381 * sets the tst_device.fs_type.
382 *
383 * @dev_fs_opts: A NULL terminated array of options passed to mkfs in the case
384 * of 'tst_test.format_device'. These options are passed to mkfs
385 * before the device path.
386 *
387 * @dev_extra_opts: A NULL terminated array of extra options passed to mkfs in
388 * the case of 'tst_test.format_device'. Extra options are
389 * passed to mkfs after the device path. Commonly the option
390 * after mkfs is the number of blocks and can be used to limit
391 * the file system not to use the whole block device.
392 *
393 * @mntpoint: A mount point where the test library mounts requested file system.
394 * The directory is created by the library, the test must not create
395 * it itself.
396 *
397 * @mnt_flags: MS_* flags passed to mount(2) when the test library mounts a
398 * device in the case of 'tst_test.mount_device'.
399 *
400 * @mnt_data: The data passed to mount(2) when the test library mounts a device
401 * in the case of 'tst_test.mount_device'.
402 *
403 * @max_runtime: Maximal test runtime in seconds. Any test that runs for more
404 * than a second or two should set this and also use
405 * tst_remaining_runtime() to exit when runtime was used up.
406 * Tests may finish sooner, for example if requested number of
407 * iterations was reached before the runtime runs out. If test
408 * runtime cannot be know in advance it should be set to
409 * TST_UNLIMITED_RUNTIME.
410 *
411 * @setup: Setup callback is called once at the start of the test in order to
412 * prepare the test environment.
413 *
414 * @cleanup: Cleanup callback is either called at the end of the test, or in a
415 * case that tst_brk() was called. That means that cleanup must be
416 * able to handle all possible states the test can be in. This
417 * usually means that we have to check if file descriptor was opened
418 * before we attempt to close it, etc.
419 *
420 *
421 * @test: A main test function, only one of the tst_test.test and test_all can
422 * be set. When this function is set the tst_test.tcnt must be set to a
423 * positive integer and this function will be executed tcnt times
424 * during a single test iteration. May be executed several times if test
425 * was passed '-i' or '-d' command line parameters.
426 *
427 * @test_all: A main test function, only one of the tst_test.test and test_all
428 * can be set. May be executed several times if test was passed '-i'
429 * or '-d' command line parameters.
430 *
431 * @resource_files: A NULL terminated array of filenames that will be copied
432 * to the test temporary directory from the LTP datafiles
433 * directory.
434 *
435 * @needs_drivers: A NULL terminated array of kernel modules required to run
436 * the test. The module has to be build in or present in order
437 * for the test to run.
438 *
439 * @save_restore: A {} terminated array of /proc or /sys files that should
440 * saved at the start of the test and restored at the end. See
441 * tst_sys_conf_save() and struct tst_path_val for details.
442 *
443 * @ulimit: A {} terminated array of process limits RLIMIT_* to be adjusted for
444 * the test.
445 *
446 * @needs_kconfigs: A NULL terminated array of kernel config options that are
447 * required for the test. All strings in the array have to be
448 * evaluated to true for the test to run. Boolean operators
449 * and parenthesis are supported, e.g.
450 * "CONFIG_X86_INTEL_UMIP=y | CONFIG_X86_UIMP=y" is evaluated
451 * to true if at least one of the options is present.
452 *
453 * @bufs: A description of guarded buffers to be allocated for the test. Guarded
454 * buffers are buffers with poisoned page allocated right before the start
455 * of the buffer and canary right after the end of the buffer. See
456 * struct tst_buffers and tst_buffer_alloc() for details.
457 *
458 * @caps: A {} terminated array of capabilities to change before the start of
459 * the test. See struct tst_cap and tst_cap_setup() for details.
460 *
461 * @tags: A {} terminated array of test tags. See struct tst_tag for details.
462 *
463 * @needs_cmds: A NULL terminated array of commands required for the test to run.
464 *
465 * @needs_cgroup_ver: If set the test will run only if the specified cgroup
466 * version is present on the system.
467 *
468 * @needs_cgroup_ctrls: A {} terminated array of cgroup controllers the test
469 * needs to run.
470 *
471 * @needs_cgroup_nsdelegate: If set test the will run only if cgroup2 is mounted
472 * with nsdelegate option.
473 */
474
475 struct tst_test {
476 unsigned int tcnt;
477
478 struct tst_option *options;
479
480 const char *min_kver;
481
482 const char *const *supported_archs;
483
484 const char *tconf_msg;
485
486 unsigned int needs_tmpdir:1;
487 unsigned int needs_root:1;
488 unsigned int forks_child:1;
489 unsigned int needs_device:1;
490 unsigned int needs_checkpoints:1;
491 unsigned int needs_overlay:1;
492 unsigned int format_device:1;
493 unsigned int mount_device:1;
494 unsigned int needs_rofs:1;
495 unsigned int child_needs_reinit:1;
496 unsigned int needs_devfs:1;
497 unsigned int restore_wallclock:1;
498
499 unsigned int all_filesystems:1;
500
501 unsigned int skip_in_lockdown:1;
502 unsigned int skip_in_secureboot:1;
503 unsigned int skip_in_compat:1;
504 int needs_abi_bits;
505
506 unsigned int needs_hugetlbfs:1;
507
508 const char *const *skip_filesystems;
509
510 unsigned long min_cpus;
511 unsigned long min_mem_avail;
512 unsigned long min_swap_avail;
513
514 struct tst_hugepage hugepages;
515
516 unsigned int taint_check;
517
518 unsigned int test_variants;
519
520 unsigned int dev_min_size;
521
522 const char *dev_fs_type;
523
524 const char *const *dev_fs_opts;
525 const char *const *dev_extra_opts;
526
527 const char *mntpoint;
528 unsigned int mnt_flags;
529 void *mnt_data;
530
531 int max_runtime;
532
533 void (*setup)(void);
534 void (*cleanup)(void);
535 void (*test)(unsigned int test_nr);
536 void (*test_all)(void);
537
538 const char *scall;
539 int (*sample)(int clk_id, long long usec);
540
541 const char *const *resource_files;
542 const char * const *needs_drivers;
543
544 const struct tst_path_val *save_restore;
545
546 const struct tst_ulimit_val *ulimit;
547
548 const char *const *needs_kconfigs;
549
550 struct tst_buffers *bufs;
551
552 struct tst_cap *caps;
553
554 const struct tst_tag *tags;
555
556 const char *const *needs_cmds;
557
558 const enum tst_cg_ver needs_cgroup_ver;
559
560 const char *const *needs_cgroup_ctrls;
561
562 int needs_cgroup_nsdelegate:1;
563 };
564
565 /**
566 * tst_run_tcases() - Entry point to the test library.
567 *
568 * @argc: An argc that was passed to the main().
569 * @argv: An argv that was passed to the main().
570 * @self: The test description and callbacks packed in the struct tst_test
571 * structure.
572 *
573 * A main() function which calls this function is added to each test
574 * automatically by including the tst_test.h header. The test has to define the
575 * struct tst_test called test.
576 *
577 * This function does not return, i.e. calls exit() after the test has finished.
578 */
579 void tst_run_tcases(int argc, char *argv[], struct tst_test *self)
580 __attribute__ ((noreturn));
581
582 #define IPC_ENV_VAR "LTP_IPC_PATH"
583
584 /**
585 * tst_reinit() - Reinitialize the test library.
586 *
587 * In a cases where a test child process calls exec() it no longer can access
588 * the test library shared memory and therefore use the test reporting
589 * functions, checkpoint library, etc. This function re-initializes the test
590 * library so that it can be used again.
591 *
592 * @important The LTP_IPC_PATH variable must be passed to the program environment.
593 */
594 void tst_reinit(void);
595
596 unsigned int tst_multiply_timeout(unsigned int timeout);
597
598 /*
599 * Returns remaining test runtime. Test that runs for more than a few seconds
600 * should check if they should exit by calling this function regularly.
601 *
602 * The function returns remaining runtime in seconds. If runtime was used up
603 * zero is returned.
604 */
605 unsigned int tst_remaining_runtime(void);
606
607 /*
608 * Sets maximal test runtime in seconds.
609 */
610 void tst_set_max_runtime(int max_runtime);
611
612 /*
613 * Create and open a random file inside the given dir path.
614 * It unlinks the file after opening and return file descriptor.
615 */
616 int tst_creat_unlinked(const char *path, int flags);
617
618 /*
619 * Returns path to the test temporary directory in a newly allocated buffer.
620 */
621 char *tst_get_tmpdir(void);
622
623 /*
624 * Returns path to the test temporary directory root (TMPDIR).
625 */
626 const char *tst_get_tmpdir_root(void);
627
628 /*
629 * Validates exit status of child processes
630 */
631 int tst_validate_children_(const char *file, const int lineno,
632 unsigned int count);
633 #define tst_validate_children(child_count) \
634 tst_validate_children_(__FILE__, __LINE__, (child_count))
635
636 #ifndef TST_NO_DEFAULT_MAIN
637
638 static struct tst_test test;
639
main(int argc,char * argv[])640 int main(int argc, char *argv[])
641 {
642 tst_run_tcases(argc, argv, &test);
643 }
644
645 #endif /* TST_NO_DEFAULT_MAIN */
646
647 /**
648 * TST_TEST_TCONF() - Exit tests with a TCONF message.
649 *
650 * This macro is used in test that couldn't be compiled either because current
651 * CPU architecture is unsupported or because of missing development libraries.
652 */
653 #define TST_TEST_TCONF(message) \
654 static struct tst_test test = { .tconf_msg = message } \
655
656 #endif /* TST_TEST_H__ */
657