1 // SPDX-License-Identifier: GPL-2.0-or-later
2 /*
3 * Copyright (c) 2015-2016 Cyril Hrubis <chrubis@suse.cz>
4 * Copyright (c) Linux Test Project, 2016-2019
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
19 #include "tst_common.h"
20 #include "tst_res_flags.h"
21 #include "tst_test_macros.h"
22 #include "tst_checkpoint.h"
23 #include "tst_device.h"
24 #include "tst_mkfs.h"
25 #include "tst_fs.h"
26 #include "tst_pid.h"
27 #include "tst_cmd.h"
28 #include "tst_cpu.h"
29 #include "tst_process_state.h"
30 #include "tst_atomic.h"
31 #include "tst_kvercmp.h"
32 #include "tst_kernel.h"
33 #include "tst_minmax.h"
34 #include "tst_get_bad_addr.h"
35 #include "tst_path_has_mnt_flags.h"
36 #include "tst_sys_conf.h"
37 #include "tst_coredump.h"
38 #include "tst_buffers.h"
39 #include "tst_capability.h"
40 #include "tst_hugepage.h"
41 #include "tst_assert.h"
42 #include "tst_lockdown.h"
43 #include "tst_fips.h"
44 #include "tst_taint.h"
45 #include "tst_memutils.h"
46 #include "tst_arch.h"
47 #include "tst_fd.h"
48
49 /*
50 * Reports testcase result.
51 */
52 void tst_res_(const char *file, const int lineno, int ttype,
53 const char *fmt, ...)
54 __attribute__ ((format (printf, 4, 5)));
55
56 #define tst_res(ttype, arg_fmt, ...) \
57 ({ \
58 TST_RES_SUPPORTS_TCONF_TDEBUG_TFAIL_TINFO_TPASS_TWARN(\
59 !((TTYPE_RESULT(ttype) ?: TCONF) & \
60 (TCONF | TDEBUG | TFAIL | TINFO | TPASS | TWARN))); \
61 tst_res_(__FILE__, __LINE__, (ttype), (arg_fmt), ##__VA_ARGS__);\
62 })
63
64 void tst_resm_hexd_(const char *file, const int lineno, int ttype,
65 const void *buf, size_t size, const char *arg_fmt, ...)
66 __attribute__ ((format (printf, 6, 7)));
67
68 #define tst_res_hexd(ttype, buf, size, arg_fmt, ...) \
69 tst_resm_hexd_(__FILE__, __LINE__, (ttype), (buf), (size), \
70 (arg_fmt), ##__VA_ARGS__)
71
72 /*
73 * Reports result and exits a test.
74 */
75 void tst_brk_(const char *file, const int lineno, int ttype,
76 const char *fmt, ...)
77 __attribute__ ((format (printf, 4, 5)));
78
79 #define tst_brk(ttype, arg_fmt, ...) \
80 ({ \
81 TST_BRK_SUPPORTS_ONLY_TCONF_TBROK(!((ttype) & \
82 (TBROK | TCONF | TFAIL))); \
83 tst_brk_(__FILE__, __LINE__, (ttype), (arg_fmt), ##__VA_ARGS__);\
84 })
85
86 void tst_printf(const char *const fmt, ...)
87 __attribute__((nonnull(1), format (printf, 1, 2)));
88
89 /* flush stderr and stdout */
90 void tst_flush(void);
91
92 pid_t safe_fork(const char *filename, unsigned int lineno);
93 #define SAFE_FORK() \
94 safe_fork(__FILE__, __LINE__)
95
96 #define TST_TRACE(expr) \
97 ({int ret = expr; \
98 ret != 0 ? tst_res(TINFO, #expr " failed"), ret : ret; }) \
99
100 /*
101 * Functions to convert ERRNO to its name and SIGNAL to its name.
102 */
103 const char *tst_strerrno(int err);
104 const char *tst_strsig(int sig);
105 /*
106 * Returns string describing status as returned by wait().
107 *
108 * BEWARE: Not thread safe.
109 */
110 const char *tst_strstatus(int status);
111
112 #include "tst_safe_macros.h"
113 #include "tst_safe_file_ops.h"
114 #include "tst_safe_net.h"
115 #include "tst_clone.h"
116 #include "tst_cgroup.h"
117
118 /*
119 * Wait for all children and exit with TBROK if
120 * any of them returned a non-zero exit status.
121 */
122 void tst_reap_children(void);
123
124 struct tst_option {
125 char *optstr;
126 char **arg;
127 char *help;
128 };
129
130 /*
131 * Options parsing helpers.
132 *
133 * If str is NULL these are No-op.
134 *
135 * On failure non-zero (errno) is returned.
136 */
137 int tst_parse_int(const char *str, int *val, int min, int max);
138 int tst_parse_long(const char *str, long *val, long min, long max);
139 int tst_parse_float(const char *str, float *val, float min, float max);
140 int tst_parse_filesize(const char *str, long long *val, long long min, long long max);
141
142 struct tst_tag {
143 const char *name;
144 const char *value;
145 };
146
147 extern unsigned int tst_variant;
148
149 #define TST_NO_HUGEPAGES ((unsigned long)-1)
150
151 #define TST_UNLIMITED_RUNTIME (-1)
152
153 struct tst_test {
154 /* number of tests available in test() function */
155 unsigned int tcnt;
156
157 struct tst_option *options;
158
159 const char *min_kver;
160
161 /*
162 * The supported_archs is a NULL terminated list of archs the test
163 * does support.
164 */
165 const char *const *supported_archs;
166
167 /* If set the test is compiled out */
168 const char *tconf_msg;
169
170 int needs_tmpdir:1;
171 int needs_root:1;
172 int forks_child:1;
173 int needs_device:1;
174 int needs_checkpoints:1;
175 int needs_overlay:1;
176 int format_device:1;
177 int mount_device:1;
178 int needs_rofs:1;
179 int child_needs_reinit:1;
180 int needs_devfs:1;
181 int restore_wallclock:1;
182
183 /*
184 * If set the test function will be executed for all available
185 * filesystems and the current filesystem type would be set in the
186 * tst_device->fs_type.
187 *
188 * The test setup and cleanup are executed before/after __EACH__ call
189 * to the test function.
190 */
191 int all_filesystems:1;
192
193 int skip_in_lockdown:1;
194 int skip_in_secureboot:1;
195 int skip_in_compat:1;
196
197 /*
198 * If set, the hugetlbfs will be mounted at .mntpoint.
199 */
200 int needs_hugetlbfs:1;
201
202 /*
203 * The skip_filesystems is a NULL terminated list of filesystems the
204 * test does not support. It can also be used to disable whole class of
205 * filesystems with a special keywords such as "fuse".
206 */
207 const char *const *skip_filesystems;
208
209 /* Minimum number of online CPU required by the test */
210 unsigned long min_cpus;
211
212 /* Minimum size(MB) of MemAvailable required by the test */
213 unsigned long min_mem_avail;
214
215 /* Minimum size(MB) of SwapFree required by the test */
216 unsigned long min_swap_avail;
217
218 /*
219 * Two policies for reserving hugepage:
220 *
221 * TST_REQUEST:
222 * It will try the best to reserve available huge pages and return the number
223 * of available hugepages in tst_hugepages, which may be 0 if hugepages are
224 * not supported at all.
225 *
226 * TST_NEEDS:
227 * This is an enforced requirement, LTP should strictly do hpages applying and
228 * guarantee the 'HugePages_Free' no less than pages which makes that test can
229 * use these specified numbers correctly. Otherwise, test exits with TCONF if
230 * the attempt to reserve hugepages fails or reserves less than requested.
231 *
232 * With success test stores the reserved hugepage number in 'tst_hugepages. For
233 * the system without hugetlb supporting, variable 'tst_hugepages' will be set to 0.
234 * If the hugepage number needs to be set to 0 on supported hugetlb system, please
235 * use '.hugepages = {TST_NO_HUGEPAGES}'.
236 *
237 * Also, we do cleanup and restore work for the hpages resetting automatically.
238 */
239 struct tst_hugepage hugepages;
240
241 /*
242 * If set to non-zero, call tst_taint_init(taint_check) during setup
243 * and check kernel taint at the end of the test. If all_filesystems
244 * is non-zero, taint check will be performed after each FS test and
245 * testing will be terminated by TBROK if taint is detected.
246 */
247 unsigned int taint_check;
248
249 /*
250 * If set non-zero denotes number of test variant, the test is executed
251 * variants times each time with tst_variant set to different number.
252 *
253 * This allows us to run the same test for different settings. The
254 * intended use is to test different syscall wrappers/variants but the
255 * API is generic and does not limit the usage in any way.
256 */
257 unsigned int test_variants;
258
259 /* Minimal device size in megabytes */
260 unsigned int dev_min_size;
261
262 /* Device filesystem type override NULL == default */
263 const char *dev_fs_type;
264
265 /* Options passed to SAFE_MKFS() when format_device is set */
266 const char *const *dev_fs_opts;
267 const char *const *dev_extra_opts;
268
269 /* Device mount options, used if mount_device is set */
270 const char *mntpoint;
271 unsigned int mnt_flags;
272 void *mnt_data;
273
274 /*
275 * Maximal test runtime in seconds.
276 *
277 * Any test that runs for more than a second or two should set this and
278 * also use tst_remaining_runtime() to exit when runtime was used up.
279 * Tests may finish sooner, for example if requested number of
280 * iterations was reached before the runtime runs out.
281 *
282 * If test runtime cannot be know in advance it should be set to
283 * TST_UNLIMITED_RUNTIME.
284 */
285 int max_runtime;
286
287 void (*setup)(void);
288 void (*cleanup)(void);
289
290 void (*test)(unsigned int test_nr);
291 void (*test_all)(void);
292
293 /* Syscall name used by the timer measurement library */
294 const char *scall;
295
296 /* Sampling function for timer measurement testcases */
297 int (*sample)(int clk_id, long long usec);
298
299 /* NULL terminated array of resource file names */
300 const char *const *resource_files;
301
302 /* NULL terminated array of needed kernel drivers */
303 const char * const *needs_drivers;
304
305 /*
306 * {NULL, NULL} terminated array of (/proc, /sys) files to save
307 * before setup and restore after cleanup
308 */
309 const struct tst_path_val *save_restore;
310
311 /*
312 * NULL terminated array of kernel config options required for the
313 * test.
314 */
315 const char *const *needs_kconfigs;
316
317 /*
318 * {NULL, NULL} terminated array to be allocated buffers.
319 */
320 struct tst_buffers *bufs;
321
322 /*
323 * {NULL, NULL} terminated array of capability settings
324 */
325 struct tst_cap *caps;
326
327 /*
328 * {NULL, NULL} terminated array of tags.
329 */
330 const struct tst_tag *tags;
331
332 /* NULL terminated array of required commands */
333 const char *const *needs_cmds;
334
335 /* Requires a particular CGroup API version. */
336 const enum tst_cg_ver needs_cgroup_ver;
337
338 /* {} terminated array of required CGroup controllers */
339 const char *const *needs_cgroup_ctrls;
340 };
341
342 /*
343 * Runs tests.
344 */
345 void tst_run_tcases(int argc, char *argv[], struct tst_test *self)
346 __attribute__ ((noreturn));
347
348 #define IPC_ENV_VAR "LTP_IPC_PATH"
349
350 /*
351 * Does library initialization for child processes started by exec()
352 *
353 * The LTP_IPC_PATH variable must be passed to the program environment.
354 */
355 void tst_reinit(void);
356
357 unsigned int tst_multiply_timeout(unsigned int timeout);
358
359 /*
360 * Returns remaining test runtime. Test that runs for more than a few seconds
361 * should check if they should exit by calling this function regularly.
362 *
363 * The function returns remaining runtime in seconds. If runtime was used up
364 * zero is returned.
365 */
366 unsigned int tst_remaining_runtime(void);
367
368 /*
369 * Sets maximal test runtime in seconds.
370 */
371 void tst_set_max_runtime(int max_runtime);
372
373 /*
374 * Create and open a random file inside the given dir path.
375 * It unlinks the file after opening and return file descriptor.
376 */
377 int tst_creat_unlinked(const char *path, int flags);
378
379 /*
380 * Returns path to the test temporary directory in a newly allocated buffer.
381 */
382 char *tst_get_tmpdir(void);
383
384 /*
385 * Returns path to the test temporary directory root (TMPDIR).
386 */
387 const char *tst_get_tmpdir_root(void);
388
389 /*
390 * Validates exit status of child processes
391 */
392 int tst_validate_children_(const char *file, const int lineno,
393 unsigned int count);
394 #define tst_validate_children(child_count) \
395 tst_validate_children_(__FILE__, __LINE__, (child_count))
396
397 #ifndef TST_NO_DEFAULT_MAIN
398
399 static struct tst_test test;
400
main(int argc,char * argv[])401 int main(int argc, char *argv[])
402 {
403 tst_run_tcases(argc, argv, &test);
404 }
405
406 #endif /* TST_NO_DEFAULT_MAIN */
407
408 #define TST_TEST_TCONF(message) \
409 static struct tst_test test = { .tconf_msg = message } \
410
411 #endif /* TST_TEST_H__ */
412