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