[LTP] [PATCH 2/2] macros: Add basic docs
Petr Vorel
pvorel@suse.cz
Thu Jan 9 14:23:34 CET 2025
Describe all "public" macros.
Move variables to the top.
Add header to the sphinx doc.
Signed-off-by: Petr Vorel <pvorel@suse.cz>
---
* I also wanted to document extern variables, but I haven't found a proper
syntax.
* TPASS/TFAIL cross reference is a bit verbose. I'd like to have some
helper for it, but creating extension is overkill.
extern long TST_RET;
extern void *TST_RET_PTR;
extern int TST_ERR;
extern int TST_PASS;
doc/developers/api_c_tests.rst | 1 +
include/tst_test_macros.h | 257 ++++++++++++++++++++++++++++++++-
2 files changed, 251 insertions(+), 7 deletions(-)
diff --git a/doc/developers/api_c_tests.rst b/doc/developers/api_c_tests.rst
index 46f5d3360b..515d843c00 100644
--- a/doc/developers/api_c_tests.rst
+++ b/doc/developers/api_c_tests.rst
@@ -11,6 +11,7 @@ Core LTP API
------------
.. kernel-doc:: ../../include/tst_res_flags.h
.. kernel-doc:: ../../include/tst_test.h
+.. kernel-doc:: ../../include/tst_test_macros.h
Capabilities
------------
diff --git a/include/tst_test_macros.h b/include/tst_test_macros.h
index b2b446b70c..2e8d88b1b7 100644
--- a/include/tst_test_macros.h
+++ b/include/tst_test_macros.h
@@ -1,7 +1,11 @@
// SPDX-License-Identifier: GPL-2.0-or-later
/*
* Copyright (c) 2015-2024 Cyril Hrubis <chrubis@suse.cz>
- * Copyright (c) Linux Test Project, 2021-2022
+ * Copyright (c) Linux Test Project, 2021-2024
+ */
+
+/**
+ * DOC: tst_test_macros.h -- helpers for testing syscalls
*/
#ifndef TST_TEST_MACROS_H__
@@ -9,6 +13,18 @@
#include <stdbool.h>
+extern long TST_RET;
+extern void *TST_RET_PTR;
+extern int TST_ERR;
+extern int TST_PASS;
+
+/**
+ * TEST() - Test syscall which return long (most of syscalls).
+ *
+ * @SCALL: Tested syscall.
+ *
+ * Sets TST_RET and TST_ERR.
+ */
#define TEST(SCALL) \
do { \
errno = 0; \
@@ -16,12 +32,13 @@
TST_ERR = errno; \
} while (0)
-extern long TST_RET;
-extern int TST_ERR;
-extern int TST_PASS;
-
-extern void *TST_RET_PTR;
-
+/**
+ * TESTPTR() - Test syscall which returns void pointer.
+ *
+ * @SCALL: Tested syscall.
+ *
+ * Sets TST_RET_PTR and TST_ERR.
+ */
#define TESTPTR(SCALL) \
do { \
errno = 0; \
@@ -74,6 +91,12 @@ extern void *TST_RET_PTR;
TST_RET; \
})
+/**
+ * TST_EXP_POSITIVE() - Test syscall, expect return value >= 0.
+ *
+ * @SCALL: Tested syscall.
+ * @...: A printf-like parameters.
+ */
#define TST_EXP_POSITIVE(SCALL, ...) \
({ \
TST_EXP_POSITIVE__(SCALL, #SCALL, ##__VA_ARGS__); \
@@ -86,8 +109,22 @@ extern void *TST_RET_PTR;
TST_RET; \
})
+/**
+ * TST_EXP_FD_SILENT() - Test syscall to return a file descriptor, silent variant.
+ *
+ * @SCALL: Tested syscall.
+ * @...: A printf-like parameters.
+ *
+ * Unlike TST_EXP_FD() does not print :c:enum:`TPASS <tst_res_flags>` on success, only prints :c:enum:`TFAIL <tst_res_flags>` on failure.
+ */
#define TST_EXP_FD_SILENT(SCALL, ...) TST_EXP_POSITIVE_(SCALL, #SCALL, ##__VA_ARGS__)
+/**
+ * TST_EXP_FD() - Test syscall to return a file descriptor.
+ *
+ * @SCALL: Tested syscall.
+ * @...: A printf-like parameters.
+ */
#define TST_EXP_FD(SCALL, ...) \
({ \
TST_EXP_POSITIVE__(SCALL, #SCALL, ##__VA_ARGS__); \
@@ -99,6 +136,18 @@ extern void *TST_RET_PTR;
TST_RET; \
})
+/**
+ * TST_EXP_FD_OR_FAIL() - Test syscall to return file descriptor or fail with
+ * expected errno.
+ *
+ * @SCALL: Tested syscall.
+ * @ERRNO: Expected errno or 0.
+ * @...: A printf-like parameters.
+ *
+ * Expect a file descriptor if errno is 0 otherwise fail with expected errno.
+ *
+ * Internally it uses TST_EXP_FAIL() and TST_EXP_FD().
+ */
#define TST_EXP_FD_OR_FAIL(SCALL, ERRNO, ...) \
({ \
if (ERRNO) \
@@ -109,8 +158,22 @@ extern void *TST_RET_PTR;
TST_RET; \
})
+/**
+ * TST_EXP_PID_SILENT() - Test syscall to return PID, silent variant.
+ *
+ * @SCALL: Tested syscall.
+ * @...: A printf-like parameters.
+ *
+ * Unlike TST_EXP_PID() does not print :c:enum:`TPASS <tst_res_flags>` on success, only prints :c:enum:`TFAIL <tst_res_flags>` on failure.
+ */
#define TST_EXP_PID_SILENT(SCALL, ...) TST_EXP_POSITIVE_(SCALL, #SCALL, ##__VA_ARGS__)
+/**
+ * TST_EXP_PID() - Test syscall to return PID.
+ *
+ * @SCALL: Tested syscall.
+ * @...: A printf-like parameters.
+ */
#define TST_EXP_PID(SCALL, ...) \
({ \
TST_EXP_POSITIVE__(SCALL, #SCALL, ##__VA_ARGS__); \
@@ -138,8 +201,24 @@ extern void *TST_RET_PTR;
\
} while (0)
+/**
+ * TST_EXP_VAL_SILENT() - Test syscall to return specified value, silent variant.
+ *
+ * @SCALL: Tested syscall.
+ * @VAL: Expected return value.
+ * @...: A printf-like parameters.
+ *
+ * Unlike TST_EXP_VAL() does not print :c:enum:`TPASS <tst_res_flags>` on success, only prints :c:enum:`TFAIL <tst_res_flags>` on failure.
+ */
#define TST_EXP_VAL_SILENT(SCALL, VAL, ...) TST_EXP_VAL_SILENT_(SCALL, VAL, #SCALL, ##__VA_ARGS__)
+/**
+ * TST_EXP_VAL() - Test syscall to return specified value.
+ *
+ * @SCALL: Tested syscall.
+ * @VAL: Expected return value.
+ * @...: A printf-like parameters.
+ */
#define TST_EXP_VAL(SCALL, VAL, ...) \
do { \
TST_EXP_VAL_SILENT_(SCALL, VAL, #SCALL, ##__VA_ARGS__); \
@@ -171,8 +250,22 @@ extern void *TST_RET_PTR;
\
} while (0)
+/**
+ * TST_EXP_PASS_SILENT() - Test syscall to return 0, silent variant.
+ *
+ * @SCALL: Tested syscall.
+ * @...: A printf-like parameters.
+ *
+ * Unlike TST_EXP_PASS() does not print :c:enum:`TPASS <tst_res_flags>` on success, only prints :c:enum:`TFAIL <tst_res_flags>` on failure.
+ */
#define TST_EXP_PASS_SILENT(SCALL, ...) TST_EXP_PASS_SILENT_(SCALL, #SCALL, ##__VA_ARGS__)
+/**
+ * TST_EXP_PASS() - Test syscall to return 0.
+ *
+ * @SCALL: Tested syscall.
+ * @...: A printf-like parameters.
+ */
#define TST_EXP_PASS(SCALL, ...) \
do { \
TST_EXP_PASS_SILENT_(SCALL, #SCALL, ##__VA_ARGS__); \
@@ -263,6 +356,15 @@ const char *tst_errno_names(char *buf, const int *exp_errs, int exp_errs_cnt);
TST_MSG_(TPASS | TTERRNO, " ", SSCALL, ##__VA_ARGS__); \
} while (0)
+/**
+ * TST_EXP_FAIL() - Test syscall to fail with expected errno.
+ *
+ * @SCALL: Tested syscall.
+ * @EXP_ERR: Expected errno.
+ * @...: A printf-like parameters.
+ *
+ * For syscalls which valid return value is 0.
+ */
#define TST_EXP_FAIL(SCALL, EXP_ERR, ...) \
do { \
int tst_exp_err__ = EXP_ERR; \
@@ -270,6 +372,14 @@ const char *tst_errno_names(char *buf, const int *exp_errs, int exp_errs_cnt);
##__VA_ARGS__); \
} while (0)
+/**
+ * TST_EXP_FAIL_ARR() - Test syscall to fail with expected errnos.
+ *
+ * @SCALL: Tested syscall.
+ * @EXP_ERRS: Array of expected errnos.
+ * @EXP_ERRS_CNT: Lenght of EXP_ERRS.
+ * @...: A printf-like parameters.
+ */
#define TST_EXP_FAIL_ARR(SCALL, EXP_ERRS, EXP_ERRS_CNT, ...) \
TST_EXP_FAIL_ARR_(SCALL, #SCALL, EXP_ERRS, \
EXP_ERRS_CNT, ##__VA_ARGS__);
@@ -286,6 +396,15 @@ const char *tst_errno_names(char *buf, const int *exp_errs, int exp_errs_cnt);
TST_EXP_FAIL2_ARR_(SCALL, #SCALL, EXP_ERRS, \
EXP_ERRS_CNT, ##__VA_ARGS__);
+/**
+ * TST_EXP_FAIL_PTR_NULL() - Test syscall to fail with expected errno and return a NULL pointer.
+ *
+ * @SCALL: Tested syscall.
+ * @EXP_ERR: Expected errno.
+ * @...: A printf-like parameters.
+ *
+ * Unlike most of macros it sets TST_RET_PTR instead of TST_RET.
+ */
#define TST_EXP_FAIL_PTR_NULL(SCALL, EXP_ERR, ...) \
do { \
int tst_exp_err__ = EXP_ERR; \
@@ -293,12 +412,31 @@ const char *tst_errno_names(char *buf, const int *exp_errs, int exp_errs_cnt);
&tst_exp_err__, 1, ##__VA_ARGS__); \
} while (0)
+/**
+ * TST_EXP_FAIL_PTR_NULL_ARR() - Test syscall to fail with expected errnos and return a NULL pointer.
+ *
+ * @SCALL: Tested syscall.
+ * @EXP_ERRS: Array of expected errnos.
+ * @EXP_ERRS_CNT: Lenght of EXP_ERRS.
+ * @...: A printf-like parameters.
+ *
+ * Unlike most of macros it sets TST_RET_PTR instead of TST_RET.
+ */
#define TST_EXP_FAIL_PTR_NULL_ARR(SCALL, EXP_ERRS, EXP_ERRS_CNT, ...) \
do { \
TST_EXP_FAIL_PTR_(SCALL, #SCALL, NULL, \
EXP_ERRS, EXP_ERRS_CNT, ##__VA_ARGS__); \
} while (0)
+/**
+ * TST_EXP_FAIL_PTR_VOID() - Test syscall to fail with expected errno and return a void pointer.
+ *
+ * @SCALL: Tested syscall.
+ * @EXP_ERR: Expected errno.
+ * @...: A printf-like parameters.
+ *
+ * Unlike most of macros it sets TST_RET_PTR instead of TST_RET.
+ */
#define TST_EXP_FAIL_PTR_VOID(SCALL, EXP_ERR, ...) \
do { \
int tst_exp_err__ = EXP_ERR; \
@@ -306,12 +444,31 @@ const char *tst_errno_names(char *buf, const int *exp_errs, int exp_errs_cnt);
&tst_exp_err__, 1, ##__VA_ARGS__); \
} while (0)
+/**
+ * TST_EXP_FAIL_PTR_VOID_ARR() - Test syscall to fail with expected errnos and return a void pointer.
+ *
+ * @SCALL: Tested syscall.
+ * @EXP_ERRS: Array of expected errnos.
+ * @EXP_ERRS_CNT: Lenght of EXP_ERRS.
+ * @...: A printf-like parameters.
+ *
+ * Unlike most of macros it sets TST_RET_PTR instead of TST_RET.
+ */
#define TST_EXP_FAIL_PTR_VOID_ARR(SCALL, EXP_ERRS, EXP_ERRS_CNT, ...) \
do { \
TST_EXP_FAIL_PTR_(SCALL, #SCALL, (void *)-1, \
EXP_ERRS, EXP_ERRS_CNT, ##__VA_ARGS__); \
} while (0)
+/**
+ * TST_EXP_FAIL2() - Test syscall to fail with expected errno.
+ *
+ * @SCALL: Tested syscall.
+ * @EXP_ERR: Expected errno.
+ * @...: A printf-like parameters.
+ *
+ * For syscalls which valid return value is >= 0.
+ */
#define TST_EXP_FAIL2(SCALL, EXP_ERR, ...) \
do { \
int tst_exp_err__ = EXP_ERR; \
@@ -319,6 +476,15 @@ const char *tst_errno_names(char *buf, const int *exp_errs, int exp_errs_cnt);
##__VA_ARGS__); \
} while (0)
+/**
+ * TST_EXP_FAIL_SILENT() - Test syscall to fail with expected errno, silent variant.
+ *
+ * @SCALL: Tested syscall.
+ * @EXP_ERR: Expected errno.
+ * @...: A printf-like parameters.
+ *
+ * Unlike TST_EXP_FAIL() does not print :c:enum:`TPASS <tst_res_flags>` on success, only prints :c:enum:`TFAIL <tst_res_flags>` on failure.
+ */
#define TST_EXP_FAIL_SILENT(SCALL, EXP_ERR, ...) \
do { \
int tst_exp_err__ = EXP_ERR; \
@@ -326,6 +492,15 @@ const char *tst_errno_names(char *buf, const int *exp_errs, int exp_errs_cnt);
&tst_exp_err__, 1, ##__VA_ARGS__); \
} while (0)
+/**
+ * TST_EXP_FAIL2_SILENT() - Test syscall to fail with expected errno, silent variant.
+ *
+ * @SCALL: Tested syscall.
+ * @EXP_ERR: Expected errno.
+ * @...: A printf-like parameters.
+ *
+ * Unlike TST_EXP_FAIL2() does not print :c:enum:`TPASS <tst_res_flags>` on success, only prints :c:enum:`TFAIL <tst_res_flags>` on failure.
+ */
#define TST_EXP_FAIL2_SILENT(SCALL, EXP_ERR, ...) \
do { \
int tst_exp_err__ = EXP_ERR; \
@@ -333,6 +508,12 @@ const char *tst_errno_names(char *buf, const int *exp_errs, int exp_errs_cnt);
&tst_exp_err__, 1, ##__VA_ARGS__); \
} while (0)
+/**
+ * TST_EXP_EXPR() - Check for expected expression.
+ *
+ * @EXPR: Expression to be tested.
+ * @...: A printf-like parameters.
+ */
#define TST_EXP_EXPR(EXPR, ...) \
tst_res_(__FILE__, __LINE__, (EXPR) ? TPASS : TFAIL, "Expect: " \
TST_FMT_(TST_2_(dummy, ##__VA_ARGS__, #EXPR), __VA_ARGS__));
@@ -352,6 +533,12 @@ const char *tst_errno_names(char *buf, const int *exp_errs, int exp_errs_cnt);
} \
} while (0)
+/**
+ * TST_EXP_EQ_LI() - Compare two long long values.
+ *
+ * @VAL_A: long long value A.
+ * @VAL_B: long long value B.
+ */
#define TST_EXP_EQ_LI(VAL_A, VAL_B) do { \
TST_EXP_EQ_SILENT_(VAL_A, #VAL_A, VAL_B, #VAL_B, long long, "%lli"); \
\
@@ -362,9 +549,23 @@ const char *tst_errno_names(char *buf, const int *exp_errs, int exp_errs_cnt);
} \
} while (0)
+/**
+ * TST_EXP_EQ_LI_SILENT() - Compare two long long values, silent variant.
+ *
+ * @VAL_A: long long value A.
+ * @VAL_B: long long value B.
+ *
+ * Unlike TST_EXP_EQ_LI() does not print :c:enum:`TPASS <tst_res_flags>` on success, only prints :c:enum:`TFAIL <tst_res_flags>` on failure.
+ */
#define TST_EXP_EQ_LI_SILENT(VAL_A, VAL_B) \
TST_EXP_EQ_SILENT_(VAL_A, #VAL_A, VAL_B, #VAL_B, long long, "%lli")
+/**
+ * TST_EXP_EQ_LU() - Compare two unsigned long long values.
+ *
+ * @VAL_A: unsigned long long value A.
+ * @VAL_B: unsigned long long value B.
+ */
#define TST_EXP_EQ_LU(VAL_A, VAL_B) do { \
TST_EXP_EQ_SILENT_(VAL_A, #VAL_A, VAL_B, #VAL_B, unsigned long long, "%llu"); \
\
@@ -375,9 +576,23 @@ const char *tst_errno_names(char *buf, const int *exp_errs, int exp_errs_cnt);
} \
} while (0)
+/**
+ * TST_EXP_EQ_LU_SILENT() - Compare two unsigned long long values, silent variant.
+ *
+ * @VAL_A: unsigned long long value A.
+ * @VAL_B: unsigned long long value B.
+ *
+ * Unlike TST_EXP_EQ_LU() does not print :c:enum:`TPASS <tst_res_flags>` on success, only prints :c:enum:`TFAIL <tst_res_flags>` on failure.
+ */
#define TST_EXP_EQ_LU_SILENT(VAL_A, VAL_B) \
TST_EXP_EQ_SILENT_(VAL_A, #VAL_A, VAL_B, #VAL_B, unsigned long long, "%llu")
+/**
+ * TST_EXP_EQ_SZ() - Compare two unsigned size_t values.
+ *
+ * @VAL_A: unsigned long long value A.
+ * @VAL_B: unsigned long long value B.
+ */
#define TST_EXP_EQ_SZ(VAL_A, VAL_B) do { \
TST_EXP_EQ_SILENT_(VAL_A, #VAL_A, VAL_B, #VAL_B, size_t, "%zu"); \
\
@@ -388,9 +603,23 @@ const char *tst_errno_names(char *buf, const int *exp_errs, int exp_errs_cnt);
} \
} while (0)
+/**
+ * TST_EXP_EQ_SZ_SILENT() - Compare two unsigned size_t values, silent variant.
+ *
+ * @VAL_A: unsigned long long value A.
+ * @VAL_B: unsigned long long value B.
+ *
+ * Unlike TST_EXP_EQ_SZ() does not print :c:enum:`TPASS <tst_res_flags>` on success, only prints :c:enum:`TFAIL <tst_res_flags>` on failure.
+ */
#define TST_EXP_EQ_SZ_SILENT(VAL_A, VAL_B) \
TST_EXP_EQ_SILENT_(VAL_A, #VAL_A, VAL_B, #VAL_B, size_t, "%zu")
+/**
+ * TST_EXP_EQ_SSZ() - Compare two unsigned ssize_t values.
+ *
+ * @VAL_A: unsigned long long value A.
+ * @VAL_B: unsigned long long value B.
+ */
#define TST_EXP_EQ_SSZ(VAL_A, VAL_B) do { \
TST_EXP_EQ_SILENT_(VAL_A, #VAL_A, VAL_B, #VAL_B, size_t, "%zi"); \
\
@@ -401,9 +630,23 @@ const char *tst_errno_names(char *buf, const int *exp_errs, int exp_errs_cnt);
} \
} while (0)
+/**
+ * TST_EXP_EQ_SSZ_SILENT() - Compare two unsigned ssize_t values, silent variant.
+ *
+ * @VAL_A: unsigned long long value A.
+ * @VAL_B: unsigned long long value B.
+ *
+ * Unlike TST_EXP_EQ_SSZ() does not print :c:enum:`TPASS <tst_res_flags>` on success, only prints :c:enum:`TFAIL <tst_res_flags>` on failure.
+ */
#define TST_EXP_EQ_SSZ_SILENT(VAL_A, VAL_B) \
TST_EXP_EQ_SILENT_(VAL_A, #VAL_A, VAL_B, #VAL_B, ssize_t, "%zi")
+/**
+ * TST_EXP_EQ_STR() - Compare two strings.
+ *
+ * @STR_A: string to compare.
+ * @STR_B: string to compare.
+ */
#define TST_EXP_EQ_STR(STR_A, STR_B) do { \
TST_PASS = strcmp(STR_A, STR_B) == 0; \
\
--
2.47.1
More information about the ltp
mailing list