From: Avinesh Kumar <akumar@suse.de>
To: Petr Vorel <pvorel@suse.cz>
Cc: ltp@lists.linux.it
Subject: Re: [LTP] [PATCH 2/2] macros: Add basic docs
Date: Mon, 12 May 2025 11:17:24 +0200 [thread overview]
Message-ID: <4653486.LvFx2qVVIh@thinkpad> (raw)
In-Reply-To: <20250109132334.212281-2-pvorel@suse.cz>
Hi Petr,
This is very helpful. Thank you!
Reviewed-by: Avinesh Kumar <akumar@suse.de>
for both patches in series.
On Thursday, January 9, 2025 2:23:34 PM CEST Petr Vorel wrote:
> 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; \
> \
>
Regards,
Avinesh
--
Mailing list info: https://lists.linux.it/listinfo/ltp
next prev parent reply other threads:[~2025-05-12 9:17 UTC|newest]
Thread overview: 12+ messages / expand[flat|nested] mbox.gz Atom feed top
2025-01-09 13:23 [LTP] [PATCH 1/2] [RFC] macros: Remove TEST_VOID() Petr Vorel
2025-01-09 13:23 ` [LTP] [PATCH 2/2] macros: Add basic docs Petr Vorel
2025-01-09 13:35 ` Andrea Cervesato via ltp
2025-01-10 14:57 ` Petr Vorel
2025-01-14 14:44 ` Andrea Cervesato via ltp
2025-05-09 7:00 ` Li Wang via ltp
2025-05-12 9:17 ` Avinesh Kumar [this message]
2025-06-09 7:17 ` Petr Vorel
2025-01-14 14:46 ` [LTP] [PATCH 1/2] [RFC] macros: Remove TEST_VOID() Andrea Cervesato via ltp
2025-01-14 16:20 ` Petr Vorel
2025-05-09 6:46 ` Li Wang via ltp
2025-06-09 7:14 ` Petr Vorel
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=4653486.LvFx2qVVIh@thinkpad \
--to=akumar@suse.de \
--cc=ltp@lists.linux.it \
--cc=pvorel@suse.cz \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.