diff mbox series

[2/2] macros: Add basic docs

Message ID 20250109132334.212281-2-pvorel@suse.cz
State New
Headers show
Series [1/2,RFC] macros: Remove TEST_VOID() | expand

Commit Message

Petr Vorel Jan. 9, 2025, 1:23 p.m. UTC
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(-)

Comments

Andrea Cervesato Jan. 9, 2025, 1:35 p.m. UTC | #1
Hi Petr,

thanks for this documentation. It's really needed.

On 1/9/25 14:23, 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
>    */
Is this really needed?
>   
>   #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;                                  \
>                                                                                  \

Reviewed-by: Andrea Cervesato <andrea.cervesato@suse.com>

Andrea
Petr Vorel Jan. 10, 2025, 2:57 p.m. UTC | #2
Hi Andrea,

> Hi Petr,

> thanks for this documentation. It's really needed.

Yes, I had it long time in my mind. Thanks for the review.
...
> > +++ 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
> >    */
> Is this really needed?

Well, IMHO throwing just functions description to users is not enough.
I would even add a short description about the goal of these macros.

And because sooner or later as we increase sphinx doc in the headers the list
will be quite long. Therefore for the start I added just a title (short
paragraph with a description would be of curse  better).

Kind regards,
Petr
Andrea Cervesato Jan. 14, 2025, 2:44 p.m. UTC | #3
Ok thanks,

Reviewed-by: Andrea Cervesato <andrea.cervesato@suse.com>

Kind regards,
Andrea

On 1/10/25 15:57, Petr Vorel wrote:
> Hi Andrea,
>
>> Hi Petr,
>> thanks for this documentation. It's really needed.
> Yes, I had it long time in my mind. Thanks for the review.
> ...
>>> +++ 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
>>>     */
>> Is this really needed?
> Well, IMHO throwing just functions description to users is not enough.
> I would even add a short description about the goal of these macros.
>
> And because sooner or later as we increase sphinx doc in the headers the list
> will be quite long. Therefore for the start I added just a title (short
> paragraph with a description would be of curse  better).
>
> Kind regards,
> Petr
diff mbox series

Patch

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;                                  \
                                                                                \