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 * If set the test function will be executed for all available
182 * filesystems and the current filesystem type would be set in the
183 * tst_device->fs_type.
184 *
185 * The test setup and cleanup are executed before/after __EACH__ call
186 * to the test function.
187 */
188 int all_filesystems:1;
189 int skip_in_lockdown:1;
190 int skip_in_compat:1;
191 /*
192 * If set, the hugetlbfs will be mounted at .mntpoint.
193 */
194 int needs_hugetlbfs:1;
195
196 /*
197 * The skip_filesystems is a NULL terminated list of filesystems the
198 * test does not support. It can also be used to disable whole class of
199 * filesystems with a special keywords such as "fuse".
200 */
201 const char *const *skip_filesystems;
202
203 /* Minimum number of online CPU required by the test */
204 unsigned long min_cpus;
205
206 /* Minimum size(MB) of MemAvailable required by the test */
207 unsigned long min_mem_avail;
208
209 /*
210 * Two policies for reserving hugepage:
211 *
212 * TST_REQUEST:
213 * It will try the best to reserve available huge pages and return the number
214 * of available hugepages in tst_hugepages, which may be 0 if hugepages are
215 * not supported at all.
216 *
217 * TST_NEEDS:
218 * This is an enforced requirement, LTP should strictly do hpages applying and
219 * guarantee the 'HugePages_Free' no less than pages which makes that test can
220 * use these specified numbers correctly. Otherwise, test exits with TCONF if
221 * the attempt to reserve hugepages fails or reserves less than requested.
222 *
223 * With success test stores the reserved hugepage number in 'tst_hugepages. For
224 * the system without hugetlb supporting, variable 'tst_hugepages' will be set to 0.
225 * If the hugepage number needs to be set to 0 on supported hugetlb system, please
226 * use '.hugepages = {TST_NO_HUGEPAGES}'.
227 *
228 * Also, we do cleanup and restore work for the hpages resetting automatically.
229 */
230 struct tst_hugepage hugepages;
231
232 /*
233 * If set to non-zero, call tst_taint_init(taint_check) during setup
234 * and check kernel taint at the end of the test. If all_filesystems
235 * is non-zero, taint check will be performed after each FS test and
236 * testing will be terminated by TBROK if taint is detected.
237 */
238 unsigned int taint_check;
239
240 /*
241 * If set non-zero denotes number of test variant, the test is executed
242 * variants times each time with tst_variant set to different number.
243 *
244 * This allows us to run the same test for different settings. The
245 * intended use is to test different syscall wrappers/variants but the
246 * API is generic and does not limit the usage in any way.
247 */
248 unsigned int test_variants;
249
250 /* Minimal device size in megabytes */
251 unsigned int dev_min_size;
252
253 /* Device filesystem type override NULL == default */
254 const char *dev_fs_type;
255
256 /* Options passed to SAFE_MKFS() when format_device is set */
257 const char *const *dev_fs_opts;
258 const char *const *dev_extra_opts;
259
260 /* Device mount options, used if mount_device is set */
261 const char *mntpoint;
262 unsigned int mnt_flags;
263 void *mnt_data;
264
265 /*
266 * Maximal test runtime in seconds.
267 *
268 * Any test that runs for more than a second or two should set this and
269 * also use tst_remaining_runtime() to exit when runtime was used up.
270 * Tests may finish sooner, for example if requested number of
271 * iterations was reached before the runtime runs out.
272 *
273 * If test runtime cannot be know in advance it should be set to
274 * TST_UNLIMITED_RUNTIME.
275 */
276 int max_runtime;
277
278 void (*setup)(void);
279 void (*cleanup)(void);
280
281 void (*test)(unsigned int test_nr);
282 void (*test_all)(void);
283
284 /* Syscall name used by the timer measurement library */
285 const char *scall;
286
287 /* Sampling function for timer measurement testcases */
288 int (*sample)(int clk_id, long long usec);
289
290 /* NULL terminated array of resource file names */
291 const char *const *resource_files;
292
293 /* NULL terminated array of needed kernel drivers */
294 const char * const *needs_drivers;
295
296 /*
297 * {NULL, NULL} terminated array of (/proc, /sys) files to save
298 * before setup and restore after cleanup
299 */
300 const struct tst_path_val *save_restore;
301
302 /*
303 * NULL terminated array of kernel config options required for the
304 * test.
305 */
306 const char *const *needs_kconfigs;
307
308 /*
309 * {NULL, NULL} terminated array to be allocated buffers.
310 */
311 struct tst_buffers *bufs;
312
313 /*
314 * {NULL, NULL} terminated array of capability settings
315 */
316 struct tst_cap *caps;
317
318 /*
319 * {NULL, NULL} terminated array of tags.
320 */
321 const struct tst_tag *tags;
322
323 /* NULL terminated array of required commands */
324 const char *const *needs_cmds;
325
326 /* Requires a particular CGroup API version. */
327 const enum tst_cg_ver needs_cgroup_ver;
328
329 /* {} terminated array of required CGroup controllers */
330 const char *const *needs_cgroup_ctrls;
331 };
332
333 /*
334 * Runs tests.
335 */
336 void tst_run_tcases(int argc, char *argv[], struct tst_test *self)
337 __attribute__ ((noreturn));
338
339 #define IPC_ENV_VAR "LTP_IPC_PATH"
340
341 /*
342 * Does library initialization for child processes started by exec()
343 *
344 * The LTP_IPC_PATH variable must be passed to the program environment.
345 */
346 void tst_reinit(void);
347
348 unsigned int tst_multiply_timeout(unsigned int timeout);
349
350 /*
351 * Returns remaining test runtime. Test that runs for more than a few seconds
352 * should check if they should exit by calling this function regularly.
353 *
354 * The function returns remaining runtime in seconds. If runtime was used up
355 * zero is returned.
356 */
357 unsigned int tst_remaining_runtime(void);
358
359 /*
360 * Sets maximal test runtime in seconds.
361 */
362 void tst_set_max_runtime(int max_runtime);
363
364 /*
365 * Create and open a random file inside the given dir path.
366 * It unlinks the file after opening and return file descriptor.
367 */
368 int tst_creat_unlinked(const char *path, int flags);
369
370 /*
371 * Returns path to the test temporary directory in a newly allocated buffer.
372 */
373 char *tst_get_tmpdir(void);
374
375 /*
376 * Returns path to the test temporary directory root (TMPDIR).
377 */
378 const char *tst_get_tmpdir_root(void);
379
380 /*
381 * Validates exit status of child processes
382 */
383 int tst_validate_children_(const char *file, const int lineno,
384 unsigned int count);
385 #define tst_validate_children(child_count) \
386 tst_validate_children_(__FILE__, __LINE__, (child_count))
387
388 #ifndef TST_NO_DEFAULT_MAIN
389
390 static struct tst_test test;
391
main(int argc,char * argv[])392 int main(int argc, char *argv[])
393 {
394 tst_run_tcases(argc, argv, &test);
395 }
396
397 #endif /* TST_NO_DEFAULT_MAIN */
398
399 #define TST_TEST_TCONF(message) \
400 static struct tst_test test = { .tconf_msg = message } \
401
402 #endif /* TST_TEST_H__ */
403